@rocapine/rocalytics-sdk 0.0.0-stage → 0.3.0

package/src/onboarding/contract.ts

@@ -0,0 +1,144 @@
+// Onboarding run contract, schema_version 1: TypeScript types.
+//
+// The normative text is onboarding-run-contract.md; the machine-checkable shape
+// is onboarding-run.schema.json. These types mirror the schema. Where a rule is
+// a pattern or a limit (key characters, list lengths), the type says `string`
+// or `T[]` and the comment names the rule; the schema enforces it.
+//
+// This file has no imports, so it can be copied into any TypeScript project.
+
+/**
+ * RFC 3339 timestamp in UTC with exactly three fractional digits and a `Z`
+ * suffix, e.g. `2026-01-10T09:00:00.000Z`.
+ */
+export type Timestamp = string;
+
+/**
+ * An identifier chosen by the app: 1 to 128 characters from `A-Z a-z 0-9 _ . : -`,
+ * starting with a letter or digit. Case-sensitive. Used for onboarding, step,
+ * question, option, slot and variant keys.
+ */
+export type Key = string;
+
+export interface OnboardingIdentity {
+  /**
+   * Stable key for one flow. Never reused for a different flow. Each
+   * Studio-served A/B arm is its own onboarding, so it has its own key.
+   */
+  key: Key;
+  /**
+   * Revision of the flow. 1 to 64 characters from `A-Z a-z 0-9 _ . : + -`,
+   * starting with a letter or digit. Must change whenever the manifest changes,
+   * except for the reserved version `draft`, which a Studio-served draft or
+   * preview must send because it has no deployment id.
+   */
+  version: string;
+  /**
+   * In-flow variant, for an app that runs one flow (one key) with its own
+   * variants. Not set for a Studio-served run. Absent or null otherwise.
+   */
+  variant_key?: Key | null;
+}
+
+/** Optional links to Studio records. Opaque strings of 1 to 128 characters; numeric ids are sent in decimal. */
+export interface StudioLinks {
+  onboarding_id?: string | null;
+  deployment_id?: string | null;
+  audience_id?: string | null;
+}
+
+/** Captured once, at run start, and repeated unchanged in every snapshot. */
+export interface RunContext {
+  /** Marketing version, e.g. `2.4.0`. 1 to 32 characters. */
+  app_version: string;
+  /** Build number, 1 to 32 characters, or null on a platform with no such concept. */
+  build: string | null;
+  platform: "ios" | "android" | "web";
+  /** OS version, 1 to 32 characters, or null when the platform cannot report one. */
+  os_version: string | null;
+  /** BCP 47 language tag the onboarding is shown in, e.g. `fr-FR`. */
+  locale: string;
+  /** IANA time zone, e.g. `Europe/Paris`. At most 64 characters. */
+  timezone: string;
+  /** Version of the tracking library that produced the payload. 1 to 32 characters. */
+  library_version?: string;
+}
+
+export interface ManifestStep {
+  step_key: Key;
+  /** Steps sharing a slot are alternatives shown at one position. Must be contiguous. */
+  slot?: Key;
+}
+
+/** Declared once, at run start, and repeated unchanged in every snapshot. */
+export interface Manifest {
+  /** Every step the flow can show, in flow order. 1 to 200 entries. */
+  steps: ManifestStep[];
+}
+
+/** Run-level custom property value. Strings are at most 256 characters; numbers are finite. */
+export type PropertyValue = string | number | boolean | null;
+
+/** At most 20 keys, each matching `^[a-z][a-z0-9_]{0,39}$`. */
+export type Properties = Record<string, PropertyValue>;
+
+export type Answer =
+  | { question_key: Key; kind: "single"; value: Key }
+  /** At most 50 option keys, unique. */
+  | { question_key: Key; kind: "multi"; value: Key[] }
+  | { question_key: Key; kind: "numeric"; value: number; unit?: Key }
+  /** At most 1,000 characters. Never aggregated. */
+  | { question_key: Key; kind: "text"; value: string };
+
+/**
+ * One visit to a screen the user was shown. A step that was not shown has no
+ * entry; whether the run passed over it is derived from the manifest.
+ */
+export interface StepEntry {
+  step_key: Key;
+  entered_at: Timestamp;
+  /**
+   * Null only on the last entry of an in_progress run. In a truncated run the
+   * last kept entry may already be closed, and keeps its own exit on completion.
+   */
+  exited_at: Timestamp | null;
+  /** At most 50. `question_key` is unique within an entry. */
+  answers: Answer[];
+}
+
+interface RunSnapshotBase {
+  schema_version: 1;
+  /** Client-minted, lowercase UUID. One per run. */
+  run_id: string;
+  /** Starts at 1 and increases with every send of this run. A retry reuses it. */
+  seq: number;
+  started_at: Timestamp;
+  /** Client clock when this snapshot was sent. Advisory only. */
+  sent_at: Timestamp;
+  onboarding: OnboardingIdentity;
+  studio?: StudioLinks;
+  context: RunContext;
+  manifest: Manifest;
+  properties?: Properties;
+  /**
+   * Present once the tracker has stopped recording (no new entries, answers or
+   * property changes) because recording more would break the 500-entry or
+   * 256 KiB limit. What was recorded is kept.
+   */
+  truncated?: true;
+  /** Every entry so far, in the order they happened. 1 to 500 entries. */
+  steps: StepEntry[];
+}
+
+export interface InProgressRunSnapshot extends RunSnapshotBase {
+  status: "in_progress";
+  completed_at: null;
+}
+
+export interface CompletedRunSnapshot extends RunSnapshotBase {
+  status: "completed";
+  completed_at: Timestamp;
+}
+
+/** One send. Each send replaces the run's previous snapshot. */
+export type OnboardingRunSnapshot = InProgressRunSnapshot | CompletedRunSnapshot;

