@rocapine/rocalytics-sdk 0.0.0-stage → 0.3.0

package/src/core/delivery.ts

@@ -0,0 +1,181 @@
+import { normalizeResult, type Sink, type SinkResult } from "./sink";
+import type { Timers } from "./time";
+
+/** One send: a full snapshot and the `seq` it carries. A retry reuses both, unchanged. */
+export interface Outbound<T> {
+  seq: number;
+  body: T;
+}
+
+export interface RetryPolicy {
+  /** Delay before the first retry. Default 1,000 ms. */
+  initialDelayMs?: number;
+  /** Multiplier per further retry. Default 2. */
+  factor?: number;
+  /** Ceiling on the delay. Default 60,000 ms. */
+  maxDelayMs?: number;
+}
+
+export interface DeliveryOptions<T> {
+  sink: Sink<T>;
+  timers: Timers;
+  retry?: RetryPolicy;
+  /** A send that has not answered after this long counts as transient. Default 30,000 ms. */
+  attemptTimeoutMs?: number;
+  /** Called once a snapshot is settled for good: accepted, ignored or rejected. */
+  onSettled?(item: Outbound<T>, result: SinkResult): void;
+  /** Called whenever the pending snapshot changes, so it can be persisted. */
+  onPendingChange?(pending: Outbound<T> | null): void;
+}
+
+export interface Delivery<T> {
+  /**
+   * Hands over a snapshot. It replaces any pending one with a lower `seq`: full
+   * snapshots supersede each other, so only the latest needs to arrive.
+   */
+  enqueue(item: Outbound<T>): void;
+  /** Sends the pending snapshot now, without waiting out a backoff. */
+  flush(): void;
+  /** The snapshot not yet settled, if any. */
+  pending(): Outbound<T> | null;
+  /** Stops all timers. The pending snapshot is kept. */
+  stop(): void;
+  /**
+   * Winds down: skips any backoff to give the pending snapshot (and any
+   * handed over later) one last attempt each, and never schedules a retry.
+   * A snapshot that still fails stays pending, so it is not lost.
+   */
+  close(): void;
+  /**
+   * Resolves once no attempt is in flight. After `close()` nothing is retried,
+   * so this is when the last attempts are over, and `pending()` is what the
+   * sink did not take.
+   */
+  idle(): Promise<void>;
+}
+
+/**
+ * Delivers the latest snapshot of one run through a sink, one send at a time.
+ *
+ * - Only `accepted`, `ignored` and `rejected` settle a snapshot. Everything
+ *   else (a throw, a timeout, a result without an outcome) is transient and
+ *   the same snapshot is sent again after an exponential backoff.
+ * - A settled `seq` is never sent again, so a rejected snapshot is never
+ *   resent unchanged.
+ * - Nothing here throws into the caller.
+ */
+export function createDelivery<T>(options: DeliveryOptions<T>): Delivery<T> {
+  const { sink, timers } = options;
+  const initial = options.retry?.initialDelayMs ?? 1000;
+  const factor = options.retry?.factor ?? 2;
+  const max = options.retry?.maxDelayMs ?? 60_000;
+  const timeoutMs = options.attemptTimeoutMs ?? 30_000;
+
+  let pending: Outbound<T> | null = null;
+  let inFlight: Outbound<T> | null = null;
+  let settledSeq = 0;
+  let failures = 0;
+  let retryTimer: unknown = null;
+  let stopped = false;
+  let closed = false;
+  let idleWaiters: (() => void)[] = [];
+
+  const safe = (fn: () => void) => {
+    try {
+      fn();
+    } catch {
+      // A host callback that throws must not break delivery.
+    }
+  };
+  const setPending = (next: Outbound<T> | null) => {
+    pending = next;
+    safe(() => options.onPendingChange?.(next));
+  };
+  const clearRetry = () => {
+    if (retryTimer !== null) timers.clearTimeout(retryTimer);
+    retryTimer = null;
+  };
+
+  const callSink = (item: Outbound<T>): Promise<SinkResult> =>
+    new Promise<SinkResult>((resolve) => {
+      const timer = timers.setTimeout(() => resolve({ outcome: "transient", reason: "timeout" }), timeoutMs);
+      const done = (r: SinkResult) => {
+        timers.clearTimeout(timer);
+        resolve(r);
+      };
+      try {
+        Promise.resolve(sink.send(item.body)).then(
+          (value) => done(normalizeResult(value)),
+          (error) => done({ outcome: "transient", reason: String(error) }),
+        );
+      } catch (error) {
+        done({ outcome: "transient", reason: String(error) });
+      }
+    });
+
+  const wakeIdle = () => {
+    if (inFlight) return;
+    const waiters = idleWaiters;
+    idleWaiters = [];
+    for (const resolve of waiters) resolve();
+  };
+
+  const attempt = () => {
+    if (stopped || inFlight || !pending) return;
+    clearRetry();
+    const item = pending;
+    inFlight = item;
+    void callSink(item).then((result) => {
+      inFlight = null;
+      if (result.outcome === "transient") {
+        if (closed) {
+          // No retry after close; a newer snapshot handed over meanwhile still gets its one attempt.
+          if (pending && pending.seq > item.seq) attempt();
+          return wakeIdle();
+        }
+        failures += 1;
+        const delay = Math.min(max, initial * Math.pow(factor, failures - 1));
+        if (!stopped) retryTimer = timers.setTimeout(() => {
+          retryTimer = null;
+          attempt();
+        }, delay);
+        return wakeIdle();
+      }
+      failures = 0;
+      settledSeq = Math.max(settledSeq, item.seq);
+      if (pending && pending.seq <= item.seq) setPending(null);
+      safe(() => options.onSettled?.(item, result));
+      attempt(); // a newer snapshot may have arrived meanwhile
+      wakeIdle();
+    });
+  };
+
+  return {
+    enqueue(item) {
+      if (item.seq <= settledSeq) return;
+      if (pending && item.seq <= pending.seq) return;
+      setPending(item);
+      if (retryTimer === null) attempt();
+    },
+    flush() {
+      clearRetry();
+      attempt();
+    },
+    pending: () => pending,
+    stop() {
+      stopped = true;
+      clearRetry();
+    },
+    close() {
+      if (closed) return;
+      closed = true;
+      clearRetry();
+      attempt();
+    },
+    idle: () =>
+      new Promise<void>((resolve) => {
+        idleWaiters.push(resolve);
+        wakeIdle();
+      }),
+  };
+}

