@bananalytics/react-native 0.1.0

package/dist/types/config.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Configuration for the Bananalytics analytics SDK.
+ */
+export interface BananalyticsConfig {
+    /** Write-only public API key. */
+    apiKey: string;
+    /** Ingestion API endpoint URL. */
+    endpoint: string;
+    /** Milliseconds between automatic flushes. @default 30000 */
+    flushInterval?: number;
+    /** Number of events that triggers an immediate flush. @default 20 */
+    flushAt?: number;
+    /** Maximum number of events held in memory. @default 1000 */
+    maxQueueSize?: number;
+    /** Maximum retry attempts for failed flushes. @default 3 */
+    maxRetries?: number;
+    /** Enable debug console logging. @default false */
+    debug?: boolean;
+    /** Auto-track app foreground/background events. @default true */
+    trackAppLifecycle?: boolean;
+    /** Auto-track screen views (requires React Navigation setup). @default false */
+    trackScreens?: boolean;
+    /** Session inactivity timeout in milliseconds. @default 1800000 (30 minutes) */
+    sessionTimeout?: number;
+}

package/dist/types/config.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/events.d.ts

@@ -0,0 +1,53 @@
+import { Properties, Timestamp, UUID } from './common';
+/** The type of analytics event. */
+export type EventType = 'track' | 'screen' | 'identify';
+/** Device context information. */
+export interface DeviceContext {
+    os: string;
+    osVersion: string;
+    model: string;
+    manufacturer: string;
+    screenWidth: number;
+    screenHeight: number;
+}
+/** Application context information. */
+export interface AppContext {
+    name: string;
+    version: string;
+    build: string;
+    bundleId: string;
+}
+/** Session context information. */
+export interface SessionContext {
+    id: UUID;
+    startedAt: Timestamp;
+}
+/** Full event context sent with each event. */
+export interface EventContext {
+    device: DeviceContext;
+    app: AppContext;
+    session: SessionContext;
+    locale: string;
+    timezone: string;
+}
+/** The payload sent to the backend for each event. */
+export interface EventPayload {
+    event: string;
+    type: EventType;
+    properties: Properties;
+    context: EventContext;
+    userId: string | null;
+    anonymousId: UUID;
+    timestamp: Timestamp;
+    messageId: UUID;
+}
+/** Screen event tracking data. */
+export interface ScreenEvent {
+    screenName: string;
+    properties?: Properties;
+}
+/** Identify event data. */
+export interface IdentifyEvent {
+    userId: string;
+    traits?: Properties;
+}

package/dist/types/events.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/utils/id.d.ts

@@ -0,0 +1,13 @@
+import { UUID } from '../types/common';
+/**
+ * Generates a new UUID v4 identifier.
+ *
+ * @returns A unique UUID v4 string
+ *
+ * @example
+ * ```ts
+ * const id = generateId();
+ * // "550e8400-e29b-41d4-a716-446655440000"
+ * ```
+ */
+export declare function generateId(): UUID;

package/dist/utils/id.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateId = generateId;
+const uuid_1 = require("uuid");
+/**
+ * Generates a new UUID v4 identifier.
+ *
+ * @returns A unique UUID v4 string
+ *
+ * @example
+ * ```ts
+ * const id = generateId();
+ * // "550e8400-e29b-41d4-a716-446655440000"
+ * ```
+ */
+function generateId() {
+    return (0, uuid_1.v4)();
+}

package/dist/utils/logger.d.ts

@@ -0,0 +1,11 @@
+/** Internal debug logger that only outputs when debug mode is enabled. */
+export declare class Logger {
+    private enabled;
+    constructor(debug: boolean);
+    /** Log a debug message. Only outputs when debug mode is enabled. */
+    debug(message: string, ...args: unknown[]): void;
+    /** Log a warning. Always outputs regardless of debug mode. */
+    warn(message: string, ...args: unknown[]): void;
+    /** Log an error. Always outputs regardless of debug mode. */
+    error(message: string, ...args: unknown[]): void;
+}

package/dist/utils/logger.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Logger = void 0;
+/** Internal debug logger that only outputs when debug mode is enabled. */
+class Logger {
+    constructor(debug) {
+        this.enabled = debug;
+    }
+    /** Log a debug message. Only outputs when debug mode is enabled. */
+    debug(message, ...args) {
+        if (this.enabled) {
+            console.log(`[Bananalytics] ${message}`, ...args);
+        }
+    }
+    /** Log a warning. Always outputs regardless of debug mode. */
+    warn(message, ...args) {
+        console.warn(`[Bananalytics] ${message}`, ...args);
+    }
+    /** Log an error. Always outputs regardless of debug mode. */
+    error(message, ...args) {
+        console.error(`[Bananalytics] ${message}`, ...args);
+    }
+}
+exports.Logger = Logger;

package/dist/utils/network.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Checks if the device currently has network connectivity.
+ * Uses React Native's NetInfo if available, falls back to assuming online.
+ *
+ * @returns true if connected, false if offline
+ */
+export declare function isOnline(): Promise<boolean>;

package/dist/utils/network.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isOnline = isOnline;
+/**
+ * Checks if the device currently has network connectivity.
+ * Uses React Native's NetInfo if available, falls back to assuming online.
+ *
+ * @returns true if connected, false if offline
+ */
+async function isOnline() {
+    try {
+        // Try React Native NetInfo (requires @react-native-community/netinfo)
+        const NetInfo = require('@react-native-community/netinfo');
+        const state = await NetInfo.fetch();
+        return state.isConnected ?? true;
+    }
+    catch {
+        // NetInfo not installed — try fetch-based check
+        try {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), 3000);
+            await fetch('https://clients3.google.com/generate_204', {
+                method: 'HEAD',
+                signal: controller.signal,
+            });
+            clearTimeout(timeout);
+            return true;
+        }
+        catch {
+            return true; // Assume online if we can't determine — better to try and fail
+        }
+    }
+}