package/src/onboarding/index.ts

@@ -0,0 +1,39 @@
+// @rocapine/rocalytics-sdk/onboarding: the onboarding run tracker.
+//
+// Reports one run of an onboarding as snapshots in the shape of the onboarding
+// run contract v1 (docs/onboarding-run-contract.md). Headless: no renderer,
+// router or UI dependency, so a hand-coded onboarding uses it as is.
+
+export { createOnboardingRunTracker, onboardingRun } from "./tracker";
+export type { ExitOptions, OnboardingRun, OnboardingRunTracker, TrackerConfig } from "./tracker";
+export type { AnswerInput, ManifestInput, OnboardingInput, StartOptions, StudioInput } from "./input";
+export { MAX_ENTRIES, RECORDING_BUDGET } from "./state";
+export { LIBRARY_VERSION } from "../version";
+
+// Transport and environment pieces a host needs to configure the tracker.
+export { createHttpSink } from "../core/httpSink";
+export type { HttpSinkOptions } from "../core/httpSink";
+export { memoryStorage } from "../core/storage";
+export type { KeyValueStorage } from "../core/storage";
+export type { Sink, SinkOutcome, SinkResult } from "../core/sink";
+export type { Clock, Timers } from "../core/time";
+export type { RunContextInput } from "../core/context";
+export type { Diagnostic, DiagnosticHandler } from "../core/diagnostics";
+
+// The contract's payload types, exactly as docs/onboarding-run.types.ts defines them.
+export type {
+  Answer,
+  CompletedRunSnapshot,
+  InProgressRunSnapshot,
+  Key,
+  Manifest,
+  ManifestStep,
+  OnboardingIdentity,
+  OnboardingRunSnapshot,
+  Properties,
+  PropertyValue,
+  RunContext,
+  StepEntry,
+  StudioLinks,
+  Timestamp,
+} from "./contract";

package/src/onboarding/input.ts

