@rocapine/rocalytics-sdk 0.0.0-stage → 0.3.0

package/src/paywall/contract.ts

@@ -0,0 +1,73 @@
+// Paywall presentation contract v1: the payload types.
+// Normative text: docs/paywall-presentation-contract.md. src/paywall/contract.ts
+// is this file, byte for byte, except its import line (test/paywall-docs.test.ts).
+import type { RunContext, Timestamp } from "../onboarding/contract";
+
+export type PresentationStatus = "in_progress" | "ended";
+export type PresentationOutcomeStatus = "purchased" | "dismissed" | "cancelled" | "error";
+export type PresentationSurface = "present" | "paywall_step";
+
+export interface PresentationPaywall {
+  /** The moment's key: what the host passed to `present()`. */
+  moment_key: string;
+  /** The Studio paywall id the moment's audience waterfall picked. */
+  paywall_id: string;
+  /** The audience that matched; null when the catalog carried none. */
+  audience_id: string | null;
+  render_mode: "elements" | "custom";
+  billing: "store" | "stripe";
+  variant_key?: string;
+  deployment_id?: string;
+}
+
+export interface PresentationTransaction {
+  /**
+   * The exact value the app passes to Rocalytics' `purchase` call (`originalTransactionIdentifier`).
+   * iOS: StoreKit's original transaction id, the join key to the store-notification rows.
+   * Android: the Play order id (GPA.…); not used to join.
+   */
+  original_transaction_identifier?: string;
+  /** Android only: the Play purchase token, the proceeds join key on Android. */
+  purchase_token?: string;
+  product_id?: string;
+  /** True when the purchase only restored existing access (a restore, a web redemption). Not a conversion. */
+  restored?: boolean;
+}
+
+export interface PresentationOutcome {
+  status: PresentationOutcomeStatus;
+  /** Only with status "error": the SDK's reason, e.g. "render-error". */
+  reason?: string;
+  /** Only with status "purchased". Absent when the host reported none. */
+  transaction?: PresentationTransaction;
+}
+
+interface PresentationBase {
+  schema_version: 1;
+  /** Client-minted, lowercase UUID. One per presentation. */
+  presentation_id: string;
+  /** Starts at 1 and increases with every send of this presentation. */
+  seq: number;
+  started_at: Timestamp;
+  shown_at: Timestamp | null;
+  sent_at: Timestamp;
+  paywall: PresentationPaywall;
+  surface: PresentationSurface;
+  /** Only for surface "paywall_step": the onboarding run it sits in. */
+  onboarding_run?: { run_id: string; step_key: string };
+  context: RunContext;
+}
+
+export interface InProgressPresentationSnapshot extends PresentationBase {
+  status: "in_progress";
+  ended_at: null;
+  outcome: null;
+}
+
+export interface EndedPresentationSnapshot extends PresentationBase {
+  status: "ended";
+  ended_at: Timestamp;
+  outcome: PresentationOutcome;
+}
+
+export type PaywallPresentationSnapshot = InProgressPresentationSnapshot | EndedPresentationSnapshot;

package/src/paywall/index.ts

@@ -0,0 +1,36 @@
+// @rocapine/rocalytics-sdk/paywall: the paywall presentation tracker.
+//
+// Reports each paywall presentation as snapshots in the shape of the paywall
+// presentation contract v1 (docs/paywall-presentation-contract.md). Pass the
+// tracker to the paywall host as its `observer`. Headless: no dependency.
+
+export { createPaywallTracker, DEFAULT_PAYWALL_STORAGE_KEY, MAX_STORED_PRESENTATIONS } from "./tracker";
+export type { PaywallTracker, PaywallTrackerConfig } from "./tracker";
+export type {
+  PaywallObserver,
+  PaywallPresentationEnd,
+  PaywallPresentationHandle,
+  PaywallPresentationInfo,
+  PaywallSurface,
+  PaywallTransactionInfo,
+} from "./observer";
+export { LIBRARY_VERSION } from "../version";
+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";
+export type {
+  EndedPresentationSnapshot,
+  InProgressPresentationSnapshot,
+  PaywallPresentationSnapshot,
+  PresentationOutcome,
+  PresentationOutcomeStatus,
+  PresentationPaywall,
+  PresentationStatus,
+  PresentationSurface,
+  PresentationTransaction,
+} from "./contract";

package/src/paywall/observer.ts

