@rocapine/rocalytics-sdk 0.0.0-stage → 0.3.0

package/dist/onboarding/persisted.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persisted.js","sourceRoot":"","sources":["../../src/onboarding/persisted.ts"],"names":[],"mappings":"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"}

package/dist/onboarding/state.d.ts

@@ -0,0 +1,65 @@
+import type { WireRunContext } from "../core/context";
+import type { Answer, Manifest, OnboardingIdentity, OnboardingRunSnapshot, Properties, StepEntry, StudioLinks } from "./contract";
+/** 256 KiB minus 1 KiB of headroom for what lands after the measure (D26). */
+export declare const RECORDING_BUDGET = 261120;
+/** The most entries a snapshot holds (D8). */
+export declare const MAX_ENTRIES = 500;
+export interface RunState {
+    runId: string;
+    /** The last `seq` assigned to a send. 0 before the first. */
+    lastSeq: number;
+    onboarding: OnboardingIdentity;
+    studio?: StudioLinks;
+    context: WireRunContext;
+    manifest: Manifest;
+    properties?: Properties;
+    /** Entries as recorded. The last one's exit may be provisional, see below. */
+    steps: StepEntry[];
+    /**
+     * The last entry's `exited_at` was set by exitStep while the run goes on.
+     * An in-progress snapshot of an untruncated run still sends it as null
+     * (rule 6: only the current screen is open), until the next entry closes it
+     * for good or completion replaces it with `completed_at` (rule 7).
+     */
+    provisionalExit: boolean;
+    truncated: boolean;
+    status: "in_progress" | "completed";
+    completedAt: string | null;
+    /** Last moment the app was known to be in the foreground on the current screen (3.2). Epoch ms. */
+    lastActiveAt: number;
+    /** A recorded change has not gone into a send yet (it is waiting on the debounce). */
+    dirty?: boolean;
+}
+/** What an operation did, for the tracker to report. */
+export type Note = "truncated" | "too-many-answers";
+export interface Result {
+    state: RunState;
+    changed: boolean;
+    notes: Note[];
+}
+/** The snapshot `state` sends with `seq` at `nowMs`, in the key order of the contract's examples. */
+export declare function toSnapshot(state: RunState, seq: number, nowMs: number): OnboardingRunSnapshot;
+/** Completion as the contract defines it: every open exit closed at `completed_at`, a truncated run's closed exit kept. */
+export declare function completeState(state: RunState, nowMs: number): RunState;
+/** Whether `state` stays within the recording budget, measured on its completion form with the next seq (D26). */
+export declare function fits(state: RunState, nowMs: number): boolean;
+/** A new screen is shown. */
+export declare function enter(state: RunState, stepKey: string, nowMs: number): Result;
+/**
+ * The user leaves the screen at `index` (the current entry, or the one just
+ * before it when the next screen was entered first), with what they answered.
+ */
+export declare function exit(state: RunState, index: number, answers: Answer[], nowMs: number): Result;
+/** A new or changed property set: `merged` is the whole map after the change. */
+export declare function setProperties(state: RunState, merged: Properties, nowMs: number): Result;
+/**
+ * Restore after relaunch (3.2): close a still-open pre-kill entry at
+ * last_active_at, or at the exit exitStep recorded if that is later (the
+ * user is known to have left then); never rewrite an exit already final. Then append a new
+ * entry for the restored screen at `nowMs`, unless the run is truncated or the
+ * entry would break a limit, in which case recording stops instead.
+ */
+export declare function restore(state: RunState, nowMs: number): Result;
+/** The latest moment recorded in the run, so a clock set backwards cannot make timestamps go back. */
+export declare function floorMs(state: RunState): number;
+//# sourceMappingURL=state.d.ts.map