package/src/core/diagnostics.ts

@@ -0,0 +1,30 @@
+/**
+ * Something the SDK chose not to do, or could not do, reported instead of
+ * thrown: tracking must never break the app it runs in.
+ */
+export interface Diagnostic {
+  /** Stable machine-readable code, e.g. `unknown-step`, `rejected`, `truncated`. */
+  code: string;
+  message: string;
+  runId?: string;
+}
+
+export type DiagnosticHandler = (diagnostic: Diagnostic) => void;
+
+/** The default handler: a console warning, when a console exists. */
+export const consoleDiagnostics: DiagnosticHandler = (d) => {
+  const c = (globalThis as { console?: { warn?: (...a: unknown[]) => void } }).console;
+  c?.warn?.(`[rocalytics-sdk] ${d.code}: ${d.message}`);
+};
+
+/** Wraps a host handler so that a handler which throws cannot break the caller. */
+export function safeDiagnostics(handler: DiagnosticHandler | undefined): DiagnosticHandler {
+  const h = handler ?? consoleDiagnostics;
+  return (d) => {
+    try {
+      h(d);
+    } catch {
+      // ignored on purpose
+    }
+  };
+}

package/src/core/httpSink.ts

@@ -0,0 +1,70 @@
+import { normalizeResult, type Sink, type SinkResult } from "./sink";
+
+type Headers = Record<string, string>;
+
+export interface HttpSinkOptions {
+  /** The collector endpoint. Each payload is POSTed to it as JSON. */
+  url: string;
+  /** Extra request headers, such as an authorization token. A function is called for every send. */
+  headers?: Headers | (() => Headers | Promise<Headers>);
+  /** Defaults to the global `fetch`. */
+  fetch?: (url: string, init: { method: string; headers: Headers; body: string; signal?: unknown }) => Promise<{
+    text(): Promise<string>;
+  }>;
+  /** Gives up on a request after this long; the send is then transient. Default 15,000 ms. */
+  timeoutMs?: number;
+}
+
+/**
+ * A sink that POSTs each payload to an HTTP collector.
+ *
+ * The outcome comes from the response BODY only: `{"outcome": "accepted" |
+ * "ignored" | "rejected"}`. The status code is not read, because a proxy or
+ * gateway can answer 401, 404 or 413 without having looked at the payload, so
+ * any response without an outcome, and no response at all, is transient.
+ * It never throws.
+ *
+ * Its `destination` is `url`, marked ` (custom fetch)` when a `fetch` is
+ * passed: that one may never reach `url` (a test double), so it never counts
+ * as the same destination as the real one. Headers are not part of it.
+ */
+export function createHttpSink(options: HttpSinkOptions): Sink<unknown> {
+  const timeoutMs = options.timeoutMs ?? 15_000;
+  return {
+    destination: options.fetch ? `${options.url} (custom fetch)` : options.url,
+    async send(payload): Promise<SinkResult> {
+      const doFetch = options.fetch ?? (globalThis.fetch as unknown as HttpSinkOptions["fetch"]);
+      if (!doFetch) return { outcome: "transient", reason: "no fetch available" };
+      const Abort = (globalThis as { AbortController?: new () => { signal: unknown; abort(): void } }).AbortController;
+      const controller = Abort ? new Abort() : null;
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      try {
+        const extra = typeof options.headers === "function" ? await options.headers() : options.headers;
+        const request = doFetch(options.url, {
+          method: "POST",
+          headers: { ...extra, "content-type": "application/json" },
+          body: JSON.stringify(payload),
+          signal: controller?.signal,
+        }).then((res) => res.text());
+        const timeout = new Promise<never>((_, reject) => {
+          timer = setTimeout(() => {
+            controller?.abort();
+            reject(new Error("timeout"));
+          }, timeoutMs);
+        });
+        const text = await Promise.race([request, timeout]);
+        let body: unknown = undefined;
+        try {
+          body = JSON.parse(text);
+        } catch {
+          // Not JSON: no outcome, so transient.
+        }
+        return normalizeResult(body);
+      } catch (error) {
+        return { outcome: "transient", reason: String(error) };
+      } finally {
+        if (timer !== undefined) clearTimeout(timer);
+      }
+    },
+  };
+}

