@baukit/analytics-posthog-native 0.7.1 → 0.7.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@baukit/analytics-posthog-native",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "PostHog React Native transport for @baukit/analytics-core.",
   "license": "MIT",
   "author": "Patrick Koss",
@@ -35,6 +35,7 @@
   },
   "files": [
     "dist",
+    "src",
     "README.md",
     "LICENSE"
   ],
@@ -51,7 +52,7 @@
     "typescript": "6.0.3"
   },
   "peerDependencies": {
-    "@baukit/analytics-core": "^0.7.1",
+    "@baukit/analytics-core": "^0.7.3",
     "posthog-react-native": "^4.78.3"
   },
   "peerDependenciesMeta": {

package/src/index.test.ts

@@ -0,0 +1,285 @@
+import { AnalyticsClient } from '@baukit/analytics-core';
+import type { AnalyticsContext, AnalyticsEnvelope, EventAllowlist } from '@baukit/analytics-core';
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  createPostHogNativeTransport,
+  PostHogNativeTransport,
+  type PostHogNativeClient,
+} from './index.js';
+
+interface ProductEvent {
+  name: 'onboarding_started';
+  properties: { source: 'organic' | 'invite'; contact?: string };
+}
+
+const ANONYMOUS_ID = '00000000-0000-4000-8000-000000000001';
+const USER_ID = '10000000-0000-4000-8000-000000000001';
+const CAPTURED_AT = '2026-08-08T10:00:00.000Z';
+
+const context: AnalyticsContext = {
+  schema_version: 1,
+  app: 'example-native',
+  app_version: '1.0.0',
+  platform: 'native',
+  environment: 'test',
+  locale: 'en-GB',
+};
+
+interface MockClient {
+  readonly client: PostHogNativeClient;
+  readonly capture: ReturnType<typeof vi.fn>;
+  readonly identify: ReturnType<typeof vi.fn>;
+  readonly alias: ReturnType<typeof vi.fn>;
+  readonly reset: ReturnType<typeof vi.fn>;
+  readonly optIn: ReturnType<typeof vi.fn>;
+  readonly optOut: ReturnType<typeof vi.fn>;
+  readonly setPersistedProperty: ReturnType<typeof vi.fn>;
+  readonly queue: string[];
+}
+
+function createMockClient(): MockClient {
+  const capture = vi.fn();
+  const identify = vi.fn();
+  const alias = vi.fn();
+  const reset = vi.fn();
+  const optIn = vi.fn();
+  const optOut = vi.fn();
+  const setPersistedProperty = vi.fn();
+  const queue: string[] = [];
+  let optedOut = true;
+  const client: PostHogNativeClient = {
+    capture(event, properties, options) {
+      capture(event, properties, options);
+      if (!optedOut) {
+        queue.push(event);
+      }
+    },
+    identify,
+    alias,
+    reset,
+    optIn() {
+      optIn();
+      optedOut = false;
+    },
+    optOut() {
+      optOut();
+      optedOut = true;
+    },
+    setPersistedProperty(key, value) {
+      setPersistedProperty(key, value);
+      if (Array.isArray(value)) {
+        queue.length = 0;
+      }
+    },
+  };
+  return {
+    client,
+    capture,
+    identify,
+    alias,
+    reset,
+    optIn,
+    optOut,
+    setPersistedProperty,
+    queue,
+  };
+}
+
+function lifecycleEnvelopes(): readonly AnalyticsEnvelope<ProductEvent>[] {
+  return [
+    {
+      type: 'capture',
+      captured_at: CAPTURED_AT,
+      anonymous_id: ANONYMOUS_ID,
+      event: {
+        ...context,
+        name: 'onboarding_started',
+        properties: { source: 'organic', contact: '[redacted]' },
+      },
+    },
+    {
+      type: 'identify',
+      captured_at: CAPTURED_AT,
+      anonymous_id: ANONYMOUS_ID,
+      user_id: USER_ID,
+      traits: { plan: 'free', email: '[redacted]' },
+    },
+    {
+      type: 'alias',
+      captured_at: CAPTURED_AT,
+      anonymous_id: ANONYMOUS_ID,
+      user_id: USER_ID,
+    },
+    {
+      type: 'reset',
+      captured_at: CAPTURED_AT,
+      previous_anonymous_id: ANONYMOUS_ID,
+      previous_user_id: USER_ID,
+    },
+  ];
+}
+
+describe('PostHogNativeTransport mapping', () => {
+  it('maps capture, identify, alias, and reset without adding properties', async () => {
+    const posthog = createMockClient();
+    const transport = new PostHogNativeTransport<ProductEvent>(posthog.client);
+
+    await transport.send(lifecycleEnvelopes());
+
+    expect(posthog.capture).toHaveBeenCalledWith(
+      'onboarding_started',
+      {
+        source: 'organic',
+        contact: '[redacted]',
+        ...context,
+      },
+      { timestamp: new Date(CAPTURED_AT) },
+    );
+    expect(posthog.identify).toHaveBeenCalledWith(USER_ID, {
+      plan: 'free',
+      email: '[redacted]',
+    });
+    expect(posthog.alias).toHaveBeenCalledWith(USER_ID);
+    expect(posthog.reset).toHaveBeenCalledWith();
+  });
+
+  it('contains client and diagnostic failures', async () => {
+    const posthog = createMockClient();
+    posthog.capture.mockImplementation(() => {
+      throw new Error('provider failed');
+    });
+    const transport = new PostHogNativeTransport<ProductEvent>(posthog.client, () => {
+      throw new Error('diagnostic failed');
+    });
+
+    await expect(transport.send(lifecycleEnvelopes())).resolves.toBeUndefined();
+    expect(posthog.identify).toHaveBeenCalledOnce();
+  });
+});
+
+describe('createPostHogNativeTransport', () => {
+  it('requires a self-hosted API host and API key', () => {
+    expect(() => createPostHogNativeTransport({ apiKey: 'phc_key', apiHost: '' })).toThrow(
+      'apiHost must not be empty',
+    );
+    expect(() =>
+      createPostHogNativeTransport({ apiKey: 'phc_key', apiHost: 'posthog.internal' }),
+    ).toThrow('apiHost must be an absolute http(s) URL');
+    expect(() =>
+      createPostHogNativeTransport({ apiKey: '', apiHost: 'https://posthog.example.test' }),
+    ).toThrow('apiKey must not be empty');
+  });
+
+  it('initializes lazily with typed-only privacy defaults and the core anonymous ID', async () => {
+    const posthog = createMockClient();
+    const initializer = vi.fn(() => posthog.client);
+    const transport = createPostHogNativeTransport<ProductEvent>({
+      apiKey: ' phc_key ',
+      apiHost: 'https://posthog.example.test/',
+      initializer,
+    });
+
+    expect(initializer).not.toHaveBeenCalled();
+    await transport.send(lifecycleEnvelopes().slice(0, 1));
+
+    expect(initializer).toHaveBeenCalledWith(
+      'phc_key',
+      expect.objectContaining({
+        host: 'https://posthog.example.test',
+        bootstrap: { distinctId: ANONYMOUS_ID, isIdentifiedId: false },
+        captureAppLifecycleEvents: false,
+        capturePushNotificationOpened: false,
+        capturePushNotificationSubscriptions: false,
+        disableSurveys: true,
+        enableSessionReplay: false,
+        errorTracking: { autocapture: false },
+        defaultOptIn: false,
+        personProfiles: 'identified_only',
+        preloadFeatureFlags: false,
+        setDefaultPersonProperties: false,
+      }),
+    );
+  });
+});
+
+describe('native adapter composed with analytics core', () => {
+  it('opts out and clears the persisted provider queue when consent is withdrawn', async () => {
+    const posthog = createMockClient();
+    const transport = new PostHogNativeTransport<ProductEvent>(posthog.client);
+    const clearPending = vi.spyOn(transport, 'clearPending');
+    const analytics = new AnalyticsClient<ProductEvent>({
+      context,
+      allowlist: { onboarding_started: ['source'] },
+      transport,
+      uuidFactory: () => ANONYMOUS_ID,
+      flushBatchSize: 100,
+      flushIntervalMs: 60_000,
+      development: false,
+    });
+
+    analytics.setConsent('granted');
+    analytics.capture({ name: 'onboarding_started', properties: { source: 'organic' } });
+    await analytics.flush();
+    expect(posthog.queue).toEqual(['onboarding_started']);
+
+    analytics.setConsent('denied');
+    await vi.waitFor(() => {
+      expect(posthog.queue).toEqual([]);
+    });
+
+    expect(clearPending).toHaveBeenCalledOnce();
+    expect(posthog.optOut).toHaveBeenCalledOnce();
+    expect(posthog.setPersistedProperty.mock.calls).toEqual([
+      ['queue', []],
+      ['ai_queue', []],
+      ['ai_capture_queue', []],
+      ['logs_queue', []],
+    ]);
+  });
+
+  it('drops before consent and transports only allowlisted, scrubbed properties after opt-in', async () => {
+    const posthog = createMockClient();
+    const allowlist = {
+      onboarding_started: ['source', 'contact'],
+    } as const satisfies EventAllowlist<ProductEvent>;
+    const analytics = new AnalyticsClient<ProductEvent>({
+      context,
+      allowlist,
+      transport: new PostHogNativeTransport(posthog.client),
+      uuidFactory: () => ANONYMOUS_ID,
+      flushBatchSize: 100,
+      flushIntervalMs: 60_000,
+      development: false,
+    });
+
+    analytics.capture({ name: 'onboarding_started', properties: { source: 'organic' } });
+    await analytics.flush();
+    analytics.setConsent('denied');
+    analytics.capture({ name: 'onboarding_started', properties: { source: 'invite' } });
+    await analytics.flush();
+    expect(posthog.capture).not.toHaveBeenCalled();
+
+    analytics.setConsent('granted');
+    analytics.capture({
+      name: 'onboarding_started',
+      properties: {
+        source: 'organic',
+        contact: 'person@example.com',
+        unlisted: 'must not arrive',
+      },
+    } as ProductEvent);
+    await analytics.flush();
+
+    expect(posthog.capture).toHaveBeenCalledOnce();
+    expect(posthog.capture).toHaveBeenCalledWith(
+      'onboarding_started',
+      {
+        source: 'organic',
+        contact: '[redacted]',
+        ...context,
+      },
+      expect.any(Object),
+    );
+  });
+});