package/dist/utils/time.d.ts

@@ -0,0 +1,13 @@
+import { Timestamp } from '../types/common';
+/**
+ * Returns the current time as an ISO 8601 timestamp string.
+ *
+ * @returns ISO 8601 formatted timestamp
+ *
+ * @example
+ * ```ts
+ * const ts = now();
+ * // "2025-01-15T10:30:00.000Z"
+ * ```
+ */
+export declare function now(): Timestamp;

package/dist/utils/time.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.now = now;
+/**
+ * Returns the current time as an ISO 8601 timestamp string.
+ *
+ * @returns ISO 8601 formatted timestamp
+ *
+ * @example
+ * ```ts
+ * const ts = now();
+ * // "2025-01-15T10:30:00.000Z"
+ * ```
+ */
+function now() {
+    return new Date().toISOString();
+}

package/dist/utils/validation.d.ts

@@ -0,0 +1,26 @@
+import { Properties } from '../types/common';
+/**
+ * Validates an event name.
+ *
+ * @param name - The event name to validate
+ * @returns Error message if invalid, null if valid
+ *
+ * @example
+ * ```ts
+ * validateEventName('button_clicked'); // null
+ * validateEventName(''); // "event name is required"
+ * ```
+ */
+export declare function validateEventName(name: string): string | null;
+/**
+ * Validates event properties.
+ *
+ * @param properties - The properties object to validate
+ * @returns Error message if invalid, null if valid
+ *
+ * @example
+ * ```ts
+ * validateProperties({ key: 'value' }); // null
+ * ```
+ */
+export declare function validateProperties(properties: Properties): string | null;

package/dist/utils/validation.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateEventName = validateEventName;
+exports.validateProperties = validateProperties;
+const MAX_EVENT_NAME_LENGTH = 256;
+const MAX_PROPERTY_KEY_LENGTH = 256;
+const MAX_PROPERTY_VALUE_SIZE = 8192; // 8KB
+const MAX_PROPERTIES_COUNT = 256;
+const EVENT_NAME_REGEX = /^[\w$]+$/;
+/**
+ * Validates an event name.
+ *
+ * @param name - The event name to validate
+ * @returns Error message if invalid, null if valid
+ *
+ * @example
+ * ```ts
+ * validateEventName('button_clicked'); // null
+ * validateEventName(''); // "event name is required"
+ * ```
+ */
+function validateEventName(name) {
+    if (!name) {
+        return 'event name is required';
+    }
+    if (name.length > MAX_EVENT_NAME_LENGTH) {
+        return `event name exceeds ${MAX_EVENT_NAME_LENGTH} character limit: got ${name.length}`;
+    }
+    if (!EVENT_NAME_REGEX.test(name)) {
+        return 'event name must contain only alphanumeric characters, underscores, and dollar signs';
+    }
+    return null;
+}
+/**
+ * Validates event properties.
+ *
+ * @param properties - The properties object to validate
+ * @returns Error message if invalid, null if valid
+ *
+ * @example
+ * ```ts
+ * validateProperties({ key: 'value' }); // null
+ * ```
+ */
+function validateProperties(properties) {
+    const keys = Object.keys(properties);
+    if (keys.length > MAX_PROPERTIES_COUNT) {
+        return `too many properties: got ${keys.length}, max ${MAX_PROPERTIES_COUNT}`;
+    }
+    for (const key of keys) {
+        if (key.length > MAX_PROPERTY_KEY_LENGTH) {
+            return `property key "${key}" exceeds ${MAX_PROPERTY_KEY_LENGTH} character limit`;
+        }
+        const serialized = JSON.stringify(properties[key]);
+        if (serialized.length > MAX_PROPERTY_VALUE_SIZE) {
+            return `property value for key "${key}" exceeds ${MAX_PROPERTY_VALUE_SIZE} byte limit: got ${serialized.length}`;
+        }
+    }
+    return null;
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@bananalytics/react-native",
+  "version": "0.1.0",
+  "description": "Self-hosted, privacy-first analytics SDK for React Native and Expo apps. Funnels, retention, sessions, geography — your server, your data.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "analytics",
+    "react-native",
+    "expo",
+    "self-hosted",
+    "privacy",
+    "tracking",
+    "events",
+    "funnels",
+    "retention",
+    "mixpanel-alternative",
+    "amplitude-alternative",
+    "posthog-alternative"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run lint && npm run test && npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0",
+    "react-native": ">=0.60.0",
+    "@react-native-async-storage/async-storage": ">=1.0.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/react": "^18.2.0",
+    "@types/uuid": "^9.0.8",
+    "jest": "^29.7.0",
+    "react": "^18.2.0",
+    "react-native": "^0.73.0",
+    "ts-jest": "^29.1.2",
+    "typescript": "^5.4.0"
+  },
+  "dependencies": {
+    "uuid": "^9.0.1"
+  },
+  "license": "MIT",
+  "author": "Bananalytics",
+  "homepage": "https://bananalytics.xyz",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TableTennisCoder/bananalytics.git",
+    "directory": "packages/react-native"
+  },
+  "bugs": {
+    "url": "https://github.com/TableTennisCoder/bananalytics/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}