@stapel/core 0.2.0

package/src/analytics/createAnalytics.ts

@@ -0,0 +1,310 @@
+import { defaultPersistStorage } from "../storage.js";
+import type { PersistStorage } from "../storage.js";
+import { guardPii } from "./pii.js";
+import { sha256Hex } from "./hash.js";
+import type {
+  Analytics,
+  AnalyticsEvent,
+  AnalyticsEventKind,
+  AnalyticsOptions,
+  AnalyticsProvider,
+  ConsentState,
+} from "./types.js";
+
+/** Exponential backoff delay for a batch delivery attempt (1-based). */
+export function backoffDelay(attempt: number, baseMs: number): number {
+  return Math.min(30_000, baseMs * 2 ** Math.max(0, attempt - 1));
+}
+
+interface InflightBatch {
+  events: AnalyticsEvent[];
+  attempts: number;
+  /** Provider names that already accepted this batch (never re-called). */
+  delivered: Set<string>;
+}
+
+async function deliverToProvider(
+  provider: AnalyticsProvider,
+  events: readonly AnalyticsEvent[]
+): Promise<void> {
+  for (const event of events) {
+    if (event.kind === "identify" && provider.identify) {
+      await provider.identify(event.userHash ?? "", event.props);
+    } else if (event.kind === "page" && provider.page) {
+      await provider.page(event.name, event.props);
+    } else {
+      await provider.track(event);
+    }
+  }
+  await provider.flush?.();
+}
+
+/**
+ * The analytics facade (analytics-standard §2): fan-out to N providers,
+ * consent gate, offline queue on the core persist layer, batched delivery
+ * with retry/backoff, PII guard, hashed identify.
+ */
+export function createAnalytics(options: AnalyticsOptions = {}): Analytics {
+  const providers = new Map<string, AnalyticsProvider>(
+    Object.entries(options.providers ?? {})
+  );
+  const registry =
+    options.registry !== undefined ? new Set(options.registry) : null;
+  const piiMode = options.piiGuard ?? "strip";
+  const persistKey = options.persistKey ?? "stapel-analytics";
+  const storage: PersistStorage = options.storage ?? defaultPersistStorage();
+  const maxSize = options.batch?.maxSize ?? 20;
+  const flushIntervalMs = options.batch?.flushIntervalMs ?? 10_000;
+  const maxAttempts = options.batch?.maxAttempts ?? 5;
+  const backoffBaseMs = options.batch?.backoffBaseMs ?? 500;
+
+  const eventsKey = `${persistKey}:events`;
+  const consentKey = `${persistKey}:consent`;
+
+  let consent: ConsentState = options.consent ?? "pending";
+  let queue: AnalyticsEvent[] = [];
+  let batch: InflightBatch | null = null;
+  let flushing = false;
+  let retryTimer: ReturnType<typeof setTimeout> | null = null;
+  let seq = 0;
+  const warnedPii = new Set<string>();
+  const warnedRegistry = new Set<string>();
+  /** In-flight async work (identify hashing, persist writes) awaited by flush. */
+  let pendingOps: Promise<unknown>[] = [];
+  /** Serializes identify hashing so enqueue order matches call order. */
+  let identifyChain: Promise<void> = Promise.resolve();
+
+  const ready: Promise<void> = (async () => {
+    try {
+      const storedConsent = await storage.get(consentKey);
+      if (
+        storedConsent === "granted" ||
+        storedConsent === "denied" ||
+        storedConsent === "pending"
+      ) {
+        consent = storedConsent;
+      }
+      const storedEvents = await storage.get(eventsKey);
+      if (Array.isArray(storedEvents)) {
+        // Restored events precede anything captured before init finished.
+        queue = [...(storedEvents as AnalyticsEvent[]), ...queue];
+      }
+    } catch {
+      // Storage unavailable — degrade to in-memory only.
+    }
+  })();
+
+  async function persistQueue(): Promise<void> {
+    try {
+      if (consent === "denied") {
+        await storage.del(eventsKey);
+        return;
+      }
+      const pending = batch ? [...batch.events, ...queue] : queue;
+      await storage.set(eventsKey, pending);
+    } catch {
+      // Best-effort.
+    }
+  }
+
+  function schedulePersist(): void {
+    pendingOps.push(ready.then(persistQueue));
+  }
+
+  function clearRetryTimer(): void {
+    if (retryTimer !== null) {
+      clearTimeout(retryTimer);
+      retryTimer = null;
+    }
+  }
+
+  function scheduleRetry(delayMs: number): void {
+    if (retryTimer !== null) return;
+    retryTimer = setTimeout(() => {
+      retryTimer = null;
+      void flush();
+    }, delayMs);
+    (retryTimer as { unref?: () => void }).unref?.();
+  }
+
+  function enqueue(
+    kind: AnalyticsEventKind,
+    name: string,
+    props: Record<string, unknown>,
+    userHash?: string
+  ): void {
+    seq += 1;
+    const event: AnalyticsEvent = {
+      id: `${String(Date.now())}-${String(seq)}`,
+      kind,
+      name,
+      props,
+      ...(userHash !== undefined ? { userHash } : {}),
+      ts: Date.now(),
+    };
+    queue.push(event);
+    schedulePersist();
+    if (consent === "granted" && queue.length >= maxSize) {
+      void flush();
+    }
+  }
+
+  /** One delivery attempt for the current batch. True = batch settled. */
+  async function attemptBatch(): Promise<boolean> {
+    const current = batch;
+    if (current === null) return true;
+    current.attempts += 1;
+    await Promise.all(
+      [...providers.entries()].map(async ([name, provider]) => {
+        if (current.delivered.has(name)) return;
+        try {
+          await deliverToProvider(provider, current.events);
+          current.delivered.add(name);
+        } catch {
+          // Undelivered for this provider; batch will be retried.
+        }
+      })
+    );
+    const undelivered = [...providers.keys()].filter(
+      (name) => !current.delivered.has(name)
+    );
+    if (undelivered.length === 0) {
+      batch = null;
+      clearRetryTimer();
+      return true;
+    }
+    if (current.attempts >= maxAttempts) {
+      console.warn(
+        `[stapel analytics] dropping a batch of ${String(current.events.length)} event(s) ` +
+          `after ${String(current.attempts)} attempts; undelivered to: ${undelivered.join(", ")}`
+      );
+      batch = null;
+      clearRetryTimer();
+      return true;
+    }
+    scheduleRetry(backoffDelay(current.attempts, backoffBaseMs));
+    return false;
+  }
+
+  async function flush(): Promise<void> {
+    await ready;
+    const ops = pendingOps;
+    pendingOps = [];
+    await Promise.all(ops);
+    if (flushing) return;
+    flushing = true;
+    try {
+      if (consent !== "granted") return;
+      for (;;) {
+        if (batch === null) {
+          if (queue.length === 0 || providers.size === 0) break;
+          batch = {
+            events: queue.splice(0, maxSize),
+            attempts: 0,
+            delivered: new Set<string>(),
+          };
+        }
+        const settled = await attemptBatch();
+        if (!settled) break;
+      }
+    } finally {
+      flushing = false;
+      await persistQueue();
+    }
+  }
+
+  async function setConsent(state: ConsentState): Promise<void> {
+    await ready;
+    consent = state;
+    try {
+      await storage.set(consentKey, state);
+    } catch {
+      // Best-effort.
+    }
+    if (state === "denied") {
+      queue = [];
+      batch = null;
+      clearRetryTimer();
+      try {
+        await storage.del(eventsKey);
+      } catch {
+        // Best-effort.
+      }
+      return;
+    }
+    if (state === "granted") {
+      await flush();
+    }
+  }
+
+  function track(event: string, props?: Record<string, unknown>): void {
+    if (consent === "denied") return;
+    if (registry && !registry.has(event) && !warnedRegistry.has(event)) {
+      warnedRegistry.add(event);
+      console.warn(
+        `[stapel analytics] event "${event}" is not in the registry ` +
+          "(analytics-standard §1.1) — delivered anyway; declare it in events.json."
+      );
+    }
+    enqueue("track", event, guardPii(event, props ?? {}, piiMode, warnedPii));
+  }
+
+  function page(name: string, props?: Record<string, unknown>): void {
+    if (consent === "denied") return;
+    enqueue("page", name, guardPii(name, props ?? {}, piiMode, warnedPii));
+  }
+
+  function identify(userId: string, traits?: Record<string, unknown>): void {
+    if (consent === "denied") return;
+    const guarded = guardPii("identify", traits ?? {}, piiMode, warnedPii);
+    identifyChain = identifyChain
+      .then(() => sha256Hex(userId))
+      .then((userHash) => {
+        enqueue("identify", "identify", guarded, userHash);
+      });
+    pendingOps.push(identifyChain);
+  }
+
+  function finalFlush(): void {
+    // Best-effort teardown flush; batching providers use sendBeacon here.
+    void flush();
+    for (const provider of providers.values()) {
+      try {
+        void provider.flush?.();
+      } catch {
+        // Never break page teardown.
+      }
+    }
+  }
+
+  if (typeof window !== "undefined") {
+    window.addEventListener("pagehide", finalFlush);
+  }
+  if (typeof document !== "undefined") {
+    document.addEventListener("visibilitychange", () => {
+      if (document.visibilityState === "hidden") finalFlush();
+    });
+  }
+
+  const interval = setInterval(() => {
+    if (consent === "granted" && (queue.length > 0 || batch !== null)) {
+      void flush();
+    }
+  }, flushIntervalMs);
+  (interval as { unref?: () => void }).unref?.();
+
+  return {
+    track,
+    identify,
+    page,
+    flush,
+    setConsent,
+    getConsent: () => consent,
+    register: (name, provider) => {
+      providers.set(name, provider);
+    },
+    unregister: (name) => {
+      providers.delete(name);
+    },
+  };
+}