@@ -0,0 +1,43 @@
+// The observer a paywall host calls, mirrored here so this package imports
+// nothing from the host SDK: createPaywallTracker() satisfies it structurally.
+// Names are those of the host SDK's PaywallObserver, verbatim.
+
+export type PaywallSurface = "present" | "paywall_step";
+
+export interface PaywallPresentationInfo {
+  moment: string;
+  paywallId: string;
+  audienceId: string | null;
+  renderMode: "elements" | "custom";
+  billing: "store" | "stripe";
+  surface: PaywallSurface;
+  variantKey?: string;
+  deploymentId?: string;
+  onboardingRun?: { runId: string; stepKey: string };
+}
+
+export interface PaywallTransactionInfo {
+  /** The exact value the app passes to Rocalytics' `purchase` call: iOS StoreKit original transaction id (iOS join key); Android Play order id (GPA.…). */
+  originalTransactionIdentifier?: string;
+  /** Android only: the Play purchase token (RevenueCat `transaction.purchaseToken`). Android join key. */
+  purchaseToken?: string;
+  productId?: string;
+  /** True when the purchase only restored existing access. Not a conversion. */
+  restored?: boolean;
+}
+
+export interface PaywallPresentationEnd {
+  status: "purchased" | "dismissed" | "cancelled" | "error";
+  /** The host SDK's error reason; accepted as any string. */
+  reason?: string;
+  transaction?: PaywallTransactionInfo;
+}
+
+export interface PaywallPresentationHandle {
+  shown(): void;
+  end(outcome: PaywallPresentationEnd): void;
+}
+
+export interface PaywallObserver {
+  start(info: PaywallPresentationInfo): PaywallPresentationHandle | void;
+}

package/src/paywall/state.ts

