pulse-updates 1.0.21 → 1.1.1

package/scripts/publish.mjs

@@ -447,6 +447,10 @@ function parseArgs() {
     options: {},
   };
 
+  // Positionals collect into `_`, which is how `experiment <key>` and
+  // `promote <key>` name their subject. Anything consumed as a flag's value is not one.
+  result.options._ = [];
+
   for (let i = 1; i < args.length; i++) {
     const arg = args[i];
     if (arg.startsWith('--')) {
@@ -458,6 +462,8 @@ function parseArgs() {
       } else {
         result.options[key] = true;
       }
+    } else {
+      result.options._.push(arg);
     }
   }
 
@@ -1101,6 +1107,174 @@ async function registerCapabilities(options) {
   logSuccess(`Capabilities registered (${nativeModules.length} native modules)`);
 }
 
+
+/**
+ * The experiments an app is running, and how their split is holding.
+ *
+ * The CLI half of the dashboard's list. It exists because the decisions an experiment
+ * produces — is it broken, has it won, ship the winner — happen in a terminal as often
+ * as in a browser, and the alternative was curl against an undocumented route.
+ */
+async function experiments(options) {
+  const { apiUrl, apiKey } = requireApi(options);
+
+  const res = await fetch(`${apiUrl}/api/apps/experiments`, { headers: { 'X-API-Key': apiKey } });
+  if (!res.ok) throw new Error(`Could not list experiments: ${res.status} ${await res.text()}`);
+
+  const { experiments: rows } = await res.json();
+  if (!rows?.length) {
+    log('No experiments yet.', colors.dim);
+    return;
+  }
+
+  for (const row of rows) {
+    const arms = JSON.parse(row.variants || '[]').map((v) => v.key).join(', ');
+    const seen = (row.exposure || []).reduce((sum, e) => sum + e.devices, 0);
+    log(`${colors.bright}${row.key}${colors.reset}  ${row.status}  [${arms}]  ${seen.toLocaleString()} installs`);
+    if (row.description) log(`  ${row.description}`, colors.dim);
+  }
+}
+
+/**
+ * What an experiment says, in the same words the dashboard uses.
+ *
+ * The verdict is the server's, not this script's: a CLI that judged the numbers itself
+ * would be a second opinion nobody asked for, and the first thing it would disagree with
+ * is the page a human just read.
+ */
+async function experimentSummary(key, options) {
+  if (!key) throw new Error('Name the experiment: pulse-updates experiment <key>');
+  const { apiUrl, apiKey } = requireApi(options);
+
+  const query = new URLSearchParams(
+    Object.entries({
+      asOf: options['as-of'],
+      platform: options.platform,
+    }).filter(([, v]) => Boolean(v))
+  ).toString();
+
+  const res = await fetch(
+    `${apiUrl}/api/apps/experiments/${encodeURIComponent(key)}/summary${query ? `?${query}` : ''}`,
+    { headers: { 'X-API-Key': apiKey } }
+  );
+  if (!res.ok) throw new Error(`Could not read ${key}: ${res.status} ${await res.text()}`);
+
+  const summary = await res.json();
+
+  log(`${colors.bright}${summary.key}${colors.reset}  ${summary.status}  (as of ${summary.asOf}${summary.slice ? `, ${summary.slice}` : ''})`);
+
+  if (summary.srm?.mismatch) {
+    logError('The split is not the one that was asked for — every number below is measuring that.');
+    for (const arm of summary.srm.arms) {
+      log(`  ${arm.variant}: ${arm.observed.toLocaleString()} vs ${Math.round(arm.expected).toLocaleString()} expected`, colors.dim);
+    }
+  }
+
+  log('');
+  log(summary.headline.sentence);
+  log('');
+
+  for (const effect of summary.effects) {
+    const size = effect.relative != null
+      ? `${(effect.relative * 100).toFixed(1)}%`
+      : `${(effect.absolute * 100).toFixed(1)}pt`;
+    const decisive = effect.isPrimary ? effect.significant : effect.significantAdjusted;
+    const mark = decisive ? (effect.better ? '+' : '-') : ' ';
+    log(`  ${mark} ${effect.label} · ${effect.variant}  ${size}${decisive ? '' : '  (noise)'}`);
+  }
+
+  if (summary.headline.winner) {
+    log('');
+    log(`  pulse-updates promote ${summary.key} --variant ${summary.headline.winner}`, colors.cyan);
+  }
+}
+
+/**
+ * Ship the arm that won: its values become the config, and the experiment ends.
+ *
+ * Prints the plan and asks, unless --yes. This writes production config for every
+ * install, and a confirmation that only names the arm confirms nothing — which keys move
+ * and what they move from is the question.
+ */
+async function promoteExperiment(key, options) {
+  if (!key) throw new Error('Name the experiment: pulse-updates promote <key> --variant <arm>');
+  const variant = options.variant;
+  if (!variant) throw new Error('Name the arm to promote: --variant <arm>');
+
+  const { apiUrl, apiKey } = requireApi(options);
+  const scope = options.scope || 'everyone';
+  const complete = !options['keep-running'];
+
+  const planQuery = new URLSearchParams({ variant, scope, complete: String(complete) }).toString();
+  const planRes = await fetch(
+    `${apiUrl}/api/apps/experiments/${encodeURIComponent(key)}/promotion?${planQuery}`,
+    { headers: { 'X-API-Key': apiKey } }
+  );
+
+  const plan = await planRes.json();
+  if (!planRes.ok) {
+    throw new Error(`${plan.error}${plan.hint ? `\n  ${plan.hint}` : ''}`);
+  }
+
+  log(`${colors.bright}Promoting ${plan.variant} of ${plan.experimentKey}${colors.reset}${scope === 'audience' ? ' (to the experiment audience)' : ''}`);
+  for (const row of plan.rows) {
+    log(`  ${row.key}: ${row.current ?? '—'} → ${row.next}  [${row.action}]`);
+  }
+  for (const warning of plan.warnings) log(`  ! ${warning}`, colors.yellow);
+
+  if (!options.yes) {
+    // Refused rather than prompted: a pipe has no stdin to answer with, and a config
+    // write that happens because nobody typed anything is the worst of both.
+    log('');
+    log('Re-run with --yes to write these values.', colors.cyan);
+    return;
+  }
+
+  const res = await fetch(`${apiUrl}/api/apps/experiments/${encodeURIComponent(key)}/promote`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', 'X-API-Key': apiKey },
+    body: JSON.stringify({ variant, scope, complete }),
+  });
+
+  const result = await res.json();
+  if (!res.ok) throw new Error(`${result.error}${result.hint ? `\n  ${result.hint}` : ''}`);
+
+  logSuccess(
+    `${result.variant} promoted — ${result.updated} key(s) written` +
+    (result.status === 'completed' ? ', experiment completed' : ', experiment still running')
+  );
+}
+
+/**
+ * The two things every experiment command needs, and the error that says where to put them.
+ *
+ * Deliberately not loadConfig: that one auto-detects the runtime version, the API URL
+ * and whether the app uses Hermes by reading native build files, which is right before a
+ * publish and is three lines of irrelevant chatter before reading a result.
+ */
+function requireApi(options) {
+  const file = (() => {
+    const configPath = path.join(process.cwd(), 'pulse.config.json');
+    try {
+      return fs.existsSync(configPath) ? JSON.parse(fs.readFileSync(configPath, 'utf8')) : {};
+    } catch {
+      return {};
+    }
+  })();
+
+  const apiUrl = options['api-url'] || process.env.PULSE_API_URL || file.apiUrl;
+  const apiKey = options['api-key'] || process.env.PULSE_API_KEY || file.apiKey;
+
+  if (!apiUrl) {
+    throw new Error('API URL is required. Set --api-url, PULSE_API_URL env, or apiUrl in pulse.config.json');
+  }
+  if (!apiKey) {
+    throw new Error('API key is required. Set --api-key, PULSE_API_KEY env, or apiKey in pulse.config.json');
+  }
+
+  return { apiUrl: apiUrl.replace(/\/+$/, ''), apiKey };
+}
+
 /**
  * Print a fresh signing keypair, with copy-paste config for the server and the app.
  */