package/src/analytics/flow.ts

@@ -0,0 +1,19 @@
+import type { Analytics } from "./types.js";
+
+export type FlowStepPhase = "started" | "completed" | "failed";
+
+/**
+ * Auto-instrumentation seam for flow machines (analytics-standard §1.2):
+ * emits `flow.<flowId>.<stepId>` with `{phase, ...props}`. Funnel = flow —
+ * the `@stapel/<module>-react` machines call this on every transition, so
+ * funnels exist without hand-written instrumentation.
+ */
+export function trackFlowStep(
+  analytics: Analytics,
+  flowId: string,
+  stepId: string,
+  phase: FlowStepPhase,
+  props?: Record<string, unknown>
+): void {
+  analytics.track(`flow.${flowId}.${stepId}`, { phase, ...props });
+}

package/src/analytics/hash.ts

@@ -0,0 +1,16 @@
+/** SHA-256 hex via WebCrypto — user ids are hashed before any provider sees them. */
+export async function sha256Hex(input: string): Promise<string> {
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle) {
+    throw new Error(
+      "[stapel analytics] crypto.subtle is unavailable; cannot hash user ids"
+    );
+  }
+  const digest = await subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(input)
+  );
+  return [...new Uint8Array(digest)]
+    .map((byte) => byte.toString(16).padStart(2, "0"))
+    .join("");
+}

