pulse-updates 1.1.1 → 1.2.0

package/src/decisions.ts

@@ -0,0 +1,179 @@
+export type DecisionChannel = 'in_app' | 'encore' | 'replio' | 'email' | 'push' | 'sms' | 'whatsapp' | 'webhook';
+export type DecisionOutcome = 'pending' | 'delivered' | 'dismissed' | 'accepted' | 'converted' | 'failed';
+
+export interface DecisionContext {
+  userId?: string;
+  deviceId?: string;
+  platform?: string;
+  appVersion?: string;
+  country?: string;
+  language?: string;
+  osVersion?: string;
+  attributes?: Record<string, string>;
+}
+
+export interface DecisionAction { kind: string; [key: string]: unknown }
+
+export interface PulseDecision {
+  decisionId: string;
+  replayed: boolean;
+  execute: boolean;
+  mode: 'shadow' | 'live' | string;
+  verdict: string;
+  reasonCode: string;
+  policyKey?: string | null;
+  policyVersion?: number | null;
+  action?: DecisionAction | null;
+}
+
+export interface DecisionHandlerResult {
+  outcome?: DecisionOutcome;
+  metadata?: Record<string, unknown>;
+}
+
+export type DecisionHandler = (
+  action: DecisionAction,
+  decision: PulseDecision,
+) => void | DecisionHandlerResult | Promise<void | DecisionHandlerResult>;
+
+export interface PulseDecisionClientOptions {
+  apiUrl: string;
+  appSlug: string;
+  getContext: () => DecisionContext | Promise<DecisionContext>;
+  fetch?: typeof globalThis.fetch;
+  timeoutMs?: number;
+  /** Safe default. User-facing execution needs an explicit per-app opt-in. */
+  executionMode?: 'shadow-only' | 'allow-live';
+  handlers?: Record<string, DecisionHandler>;
+  onError?: (error: unknown) => void;
+}
+
+export interface DecideOptions {
+  channel?: DecisionChannel;
+  idempotencyKey?: string;
+  attributes?: Record<string, string>;
+}
+
+export interface PulseDecisionClient {
+  decide(trigger: string, options?: DecideOptions): Promise<PulseDecision | null>;
+  reportOutcome(decisionId: string, outcome: DecisionOutcome, metadata?: Record<string, unknown>): Promise<boolean>;
+}
+
+/** Generic decision protocol. Product-specific action handlers remain in each app. */
+export function createPulseDecisionClient(options: PulseDecisionClientOptions): PulseDecisionClient {
+  const fetcher = options.fetch ?? globalThis.fetch;
+  const base = options.apiUrl.replace(/\/+$/, '');
+  const slug = encodeURIComponent(options.appSlug);
+  const timeoutMs = Math.max(250, options.timeoutMs ?? 3_000);
+  const executionMode = options.executionMode ?? 'shadow-only';
+
+  const reportOutcome = async (
+    decisionId: string,
+    outcome: DecisionOutcome,
+    metadata?: Record<string, unknown>,
+  ): Promise<boolean> => {
+    try {
+      const response = await timedFetch(fetcher,
+        `${base}/pulse/decisions/${slug}/${encodeURIComponent(decisionId)}/outcome`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ outcome, ...(metadata ? { metadata } : {}) }),
+        }, timeoutMs);
+      return response.ok;
+    } catch (error) {
+      options.onError?.(error);
+      return false;
+    }
+  };
+
+  const decide = async (trigger: string, request: DecideOptions = {}): Promise<PulseDecision | null> => {
+    try {
+      const context = await options.getContext();
+      const response = await timedFetch(fetcher, `${base}/pulse/decisions/${slug}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          ...context,
+          attributes: { ...(context.attributes ?? {}), ...(request.attributes ?? {}) },
+          trigger,
+          channel: request.channel ?? 'in_app',
+          idempotencyKey: request.idempotencyKey ?? randomKey(),
+        }),
+      }, timeoutMs);
+      if (!response.ok) throw new Error(`Pulse decision HTTP ${response.status}`);
+
+      const decision = parseDecision(await response.json());
+      if (!decision.execute) return decision;
+      if (executionMode !== 'allow-live') {
+        void reportOutcome(decision.decisionId, 'failed', { reason: 'client_executor_not_armed' });
+        return decision;
+      }
+
+      const action = decision.action;
+      const handler = action?.kind ? options.handlers?.[action.kind] : undefined;
+      if (!action || !handler) {
+        void reportOutcome(decision.decisionId, 'failed', {
+          reason: 'unknown_action_kind',
+          kind: action?.kind ?? null,
+        });
+        return decision;
+      }
+
+      try {
+        const result = await handler(action, decision);
+        void reportOutcome(decision.decisionId, result?.outcome ?? 'accepted', result?.metadata);
+      } catch (error) {
+        options.onError?.(error);
+        void reportOutcome(decision.decisionId, 'failed', { reason: 'handler_failed' });
+      }
+      return decision;
+    } catch (error) {
+      options.onError?.(error);
+      return null;
+    }
+  };
+
+  return { decide, reportOutcome };
+}
+
+function parseDecision(raw: unknown): PulseDecision {
+  if (!raw || typeof raw !== 'object') throw new Error('Malformed Pulse decision');
+  const value = raw as Record<string, unknown>;
+  if (typeof value.decisionId !== 'string' || typeof value.execute !== 'boolean' ||
+      typeof value.mode !== 'string' || typeof value.verdict !== 'string' ||
+      typeof value.reasonCode !== 'string') throw new Error('Malformed Pulse decision');
+  const action = value.action;
+  if (action != null && (typeof action !== 'object' ||
+      typeof (action as Record<string, unknown>).kind !== 'string')) {
+    throw new Error('Malformed Pulse action');
+  }
+  return {
+    decisionId: value.decisionId,
+    replayed: value.replayed === true,
+    execute: value.execute,
+    mode: value.mode,
+    verdict: value.verdict,
+    reasonCode: value.reasonCode,
+    policyKey: typeof value.policyKey === 'string' ? value.policyKey : null,
+    policyVersion: typeof value.policyVersion === 'number' ? value.policyVersion : null,
+    action: (action as DecisionAction | null | undefined) ?? null,
+  };
+}
+
+async function timedFetch(
+  fetcher: typeof globalThis.fetch,
+  url: string,
+  init: RequestInit,
+  timeoutMs: number,
+): Promise<Response> {
+  const controller = typeof AbortController !== 'undefined' ? new AbortController() : null;
+  const timer = controller ? setTimeout(() => controller.abort(), timeoutMs) : null;
+  try { return await fetcher(url, { ...init, signal: controller?.signal }); }
+  finally { if (timer) clearTimeout(timer); }
+}
+
+function randomKey(): string {
+  const cryptoLike = globalThis.crypto as { randomUUID?: () => string } | undefined;
+  if (typeof cryptoLike?.randomUUID === 'function') return cryptoLike.randomUUID();
+  return `moment-${Date.now()}-${Math.random().toString(36).slice(2, 14)}`;
+}

package/src/index.ts

@@ -5,3 +5,4 @@ export { initializeAssetResolver, updateLocalAssets } from './assetResolver';
 export * from './config';
 export * from './track';
 export * from './init';
+export * from './decisions';

package/src/init.ts

@@ -30,8 +30,21 @@ import {
   type ConfigContext,
   type ConfigStorage,
   type ConfigValue,
+  type ConfigSignature,
+  getConfigInfo,
+  getConfigBoolean,
+  getConfigNumber,
+  getConfigString,
+  getConfigJson,
 } from './config';
-import { configureTracking } from './track';
+import {
+  configureTracking,
+  disposeTracking,
+  flushEvents,
+  getTrackingInfo,
+  track,
+  type TrackedEventInput,
+} from './track';
 
 export interface InitPulseOptions {
   /** Where Pulse lives, e.g. https://pulse.example.com — no path. */
@@ -53,6 +66,9 @@ export interface InitPulseOptions {
   /** The store build, e.g. "5.2.0". Needed to target a rollout at a version. */
   appVersion?: string;
 
+  /** Locale override. When omitted the installed RN locale adapter is detected. */
+  language?: string;
+
   /**
    * A stable id for this install. Left out, one is minted and persisted.
    *
@@ -68,6 +84,19 @@ export interface InitPulseOptions {
   /** Attributes a rule can target — a plan, a storefront. Keep them few and stable. */
   getUserAttributes?: () => Record<string, string> | undefined;
 
+  /** Initial analytics consent or a live consent reader. Defaults to granted for compatibility. */
+  analyticsConsent?: boolean | (() => boolean);
+
+  /** Privacy guardrails applied to every track() call. */
+  eventPropertyAllowlist?: readonly string[];
+  redactEventProperties?: readonly string[];
+
+  /** Signed config uses the same Ed25519 public key as OTA updates. */
+  signingPublicKey?: string;
+  signingKeyId?: string;
+  requireConfigSignature?: boolean;
+  verifyConfigSignature?: (canonicalPayload: string, signature: ConfigSignature) => boolean | Promise<boolean>;
+
   /** Foreground poll interval for the config. 0 disables it; launch and resume still fetch. */
   pollIntervalMs?: number;
 
@@ -85,39 +114,108 @@ export interface InitPulseOptions {
 
 const DEVICE_ID_KEY = 'pulse.device-id';
 
+export interface PulseHealth {
+  appSlug: string;
+  deviceId: string;
+  config: ReturnType<typeof getConfigInfo>;
+  events: ReturnType<typeof getTrackingInfo>;
+  analyticsConsent: boolean;
+}
+
+export interface PulseClient {
+  deviceId: string;
+  configUrl: string;
+  trackUrl: string;
+  track: (event: string, props?: TrackedEventInput['props'], time?: Date) => void;
+  flush: () => Promise<number>;
+  setUser: (userId?: string, attributes?: Record<string, string>) => void;
+  clearUser: () => void;
+  setAnalyticsConsent: (granted: boolean) => void;
+  resetInstallId: () => string;
+  health: () => PulseHealth;
+  config: {
+    boolean: typeof getConfigBoolean;
+    number: typeof getConfigNumber;
+    string: typeof getConfigString;
+    json: typeof getConfigJson;
+    refresh: typeof fetchConfig;
+  };
+  dispose: () => Promise<void>;
+}
+
+export interface AsyncPulseStorage {
+  getItem(key: string): Promise<string | null>;
+  setItem(key: string, value: string): Promise<void>;
+}
+
+let activeClient: PulseClient | null = null;
+let stopActiveRefresh: (() => void) | null = null;
+
 /** Wires config and events, and returns the context the two share. */
-export function initPulse(opts: InitPulseOptions): { deviceId: string; configUrl: string; trackUrl: string } {
+export function initPulse(opts: InitPulseOptions): PulseClient {
+  // Reconfiguration is synchronous. Calling the old async dispose without awaiting
+  // it lets its eventual flush tear down the brand-new tracker — exactly the race a
+  // fast app switch or test setup triggers. Persist the old outbox, stop its refresh,
+  // then configure the new app in one uninterrupted turn.
+  stopActiveRefresh?.();
+  disposeTracking();
+  activeClient = null;
+  stopActiveRefresh = null;
   const base = opts.apiUrl.replace(/\/+$/, '');
   const slug = opts.appSlug.trim();
   const configUrl = `${base}/pulse/config/${slug}`;
   const trackUrl = `${base}/pulse/track/${slug}`;
 
-  const deviceId = opts.deviceId?.trim() || resolveDeviceId(opts.storage);
+  const deviceStorageKey = `pulse.${slug}.device-id`;
+  let deviceId = opts.deviceId?.trim() || resolveDeviceId(opts.storage, deviceStorageKey);
   const platform = detectPlatform();
   const osVersion = detectOsVersion();
+  const appVersion = opts.appVersion ?? detectAppVersion();
+  const language = opts.language ?? detectLanguage();
+  let userId: string | undefined;
+  let userAttributes: Record<string, string> | undefined;
+  let consentOverride: boolean | undefined = typeof opts.analyticsConsent === 'boolean'
+    ? opts.analyticsConsent
+    : undefined;
+
+  const hasConsent = (): boolean => consentOverride ??
+    (typeof opts.analyticsConsent === 'function' ? opts.analyticsConsent() : true);
 
   const getContext = (): ConfigContext => ({
     platform,
     osVersion,
-    appVersion: opts.appVersion,
+    appVersion,
+    language,
     deviceId,
-    userId: opts.getUserId?.(),
-    userAttributes: opts.getUserAttributes?.(),
+    userId: userId ?? opts.getUserId?.(),
+    userAttributes: userAttributes ?? opts.getUserAttributes?.(),
   });
 
   configureConfig({
     url: configUrl,
     defaults: opts.defaults,
     storage: opts.storage,
+    storageKey: `pulse.${slug}.config.v1`,
     getContext,
     pollIntervalMs: opts.pollIntervalMs,
     onError: opts.onError,
+    signingPublicKey: opts.signingPublicKey,
+    signingKeyId: opts.signingKeyId,
+    requireSignature: opts.requireConfigSignature,
+    verifySignature: opts.verifyConfigSignature ??
+      (opts.requireConfigSignature && !opts.signingPublicKey ? verifyWithNativeKey : undefined),
   });
 
   configureTracking({
     url: trackUrl,
     getContext,
     flushIntervalMs: opts.flushIntervalMs,
+    storage: opts.storage,
+    storageKey: `pulse.${slug}.events.v1`,
+    hasConsent,
+    propertyAllowlist: opts.eventPropertyAllowlist,
+    redactProperties: opts.redactEventProperties,
+    appState: opts.appState,
     onIgnored: opts.onIgnoredEvents,
     onError: opts.onError,
   });
@@ -127,7 +225,7 @@ export function initPulse(opts: InitPulseOptions): { deviceId: string; configUrl
   // simply does not match this install — which reads as "the rollout did nothing".
   // Without storage the id is new on every launch, so the arm is re-dealt each time
   // and no experiment can mean anything.
-  if (!opts.appVersion) {
+  if (!appVersion) {
     opts.onError?.(new Error(
       'Pulse: no appVersion given — version targeting and version slices will not match this install'));
   }
@@ -140,9 +238,77 @@ export function initPulse(opts: InitPulseOptions): { deviceId: string; configUrl
   // the first response is the launch that runs on defaults, and defaults are the
   // off position of every flag.
   void fetchConfig();
-  startConfigAutoRefresh(opts.appState);
+  const stopRefresh = startConfigAutoRefresh(opts.appState);
+
+  const client: PulseClient = {
+    get deviceId() { return deviceId; },
+    configUrl,
+    trackUrl,
+    track,
+    flush: flushEvents,
+    setUser: (nextUserId, attributes) => {
+      userId = nextUserId?.trim() || undefined;
+      userAttributes = sanitizeAttributes(attributes);
+    },
+    clearUser: () => {
+      userId = undefined;
+      userAttributes = undefined;
+    },
+    setAnalyticsConsent: (granted) => { consentOverride = granted; },
+    resetInstallId: () => {
+      deviceId = randomId();
+      try { opts.storage?.set(deviceStorageKey, deviceId); } catch { /* memory-only fallback */ }
+      return deviceId;
+    },
+    health: () => ({ appSlug: slug, deviceId, config: getConfigInfo(), events: getTrackingInfo(), analyticsConsent: hasConsent() }),
+    config: {
+      boolean: getConfigBoolean,
+      number: getConfigNumber,
+      string: getConfigString,
+      json: getConfigJson,
+      refresh: fetchConfig,
+    },
+    dispose: async () => {
+      stopRefresh();
+      if (activeClient !== client) return;
+      await flushEvents();
+      // Another init may have taken ownership while this network flush was pending.
+      if (activeClient === client) {
+        disposeTracking();
+        activeClient = null;
+        stopActiveRefresh = null;
+      }
+    },
+  };
+  activeClient = client;
+  stopActiveRefresh = stopRefresh;
+  return client;
+}
 
-  return { deviceId, configUrl, trackUrl };
+/**
+ * AsyncStorage-friendly one-call setup. It preloads only Pulse's three app-scoped
+ * records, then exposes the same synchronous hot-path API as initPulse.
+ */
+export async function initPulseAsync(
+  opts: Omit<InitPulseOptions, 'storage'> & { storage: AsyncPulseStorage },
+): Promise<PulseClient> {
+  const slug = opts.appSlug.trim();
+  const keys = [
+    `pulse.${slug}.device-id`,
+    `pulse.${slug}.config.v1`,
+    `pulse.${slug}.events.v1`,
+    DEVICE_ID_KEY,
+  ];
+  const loaded = await Promise.all(keys.map(async (key) => [key, await opts.storage.getItem(key)] as const));
+  const memory = new Map(loaded.filter((entry): entry is readonly [string, string] => entry[1] !== null));
+  const storage: ConfigStorage = {
+    getString: (key) => memory.get(key),
+    set: (key, value) => {
+      memory.set(key, value);
+      void opts.storage.setItem(key, value);
+    },
+  };
+  return initPulse({ ...opts, storage });
 }
 
 /**
@@ -152,20 +318,28 @@ export function initPulse(opts: InitPulseOptions): { deviceId: string; configUrl
  * arm is a hash of it, so every launch would be a fresh coin toss and no experiment
  * could mean anything. Said out loud through onError rather than hidden.
  */
-function resolveDeviceId(storage?: ConfigStorage): string {
+function resolveDeviceId(storage?: ConfigStorage, key = DEVICE_ID_KEY): string {
   if (!storage) return randomId();
 
   try {
-    const existing = storage.getString(DEVICE_ID_KEY);
+    const existing = storage.getString(key) ?? storage.getString(DEVICE_ID_KEY);
     if (existing) return existing;
     const minted = randomId();
-    storage.set(DEVICE_ID_KEY, minted);
+    storage.set(key, minted);
     return minted;
   } catch {
     return randomId();
   }
 }
 
+function sanitizeAttributes(attributes?: Record<string, string>): Record<string, string> | undefined {
+  if (!attributes) return undefined;
+  const clean = Object.fromEntries(Object.entries(attributes)
+    .filter(([key, value]) => key.trim() !== '' && typeof value === 'string')
+    .slice(0, 50));
+  return Object.keys(clean).length > 0 ? clean : undefined;
+}
+
 function randomId(): string {
   const bytes = new Uint8Array(16);
   const crypto = (globalThis as { crypto?: { getRandomValues?: (a: Uint8Array) => void } }).crypto;
@@ -208,3 +382,44 @@ function detectOsVersion(): string | undefined {
     return undefined;
   }
 }
+
+function detectAppVersion(): string | undefined {
+  try {
+    // Optional by design: most RN apps already carry this package, plain JS hosts do not.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const loaded = require('react-native-device-info') as { default?: { getVersion?: () => string }; getVersion?: () => string };
+    return loaded.default?.getVersion?.() ?? loaded.getVersion?.();
+  } catch {
+    return undefined;
+  }
+}
+
+async function verifyWithNativeKey(
+  canonicalPayload: string,
+  signature: ConfigSignature,
+): Promise<boolean> {
+  try {
+    // Kept lazy so init/config remain usable in Node, web and test hosts without RN.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const updates = require('./PulseUpdates') as {
+      verifyConfigSignatureAsync?: (payload: string, value: ConfigSignature) => Promise<boolean>;
+    };
+    return await updates.verifyConfigSignatureAsync?.(canonicalPayload, signature) ?? false;
+  } catch {
+    return false;
+  }
+}
+
+function detectLanguage(): string | undefined {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const localize = require('react-native-localize') as { getLocales?: () => Array<{ languageTag?: string }> };
+    return localize.getLocales?.()[0]?.languageTag;
+  } catch {
+    try {
+      return Intl.DateTimeFormat().resolvedOptions().locale;
+    } catch {
+      return undefined;
+    }
+  }
+}