@@ -0,0 +1,125 @@
+import type { WireRunContext } from "../core/context";
+import { toTimestamp } from "../core/time";
+import type { PaywallPresentationSnapshot, PresentationOutcome, PresentationPaywall, PresentationTransaction } from "./contract";
+import type { PaywallPresentationEnd, PaywallPresentationInfo, PaywallTransactionInfo } from "./observer";
+
+const OUTCOMES = new Set(["purchased", "dismissed", "cancelled", "error"]);
+const id = (v: unknown) => typeof v === "string" && v.length >= 1 && v.length <= 128;
+const storeId = (v: unknown): v is string => typeof v === "string" && v.length >= 1 && v.length <= 1024;
+const KEY = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+/** Problems that would make the snapshot fail the schema. Empty when the info is usable. */
+export function validateInfo(info: unknown): string[] {
+  if (!info || typeof info !== "object") return ["info is not an object"];
+  const i = info as Record<string, unknown>;
+  const errors: string[] = [];
+  if (!id(i.moment)) errors.push("moment must be 1 to 128 characters");
+  if (!id(i.paywallId)) errors.push("paywallId must be 1 to 128 characters");
+  if (i.audienceId !== null && !id(i.audienceId)) errors.push("audienceId must be null or 1 to 128 characters");
+  if (i.renderMode !== "elements" && i.renderMode !== "custom") errors.push("renderMode must be elements or custom");
+  if (i.billing !== "store" && i.billing !== "stripe") errors.push("billing must be store or stripe");
+  if (i.surface !== "present" && i.surface !== "paywall_step") errors.push("surface must be present or paywall_step");
+  if (i.variantKey !== undefined && !id(i.variantKey)) errors.push("variantKey must be 1 to 128 characters");
+  if (i.deploymentId !== undefined && !id(i.deploymentId)) errors.push("deploymentId must be 1 to 128 characters");
+  const run = i.onboardingRun as { runId?: unknown; stepKey?: unknown } | undefined;
+  if (run !== undefined && (typeof run !== "object" || run === null || typeof run.runId !== "string" || !UUID.test(run.runId) || typeof run.stepKey !== "string" || !KEY.test(run.stepKey))) {
+    errors.push("onboardingRun must be { runId: lowercase UUID, stepKey: key }");
+  }
+  return errors;
+}
+
+export interface PresentationState {
+  readonly id: string;
+  seq: number;
+  readonly startedAt: number;
+  shownAt: number | null;
+  endedAt: number | null;
+  outcome: PresentationOutcome | null;
+  readonly paywall: PresentationPaywall;
+  readonly surface: "present" | "paywall_step";
+  readonly onboardingRun?: { run_id: string; step_key: string };
+  readonly context: WireRunContext;
+}
+
+export function createState(info: PaywallPresentationInfo, presentationId: string, nowMs: number, context: WireRunContext): PresentationState {
+  const paywall: PresentationPaywall = {
+    moment_key: info.moment,
+    paywall_id: info.paywallId,
+    audience_id: info.audienceId,
+    render_mode: info.renderMode,
+    billing: info.billing,
+  };
+  if (info.variantKey !== undefined) paywall.variant_key = info.variantKey;
+  if (info.deploymentId !== undefined) paywall.deployment_id = info.deploymentId;
+  return {
+    id: presentationId,
+    seq: 0,
+    startedAt: nowMs,
+    shownAt: null,
+    endedAt: null,
+    outcome: null,
+    paywall,
+    surface: info.surface,
+    ...(info.surface === "paywall_step" && info.onboardingRun
+      ? { onboardingRun: { run_id: info.onboardingRun.runId, step_key: info.onboardingRun.stepKey } }
+      : {}),
+    context,
+  };
+}
+
+/** The latest timestamp recorded so far: the floor for the next one. */
+const floor = (s: PresentationState) => Math.max(s.startedAt, s.shownAt ?? s.startedAt, s.endedAt ?? s.startedAt);
+
+export function markShown(s: PresentationState, nowMs: number): "ok" | "already-shown" | "after-end" {
+  if (s.endedAt !== null) return "after-end";
+  if (s.shownAt !== null) return "already-shown";
+  s.shownAt = Math.max(nowMs, floor(s));
+  return "ok";
+}
+
+function toTransaction(t: PaywallTransactionInfo | undefined): PresentationTransaction | undefined {
+  if (!t || typeof t !== "object") return undefined;
+  const out: PresentationTransaction = {};
+  if (storeId(t.originalTransactionIdentifier)) out.original_transaction_identifier = t.originalTransactionIdentifier;
+  if (storeId(t.purchaseToken)) out.purchase_token = t.purchaseToken;
+  if (storeId(t.productId)) out.product_id = t.productId;
+  if (t.restored === true) out.restored = true;
+  return Object.keys(out).length ? out : undefined;
+}
+
+export function markEnded(s: PresentationState, end: PaywallPresentationEnd, nowMs: number): "ok" | "already-ended" | "invalid-status" {
+  if (s.endedAt !== null) return "already-ended";
+  if (!end || !OUTCOMES.has(end.status)) return "invalid-status";
+  const outcome: PresentationOutcome = { status: end.status };
+  if (end.status === "error" && typeof end.reason === "string" && KEY.test(end.reason)) outcome.reason = end.reason;
+  if (end.status === "purchased") {
+    const t = toTransaction(end.transaction);
+    if (t) outcome.transaction = t;
+  }
+  s.endedAt = Math.max(nowMs, floor(s));
+  // A purchase implies the paywall was on screen (P7): the contract requires shown_at with purchased.
+  if (end.status === "purchased" && s.shownAt === null) s.shownAt = s.endedAt;
+  s.outcome = outcome;
+  return "ok";
+}
+
+/** The next send: increments seq. */
+export function toSnapshot(s: PresentationState, nowMs: number): PaywallPresentationSnapshot {
+  s.seq += 1;
+  const base = {
+    schema_version: 1 as const,
+    presentation_id: s.id,
+    seq: s.seq,
+    started_at: toTimestamp(s.startedAt),
+    shown_at: s.shownAt === null ? null : toTimestamp(s.shownAt),
+    sent_at: toTimestamp(Math.max(nowMs, floor(s))),
+    paywall: { ...s.paywall },
+    surface: s.surface,
+    ...(s.onboardingRun ? { onboarding_run: { ...s.onboardingRun } } : {}),
+    context: { ...s.context },
+  };
+  return s.endedAt !== null && s.outcome !== null
+    ? { ...base, status: "ended", ended_at: toTimestamp(s.endedAt), outcome: { ...s.outcome } }
+    : { ...base, status: "in_progress", ended_at: null, outcome: null };
+}

package/src/paywall/tracker.ts