package/src/analytics/pii.ts

@@ -0,0 +1,66 @@
+import type { PiiGuardMode } from "./types.js";
+
+/**
+ * PII guard heuristics (analytics-standard §1.4): prop VALUES that look
+ * like emails or phone numbers are redacted ("strip"), kept with a warning
+ * ("warn"), or passed through ("off"). Applies to track/page props and
+ * identify traits. Keys are not judged — only values.
+ */
+
+const EMAIL_RE = /[^\s@]+@[^\s@]+\.[a-zA-Z]{2,}/;
+const PHONE_SHAPE_RE = /^\+?[\d\s\-().]{7,}$/;
+
+export function looksLikePii(value: string): boolean {
+  if (EMAIL_RE.test(value)) return true;
+  const trimmed = value.trim();
+  if (!PHONE_SHAPE_RE.test(trimmed)) return false;
+  return trimmed.replace(/\D/g, "").length >= 7;
+}
+
+export const PII_REDACTED = "[redacted]";
+
+function sanitizeValue(
+  value: unknown,
+  mode: PiiGuardMode,
+  hit: { found: boolean }
+): unknown {
+  if (typeof value === "string" && looksLikePii(value)) {
+    hit.found = true;
+    return mode === "strip" ? PII_REDACTED : value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => sanitizeValue(item, mode, hit));
+  }
+  if (typeof value === "object" && value !== null) {
+    const result: Record<string, unknown> = {};
+    for (const [key, nested] of Object.entries(value)) {
+      result[key] = sanitizeValue(nested, mode, hit);
+    }
+    return result;
+  }
+  return value;
+}
+
+/**
+ * Guard a props/traits object. Warns once per event name (per facade
+ * instance) via the caller-owned `warned` set.
+ */
+export function guardPii(
+  eventName: string,
+  props: Record<string, unknown>,
+  mode: PiiGuardMode,
+  warned: Set<string>
+): Record<string, unknown> {
+  if (mode === "off") return props;
+  const hit = { found: false };
+  const guarded = sanitizeValue(props, mode, hit) as Record<string, unknown>;
+  if (hit.found && !warned.has(eventName)) {
+    warned.add(eventName);
+    console.warn(
+      `[stapel analytics] PII-like value in props of "${eventName}" — ` +
+        (mode === "strip" ? "redacted" : "kept (piiGuard: warn)") +
+        ". PII in analytics props is banned (analytics-standard §1.4)."
+    );
+  }
+  return guarded;
+}

