@baukit/analytics-posthog-native 0.4.0 → 0.5.0

package/README.md

@@ -52,6 +52,34 @@ The adapter exports a minimal structural `PostHogNativeClient` interface for moc
 while its initializer options compile against `posthog-react-native`'s published types. This keeps
 unit tests runnable without installing or booting a React Native runtime.
 
+## Persisted identity storage
+
+`AnalyticsClient` reads storage synchronously, while React Native storage is asynchronous. The
+`/storage` subpath bridges the two. `HydratedAnalyticsStorage.load` reads the listed keys once,
+serves later reads from memory, and writes those keys through without waiting. Other keys stay in
+memory. The subpath does not import `posthog-react-native`, so apps with another transport can use
+it without the SDK.
+
+```ts
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import { AnalyticsClient, analyticsStorageKeys } from '@baukit/analytics-core';
+import { HydratedAnalyticsStorage } from '@baukit/analytics-posthog-native/storage';
+
+const keys = analyticsStorageKeys(storageKeyPrefix);
+const storage = await HydratedAnalyticsStorage.load({
+  persistence: AsyncStorage,
+  persistentKeys: [keys.anonymousId, keys.userId, keys.aliasedUserId],
+});
+const analytics = new AnalyticsClient({ context, allowlist, storage, storageKeyPrefix });
+```
+
+Include `keys.consent` only when analytics consent has no other durable home. A key that fails to
+read starts absent, and the other keys still load. A failed write keeps the in-memory value and is
+not reported. The storage holds only what the client writes: the consent state and pseudonymous
+UUIDs.
+
+`posthog-react-native` is an optional peer. Install it only when you use the transport.
+
 ## Mapping
 
 - `capture` flattens the core-stamped context and already-scrubbed event properties, preserving the

package/dist/storage.d.ts