package/src/index.ts

@@ -0,0 +1,303 @@
+import type { PostHogOptions, PostHogPersistedProperty } from 'posthog-react-native';
+
+import type {
+  AnalyticsEnvelope,
+  AnalyticsEvent,
+  CaptureEnvelope,
+  Transport,
+} from '@baukit/analytics-core';
+
+/** Structural surface used so tests do not require a React Native runtime. */
+export interface PostHogNativeClient {
+  capture(
+    event: string,
+    properties?: Readonly<Record<string, unknown>>,
+    options?: { readonly timestamp?: Date },
+  ): unknown;
+  identify(distinctId: string, traits?: Readonly<Record<string, unknown>>): unknown;
+  alias(alias: string): unknown;
+  reset(): unknown;
+  optIn(): Promise<void> | void;
+  optOut(): Promise<void> | void;
+  setPersistedProperty(key: `${PostHogPersistedProperty}`, value: unknown): void;
+}
+
+type GuardedPostHogNativeOption =
+  | 'bootstrap'
+  | 'captureAppLifecycleEvents'
+  | 'capturePushNotificationOpened'
+  | 'capturePushNotificationSubscriptions'
+  | 'disableSurveys'
+  | 'enableSessionReplay'
+  | 'errorTracking'
+  | 'host'
+  | 'personProfiles'
+  | 'preloadFeatureFlags'
+  | 'setDefaultPersonProperties'
+  | 'defaultOptIn';
+
+export type PostHogNativeInitOptions = Omit<PostHogOptions, GuardedPostHogNativeOption>;
+
+export type PostHogNativeInitializer = (
+  apiKey: string,
+  options: PostHogOptions,
+) => PostHogNativeClient | Promise<PostHogNativeClient>;
+
+export interface PostHogNativeTransportConfig {
+  readonly apiKey: string;
+  /** Absolute URL of the product's self-hosted PostHog instance. */
+  readonly apiHost: string;
+  readonly options?: PostHogNativeInitOptions;
+  readonly initializer?: PostHogNativeInitializer;
+  readonly onError?: (error: unknown) => void;
+}
+
+type ClientFactory = (
+  firstEnvelope: AnalyticsEnvelope,
+) => PostHogNativeClient | Promise<PostHogNativeClient>;
+
+const PENDING_QUEUE_KEYS: readonly `${PostHogPersistedProperty}`[] = [
+  'queue',
+  'ai_queue',
+  'ai_capture_queue',
+  'logs_queue',
+];
+
+function requireNonEmpty(name: string, value: string): string {
+  const normalized = value.trim();
+  if (normalized.length === 0) {
+    throw new TypeError(`${name} must not be empty`);
+  }
+  return normalized;
+}
+
+function requireApiHost(value: string): string {
+  const apiHost = requireNonEmpty('apiHost', value).replace(/\/+$/, '');
+  if (!/^https?:\/\/[^\s/]+(?:\/.*)?$/u.test(apiHost)) {
+    throw new TypeError('apiHost must be an absolute http(s) URL');
+  }
+  return apiHost;
+}
+
+function initialIdentity(envelope: AnalyticsEnvelope): {
+  readonly distinctId: string;
+  readonly isIdentifiedId: boolean;
+} {
+  if (envelope.type === 'capture') {
+    return envelope.user_id === undefined
+      ? { distinctId: envelope.anonymous_id, isIdentifiedId: false }
+      : { distinctId: envelope.user_id, isIdentifiedId: true };
+  }
+  if (envelope.type === 'reset') {
+    return envelope.previous_user_id === undefined
+      ? { distinctId: envelope.previous_anonymous_id, isIdentifiedId: false }
+      : { distinctId: envelope.previous_user_id, isIdentifiedId: true };
+  }
+  return { distinctId: envelope.anonymous_id, isIdentifiedId: false };
+}
+
+function captureProperties<E extends AnalyticsEvent>(
+  envelope: CaptureEnvelope<E>,
+): Readonly<Record<string, unknown>> {
+  return {
+    ...envelope.event.properties,
+    schema_version: envelope.event.schema_version,
+    app: envelope.event.app,
+    app_version: envelope.event.app_version,
+    platform: envelope.event.platform,
+    environment: envelope.event.environment,
+    locale: envelope.event.locale,
+  };
+}
+
+async function defaultInitializer(
+  apiKey: string,
+  options: PostHogOptions,
+): Promise<PostHogNativeClient> {
+  const posthogModule = await import('posthog-react-native');
+  return new posthogModule.PostHog(apiKey, options);
+}
+
+/** Translates privacy-checked core envelopes to a PostHog React Native client. */
+export class PostHogNativeTransport<
+  E extends AnalyticsEvent = AnalyticsEvent,
+> implements Transport<E> {
+  readonly #clientFactory: ClientFactory;
+  readonly #onError: ((error: unknown) => void) | undefined;
+  #client: Promise<PostHogNativeClient> | undefined;
+  #clearGeneration = 0;
+  #clearRequired = false;
+  #clearOperation: Promise<void> | undefined;
+  #providerOptedOut = true;
+
+  public constructor(
+    client: PostHogNativeClient | ClientFactory,
+    onError?: (error: unknown) => void,
+  ) {
+    this.#clientFactory = typeof client === 'function' ? client : () => client;
+    this.#onError = onError;
+  }
+
+  /** Provider failures are contained and never reject into application code. */
+  public async send(envelopes: readonly AnalyticsEnvelope<E>[]): Promise<void> {
+    if (envelopes.length === 0) {
+      return;
+    }
+
+    const generation = this.#clearGeneration;
+    let client: PostHogNativeClient;
+    try {
+      client = await this.#getClient(envelopes[0] as AnalyticsEnvelope);
+    } catch (error: unknown) {
+      this.#reportError(error);
+      return;
+    }
+
+    await this.#clearOperation;
+    if (generation !== this.#clearGeneration) {
+      return;
+    }
+    if (this.#clearRequired) {
+      await this.#purgeClient(client);
+      if (generation !== this.#clearGeneration) {
+        return;
+      }
+      this.#clearRequired = false;
+    }
+    if (!(await this.#optIn(client))) {
+      return;
+    }
+
+    for (const envelope of envelopes) {
+      if (generation !== this.#clearGeneration) {
+        return;
+      }
+      try {
+        await this.#dispatch(client, envelope);
+      } catch (error: unknown) {
+        this.#reportError(error);
+      }
+    }
+  }
+
+  /** Opts PostHog out and purges every persisted provider queue. */
+  public clearPending(): Promise<void> {
+    this.#clearGeneration += 1;
+    this.#clearRequired = true;
+    this.#providerOptedOut = true;
+    const client = this.#client;
+    if (client === undefined) {
+      return Promise.resolve();
+    }
+
+    const generation = this.#clearGeneration;
+    const operation = client
+      .then(async (resolvedClient) => {
+        await this.#purgeClient(resolvedClient);
+        if (generation === this.#clearGeneration) {
+          this.#clearRequired = false;
+        }
+      })
+      .catch((error: unknown) => {
+        this.#reportError(error);
+      })
+      .finally(() => {
+        if (this.#clearOperation === operation) {
+          this.#clearOperation = undefined;
+        }
+      });
+    this.#clearOperation = operation;
+    return operation;
+  }
+
+  #getClient(firstEnvelope: AnalyticsEnvelope): Promise<PostHogNativeClient> {
+    this.#client ??= Promise.resolve(this.#clientFactory(firstEnvelope));
+    return this.#client;
+  }
+
+  async #dispatch(client: PostHogNativeClient, envelope: AnalyticsEnvelope<E>): Promise<void> {
+    switch (envelope.type) {
+      case 'capture':
+        await Promise.resolve(
+          client.capture(envelope.event.name, captureProperties(envelope), {
+            timestamp: new Date(envelope.captured_at),
+          }),
+        );
+        break;
+      case 'identify':
+        await Promise.resolve(client.identify(envelope.user_id, envelope.traits));
+        break;
+      case 'alias':
+        await Promise.resolve(client.alias(envelope.user_id));
+        break;
+      case 'reset':
+        await Promise.resolve(client.reset());
+        break;
+    }
+  }
+
+  async #optIn(client: PostHogNativeClient): Promise<boolean> {
+    if (!this.#providerOptedOut) {
+      return true;
+    }
+    try {
+      await Promise.resolve(client.optIn());
+      this.#providerOptedOut = false;
+      return true;
+    } catch (error: unknown) {
+      this.#reportError(error);
+      return false;
+    }
+  }
+
+  async #purgeClient(client: PostHogNativeClient): Promise<void> {
+    try {
+      await Promise.resolve(client.optOut());
+    } catch (error: unknown) {
+      this.#reportError(error);
+    }
+    for (const key of PENDING_QUEUE_KEYS) {
+      try {
+        client.setPersistedProperty(key, []);
+      } catch (error: unknown) {
+        this.#reportError(error);
+      }
+    }
+  }
+
+  #reportError(error: unknown): void {
+    try {
+      this.#onError?.(error);
+    } catch {
+      // Provider diagnostics must not affect the application journey.
+    }
+  }
+}
+
+/** Creates a lazy, safely configured PostHog React Native transport. */
+export function createPostHogNativeTransport<E extends AnalyticsEvent = AnalyticsEvent>(
+  config: PostHogNativeTransportConfig,
+): PostHogNativeTransport<E> {
+  const apiKey = requireNonEmpty('apiKey', config.apiKey);
+  const apiHost = requireApiHost(config.apiHost);
+  const initializer = config.initializer ?? defaultInitializer;
+
+  return new PostHogNativeTransport<E>((firstEnvelope) => {
+    const options: PostHogOptions = {
+      ...config.options,
+      host: apiHost,
+      bootstrap: initialIdentity(firstEnvelope),
+      captureAppLifecycleEvents: false,
+      capturePushNotificationOpened: false,
+      capturePushNotificationSubscriptions: false,
+      disableSurveys: true,
+      enableSessionReplay: false,
+      errorTracking: { autocapture: false },
+      defaultOptIn: false,
+      personProfiles: 'identified_only',
+      preloadFeatureFlags: false,
+      setDefaultPersonProperties: false,
+    };
+    return initializer(apiKey, options);
+  }, config.onError);
+}