package/src/analytics/providers.ts

@@ -0,0 +1,108 @@
+import type { StapelClient } from "../client.js";
+import type { AnalyticsEvent, AnalyticsProvider } from "./types.js";
+
+/** Dev provider: logs every event via console.debug. Never throws. */
+export function consoleProvider(): AnalyticsProvider {
+  const log = (...args: unknown[]): void => {
+    try {
+      console.debug("[stapel analytics]", ...args);
+    } catch {
+      // Never throws — a broken console must not fail a batch.
+    }
+  };
+  return {
+    track: (event) => {
+      log(event.kind, event.name, event.props);
+    },
+    identify: (userHash, traits) => {
+      log("identify", userHash, traits ?? {});
+    },
+    page: (name, props) => {
+      log("page", name, props ?? {});
+    },
+  };
+}
+
+export interface StapelCollectorOptions {
+  /** Collector origin, e.g. `https://api.example.com`. */
+  readonly baseUrl?: string;
+  /**
+   * Alternatively reuse a `StapelClient` (its base URL, auth headers and
+   * error envelope handling).
+   */
+  readonly client?: StapelClient;
+  /** Source write key (analytics-standard §3); sent in the batch body. */
+  readonly writeKey?: string;
+  /** Injectable fetch (tests). */
+  readonly fetch?: typeof globalThis.fetch;
+}
+
+const COLLECTOR_PATH = "/analytics/api/events";
+
+/**
+ * Built-in provider for the stapel-analytics ingest endpoint: buffers
+ * events handed over by the facade and POSTs `{events: [...]}` to
+ * `{base}/analytics/api/events` on flush (one request per facade batch).
+ * During page teardown (document hidden) it prefers `navigator.sendBeacon`
+ * so the final batch survives navigation; otherwise fetch with keepalive.
+ * On a failed send the buffer is surrendered back to the facade's retry
+ * (the facade re-delivers the batch, repopulating the buffer).
+ */
+export function stapelCollectorProvider(
+  options: StapelCollectorOptions
+): AnalyticsProvider {
+  const baseUrl = options.baseUrl ?? options.client?.baseUrl;
+  if (baseUrl === undefined) {
+    throw new Error("stapelCollectorProvider requires a baseUrl or a client");
+  }
+  const endpoint = `${baseUrl.replace(/\/+$/, "")}${COLLECTOR_PATH}`;
+  let buffer: AnalyticsEvent[] = [];
+
+  async function send(events: readonly AnalyticsEvent[]): Promise<void> {
+    const body: Record<string, unknown> = { events };
+    if (options.writeKey !== undefined) body["write_key"] = options.writeKey;
+
+    const teardown =
+      typeof document !== "undefined" &&
+      document.visibilityState === "hidden" &&
+      typeof navigator !== "undefined" &&
+      typeof navigator.sendBeacon === "function";
+    if (teardown) {
+      const accepted = navigator.sendBeacon(
+        endpoint,
+        new Blob([JSON.stringify(body)], { type: "application/json" })
+      );
+      if (accepted) return;
+      // Beacon rejected (payload too large / unsupported) — fall through.
+    }
+
+    if (options.client) {
+      await options.client.post(COLLECTOR_PATH, body);
+      return;
+    }
+    const fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+    const response = await fetchImpl(endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+      keepalive: true,
+    });
+    if (!response.ok) {
+      throw new Error(
+        `[stapel analytics] collector responded ${String(response.status)}`
+      );
+    }
+  }
+
+  return {
+    track: (event) => {
+      buffer.push(event);
+    },
+    flush: async () => {
+      if (buffer.length === 0) return;
+      const events = buffer;
+      buffer = [];
+      await send(events);
+    },
+  };
+}

package/src/analytics/types.ts

