@metrictrail/react-native 0.1.0

package/README.md

@@ -0,0 +1,3 @@
+# MetricTrail React Native SDK
+
+React Native with an ES2022 runtime. Inject the app's encrypted/AsyncStorage-compatible adapter through `storage`; MetricTrail stores only events, never the write key. Call `onAppBackground()` from `AppState` and `shutdown()` during controlled teardown. Platform must be `ios` or `android`. The package requests no location permission.

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+export interface AsyncStore {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+}
+export interface Options {
+    endpoint: string;
+    projectId: string;
+    writeKey: string;
+    platform: 'ios' | 'android';
+    storage?: AsyncStore;
+    storageKey?: string;
+    anonymousId?: string;
+    version?: string;
+    maxQueue?: number;
+    maxRetries?: number;
+    idFactory?: () => string;
+}
+export declare class MetricTrail {
+    private options;
+    private queue;
+    private anonymousId;
+    private userId;
+    private flushing?;
+    private key;
+    private id;
+    private constructor();
+    static create(options: Options): Promise<MetricTrail>;
+    identify(userId: string): void;
+    reset(): void;
+    track(name: string, properties?: Record<string, unknown>): Promise<string>;
+    flush(signal?: AbortSignal): Promise<void>;
+    onAppBackground(signal?: AbortSignal): Promise<void>;
+    shutdown(signal?: AbortSignal): Promise<void>;
+    private doFlush;
+    private persist;
+    get pending(): number;
+}

package/dist/index.js

@@ -0,0 +1,72 @@
+const fallbackId = () => globalThis.crypto?.randomUUID?.() || 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, c => { const r = Math.random() * 16 | 0; return (c === 'x' ? r : r & 3 | 8).toString(16); });
+export class MetricTrail {
+    options;
+    queue = [];
+    anonymousId;
+    userId = '';
+    flushing;
+    key;
+    id;
+    constructor(options) {
+        this.options = options;
+        if (!/^https?:\/\//.test(options.endpoint) || !options.projectId || !options.writeKey)
+            throw Error('Endpoint, project and write key required');
+        this.id = options.idFactory || fallbackId;
+        this.anonymousId = options.anonymousId || this.id();
+        this.key = options.storageKey || `metrictrail:${options.endpoint}:${options.projectId}:queue`;
+    }
+    static async create(options) { const c = new MetricTrail(options); if (options.storage) {
+        try {
+            const raw = await options.storage.getItem(c.key);
+            const value = raw ? JSON.parse(raw) : [];
+            if (Array.isArray(value))
+                c.queue = value.slice(0, options.maxQueue ?? 1000);
+        }
+        catch { /* optional storage falls back to memory */ }
+    } return c; }
+    identify(userId) { if (!userId || userId.length > 128)
+        throw Error('Invalid user ID'); if (this.userId && this.userId !== userId)
+        this.anonymousId = this.id(); this.userId = userId; }
+    reset() { this.userId = ''; this.anonymousId = this.id(); }
+    async track(name, properties = {}) { if (!/^[A-Za-z][A-Za-z0-9_.-]{0,79}$/.test(name))
+        throw Error('Invalid event name'); const encoded = JSON.stringify(properties); if (Object.keys(properties).length > 40 || encoded.length > 8192)
+        throw Error('Invalid event properties'); if (this.queue.length >= (this.options.maxQueue ?? 1000))
+        throw Error('Event queue full'); const eventId = this.id(); this.queue.push({ schema_version: 1, event_id: eventId, name, anonymous_id: this.anonymousId, user_id: this.userId, occurred_at: new Date().toISOString(), platform: this.options.platform, version: this.options.version || '', properties: JSON.parse(encoded) }); await this.persist(); return eventId; }
+    flush(signal) { if (!this.flushing)
+        this.flushing = this.doFlush(signal).finally(() => this.flushing = undefined); return this.flushing; }
+    async onAppBackground(signal) { return this.flush(signal); }
+    async shutdown(signal) { return this.flush(signal); }
+    async doFlush(signal) { while (this.queue.length) {
+        const batch = this.queue.slice(0, 100), body = JSON.stringify({ events: batch });
+        let failure;
+        const retries = Math.min(5, Math.max(0, this.options.maxRetries ?? 2));
+        for (let attempt = 0; attempt <= retries; attempt++) {
+            try {
+                const response = await fetch(`${this.options.endpoint.replace(/\/$/, '')}/v1/projects/${encodeURIComponent(this.options.projectId)}/events`, { method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${this.options.writeKey}` }, body, signal });
+                if (response.ok) {
+                    failure = undefined;
+                    break;
+                }
+                failure = Error(`Collection failed (${response.status})`);
+                if (response.status < 500 && response.status !== 429)
+                    throw failure;
+            }
+            catch (error) {
+                failure = error;
+                if (signal?.aborted)
+                    throw error;
+            }
+            if (attempt < retries)
+                await new Promise(resolve => setTimeout(resolve, 250 * 2 ** attempt));
+        }
+        if (failure)
+            throw failure;
+        this.queue.splice(0, batch.length);
+        await this.persist();
+    } }
+    async persist() { try {
+        await this.options.storage?.setItem(this.key, JSON.stringify(this.queue));
+    }
+    catch { /* queue remains in memory */ } }
+    get pending() { return this.queue.length; }
+}

package/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@metrictrail/react-native",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist", "README.md"],
+  "scripts": {"build": "tsc -p tsconfig.json", "test": "node --test tests/*.test.mjs"},
+  "devDependencies": {"typescript": "^5.7.0"}
+}