@@ -0,0 +1,246 @@
+// The tracker's public input types (camelCase, as an app writes them) and their
+// validation against the contract. Anything that would make the ingest reject a
+// snapshot is caught here, so the tracker never sends it.
+import { codePointLength } from "../core/text";
+import type { Answer, Manifest, OnboardingIdentity, Properties, PropertyValue, StudioLinks } from "./contract";
+
+export interface OnboardingInput {
+  /** A stable key for this flow. Never reused for a different flow. */
+  key: string;
+  /** The flow's revision. Must change whenever the manifest or a question's keys change. */
+  version: string;
+  /** An in-flow variant, for an app running one flow under one key with its own variants. */
+  variantKey?: string | null;
+}
+
+export interface ManifestInput {
+  /** Every step the flow can show, in flow order. Steps sharing a `slot` are alternatives at one position. */
+  steps: { stepKey: string; slot?: string }[];
+}
+
+/**
+ * Studio ids are strings. A number passed at run time (from untyped JSON, for
+ * example) is sent in decimal when it is a safe non-negative integer; any
+ * other number makes the start invalid.
+ */
+export interface StudioInput {
+  /** Null and undefined both mean absent. */
+  onboardingId?: string | null;
+  /** Null and undefined both mean absent; a Studio-served run with none is a draft. */
+  deploymentId?: string | null;
+  audienceId?: string | null;
+  /** A Studio draft or preview: always sent as version `draft`. */
+  draft?: boolean;
+}
+
+interface StartBase {
+  manifest: ManifestInput;
+  /** Run-level scalar properties for slicing runs. No personal data. */
+  properties?: Properties;
+}
+
+/**
+ * Starts a run. Either the app declares `onboarding`, or a Studio-served flow
+ * passes `studio.onboardingId` and the identity defaults to the Studio
+ * onboarding id (key) and deployment id (version, `draft` without one).
+ */
+export type StartOptions =
+  | (StartBase & { onboarding: OnboardingInput; studio?: StudioInput })
+  | (StartBase & { onboarding?: undefined; studio: StudioInput & { onboardingId: string } });
+
+export type AnswerInput =
+  | { questionKey: string; kind: "single"; value: string }
+  | { questionKey: string; kind: "multi"; value: string[] }
+  | { questionKey: string; kind: "numeric"; value: number; unit?: string }
+  | { questionKey: string; kind: "text"; value: string };
+
+const KEY = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/;
+const VERSION = /^[A-Za-z0-9][A-Za-z0-9_.:+-]{0,63}$/;
+const PROPERTY_KEY = /^[a-z][a-z0-9_]{0,39}$/;
+
+export const MAX_MANIFEST_STEPS = 200;
+export const MAX_ANSWERS = 50;
+export const MAX_PROPERTIES = 20;
+
+export const isKey = (v: unknown): v is string => typeof v === "string" && KEY.test(v);
+const isLink = (v: unknown): v is string => typeof v === "string" && codePointLength(v) >= 1 && codePointLength(v) <= 128;
+
+export interface ValidStart {
+  onboarding: OnboardingIdentity;
+  studio?: StudioLinks;
+  manifest: Manifest;
+  properties?: Properties;
+  /** Problems that were corrected rather than fatal: [code, message]. */
+  warnings: [string, string][];
+}
+
+/** A Studio id that is a safe non-negative integer, in decimal (contract 3.1); anything else as it is. */
+const decimalId = (v: unknown): unknown => (typeof v === "number" && Number.isSafeInteger(v) && v >= 0 ? String(v) : v);
+
+export function validateStart(options: StartOptions): { ok: true; value: ValidStart } | { ok: false; errors: string[] } {
+  const errors: string[] = [];
+  const warnings: [string, string][] = [];
+  if (!options || typeof options !== "object") return { ok: false, errors: ["start options are not an object"] };
+
+  // Studio links. Read once, with numeric ids converted, by both the links and the identity below.
+  const studioIn: StudioInput | undefined =
+    options.studio && typeof options.studio === "object"
+      ? {
+          ...options.studio,
+          onboardingId: decimalId(options.studio.onboardingId) as string | null | undefined,
+          deploymentId: decimalId(options.studio.deploymentId) as string | null | undefined,
+          audienceId: decimalId(options.studio.audienceId) as string | null | undefined,
+        }
+      : options.studio;
+  let studio: StudioLinks | undefined;
+  if (studioIn !== undefined) {
+    if (!studioIn || typeof studioIn !== "object") errors.push("studio is not an object");
+    else {
+      studio = {};
+      const links: [keyof StudioLinks, unknown][] = [
+        ["onboarding_id", studioIn.onboardingId],
+        ["deployment_id", studioIn.deploymentId],
+        ["audience_id", studioIn.audienceId],
+      ];
+      for (const [field, value] of links) {
+        if (value === undefined || value === null) continue;
+        if (!isLink(value)) errors.push(`studio.${field} must be 1 to 128 characters`);
+        else studio[field] = value;
+      }
+      if (Object.keys(studio).length === 0) studio = undefined;
+    }
+  }
+  const draft = !!studioIn?.draft;
+
+  // Identity.
+  let onboarding: OnboardingIdentity | undefined;
+  if (options.onboarding) {
+    const { key, version, variantKey } = options.onboarding;
+    if (!isKey(key)) errors.push("onboarding.key must be 1 to 128 characters from A-Z a-z 0-9 _ . : -");
+    if (!draft && (typeof version !== "string" || !VERSION.test(version))) {
+      errors.push("onboarding.version must be 1 to 64 characters from A-Z a-z 0-9 _ . : + -");
+    }
+    if (draft && version !== "draft") warnings.push(["draft-version", `a Studio draft sends version "draft", not "${version}"`]);
+    onboarding = { key, version: draft ? "draft" : version };
+    if (variantKey !== undefined && variantKey !== null) {
+      // Studio-served means it carries a Studio link (or is a Studio draft), not that a `studio` object was passed.
+      if (studio || draft) {
+        warnings.push(["studio-variant-dropped", "a Studio-served run does not carry variant_key: each Studio arm is its own onboarding key"]);
+      } else if (!isKey(variantKey)) errors.push("onboarding.variantKey must be a key");
+      else onboarding.variant_key = variantKey;
+    }
+  } else if (studioIn && isKey(studioIn.onboardingId)) {
+    // A null deployment id is absent, as it is for the links above: a Studio-served run with none is a draft (3.1).
+    const deployment: unknown = studioIn.deploymentId;
+    const version = draft || deployment === undefined || deployment === null ? "draft" : deployment;
+    if (typeof version !== "string" || !VERSION.test(version)) {
+      errors.push("studio.deploymentId cannot be used as onboarding.version");
+    } else {
+      onboarding = { key: studioIn.onboardingId, version };
+    }
+  } else {
+    errors.push("either onboarding { key, version } or studio.onboardingId is required");
+  }
+
+  // Manifest.
+  const manifest: Manifest = { steps: [] };
+  const stepsIn = options.manifest?.steps;
+  if (!Array.isArray(stepsIn) || stepsIn.length < 1 || stepsIn.length > MAX_MANIFEST_STEPS) {
+    errors.push(`manifest.steps must hold 1 to ${MAX_MANIFEST_STEPS} steps`);
+  } else {
+    const seen = new Set<string>();
+    const closedSlots = new Set<string>();
+    stepsIn.forEach((s, i) => {
+      const stepKey = s?.stepKey;
+      if (!isKey(stepKey)) return void errors.push(`manifest.steps[${i}].stepKey is not a valid key`);
+      if (seen.has(stepKey)) errors.push(`manifest step "${stepKey}" is declared twice`);
+      seen.add(stepKey);
+      const slot = s.slot;
+      if (slot !== undefined) {
+        if (!isKey(slot)) errors.push(`manifest.steps[${i}].slot is not a valid key`);
+        if (closedSlots.has(slot)) errors.push(`slot "${slot}" is not contiguous`);
+        if (stepsIn[i + 1]?.slot !== slot) closedSlots.add(slot);
+        manifest.steps.push({ step_key: stepKey, slot });
+      } else {
+        manifest.steps.push({ step_key: stepKey });
+      }
+    });
+  }
+
+  // Properties: invalid ones are dropped, not fatal.
+  let properties: Properties | undefined;
+  if (options.properties !== undefined) {
+    const { value, problems } = mergeProperties({}, options.properties);
+    problems.forEach((p) => warnings.push(p));
+    if (Object.keys(value).length) properties = value;
+  }
+
+  if (errors.length || !onboarding) return { ok: false, errors };
+  return { ok: true, value: { onboarding, studio, manifest, properties, warnings } };
+}
+
+export function propertyProblem(key: string, value: unknown): string | null {
+  if (!PROPERTY_KEY.test(key)) return `property key "${key}" must match ^[a-z][a-z0-9_]{0,39}$`;
+  if (value === null || typeof value === "boolean") return null;
+  if (typeof value === "number") return Number.isFinite(value) ? null : `property "${key}" is not a finite number`;
+  if (typeof value === "string") return codePointLength(value) <= 256 ? null : `property "${key}" is longer than 256 characters`;
+  return `property "${key}" must be a string, number, boolean or null`;
+}
+
+/** `base` with `patch` applied, keeping only valid entries and at most 20 keys. */
+export function mergeProperties(base: Properties, patch: unknown): { value: Properties; problems: [string, string][] } {
+  const value: Properties = { ...base };
+  const problems: [string, string][] = [];
+  if (!patch || typeof patch !== "object" || Array.isArray(patch)) {
+    return { value, problems: [["invalid-property", "properties must be an object"]] };
+  }
+  for (const [k, v] of Object.entries(patch as Record<string, unknown>)) {
+    const problem = propertyProblem(k, v);
+    if (problem) {
+      problems.push(["invalid-property", problem]);
+      continue;
+    }
+    if (!Object.prototype.hasOwnProperty.call(value, k) && Object.keys(value).length >= MAX_PROPERTIES) {
+      problems.push(["too-many-properties", `property "${k}" dropped: at most ${MAX_PROPERTIES}`]);
+      continue;
+    }
+    value[k] = v as PropertyValue;
+  }
+  return { value, problems };
+}
+
+/** One answer in wire form, or the reason it cannot be sent. */
+export function toAnswer(input: unknown): { ok: true; answer: Answer } | { ok: false; error: string } {
+  if (!input || typeof input !== "object") return { ok: false, error: "an answer must be an object" };
+  const a = input as Record<string, unknown>;
+  const q = a.questionKey;
+  if (!isKey(q)) return { ok: false, error: "questionKey is not a valid key" };
+  switch (a.kind) {
+    case "single":
+      return isKey(a.value)
+        ? { ok: true, answer: { question_key: q, kind: "single", value: a.value } }
+        : { ok: false, error: `${q}: a single answer's value must be an option key` };
+    case "multi": {
+      if (!Array.isArray(a.value) || !a.value.every(isKey)) return { ok: false, error: `${q}: a multi answer's value must be option keys` };
+      const unique = [...new Set(a.value as string[])];
+      if (unique.length > MAX_ANSWERS) return { ok: false, error: `${q}: at most ${MAX_ANSWERS} options` };
+      return { ok: true, answer: { question_key: q, kind: "multi", value: unique } };
+    }
+    case "numeric": {
+      if (typeof a.value !== "number" || !Number.isFinite(a.value)) return { ok: false, error: `${q}: a numeric answer must be a finite number` };
+      if (a.unit !== undefined && !isKey(a.unit)) return { ok: false, error: `${q}: unit must be a key` };
+      return {
+        ok: true,
+        answer: a.unit === undefined
+          ? { question_key: q, kind: "numeric", value: a.value }
+          : { question_key: q, kind: "numeric", value: a.value, unit: a.unit as string },
+      };
+    }
+    case "text":
+      return typeof a.value === "string" && codePointLength(a.value) <= 1000
+        ? { ok: true, answer: { question_key: q, kind: "text", value: a.value } }
+        : { ok: false, error: `${q}: a text answer is at most 1,000 characters` };
+    default:
+      return { ok: false, error: `${q}: unknown answer kind ${JSON.stringify(a.kind)}` };
+  }
+}