@@ -0,0 +1,105 @@
+/**
+ * Analytics facade types (analytics-standard.md §1–2). Packages and hosts
+ * talk to the facade only — never to providers directly
+ * (frontend-standard §4.7).
+ */
+
+import type { PersistStorage } from "../storage.js";
+
+export type AnalyticsEventKind = "track" | "page" | "identify";
+
+export type ConsentState = "granted" | "denied" | "pending";
+
+export type PiiGuardMode = "strip" | "warn" | "off";
+
+/** A captured event as providers receive it (PII-guarded, user id hashed). */
+export interface AnalyticsEvent {
+  /** Facade-assigned id, unique per instance lifetime (dedupe aid). */
+  readonly id: string;
+  readonly kind: AnalyticsEventKind;
+  /** track: registry event name; page: page name; identify: `"identify"`. */
+  readonly name: string;
+  /** track/page props or identify traits, after the PII guard. */
+  readonly props: Record<string, unknown>;
+  /** SHA-256 hex of the user id (identify events only). */
+  readonly userHash?: string;
+  /** Epoch ms at capture time. */
+  readonly ts: number;
+}
+
+/**
+ * A fan-out target. Only `track` is mandatory: events of kind `page` /
+ * `identify` fall back to `track(event)` when the dedicated method is
+ * absent (the event carries its `kind`). `flush` is called after each
+ * delivered batch and on page teardown — batching providers (like the
+ * Stapel collector) send there. A rejected/thrown delivery marks the whole
+ * batch as undelivered for this provider; it will be retried.
+ */
+export interface AnalyticsProvider {
+  track(event: AnalyticsEvent): void | Promise<void>;
+  identify?(
+    userHash: string,
+    traits?: Record<string, unknown>
+  ): void | Promise<void>;
+  page?(name: string, props?: Record<string, unknown>): void | Promise<void>;
+  flush?(): void | Promise<void>;
+}
+
+export interface AnalyticsBatchOptions {
+  /** Queue length that triggers an automatic flush. Default 20. */
+  readonly maxSize?: number;
+  /** Periodic flush interval, ms. Default 10000. */
+  readonly flushIntervalMs?: number;
+  /** Delivery attempts per batch before it is dropped. Default 5. */
+  readonly maxAttempts?: number;
+  /** Base of the exponential retry backoff, ms. Default 500. */
+  readonly backoffBaseMs?: number;
+}
+
+export interface AnalyticsOptions {
+  /** Initial named providers (more via `register`/`unregister`). */
+  readonly providers?: Record<string, AnalyticsProvider>;
+  /**
+   * Event registry (analytics-standard §1.1): `track` with a name outside
+   * it logs a dev console.warn but still delivers — the hard gate is the
+   * eslint rule against the project's events.json.
+   */
+  readonly registry?: readonly string[];
+  /**
+   * Initial consent when none has been persisted yet. Default `"pending"`.
+   * A state persisted by `setConsent` takes precedence on recreation.
+   */
+  readonly consent?: ConsentState;
+  /** PII guard mode for prop/trait values. Default `"strip"`. */
+  readonly piiGuard?: PiiGuardMode;
+  readonly batch?: AnalyticsBatchOptions;
+  /** Storage key prefix for the offline queue + consent. Default `"stapel-analytics"`. */
+  readonly persistKey?: string;
+  /** Storage override (tests, custom stores). Default: IndexedDB → localStorage → memory. */
+  readonly storage?: PersistStorage;
+}
+
+export interface Analytics {
+  /** Queue a registry event. No-op while consent is `"denied"`. */
+  track(event: string, props?: Record<string, unknown>): void;
+  /**
+   * Queue an identify. The raw `userId` never leaves the facade: providers
+   * see its SHA-256 hex. Traits pass the PII guard.
+   */
+  identify(userId: string, traits?: Record<string, unknown>): void;
+  /** Queue a page view. */
+  page(name: string, props?: Record<string, unknown>): void;
+  /** Deliver everything queued (one delivery attempt per pending batch). */
+  flush(): Promise<void>;
+  /**
+   * Consent gate (analytics-standard §1.4): `"pending"` buffers,
+   * `"granted"` flushes the buffer, `"denied"` drops it (memory +
+   * persisted) and turns subsequent calls into no-ops. Persisted.
+   */
+  setConsent(state: ConsentState): Promise<void>;
+  /** Current consent state (after async restore; see `flush`). */
+  getConsent(): ConsentState;
+  /** Register a provider at runtime (merge semantics). */
+  register(name: string, provider: AnalyticsProvider): void;
+  unregister(name: string): void;
+}