package/src/core/ids.ts

@@ -0,0 +1,46 @@
+import type { Clock } from "./time";
+
+const hex = (bytes: Uint8Array, from: number, to: number) => {
+  let out = "";
+  for (let i = from; i < to; i++) out += (bytes[i] + 0x100).toString(16).slice(1);
+  return out;
+};
+
+/**
+ * A lowercase UUIDv7 (RFC 9562): 48 bits of millisecond time, then random
+ * bits. It sorts by creation time, which is why the contract recommends it.
+ * `random` must hold at least 16 bytes; only the bits after the time are used.
+ */
+export function uuidv7(nowMs: number, random: Uint8Array): string {
+  const b = new Uint8Array(16);
+  for (let i = 0; i < 16; i++) b[i] = random[i] ?? 0;
+  let t = Math.max(0, Math.floor(nowMs));
+  for (let i = 5; i >= 0; i--) {
+    b[i] = t % 256;
+    t = Math.floor(t / 256);
+  }
+  b[6] = 0x70 | (b[6] & 0x0f); // version 7
+  b[8] = 0x80 | (b[8] & 0x3f); // variant 10xx
+  return `${hex(b, 0, 4)}-${hex(b, 4, 6)}-${hex(b, 6, 8)}-${hex(b, 8, 10)}-${hex(b, 10, 16)}`;
+}
+
+/**
+ * 16 random bytes from `crypto.getRandomValues` when the runtime has it, and
+ * from `Math.random` otherwise. A run id needs to be unique, not secret, so
+ * the fallback is acceptable on a runtime with no crypto global.
+ */
+export function randomBytes16(): Uint8Array {
+  const out = new Uint8Array(16);
+  const c = (globalThis as { crypto?: { getRandomValues?: (a: Uint8Array) => Uint8Array } }).crypto;
+  if (c && typeof c.getRandomValues === "function") {
+    c.getRandomValues(out);
+    return out;
+  }
+  for (let i = 0; i < 16; i++) out[i] = Math.floor(Math.random() * 256);
+  return out;
+}
+
+/** The default id minter: UUIDv7 from the injected clock. */
+export function createUuid(clock: Clock): () => string {
+  return () => uuidv7(clock.now(), randomBytes16());
+}

package/src/core/index.ts

@@ -0,0 +1,20 @@
+// @rocapine/rocalytics-sdk/core: shared building blocks for the surface subpaths.
+// Internal: exported so a custom sink or another surface can use it, with no
+// stability promise beyond what /onboarding re-exports.
+
+export { captureRunContext } from "./context";
+export type { RunContextInput, WireRunContext } from "./context";
+export { consoleDiagnostics, safeDiagnostics } from "./diagnostics";
+export type { Diagnostic, DiagnosticHandler } from "./diagnostics";
+export { createDelivery } from "./delivery";
+export type { Delivery, DeliveryOptions, Outbound, RetryPolicy } from "./delivery";
+export { createHttpSink } from "./httpSink";
+export type { HttpSinkOptions } from "./httpSink";
+export { createUuid, randomBytes16, uuidv7 } from "./ids";
+export { normalizeResult } from "./sink";
+export type { Sink, SinkOutcome, SinkResult } from "./sink";
+export { createSerialStore, memoryStorage } from "./storage";
+export type { KeyValueStorage, SerialStore } from "./storage";
+export { codePointLength, utf8ByteLength } from "./text";
+export { systemClock, systemTimers, toTimestamp } from "./time";
+export type { Clock, Timers } from "./time";