package/dist/onboarding/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/onboarding/state.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EACV,MAAM,EACN,QAAQ,EACR,kBAAkB,EAClB,qBAAqB,EACrB,UAAU,EACV,SAAS,EACT,WAAW,EACZ,MAAM,YAAY,CAAC;AAGpB,8EAA8E;AAC9E,eAAO,MAAM,gBAAgB,SAAU,CAAC;AACxC,8CAA8C;AAC9C,eAAO,MAAM,WAAW,MAAM,CAAC;AAE/B,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,kBAAkB,CAAC;IAC/B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,OAAO,EAAE,cAAc,CAAC;IACxB,QAAQ,EAAE,QAAQ,CAAC;IACnB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,8EAA8E;IAC9E,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB;;;;;OAKG;IACH,eAAe,EAAE,OAAO,CAAC;IACzB,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,aAAa,GAAG,WAAW,CAAC;IACpC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,mGAAmG;IACnG,YAAY,EAAE,MAAM,CAAC;IACrB,sFAAsF;IACtF,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,wDAAwD;AACxD,MAAM,MAAM,IAAI,GAAG,WAAW,GAAG,kBAAkB,CAAC;AACpD,MAAM,WAAW,MAAM;IACrB,KAAK,EAAE,QAAQ,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,IAAI,EAAE,CAAC;CACf;AAID,qGAAqG;AACrG,wBAAgB,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,qBAAqB,CAwB7F;AAED,2HAA2H;AAC3H,wBAAgB,aAAa,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,CAUtE;AAED,kHAAkH;AAClH,wBAAgB,IAAI,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAG5D;AAkBD,6BAA6B;AAC7B,wBAAgB,KAAK,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAW7E;AAED;;;GAGG;AACH,wBAAgB,IAAI,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CA6C7F;AAED,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAMxF;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAmB9D;AAED,sGAAsG;AACtG,wBAAgB,OAAO,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAQ/C"}

package/dist/onboarding/state.js