@@ -1153,6 +1327,16 @@ ${colors.cyan}Options:${colors.reset}
   --message <msg>         Release message/notes
   --key-id <id>           Key id for keygen (default: auto-generated)
 
+${colors.cyan}Experiments:${colors.reset}
+  pulse-updates experiments                       List them, with the split each one got
+  pulse-updates experiment <key>                  What it says: the verdict and what moved
+      --platform <ios|android>                    Read one platform's slice of it
+      --as-of <YYYY-MM-DD>                        Replay the result as it stood that day
+  pulse-updates promote <key> --variant <arm>     Write the arm's values into the config
+      --scope audience                            As a rule for the audience it ran on
+      --keep-running                              Do not finish the experiment
+      --yes                                       Actually write (without it, prints the plan)
+
 ${colors.cyan}Configuration:${colors.reset}
   Options can be set via (in priority order):
   1. Command line options
@@ -1192,6 +1376,15 @@ async function main() {
       case 'register-capabilities':
         await registerCapabilities(options);
         break;
+      case 'experiments':
+        await experiments(options);
+        break;
+      case 'experiment':
+        await experimentSummary(options._?.[0], options);
+        break;
+      case 'promote':
+        await promoteExperiment(options._?.[0], options);
+        break;
       case 'keygen':
         keygen(options);
         break;

package/src/config.ts

@@ -288,6 +288,9 @@ export function startConfigAutoRefresh(appState?: {
   if (interval > 0) {
     stopPolling();
     pollTimer = setInterval(() => void fetchConfig(), interval);
+    // Node keeps a process alive for a pending interval; React Native does not care.
+    // Without this a CLI or a test that only imports the module never exits.
+    (pollTimer as unknown as { unref?: () => void }).unref?.();
   }
 
   return () => {

package/src/index.ts

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

package/src/init.ts

@@ -0,0 +1,210 @@
+/**
+ * One call to wire an app to Pulse.
+ *
+ * The three halves — updates, config, events — each have their own setup, and each
+ * one is a place to make a mistake that shows up as an empty chart weeks later: a
+ * config url that points at one app and a track url at another, an install with no
+ * stable id (so every launch looks like a new device and every arm is re-dealt), a
+ * context that forgets the app version (so an experiment cannot be aimed at a build).
+ * They are the same three facts every time, so they are asked for once.
+ *
+ * Everything it derives, it derives from the platform and only when the caller has
+ * not said otherwise:
+ *
+ *  - the urls, from the base url and the slug, which is what stops the two halves
+ *    from ever addressing different apps;
+ *  - platform and OS version, from React Native;
+ *  - the device id, minted and persisted on first launch — an app that has a stable
+ *    identifier of its own (the vendor id, an installation id) should pass it, and an
+ *    app that has none should not have to invent one to be measurable.
+ *
+ * Deliberately not automatic: the app version. Nothing here can read the store build
+ * reliably on both platforms, and a version guessed wrong aims a rollout at the wrong
+ * installs — a targeting bug that looks like a rollout that "did not work".
+ */
+
+import {
+  configureConfig,
+  fetchConfig,
+  startConfigAutoRefresh,
+  type ConfigContext,
+  type ConfigStorage,
+  type ConfigValue,
+} from './config';
+import { configureTracking } from './track';
+
+export interface InitPulseOptions {
+  /** Where Pulse lives, e.g. https://pulse.example.com — no path. */
+  apiUrl: string;
+
+  /** The app's slug in Pulse. Both urls are built from it. */
+  appSlug: string;
+
+  /** Values in force before the server has ever been reached. */
+  defaults?: Record<string, ConfigValue>;
+
+  /**
+   * Somewhere to keep the last good config and the device id. Without it both are
+   * memory-only: the config falls back to defaults after a restart, and — worse —
+   * the install gets a new id every launch, which re-deals its arm every launch.
+   */
+  storage?: ConfigStorage;
+
+  /** The store build, e.g. "5.2.0". Needed to target a rollout at a version. */
+  appVersion?: string;
+
+  /**
+   * A stable id for this install. Left out, one is minted and persisted.
+   *
+   * Worth passing when the app already has one the rest of its analytics uses: the
+   * arm is a hash of this value, and a metric joined on a different id is not
+   * slightly wrong, it is randomised.
+   */
+  deviceId?: string;
+
+  /** The signed-in account, read fresh on every request. Only user-level experiments use it. */
+  getUserId?: () => string | undefined;
+
+  /** Attributes a rule can target — a plan, a storefront. Keep them few and stable. */
+  getUserAttributes?: () => Record<string, string> | undefined;
+
+  /** Foreground poll interval for the config. 0 disables it; launch and resume still fetch. */
+  pollIntervalMs?: number;
+
+  /** How often queued events are sent. Default 10s. */
+  flushIntervalMs?: number;
+
+  /** App-state hook, so the config refreshes on return from background. */
+  appState?: { addEventListener: (type: 'change', handler: (state: string) => void) => { remove: () => void } };
+
+  /** Event keys the server did not recognise — a typo, or an event nobody declared. */
+  onIgnoredEvents?: (events: string[]) => void;
+
+  onError?: (error: unknown) => void;
+}
+
+const DEVICE_ID_KEY = 'pulse.device-id';
+
+/** Wires config and events, and returns the context the two share. */
+export function initPulse(opts: InitPulseOptions): { deviceId: string; configUrl: string; trackUrl: string } {
+  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 platform = detectPlatform();
+  const osVersion = detectOsVersion();
+
+  const getContext = (): ConfigContext => ({
+    platform,
+    osVersion,
+    appVersion: opts.appVersion,
+    deviceId,
+    userId: opts.getUserId?.(),
+    userAttributes: opts.getUserAttributes?.(),
+  });
+
+  configureConfig({
+    url: configUrl,
+    defaults: opts.defaults,
+    storage: opts.storage,
+    getContext,
+    pollIntervalMs: opts.pollIntervalMs,
+    onError: opts.onError,
+  });
+
+  configureTracking({
+    url: trackUrl,
+    getContext,
+    flushIntervalMs: opts.flushIntervalMs,
+    onIgnored: opts.onIgnoredEvents,
+    onError: opts.onError,
+  });
+
+  // The two fields nothing can derive, said out loud when they are missing. Both
+  // fail silently and late: without a version, every rule and slice that names one
+  // 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) {
+    opts.onError?.(new Error(
+      'Pulse: no appVersion given — version targeting and version slices will not match this install'));
+  }
+  if (!opts.storage && !opts.deviceId) {
+    opts.onError?.(new Error(
+      'Pulse: no storage and no deviceId — this install gets a new id every launch, which re-deals its arm'));
+  }
+
+  // Fetch now rather than on the first read: a launch that reads the config before
+  // the first response is the launch that runs on defaults, and defaults are the
+  // off position of every flag.
+  void fetchConfig();
+  startConfigAutoRefresh(opts.appState);
+
+  return { deviceId, configUrl, trackUrl };
+}
+
+/**
+ * The install's id: the one it already had, or a new one kept from now on.
+ *
+ * Without storage this is a new id every launch, which is worse than it looks — the
+ * 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 {
+  if (!storage) return randomId();
+
+  try {
+    const existing = storage.getString(DEVICE_ID_KEY);
+    if (existing) return existing;
+    const minted = randomId();
+    storage.set(DEVICE_ID_KEY, minted);
+    return minted;
+  } catch {
+    return randomId();
+  }
+}
+
+function randomId(): string {
+  const bytes = new Uint8Array(16);
+  const crypto = (globalThis as { crypto?: { getRandomValues?: (a: Uint8Array) => void } }).crypto;
+
+  if (crypto?.getRandomValues) {
+    crypto.getRandomValues(bytes);
+  } else {
+    // React Native without a crypto polyfill. Weaker, and only ever used to tell one
+    // install from another — never as a secret.
+    for (let i = 0; i < bytes.length; i++) bytes[i] = Math.floor(Math.random() * 256);
+  }
+
+  bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x40;
+  bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80;
+
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+/** React Native when it is there, and nothing invented when it is not. */
+function detectPlatform(): string | undefined {
+  try {
+    // Required lazily so the module stays importable from a plain Node script — the
+    // CLI and the tests both do that.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const rn = require('react-native') as { Platform?: { OS?: string } };
+    return rn?.Platform?.OS;
+  } catch {
+    return undefined;
+  }
+}
+
+function detectOsVersion(): string | undefined {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const rn = require('react-native') as { Platform?: { Version?: string | number } };
+    const version = rn?.Platform?.Version;
+    return version === undefined || version === null ? undefined : String(version);
+  } catch {
+    return undefined;
+  }
+}

package/src/track.ts

@@ -0,0 +1,184 @@
+/**
+ * Pulse Track — the app's own events, sent to Pulse.
+ *
+ * The point of this half: an experiment is only worth running if something can be
+ * measured on it, and until now measuring meant owning a warehouse — a ClickHouse,
+ * a stream, and somebody to keep both alive. An app that has just adopted Pulse has
+ * none of that, so its experiments could report retention and nothing else.
+ *
+ * The event has to be declared in the registry first. That is deliberate and it is
+ * the same rule the server enforces: an event nobody declared could never be named by
+ * a metric, so accepting it would be a write into a place nothing reads. The response
+ * says which keys were ignored, and `onIgnored` surfaces them — a typo in an event
+ * name is otherwise invisible until someone wonders why a chart is empty.
+ *
+ * Batched on purpose. The endpoint takes up to a hundred events per request and is
+ * rate-limited per address, so one request per event would spend the whole allowance
+ * of a shared network on a single install. Events are queued, flushed on a timer and
+ * whenever the batch fills, and dropped oldest-first if the queue overflows: an event
+ * lost is a row missing from an average, and a request that blocks the app is a bug
+ * everybody sees.
+ */
+
+import type { ConfigContext } from './config';
+
+export interface TrackOptions {
+  /**
+   * The config url this app already uses (…/pulse/config/{slug}) or the track url
+   * itself. Accepting the first is not a convenience: it means the two halves cannot
+   * end up pointing at different apps, which would put an app's events in another
+   * app's registry and read as an empty metric on both sides.
+   */
+  url: string;
+
+  /** The same context the config uses — identity travels with the batch, once. */
+  getContext?: () => ConfigContext;
+
+  /** How often a non-empty queue is sent. Default 10s. */
+  flushIntervalMs?: number;
+
+  /** Events per request. The server refuses more than 100. */
+  maxBatch?: number;
+
+  /** Events held before the oldest are dropped. Default 500. */
+  maxQueue?: number;
+
+  /** Called with the event keys the server did not recognise. */
+  onIgnored?: (events: string[]) => void;
+
+  onError?: (error: unknown) => void;
+}
+
+export interface TrackedEventInput {
+  event: string;
+  props?: Record<string, string | number | boolean | null | undefined>;
+  time?: Date;
+}
+
+interface QueuedEvent {
+  event: string;
+  time: string;
+  props: Record<string, string>;
+}
+
+const DEFAULT_FLUSH_MS = 10_000;
+const DEFAULT_MAX_BATCH = 100;
+const DEFAULT_MAX_QUEUE = 500;
+
+let options: TrackOptions | null = null;
+let queue: QueuedEvent[] = [];
+let timer: ReturnType<typeof setInterval> | null = null;
+let sending = false;
+
+/** Turns a config url into the track url; leaves an explicit track url alone. */
+function trackUrl(url: string): string {
+  const trimmed = url.replace(/\/+$/, '');
+  return trimmed.includes('/pulse/config/')
+    ? trimmed.replace('/pulse/config/', '/pulse/track/')
+    : trimmed;
+}
+
+export function configureTracking(opts: TrackOptions): void {
+  options = opts;
+  startTimer();
+}
+
+/**
+ * Queue an event. Never throws, never awaits: a call site in a tap handler must not
+ * be able to make the tap slow, and an analytics call that can throw is one every
+ * caller has to wrap.
+ */
+export function track(event: string, props?: TrackedEventInput['props'], time?: Date): void {
+  if (!options || !event) return;
+
+  const flat: Record<string, string> = {};
+  for (const [key, value] of Object.entries(props ?? {})) {
+    if (value === null || value === undefined) continue;
+    flat[key] = typeof value === 'string' ? value : String(value);
+  }
+
+  queue.push({ event, time: (time ?? new Date()).toISOString(), props: flat });
+
+  const maxQueue = options.maxQueue ?? DEFAULT_MAX_QUEUE;
+  if (queue.length > maxQueue) queue = queue.slice(queue.length - maxQueue);
+
+  if (queue.length >= (options.maxBatch ?? DEFAULT_MAX_BATCH)) void flushEvents();
+}
+
+/**
+ * Send what is queued. Returns how many events the server accepted.
+ *
+ * Failures put the batch back at the front of the queue rather than dropping it: the
+ * usual cause is a network that is about to come back, and the usual moment is right
+ * after launch, when the first events of a session are the ones a funnel needs most.
+ */
+export async function flushEvents(): Promise<number> {
+  if (!options || sending || queue.length === 0) return 0;
+
+  const opts = options;
+  const ctx = opts.getContext?.() ?? {};
+
+  // Without a device id the server cannot put the event in an arm, and an empty id
+  // would pool every such install into one. Held rather than dropped: the id usually
+  // arrives a moment after boot.
+  if (!ctx.deviceId) return 0;
+
+  const batch = queue.slice(0, opts.maxBatch ?? DEFAULT_MAX_BATCH);
+  queue = queue.slice(batch.length);
+  sending = true;
+
+  try {
+    const response = await fetch(trackUrl(opts.url), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        deviceId: ctx.deviceId,
+        userId: ctx.userId,
+        platform: ctx.platform,
+        appVersion: ctx.appVersion,
+        events: batch.map((e) => ({ event: e.event, time: e.time, props: e.props })),
+      }),
+    });
+
+    if (!response.ok) {
+      // Rate limited or briefly down: keep the events, try on the next tick.
+      queue = [...batch, ...queue];
+      if (response.status !== 429) opts.onError?.(new Error(`Pulse track failed: ${response.status}`));
+      return 0;
+    }
+
+    const body = (await response.json()) as { accepted?: number; ignored?: string[] };
+    if (body.ignored && body.ignored.length > 0) opts.onIgnored?.(body.ignored);
+    return body.accepted ?? 0;
+  } catch (error) {
+    queue = [...batch, ...queue];
+    opts.onError?.(error);
+    return 0;
+  } finally {
+    sending = false;
+  }
+}
+
+/** How many events are waiting — for a caller that wants to flush before backgrounding. */
+export function pendingEventCount(): number {
+  return queue.length;
+}
+
+export function stopTracking(): void {
+  if (timer) {
+    clearInterval(timer);
+    timer = null;
+  }
+  options = null;
+  queue = [];
+  sending = false;
+}
+
+function startTimer(): void {
+  if (timer) clearInterval(timer);
+  const every = options?.flushIntervalMs ?? DEFAULT_FLUSH_MS;
+  timer = setInterval(() => void flushEvents(), every);
+  // Node keeps the process alive for a pending interval; React Native does not care,
+  // and a CLI importing this should still be able to exit.
+  (timer as unknown as { unref?: () => void }).unref?.();
+}