package/src/storage.test.ts

@@ -0,0 +1,114 @@
+import { AnalyticsClient, analyticsStorageKeys } from '@baukit/analytics-core';
+import { describe, expect, it, vi } from 'vitest';
+
+import { HydratedAnalyticsStorage, type AsyncKeyValueStorage } from './storage.js';
+
+const keys = analyticsStorageKeys('app');
+const persistentKeys = [keys.anonymousId, keys.userId, keys.aliasedUserId];
+const ANONYMOUS_ID = '00000000-0000-4000-8000-000000000001';
+
+class MemoryPersistence implements AsyncKeyValueStorage {
+  readonly values = new Map<string, string>();
+  readonly failingReads = new Set<string>();
+  failWrites = false;
+
+  getItem(key: string): Promise<string | null> {
+    if (this.failingReads.has(key)) return Promise.reject(new Error('read failed'));
+    return Promise.resolve(this.values.get(key) ?? null);
+  }
+
+  setItem(key: string, value: string): Promise<void> {
+    if (this.failWrites) return Promise.reject(new Error('write failed'));
+    this.values.set(key, value);
+    return Promise.resolve();
+  }
+
+  removeItem(key: string): Promise<void> {
+    if (this.failWrites) return Promise.reject(new Error('write failed'));
+    this.values.delete(key);
+    return Promise.resolve();
+  }
+}
+
+describe('HydratedAnalyticsStorage', () => {
+  it('hydrates only the persistent keys that hold a value', async () => {
+    const persistence = new MemoryPersistence();
+    persistence.values.set(keys.anonymousId, ANONYMOUS_ID);
+    persistence.values.set(keys.consent, 'granted');
+
+    const storage = await HydratedAnalyticsStorage.load({ persistence, persistentKeys });
+
+    expect(storage.getItem(keys.anonymousId)).toBe(ANONYMOUS_ID);
+    expect(storage.getItem(keys.userId)).toBeUndefined();
+    expect(storage.getItem(keys.consent)).toBeUndefined();
+  });
+
+  it('keeps the keys that load when another key fails to read', async () => {
+    const persistence = new MemoryPersistence();
+    persistence.values.set(keys.anonymousId, ANONYMOUS_ID);
+    persistence.values.set(keys.userId, 'user');
+    persistence.failingReads.add(keys.userId);
+
+    const storage = await HydratedAnalyticsStorage.load({ persistence, persistentKeys });
+
+    expect(storage.getItem(keys.anonymousId)).toBe(ANONYMOUS_ID);
+    expect(storage.getItem(keys.userId)).toBeUndefined();
+  });
+
+  it('writes persistent keys through and keeps other keys in memory', async () => {
+    const persistence = new MemoryPersistence();
+    const storage = await HydratedAnalyticsStorage.load({ persistence, persistentKeys });
+
+    storage.setItem(keys.userId, 'user');
+    storage.setItem(keys.consent, 'granted');
+    await Promise.resolve();
+
+    expect(storage.getItem(keys.consent)).toBe('granted');
+    expect(persistence.values.get(keys.userId)).toBe('user');
+    expect(persistence.values.has(keys.consent)).toBe(false);
+
+    storage.removeItem(keys.userId);
+    await Promise.resolve();
+    expect(storage.getItem(keys.userId)).toBeUndefined();
+    expect(persistence.values.has(keys.userId)).toBe(false);
+  });
+
+  it('keeps the in-memory value when a write fails or throws', async () => {
+    const persistence = new MemoryPersistence();
+    const storage = await HydratedAnalyticsStorage.load({ persistence, persistentKeys });
+    persistence.failWrites = true;
+
+    storage.setItem(keys.userId, 'user');
+    expect(storage.getItem(keys.userId)).toBe('user');
+
+    vi.spyOn(persistence, 'removeItem').mockImplementation(() => {
+      throw new Error('synchronous failure');
+    });
+    expect(() => {
+      storage.removeItem(keys.userId);
+    }).not.toThrow();
+    expect(storage.getItem(keys.userId)).toBeUndefined();
+  });
+
+  it('restores the anonymous identity for a new analytics client', async () => {
+    const persistence = new MemoryPersistence();
+    const first = new AnalyticsClient({
+      context: {
+        schema_version: 1,
+        app: 'example-native',
+        app_version: '1.0.0',
+        platform: 'native',
+        environment: 'test',
+        locale: 'en-GB',
+      },
+      allowlist: {},
+      storageKeyPrefix: 'app',
+      uuidFactory: () => ANONYMOUS_ID,
+      storage: await HydratedAnalyticsStorage.load({ persistence, persistentKeys }),
+    });
+    await Promise.resolve();
+
+    const restored = await HydratedAnalyticsStorage.load({ persistence, persistentKeys });
+    expect(restored.getItem(keys.anonymousId)).toBe(first.anonymousId);
+  });
+});