@@ -0,0 +1,207 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_ENTRIES = exports.RECORDING_BUDGET = void 0;
+exports.toSnapshot = toSnapshot;
+exports.completeState = completeState;
+exports.fits = fits;
+exports.enter = enter;
+exports.exit = exit;
+exports.setProperties = setProperties;
+exports.restore = restore;
+exports.floorMs = floorMs;
+// The run as the tracker records it, and the pure operations on it. Every
+// function returns a new state (or the same one when nothing changed); none
+// reads the clock or does I/O, so each rule of the contract is testable here.
+const text_1 = require("../core/text");
+const time_1 = require("../core/time");
+const input_1 = require("./input");
+/** 256 KiB minus 1 KiB of headroom for what lands after the measure (D26). */
+exports.RECORDING_BUDGET = 261120;
+/** The most entries a snapshot holds (D8). */
+exports.MAX_ENTRIES = 500;
+const unchanged = (state, notes = []) => ({ state, changed: false, notes });
+/** The snapshot `state` sends with `seq` at `nowMs`, in the key order of the contract's examples. */
+function toSnapshot(state, seq, nowMs) {
+    var _a, _b;
+    const steps = state.steps.map((e) => ({ ...e, answers: e.answers.slice() }));
+    if (state.status === "in_progress" && !state.truncated && state.provisionalExit && steps.length) {
+        steps[steps.length - 1].exited_at = null;
+    }
+    const head = {
+        schema_version: 1,
+        run_id: state.runId,
+        seq,
+    };
+    const tail = {
+        sent_at: (0, time_1.toTimestamp)(nowMs),
+        onboarding: state.onboarding,
+        ...(state.studio ? { studio: state.studio } : {}),
+        context: state.context,
+        manifest: state.manifest,
+        ...(state.properties ? { properties: state.properties } : {}),
+        ...(state.truncated ? { truncated: true } : {}),
+        steps,
+    };
+    const started_at = (_b = (_a = steps[0]) === null || _a === void 0 ? void 0 : _a.entered_at) !== null && _b !== void 0 ? _b : (0, time_1.toTimestamp)(nowMs);
+    return state.status === "completed"
+        ? { ...head, status: "completed", started_at, completed_at: state.completedAt, ...tail }
+        : { ...head, status: "in_progress", started_at, completed_at: null, ...tail };
+}
+/** Completion as the contract defines it: every open exit closed at `completed_at`, a truncated run's closed exit kept. */
+function completeState(state, nowMs) {
+    const completedAt = (0, time_1.toTimestamp)(nowMs);
+    const steps = state.steps.slice();
+    const lastIndex = steps.length - 1;
+    if (lastIndex >= 0) {
+        const last = steps[lastIndex];
+        const keepExit = state.truncated && last.exited_at !== null;
+        if (!keepExit)
+            steps[lastIndex] = { ...last, exited_at: completedAt };
+    }
+    return { ...state, steps, provisionalExit: false, status: "completed", completedAt };
+}
+/** Whether `state` stays within the recording budget, measured on its completion form with the next seq (D26). */
+function fits(state, nowMs) {
+    const form = toSnapshot(completeState(state, nowMs), state.lastSeq + 1, nowMs);
+    return (0, text_1.utf8ByteLength)(JSON.stringify(form)) <= exports.RECORDING_BUDGET;
+}
+const lastOf = (s) => s.steps[s.steps.length - 1];
+/** Closes the current entry for good: at its provisional exit if exitStep gave one, else at `at`. */
+function closeCurrent(state, at) {
+    var _a;
+    const last = lastOf(state);
+    if (!last)
+        return state;
+    if (last.exited_at !== null && !state.provisionalExit)
+        return state;
+    const steps = state.steps.slice();
+    steps[steps.length - 1] = { ...last, exited_at: (_a = last.exited_at) !== null && _a !== void 0 ? _a : at };
+    return { ...state, steps, provisionalExit: false };
+}
+function stopRecording(state) {
+    return { ...state, truncated: true };
+}
+/** A new screen is shown. */
+function enter(state, stepKey, nowMs) {
+    const at = (0, time_1.toTimestamp)(nowMs);
+    const closed = { ...closeCurrent(state, at), lastActiveAt: nowMs };
+    if (state.truncated)
+        return { state: closed, changed: closed.steps !== state.steps, notes: ["truncated"] };
+    if (state.steps.length >= exports.MAX_ENTRIES)
+        return { state: stopRecording(closed), changed: true, notes: ["truncated"] };
+    const next = {
+        ...closed,
+        steps: [...closed.steps, { step_key: stepKey, entered_at: at, exited_at: null, answers: [] }],
+    };
+    if (!fits(next, nowMs))
+        return { state: stopRecording(closed), changed: true, notes: ["truncated"] };
+    return { state: next, changed: true, notes: [] };
+}
+/**
+ * The user leaves the screen at `index` (the current entry, or the one just
+ * before it when the next screen was entered first), with what they answered.
+ */
+function exit(state, index, answers, nowMs) {
+    const notes = [];
+    let current = state;
+    let changed = false;
+    const isLast = index === state.steps.length - 1;
+    if (current.truncated) {
+        if (answers.length)
+            notes.push("truncated");
+    }
+    else {
+        for (const answer of answers) {
+            const entry = current.steps[index];
+            const at = entry.answers.findIndex((a) => a.question_key === answer.question_key);
+            if (at < 0 && entry.answers.length >= input_1.MAX_ANSWERS) {
+                notes.push("too-many-answers");
+                continue;
+            }
+            const list = entry.answers.slice();
+            if (at < 0)
+                list.push(answer);
+            else
+                list[at] = answer;
+            const steps = current.steps.slice();
+            steps[index] = { ...entry, answers: list };
+            const next = { ...current, steps };
+            if (!fits(next, nowMs)) {
+                current = stopRecording(current);
+                notes.push("truncated");
+                changed = true;
+                break;
+            }
+            current = next;
+            changed = true;
+        }
+    }
+    // Record when the user left. In a truncated run that exit is final at once.
+    const entry = current.steps[index];
+    if (isLast && entry.exited_at === null) {
+        const steps = current.steps.slice();
+        steps[index] = { ...entry, exited_at: (0, time_1.toTimestamp)(nowMs) };
+        current = { ...current, steps, provisionalExit: !current.truncated };
+        changed = true;
+    }
+    else if (isLast && current.truncated && current.provisionalExit) {
+        current = { ...current, provisionalExit: false };
+        changed = true;
+    }
+    return changed ? { state: current, changed, notes } : unchanged(state, notes);
+}
+/** A new or changed property set: `merged` is the whole map after the change. */
+function setProperties(state, merged, nowMs) {
+    var _a;
+    if (JSON.stringify(merged) === JSON.stringify((_a = state.properties) !== null && _a !== void 0 ? _a : {}))
+        return unchanged(state);
+    if (state.truncated)
+        return unchanged(state, ["truncated"]);
+    const next = { ...state, properties: Object.keys(merged).length ? merged : undefined };
+    if (!fits(next, nowMs))
+        return { state: stopRecording(state), changed: true, notes: ["truncated"] };
+    return { state: next, changed: true, notes: [] };
+}
+/**
+ * Restore after relaunch (3.2): close a still-open pre-kill entry at
+ * last_active_at, or at the exit exitStep recorded if that is later (the
+ * user is known to have left then); never rewrite an exit already final. Then append a new
+ * entry for the restored screen at `nowMs`, unless the run is truncated or the
+ * entry would break a limit, in which case recording stops instead.
+ */
+function restore(state, nowMs) {
+    const last = lastOf(state);
+    if (!last)
+        return unchanged(state);
+    let current = state;
+    if (last.exited_at === null || (state.provisionalExit && !state.truncated)) {
+        const provisional = last.exited_at !== null ? Date.parse(last.exited_at) : -Infinity;
+        const steps = state.steps.slice();
+        steps[steps.length - 1] = { ...last, exited_at: (0, time_1.toTimestamp)(Math.max(state.lastActiveAt, provisional)) };
+        current = { ...state, steps, provisionalExit: false };
+    }
+    current = { ...current, lastActiveAt: nowMs };
+    if (current.truncated)
+        return { state: current, changed: true, notes: [] };
+    if (current.steps.length >= exports.MAX_ENTRIES)
+        return { state: stopRecording(current), changed: true, notes: ["truncated"] };
+    const next = {
+        ...current,
+        steps: [...current.steps, { step_key: last.step_key, entered_at: (0, time_1.toTimestamp)(nowMs), exited_at: null, answers: [] }],
+    };
+    if (!fits(next, nowMs))
+        return { state: stopRecording(current), changed: true, notes: ["truncated"] };
+    return { state: next, changed: true, notes: [] };
+}
+/** The latest moment recorded in the run, so a clock set backwards cannot make timestamps go back. */
+function floorMs(state) {
+    const last = lastOf(state);
+    let floor = 0;
+    if (last) {
+        floor = Date.parse(last.entered_at);
+        if (last.exited_at)
+            floor = Math.max(floor, Date.parse(last.exited_at));
+    }
+    return floor;
+}
+//# sourceMappingURL=state.js.map