@@ -0,0 +1,25 @@
+import type { AnalyticsStorage } from '@baukit/analytics-core';
+/** Asynchronous key-value store, such as React Native AsyncStorage. */
+export interface AsyncKeyValueStorage {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+export interface HydratedAnalyticsStorageOptions {
+    readonly persistence: AsyncKeyValueStorage;
+    /** Keys copied from and written through to `persistence`. Other keys stay in memory. */
+    readonly persistentKeys: readonly string[];
+}
+/**
+ * Synchronous `AnalyticsStorage` over an asynchronous store. `load` reads the persistent keys
+ * once, then reads are served from memory and writes go through without being awaited.
+ */
+export declare class HydratedAnalyticsStorage implements AnalyticsStorage {
+    #private;
+    private constructor();
+    static load(options: HydratedAnalyticsStorageOptions): Promise<HydratedAnalyticsStorage>;
+    getItem(key: string): string | undefined;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+//# sourceMappingURL=storage.d.ts.map

package/dist/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D,uEAAuE;AACvE,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC7C,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC;AAED,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAC;IAC3C,wFAAwF;IACxF,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5C;AAED;;;GAGG;AACH,qBAAa,wBAAyB,YAAW,gBAAgB;;IAK/D,OAAO;WASa,IAAI,CACtB,OAAO,EAAE,+BAA+B,GACvC,OAAO,CAAC,wBAAwB,CAAC;IAU7B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIxC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAMzC,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;CAKrC"}

package/dist/storage.js

@@ -0,0 +1,55 @@
+/**
+ * Synchronous `AnalyticsStorage` over an asynchronous store. `load` reads the persistent keys
+ * once, then reads are served from memory and writes go through without being awaited.
+ */
+export class HydratedAnalyticsStorage {
+    #values;
+    #persistence;
+    #persistentKeys;
+    constructor(options, entries) {
+        this.#persistence = options.persistence;
+        this.#persistentKeys = new Set(options.persistentKeys);
+        this.#values = new Map(entries);
+    }
+    static async load(options) {
+        const keys = [...new Set(options.persistentKeys)];
+        const stored = await Promise.all(keys.map((key) => readOrAbsent(options.persistence, key)));
+        const entries = keys.flatMap((key, index) => {
+            const value = stored[index];
+            return value === undefined ? [] : [[key, value]];
+        });
+        return new HydratedAnalyticsStorage(options, entries);
+    }
+    getItem(key) {
+        return this.#values.get(key);
+    }
+    setItem(key, value) {
+        this.#values.set(key, value);
+        if (!this.#persistentKeys.has(key))
+            return;
+        ignoreFailure(() => this.#persistence.setItem(key, value));
+    }
+    removeItem(key) {
+        this.#values.delete(key);
+        if (!this.#persistentKeys.has(key))
+            return;
+        ignoreFailure(() => this.#persistence.removeItem(key));
+    }
+}
+async function readOrAbsent(persistence, key) {
+    try {
+        return (await persistence.getItem(key)) ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function ignoreFailure(write) {
+    try {
+        void write().catch(() => undefined);
+    }
+    catch {
+        return;
+    }
+}
+//# sourceMappingURL=storage.js.map

package/dist/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAeA;;;GAGG;AACH,MAAM,OAAO,wBAAwB;IAC1B,OAAO,CAAsB;IAC7B,YAAY,CAAuB;IACnC,eAAe,CAAsB;IAE9C,YACE,OAAwC,EACxC,OAA+C;QAE/C,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;QACxC,IAAI,CAAC,eAAe,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;QACvD,IAAI,CAAC,OAAO,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;IAClC,CAAC;IAEM,MAAM,CAAC,KAAK,CAAC,IAAI,CACtB,OAAwC;QAExC,MAAM,IAAI,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC;QAClD,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,YAAY,CAAC,OAAO,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;QAC5F,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE;YAC1C,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;YAC5B,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAU,CAAC,CAAC;QAC5D,CAAC,CAAC,CAAC;QACH,OAAO,IAAI,wBAAwB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACxD,CAAC;IAEM,OAAO,CAAC,GAAW;QACxB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC/B,CAAC;IAEM,OAAO,CAAC,GAAW,EAAE,KAAa;QACvC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC7B,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,OAAO;QAC3C,aAAa,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC;IAC7D,CAAC;IAEM,UAAU,CAAC,GAAW;QAC3B,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACzB,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,OAAO;QAC3C,aAAa,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;IACzD,CAAC;CACF;AAED,KAAK,UAAU,YAAY,CACzB,WAAiC,EACjC,GAAW;IAEX,IAAI,CAAC;QACH,OAAO,CAAC,MAAM,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,SAAS,CAAC;IACvD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,SAAS,aAAa,CAAC,KAA0B;IAC/C,IAAI,CAAC;QACH,KAAK,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IACtC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;IACT,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@baukit/analytics-posthog-native",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "PostHog React Native transport for @baukit/analytics-core.",
   "license": "MIT",
   "author": "Patrick Koss",
@@ -24,7 +24,13 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./storage": {
+      "types": "./dist/storage.d.ts",
+      "import": "./dist/storage.js",
+      "default": "./dist/storage.js"
     }
   },
   "files": [
@@ -32,19 +38,25 @@
     "README.md",
     "LICENSE"
   ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepare": "pnpm run build",
+    "test": "tsc -p tsconfig.test.json && vitest run --config ../../vitest.config.ts && node ../../scripts/test-packed-exports.mjs",
+    "lint": "eslint src --max-warnings=0",
+    "format:check": "prettier --check src package.json tsconfig.json tsconfig.test.json"
+  },
   "devDependencies": {
+    "@baukit/analytics-core": "workspace:*",
     "posthog-react-native": "4.62.0",
-    "typescript": "6.0.3",
-    "@baukit/analytics-core": "0.4.0"
+    "typescript": "6.0.3"
   },
   "peerDependencies": {
-    "@baukit/analytics-core": "^0.4.0",
+    "@baukit/analytics-core": "^0.5.0",
     "posthog-react-native": "^4.62.0"
   },
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "test": "vitest run --config ../../vitest.config.ts",
-    "lint": "eslint src --max-warnings=0",
-    "format:check": "prettier --check src package.json tsconfig.json"
+  "peerDependenciesMeta": {
+    "posthog-react-native": {
+      "optional": true
+    }
   }
-}
+}