package/src/storage.ts

@@ -0,0 +1,80 @@
+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 class HydratedAnalyticsStorage implements AnalyticsStorage {
+  readonly #values: Map<string, string>;
+  readonly #persistence: AsyncKeyValueStorage;
+  readonly #persistentKeys: ReadonlySet<string>;
+
+  private constructor(
+    options: HydratedAnalyticsStorageOptions,
+    entries: readonly (readonly [string, string])[],
+  ) {
+    this.#persistence = options.persistence;
+    this.#persistentKeys = new Set(options.persistentKeys);
+    this.#values = new Map(entries);
+  }
+
+  public static async load(
+    options: HydratedAnalyticsStorageOptions,
+  ): Promise<HydratedAnalyticsStorage> {
+    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] as const];
+    });
+    return new HydratedAnalyticsStorage(options, entries);
+  }
+
+  public getItem(key: string): string | undefined {
+    return this.#values.get(key);
+  }
+
+  public setItem(key: string, value: string): void {
+    this.#values.set(key, value);
+    if (!this.#persistentKeys.has(key)) return;
+    ignoreFailure(() => this.#persistence.setItem(key, value));
+  }
+
+  public removeItem(key: string): void {
+    this.#values.delete(key);
+    if (!this.#persistentKeys.has(key)) return;
+    ignoreFailure(() => this.#persistence.removeItem(key));
+  }
+}
+
+async function readOrAbsent(
+  persistence: AsyncKeyValueStorage,
+  key: string,
+): Promise<string | undefined> {
+  try {
+    return (await persistence.getItem(key)) ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function ignoreFailure(write: () => Promise<void>): void {
+  try {
+    void write().catch(() => undefined);
+  } catch {
+    return;
+  }
+}