package/dist/onboarding/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../src/onboarding/state.ts"],"names":[],"mappings":"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"}

package/dist/onboarding/tracker.d.ts

@@ -0,0 +1,135 @@
+import { type RunContextInput } from "../core/context";
+import { type RetryPolicy } from "../core/delivery";
+import { type DiagnosticHandler } from "../core/diagnostics";
+import type { Sink } from "../core/sink";
+import { type KeyValueStorage } from "../core/storage";
+import { type Clock, type Timers } from "../core/time";
+import type { OnboardingRunSnapshot, Properties } from "./contract";
+import { type AnswerInput, type StartOptions } from "./input";
+export interface TrackerConfig {
+    /** Where snapshots go. `createHttpSink` is the stock one. */
+    sink: Sink<OnboardingRunSnapshot>;
+    /** Device and app facts, or a function returning them, read once per run at start. */
+    context: RunContextInput | (() => RunContextInput);
+    /**
+     * Persists the run so it can be resumed after the app is killed, and keeps an
+     * unsent snapshot across restarts. AsyncStorage fits as is. Without it,
+     * nothing survives a restart, and `resume()` resolves null unless a tracker
+     * disposed in this process on the same `storageKey` handed it a run.
+     */
+    storage?: KeyValueStorage;
+    /** Storage key. Default `rocalytics-sdk:onboarding-run`. One restorable run per key. */
+    storageKey?: string;
+    clock?: Clock;
+    timers?: Timers;
+    /** Run id minter. Must return a lowercase UUID. Default: UUIDv7. */
+    uuid?: () => string;
+    /**
+     * Changes within this window go out as one send. Default 500 ms. Completion
+     * and background skip the debounce, but with `storage` every send, these
+     * included, first waits for its snapshot to be written: up to
+     * `persistTimeoutMs` (default 1,000 ms) later.
+     */
+    debounceMs?: number;
+    retry?: RetryPolicy;
+    /** A send with no answer after this long is retried. Default 30,000 ms. */
+    attemptTimeoutMs?: number;
+    /**
+     * Each snapshot is stored (with its seq) before it is handed to the sink, so
+     * a kill in between can never make a resumed run reuse that seq for a
+     * different body. A storage slower than this does not hold the send back any
+     * longer: it goes out anyway, and only then can a kill in that window cost
+     * the guarantee. Default 1,000 ms. Ignored without `storage`.
+     */
+    persistTimeoutMs?: number;
+    /**
+     * How long a storage read may take before it is reported as slow. It does
+     * not cut `resume()` short: `resume()` waits for the read however long it
+     * takes. It bounds `idle()`, which waits at most this long for the read and
+     * as long again for queued writes, so up to about twice this; and with it,
+     * how long a tracker created after a `dispose()` on the same `storageKey`
+     * waits for the disposed one's writes before it reads. `start()` never waits
+     * for the read. Default 5,000 ms.
+     */
+    storageReadTimeoutMs?: number;
+    /** Receives what the tracker declined to do. Default: `console.warn`. */
+    onDiagnostic?: DiagnosticHandler;
+}
+export interface ExitOptions {
+    /** What was answered on this visit. Values are stable option keys, never displayed labels. */
+    answers?: AnswerInput[];
+}
+/** One pass through an onboarding. Every method is safe to call at any time and never throws. */
+export interface OnboardingRun {
+    /** Lowercase UUID, minted when the run starts. */
+    readonly runId: string;
+    /**
+     * The step of the last RECORDED entry; null before the first step. In a
+     * truncated run recording has stopped, so this can be an earlier screen than
+     * the one the user was on: restore the position from the app's own
+     * navigation state, not from this.
+     */
+    readonly currentStepKey: string | null;
+    /** A screen is shown. Call it again for the same step after going back to it. */
+    enterStep(stepKey: string): void;
+    /** The user leaves a screen, with what they answered there. */
+    exitStep(stepKey: string, options?: ExitOptions): void;
+    /** Adds or changes run properties. */
+    setProperties(properties: Properties): void;
+    /** The onboarding is finished. Final: the run records nothing after it. */
+    complete(): void;
+    /** The app moved to the background: records the moment and sends now. */
+    background(): void;
+}
+export interface OnboardingRunTracker {
+    /** Starts a new run. A run already in progress is left as it is, and stays in progress (a replay is a new run). */
+    start(options: StartOptions): OnboardingRun;
+    /**
+     * Resumes the run that was in progress when the app was killed, or resolves
+     * null. Call it only when the app restores the user's position; otherwise
+     * call `start`. The restored screen is recorded as a new entry for the last
+     * recorded step. A truncated run is still returned (so it can complete) but
+     * records no new entry. Null once a run was started this session.
+     *
+     * After a reconfigure, the run is the one the disposed tracker on this
+     * `storageKey` was recording, in its newest state, with storage or without;
+     * null if that tracker completed it or started another.
+     *
+     * It waits for the stored state to be read, however long that takes: a
+     * storage that never answers the read means it never resolves. An app that
+     * cannot wait should race it with its own timeout and call `start` instead.
+     */
+    resume(): Promise<OnboardingRun | null>;
+    /** Resolves once queued storage writes are done. */
+    idle(): Promise<void>;
+    /**
+     * Stops recording without dropping what was recorded: a change on the
+     * debounce is sent, writes already queued land, and each unsent snapshot
+     * gets one last attempt (no retry timers). One the sink does not take is
+     * handed, in memory, to the next tracker created on the same `storageKey`
+     * (as `configure()` does), which sends it with its own sink and retries,
+     * with or without storage, provided its sink has the same `destination`
+     * (or, without one, is the same object). That tracker keeps this one's
+     * unsent snapshots in its writes from the start, sends none of them until
+     * these last attempts are answered, and drops any they delivered. A tracker
+     * disposed without a run of its own passes on what it was handed. With
+     * working storage the snapshot also stays stored for the next launch;
+     * without it, a snapshot is lost if the app is killed before a next tracker
+     * is created. Safe to call twice.
+     */
+    dispose(): void;
+}
+export declare function createOnboardingRunTracker(config: TrackerConfig): OnboardingRunTracker;
+/**
+ * The app-wide tracker. Call `configure` once at startup, then `start` (or
+ * `resume`) for each run. Before `configure`, `start` returns a run that
+ * records nothing, and warns.
+ */
+export declare const onboardingRun: {
+    configure(config: TrackerConfig): void;
+    start(options: StartOptions): OnboardingRun;
+    resume(): Promise<OnboardingRun | null>;
+    idle(): Promise<void>;
+    dispose(): void;
+};
+//# sourceMappingURL=tracker.d.ts.map

package/dist/onboarding/tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracker.d.ts","sourceRoot":"","sources":["../../src/onboarding/tracker.ts"],"names":[],"mappings":"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"}