package/src/core/sink.ts

@@ -0,0 +1,46 @@
+/**
+ * The three outcomes an ingest can give a snapshot, carried in its response
+ * body. Anything else (no response, an error, a response without one of these)
+ * is transient: the snapshot is kept and sent again.
+ */
+export type SinkOutcome = "accepted" | "ignored" | "rejected";
+
+export type SinkResult =
+  | { outcome: SinkOutcome; reason?: string }
+  | { outcome: "transient"; reason?: string };
+
+/**
+ * Delivers one payload somewhere. A sink reports what happened; it does not
+ * retry, and it may throw: the caller treats a throw as transient.
+ *
+ * The caller sends one payload of a run at a time, and counts a send with no
+ * answer after its attempt timeout (30 s by default) as transient. A sink that
+ * keeps working past that timeout can therefore overlap with the retry. Both
+ * carry the same seq and body, so this is safe against an ingest that ignores
+ * an equal seq, but a sink should give up before the attempt timeout (the
+ * stock HTTP sink gives up after 15 s).
+ */
+export interface Sink<T = unknown> {
+  /**
+   * Where payloads go, such as the collector's URL. Two sinks with the same
+   * destination are interchangeable: a reconfigure hands the old tracker's
+   * unsent snapshots to the new one, and stored ones are sent by either.
+   * Without it, only the same sink object counts as the same destination.
+   * A test double must not claim a real destination: the stock sinks mark
+   * theirs ` (custom fetch)` when given a `fetch`. Headers are not part of it.
+   */
+  readonly destination?: string;
+  send(payload: T): Promise<SinkResult> | SinkResult;
+}
+
+/** Reads a sink's answer strictly: only the three named outcomes end a send. */
+export function normalizeResult(value: unknown): SinkResult {
+  if (value && typeof value === "object") {
+    const { outcome, reason } = value as { outcome?: unknown; reason?: unknown };
+    if (outcome === "accepted" || outcome === "ignored" || outcome === "rejected") {
+      return typeof reason === "string" ? { outcome, reason } : { outcome };
+    }
+    if (typeof reason === "string") return { outcome: "transient", reason };
+  }
+  return { outcome: "transient" };
+}

package/src/core/storage.ts