@@ -0,0 +1,200 @@
+import { captureRunContext, type RunContextInput } from "../core/context";
+import { createDelivery, type Delivery, type Outbound, type RetryPolicy } from "../core/delivery";
+import { safeDiagnostics, type DiagnosticHandler } from "../core/diagnostics";
+import { createUuid } from "../core/ids";
+import type { Sink } from "../core/sink";
+import { createSerialStore, type KeyValueStorage, type SerialStore } from "../core/storage";
+import { systemClock, systemTimers, type Clock, type Timers } from "../core/time";
+import { LIBRARY_VERSION } from "../version";
+import type { PaywallPresentationSnapshot } from "./contract";
+import type { PaywallPresentationEnd, PaywallPresentationHandle, PaywallPresentationInfo } from "./observer";
+import { createState, markEnded, markShown, toSnapshot, validateInfo, type PresentationState } from "./state";
+
+export const DEFAULT_PAYWALL_STORAGE_KEY = "rocalytics-sdk:paywall-presentations";
+export const MAX_STORED_PRESENTATIONS = 20;
+
+export interface PaywallTrackerConfig {
+  /** Where snapshots go: `createRocalyticsPaywallSink(client)` from /client, or `createHttpSink`. */
+  sink: Sink<PaywallPresentationSnapshot>;
+  /** Device and app facts, or a function returning them, read once per presentation. */
+  context: RunContextInput | (() => RunContextInput);
+  /** Keeps unsent snapshots across restarts. AsyncStorage fits as is. */
+  storage?: KeyValueStorage;
+  storageKey?: string;
+  clock?: Clock;
+  timers?: Timers;
+  /** Presentation id minter. Must return a lowercase UUID. Default: UUIDv7. */
+  uuid?: () => string;
+  retry?: RetryPolicy;
+  attemptTimeoutMs?: number;
+  onDiagnostic?: DiagnosticHandler;
+}
+
+/** Satisfies the host SDK's `PaywallObserver`: pass it as `observer`. Never throws. */
+export interface PaywallTracker {
+  start(info: PaywallPresentationInfo): PaywallPresentationHandle | undefined;
+  /** Resolves once queued storage writes are done. */
+  idle(): Promise<void>;
+  /** Stops retry timers. Unsent snapshots stay stored for the next launch. */
+  dispose(): void;
+}
+
+type Stored = Record<string, Outbound<PaywallPresentationSnapshot>>;
+
+export function createPaywallTracker(config: PaywallTrackerConfig): PaywallTracker {
+  const report = safeDiagnostics(config.onDiagnostic);
+  const clock = config.clock ?? systemClock;
+  const timers = config.timers ?? systemTimers;
+  const uuid = config.uuid ?? createUuid(clock);
+  const store: SerialStore<Stored> | null = config.storage
+    ? createSerialStore<Stored>(config.storage, config.storageKey ?? DEFAULT_PAYWALL_STORAGE_KEY, (e) =>
+        report({ code: "storage", message: String(e) }),
+      )
+    : null;
+  const pending = new Map<string, Outbound<PaywallPresentationSnapshot>>();
+  const deliveries = new Map<string, Delivery<PaywallPresentationSnapshot>>();
+  let disposed = false;
+  // Off when the first read failed: stored state is then left untouched, never overwritten.
+  let persistenceOff = false;
+  // Writes wait for the first read, so a start() at launch cannot overwrite the stored map.
+  const loaded: Promise<Stored | null> = store
+    ? store
+        .read()
+        .then((r) => {
+          if (r.status === "ok") return r.value;
+          if (r.status === "failed") {
+            persistenceOff = true;
+            report({ code: "storage", message: `reading stored presentations failed (${String(r.error)}): left untouched; this session runs without persistence` });
+          } else report({ code: "invalid-stored", message: "stored presentations are not JSON; ignored" });
+          return null;
+        })
+        .catch(() => null)
+    : Promise.resolve(null);
+
+  const persist = () => {
+    if (!store || persistenceOff) return;
+    if (pending.size > MAX_STORED_PRESENTATIONS) {
+      const oldest = [...pending.values()].sort((a, b) => a.body.started_at.localeCompare(b.body.started_at));
+      for (const o of oldest.slice(0, pending.size - MAX_STORED_PRESENTATIONS)) {
+        pending.delete(o.body.presentation_id);
+        report({ code: "storage-cap", message: `dropped unsent presentation ${o.body.presentation_id} from storage` });
+      }
+    }
+    // The map is built when the write's turn comes, not now: a write queued at launch
+    // must include the entries the initial read restores in the meantime.
+    void loaded.then(() => {
+      if (!persistenceOff) return store.saveWith(() => (pending.size ? Object.fromEntries(pending) : null));
+    });
+  };
+
+  const deliveryFor = (presentationId: string): Delivery<PaywallPresentationSnapshot> => {
+    let d = deliveries.get(presentationId);
+    if (d) return d;
+    d = createDelivery<PaywallPresentationSnapshot>({
+      sink: config.sink,
+      timers,
+      retry: config.retry,
+      attemptTimeoutMs: config.attemptTimeoutMs,
+      onSettled: (item, result) => {
+        if (result.outcome === "rejected") {
+          report({ code: "rejected", message: `snapshot ${item.seq} rejected${result.reason ? `: ${result.reason}` : ""}` });
+        }
+      },
+      onPendingChange: (p) => {
+        if (p) pending.set(presentationId, p);
+        else {
+          pending.delete(presentationId);
+          deliveries.get(presentationId)?.stop();
+          deliveries.delete(presentationId);
+        }
+        persist();
+      },
+    });
+    deliveries.set(presentationId, d);
+    return d;
+  };
+
+  const isOutbound = (v: unknown): v is Outbound<PaywallPresentationSnapshot> => {
+    const o = v as { seq?: unknown; body?: { presentation_id?: unknown; seq?: unknown } } | null;
+    return !!o && typeof o.seq === "number" && !!o.body && typeof o.body === "object"
+      && typeof o.body.presentation_id === "string" && o.body.seq === o.seq;
+  };
+
+  if (store) {
+    void loaded.then((stored) => {
+      if (disposed || !stored || typeof stored !== "object") return;
+      for (const [id, item] of Object.entries(stored)) {
+        if (!isOutbound(item) || item.body.presentation_id !== id) {
+          report({ code: "invalid-stored", message: `ignored stored entry ${id}` });
+          continue;
+        }
+        if (deliveries.has(id)) continue;
+        deliveryFor(id).enqueue(item);
+      }
+    }).catch((e) => report({ code: "internal", message: String(e) }));
+  }
+
+  const send = (s: PresentationState) => {
+    if (disposed) return;
+    const body = toSnapshot(s, clock.now());
+    deliveryFor(s.id).enqueue({ seq: body.seq, body });
+  };
+
+  const guard = (fn: () => void) => {
+    try {
+      fn();
+    } catch (e) {
+      report({ code: "internal", message: String(e) });
+    }
+  };
+
+  const handle = (s: PresentationState): PaywallPresentationHandle => ({
+    shown: () =>
+      guard(() => {
+        const r = markShown(s, clock.now());
+        if (r === "ok") send(s);
+        else report({ code: r, message: `shown() ignored: ${r}`, runId: s.id });
+      }),
+    end: (outcome: PaywallPresentationEnd) =>
+      guard(() => {
+        const r = markEnded(s, outcome, clock.now());
+        if (r === "ok") send(s);
+        else report({ code: r, message: `end() ignored: ${r}`, runId: s.id });
+      }),
+  });
+
+  return {
+    start(info) {
+      try {
+        const problems = validateInfo(info);
+        if (problems.length) {
+          report({ code: "invalid-info", message: problems.join("; ") });
+          return undefined;
+        }
+        let input: RunContextInput;
+        try {
+          input = typeof config.context === "function" ? config.context() : config.context;
+        } catch (e) {
+          report({ code: "invalid-context", message: String(e) });
+          return undefined;
+        }
+        const captured = captureRunContext(input, LIBRARY_VERSION);
+        if (!captured.ok) {
+          report({ code: "invalid-context", message: captured.errors.join("; ") });
+          return undefined;
+        }
+        const s = createState(info, uuid(), clock.now(), captured.context);
+        send(s);
+        return handle(s);
+      } catch (e) {
+        report({ code: "internal", message: String(e) });
+        return undefined;
+      }
+    },
+    idle: () => (store ? store.idle() : Promise.resolve()),
+    dispose() {
+      disposed = true;
+      for (const d of deliveries.values()) d.stop();
+    },
+  };
+}

package/src/version.ts

@@ -0,0 +1,2 @@
+/** This package's version, sent as `context.library_version`. A test keeps it equal to package.json. */
+export const LIBRARY_VERSION = "0.3.0";