package/src/onboarding/persisted.ts

@@ -0,0 +1,93 @@
+// What the tracker keeps in storage, and the check every stored value goes
+// through before use. Storage outlives app versions and can be corrupted, so
+// nothing read from it is trusted: an invalid part is dropped and reported,
+// and the stored value is then rewritten without it.
+import type { Outbound } from "../core/delivery";
+import type { OnboardingRunSnapshot } from "./contract";
+import type { RunState } from "./state";
+
+export interface Persisted {
+  format: 1;
+  /** The destination of the sink of the tracker that wrote it; absent when that sink had none. */
+  destination?: string;
+  current: RunState | null;
+  outboxes: Record<string, Outbound<OnboardingRunSnapshot>>;
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const TIMESTAMP = /^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$/;
+
+type Obj = Record<string, unknown>;
+const isObj = (v: unknown): v is Obj => !!v && typeof v === "object" && !Array.isArray(v);
+const isTimestamp = (v: unknown) => typeof v === "string" && TIMESTAMP.test(v);
+const isSeq = (v: unknown) => typeof v === "number" && Number.isInteger(v) && v >= 1;
+
+const isEntry = (e: unknown) =>
+  isObj(e) &&
+  typeof e.step_key === "string" &&
+  isTimestamp(e.entered_at) &&
+  (e.exited_at === null || isTimestamp(e.exited_at)) &&
+  Array.isArray(e.answers) &&
+  e.answers.every(isObj);
+
+export function isRunState(v: unknown): v is RunState {
+  if (!isObj(v)) return false;
+  const { onboarding, context, manifest } = v;
+  return (
+    typeof v.runId === "string" && UUID.test(v.runId) &&
+    typeof v.lastSeq === "number" && Number.isInteger(v.lastSeq) && v.lastSeq >= 0 &&
+    isObj(onboarding) && typeof onboarding.key === "string" && typeof onboarding.version === "string" &&
+    isObj(context) &&
+    isObj(manifest) && Array.isArray(manifest.steps) && manifest.steps.length > 0 &&
+    manifest.steps.every((s) => isObj(s) && typeof s.step_key === "string") &&
+    Array.isArray(v.steps) && v.steps.every(isEntry) &&
+    (v.studio === undefined || isObj(v.studio)) &&
+    (v.properties === undefined || isObj(v.properties)) &&
+    typeof v.provisionalExit === "boolean" &&
+    typeof v.truncated === "boolean" &&
+    (v.status === "in_progress" || v.status === "completed") &&
+    (v.completedAt === null || isTimestamp(v.completedAt)) &&
+    typeof v.lastActiveAt === "number" && Number.isFinite(v.lastActiveAt) &&
+    (v.dirty === undefined || typeof v.dirty === "boolean")
+  );
+}
+
+/** An unsent snapshot of run `runId`: a positive seq and a body that is that run's snapshot at that seq. */
+export function isOutbound(runId: string, v: unknown): v is Outbound<OnboardingRunSnapshot> {
+  if (!isObj(v) || !isSeq(v.seq) || !isObj(v.body)) return false;
+  const b = v.body;
+  return (
+    b.run_id === runId &&
+    b.seq === v.seq &&
+    (b.status === "in_progress" || b.status === "completed") &&
+    Array.isArray(b.steps) && b.steps.length > 0 &&
+    isObj(b.manifest) && isObj(b.onboarding) && isObj(b.context)
+  );
+}
+
+/** The usable parts of a stored value, and what was dropped. */
+export function parsePersisted(raw: unknown): {
+  current: RunState | null;
+  outboxes: [string, Outbound<OnboardingRunSnapshot>][];
+  problems: string[];
+} {
+  const problems: string[] = [];
+  if (!isObj(raw) || raw.format !== 1) {
+    return { current: null, outboxes: [], problems: ["unrecognised stored state"] };
+  }
+  let current: RunState | null = null;
+  if (raw.current !== null && raw.current !== undefined) {
+    if (isRunState(raw.current)) current = raw.current;
+    else problems.push("the stored run is malformed");
+  }
+  const outboxes: [string, Outbound<OnboardingRunSnapshot>][] = [];
+  if (isObj(raw.outboxes)) {
+    for (const [runId, item] of Object.entries(raw.outboxes)) {
+      if (isOutbound(runId, item)) outboxes.push([runId, item]);
+      else problems.push(`the stored snapshot of run "${runId}" is malformed`);
+    }
+  } else if (raw.outboxes !== undefined) {
+    problems.push("the stored snapshots are malformed");
+  }
+  return { current, outboxes, problems };
+}