@@ -0,0 +1,112 @@
+/**
+ * A string key-value store. The shape matches `@react-native-async-storage/async-storage`
+ * and `localStorage`, so either can be passed as is; this package depends on neither.
+ */
+export interface KeyValueStorage {
+  getItem(key: string): string | null | Promise<string | null>;
+  setItem(key: string, value: string): void | Promise<void>;
+  removeItem(key: string): void | Promise<void>;
+}
+
+/** An in-memory `KeyValueStorage`. Survives nothing; useful for tests and for opting out of persistence. */
+export function memoryStorage(): KeyValueStorage & { dump(): Record<string, string> } {
+  const map = new Map<string, string>();
+  return {
+    getItem: (k) => map.get(k) ?? null,
+    setItem: (k, v) => void map.set(k, v),
+    removeItem: (k) => void map.delete(k),
+    dump: () => Object.fromEntries(map),
+  };
+}
+
+/** What a read found: a value (or nothing stored), a value that is not JSON, or no answer from storage at all. */
+export type ReadResult<T> =
+  | { status: "ok"; value: T | null }
+  | { status: "invalid"; error: unknown }
+  | { status: "failed"; error: unknown };
+
+export interface SerialStore<T> {
+  /** Reads the value, after every write queued before it. Null when absent or unreadable. */
+  load(): Promise<T | null>;
+  /**
+   * Reads the value, after every write queued before it, telling a value that
+   * is not JSON (`invalid`) from storage that did not answer (`failed`). A
+   * failed read is retried once, in the same turn, before it counts as failed.
+   * `waitFirst` is awaited inside that turn, before reading: operations queued
+   * after this read still wait for it, so it can be ordered behind work done
+   * elsewhere (another store's last writes) without them overtaking it.
+   */
+  read(waitFirst?: Promise<unknown>): Promise<ReadResult<T>>;
+  /** Queues a write (null removes the key). Never throws; failures go to `onError`. */
+  save(value: T | null): void;
+  /**
+   * Queues a write whose value is computed when its turn comes, so it is the
+   * latest one; `undefined` skips the write. Resolves once done. Never rejects.
+   */
+  saveWith(produce: () => T | null | undefined | Promise<T | null | undefined>): Promise<void>;
+  /** Resolves once every queued operation has finished. */
+  idle(): Promise<void>;
+}
+
+/**
+ * JSON values under one key, with every read and write applied in call order,
+ * so an older write can never land after a newer one.
+ */
+export function createSerialStore<T>(
+  storage: KeyValueStorage,
+  key: string,
+  onError: (error: unknown) => void,
+): SerialStore<T> {
+  const queue: { chain: Promise<unknown> } = { chain: Promise.resolve() };
+  const enqueue = <R>(op: () => R | Promise<R>, fallback: R): Promise<R> => {
+    const next = queue.chain.then(op).catch((e) => {
+      onError(e);
+      return fallback;
+    });
+    queue.chain = next;
+    return next;
+  };
+  const getRaw = async (): Promise<string | null> => {
+    try {
+      return await storage.getItem(key);
+    } catch {
+      return await storage.getItem(key); // one retry, still inside this turn of the queue
+    }
+  };
+  const read = (waitFirst?: Promise<unknown>): Promise<ReadResult<T>> =>
+    enqueue<ReadResult<T>>(async () => {
+      if (waitFirst) await waitFirst.catch(() => undefined);
+      let raw: string | null;
+      try {
+        raw = await getRaw();
+      } catch (error) {
+        return { status: "failed", error };
+      }
+      if (raw == null) return { status: "ok", value: null };
+      try {
+        return { status: "ok", value: JSON.parse(raw) as T };
+      } catch (error) {
+        return { status: "invalid", error };
+      }
+    }, { status: "failed", error: undefined });
+  const write = async (value: T | null) => {
+    if (value === null) await storage.removeItem(key);
+    else await storage.setItem(key, JSON.stringify(value));
+  };
+  return {
+    load: () =>
+      read().then((r) => {
+        if (r.status === "ok") return r.value;
+        onError(r.error);
+        return null;
+      }),
+    read,
+    save: (value) => void enqueue(() => write(value), undefined),
+    saveWith: (produce) =>
+      enqueue(async () => {
+        const value = await produce();
+        if (value !== undefined) await write(value);
+      }, undefined),
+    idle: () => enqueue(() => undefined, undefined),
+  };
+}

package/src/core/text.ts

@@ -0,0 +1,37 @@
+/**
+ * UTF-8 length of `s` in bytes, without `TextEncoder` or `Buffer` (neither is
+ * guaranteed on every JavaScript runtime an app ships on). A lone surrogate
+ * counts as the 3-byte replacement character, as an encoder would write it.
+ */
+export function utf8ByteLength(s: string): number {
+  let bytes = 0;
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i);
+    if (c < 0x80) bytes += 1;
+    else if (c < 0x800) bytes += 2;
+    else if (c >= 0xd800 && c <= 0xdbff && i + 1 < s.length) {
+      const next = s.charCodeAt(i + 1);
+      if (next >= 0xdc00 && next <= 0xdfff) {
+        bytes += 4;
+        i++;
+      } else {
+        bytes += 3;
+      }
+    } else bytes += 3;
+  }
+  return bytes;
+}
+
+/** Length in code points: what JSON Schema's `minLength` / `maxLength` count. */
+export function codePointLength(s: string): number {
+  let n = 0;
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i);
+    if (c >= 0xd800 && c <= 0xdbff && i + 1 < s.length) {
+      const next = s.charCodeAt(i + 1);
+      if (next >= 0xdc00 && next <= 0xdfff) i++;
+    }
+    n++;
+  }
+  return n;
+}

package/src/core/time.ts

@@ -0,0 +1,26 @@
+/** A source of the current time, in milliseconds since the epoch. Injected so tests can fix it. */
+export interface Clock {
+  now(): number;
+}
+
+/** The two timer functions the core uses. Injected so tests can drive time. */
+export interface Timers {
+  setTimeout(fn: () => void, ms: number): unknown;
+  clearTimeout(handle: unknown): void;
+}
+
+export const systemClock: Clock = { now: () => Date.now() };
+
+export const systemTimers: Timers = {
+  setTimeout: (fn, ms) => setTimeout(fn, ms),
+  clearTimeout: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
+};
+
+/**
+ * A UTC timestamp with exactly three fractional digits and a `Z`, e.g.
+ * `2026-01-10T09:00:00.000Z`: the only timestamp form the contract accepts.
+ * `toISOString` produces exactly that for every year from 0 to 9999.
+ */
+export function toTimestamp(ms: number): string {
+  return new Date(ms).toISOString();
+}