@rocapine/rocalytics-sdk 0.0.0-stage → 0.3.0

package/src/client/onboardingSink.ts

@@ -0,0 +1,121 @@
+import type { SinkResult, Sink } from "../core/sink";
+import type { Answer, OnboardingRunSnapshot } from "../onboarding/contract";
+import type { RocalyticsClient } from "./client";
+import type { OnboardingMetadata, OnboardingResponsePayload, OnboardingStepAnswers } from "./types";
+
+/**
+ * A v1 onboarding run snapshot in the pre-v1 `/onboarding-response` shape,
+ * which is the only onboarding payload the Rocalytics ingest reads. The keys
+ * follow docs/onboarding-run-contract.md, section 9, which is how the ingest
+ * reads such a payload back into a run.
+ *
+ * - Each entry is a response: `step_key` becomes `step_id`, timestamps are kept.
+ * - Answers become `{ [question_key]: value }`. A numeric answer's `unit` has
+ *   no place in that shape and is dropped.
+ * - `onboarding_metadata` carries the keys section 9 reads: `onboardingId`
+ *   (the Studio onboarding) or, with none, `onboarding_id` (the onboarding
+ *   key, as a hand-coded sender sets it), `audienceId`, `deployment_id`,
+ *   `locale` (from the run's context) and `draft: true` for a draft. It also
+ *   carries `onboarding_key`, `onboarding_version`, `variant_key`, `run_id`
+ *   and `seq`, which section 9 does not read.
+ * - `sent_at` is NOT the device's send time. The ingest keeps one snapshot
+ *   per sender and replaces it only when the incoming `sent_at` is strictly
+ *   later, answering 2xx either way, so two sends in one millisecond, or a
+ *   device clock stepping back, would drop a snapshot (the completion
+ *   included) while it reads as delivered. So `sent_at` is the run's latest
+ *   recorded timestamp plus `seq` milliseconds. A snapshot only ever adds
+ *   timestamps to the one before it and `seq` rises with every send, so this
+ *   strictly increases across a run's sends whatever the device clock does.
+ *   Only within a run: the ingest keeps one row per sender, so after the
+ *   clock steps back between runs, a later run's snapshots can still be
+ *   dropped while answered 2xx, as pre-v1 reporting already could.
+ *   It depends on the snapshot alone, so a retry, even after a relaunch,
+ *   resends the identical body.
+ */
+export function toOnboardingResponsePayload(snapshot: OnboardingRunSnapshot): OnboardingResponsePayload {
+  const metadata: OnboardingMetadata = {};
+  const set = (key: string, value: unknown) => {
+    if (value !== undefined && value !== null) metadata[key] = value;
+  };
+  const studioOnboardingId = snapshot.studio?.onboarding_id;
+  if (studioOnboardingId != null) set("onboardingId", studioOnboardingId);
+  else set("onboarding_id", snapshot.onboarding.key);
+  set("audienceId", snapshot.studio?.audience_id);
+  set("deployment_id", snapshot.studio?.deployment_id);
+  set("locale", snapshot.context.locale);
+  if (snapshot.onboarding.version === "draft") set("draft", true);
+  set("onboarding_key", snapshot.onboarding.key);
+  set("onboarding_version", snapshot.onboarding.version);
+  set("variant_key", snapshot.onboarding.variant_key);
+  set("run_id", snapshot.run_id);
+  set("seq", snapshot.seq);
+  return {
+    onboarding_metadata: metadata,
+    sent_at: new Date(latestRecorded(snapshot) + snapshot.seq).toISOString(),
+    responses: snapshot.steps.map((entry) => ({
+      step_id: entry.step_key,
+      entered_at: entry.entered_at,
+      exited_at: entry.exited_at,
+      answers: toAnswers(entry.answers),
+    })),
+  };
+}
+
+/** The latest timestamp the run has recorded: its start, entries, exits and completion. Not `sent_at`. */
+function latestRecorded(snapshot: OnboardingRunSnapshot): number {
+  let latest = Date.parse(snapshot.started_at);
+  const consider = (ts: string | null) => {
+    if (ts !== null) latest = Math.max(latest, Date.parse(ts));
+  };
+  for (const entry of snapshot.steps) {
+    consider(entry.entered_at);
+    consider(entry.exited_at);
+  }
+  consider(snapshot.completed_at);
+  return latest;
+}
+
+function toAnswers(answers: Answer[]): OnboardingStepAnswers {
+  const out: OnboardingStepAnswers = {};
+  for (const answer of answers) out[answer.question_key] = Array.isArray(answer.value) ? [...answer.value] : answer.value;
+  return out;
+}
+
+/**
+ * Reads an `/onboarding-response` answer as a sink outcome. The endpoint
+ * answers success with a 2xx and no body, so a 2xx is accepted. Otherwise,
+ * as the contract's section 5 requires, only a body that says
+ * `{"outcome": "rejected"}` is permanent: every other status, whatever its
+ * body, is transient and the snapshot is retried.
+ */
+export function rocalyticsOutcome(status: number, body?: unknown): SinkResult {
+  if (status >= 200 && status < 300) return { outcome: "accepted" };
+  if (body && typeof body === "object" && (body as { outcome?: unknown }).outcome === "rejected") {
+    const reason = (body as { reason?: unknown }).reason;
+    return typeof reason === "string" ? { outcome: "rejected", reason } : { outcome: "rejected" };
+  }
+  return { outcome: "transient", reason: `status ${status}` };
+}
+
+/**
+ * A sink for the onboarding run tracker (`@rocapine/rocalytics-sdk/onboarding`)
+ * that delivers each snapshot to Rocalytics through `client`, as the pre-v1
+ * onboarding payload (see `toOnboardingResponsePayload`).
+ *
+ * Once a completed snapshot is accepted, the sink also sends the
+ * `onboarding_completed` event, which is where consumers of the pre-v1 data
+ * read completion from. It is deduplicated per device, like any `track`
+ * event; if it fails, the send is transient, so the tracker's retry sends it.
+ *
+ * The ingest keeps one onboarding snapshot per roca id, so a new run replaces
+ * the previous one there, and an app should report a flow through this sink
+ * or through `client.trackOnboarding`, not both.
+ *
+ * While the client is inert every send is transient: the tracker keeps the
+ * snapshot, persisted when it has storage, for a launch where the client works.
+ *
+ * Its `destination` is the client's `onboardingRunDestination`.
+ */
+export function createRocalyticsOnboardingSink(client: RocalyticsClient): Sink<OnboardingRunSnapshot> {
+  return { destination: client.onboardingRunDestination, send: (snapshot) => client.sendOnboardingRun(snapshot) };
+}

package/src/client/paywallSink.ts

@@ -0,0 +1,25 @@
+import type { Sink, SinkResult } from "../core/sink";
+import type { PaywallPresentationSnapshot } from "../paywall/contract";
+import type { RocalyticsClient } from "./client";
+
+const OUTCOMES = new Set(["accepted", "ignored", "rejected"]);
+
+/**
+ * Reads a `/paywall-presentations` answer per the paywall contract's section 5
+ * (onboarding D27): the body's `outcome` decides. A rejected body is permanent
+ * whatever the status. Accepted or ignored counts only on a 2xx. Anything
+ * else, including a 2xx without an outcome, is transient and retried.
+ */
+export function paywallIngestOutcome(status: number, body?: unknown): SinkResult {
+  const o = body && typeof body === "object" ? (body as { outcome?: unknown; reason?: unknown }) : undefined;
+  const outcome = typeof o?.outcome === "string" && OUTCOMES.has(o.outcome) ? (o.outcome as "accepted" | "ignored" | "rejected") : undefined;
+  const reason = typeof o?.reason === "string" ? o.reason : undefined;
+  if (outcome === "rejected") return reason ? { outcome, reason } : { outcome };
+  if (outcome && status >= 200 && status < 300) return { outcome };
+  return { outcome: "transient", reason: `status ${status}` };
+}
+
+/** Delivers the paywall tracker's snapshots to Rocalytics. Its `destination` is the client's `paywallPresentationDestination`. */
+export function createRocalyticsPaywallSink(client: RocalyticsClient): Sink<PaywallPresentationSnapshot> {
+  return { destination: client.paywallPresentationDestination, send: (s) => client.sendPaywallPresentation(s) };
+}

package/src/client/requests.ts

@@ -0,0 +1,126 @@
+import type { DemandScoreSignals, IdentifyParams, OnboardingResponsePayload } from "./types";
+import type { PaywallPresentationSnapshot } from "../paywall/contract";
+
+export const ROCALYTICS_API_BASE = "https://rocalytics-api.rocapine.io";
+
+/** What every request carries: the device's roca id, the app id and the platform. There is no auth token. */
+export interface RequestContext {
+  rocaId: string;
+  /** The app's bundle id or package name; sent as `unknown` when null. */
+  applicationId: string | null;
+  /** `Platform.OS`. */
+  platform: string;
+  /** Defaults to `ROCALYTICS_API_BASE`. */
+  baseUrl?: string;
+}
+
+/** A request, ready to hand to `fetch(url, init)`. */
+export interface RocalyticsRequest {
+  url: string;
+  init: { method: "POST"; headers: Record<string, string>; body?: string };
+}
+
+export interface FetchResponseLike {
+  ok: boolean;
+  status: number;
+  json(): Promise<unknown>;
+}
+
+/** The subset of `fetch` the client uses. */
+export type FetchLike = (url: string, init: RocalyticsRequest["init"]) => Promise<FetchResponseLike>;
+
+export function rocalyticsHeaders(context: RequestContext): Record<string, string> {
+  return {
+    "Content-Type": "application/json",
+    "X-Roca-ID": context.rocaId,
+    "X-Application-ID": context.applicationId ?? "unknown",
+    "X-Platform": context.platform,
+  };
+}
+
+const post = (context: RequestContext, endpoint: string, body?: unknown): RocalyticsRequest => ({
+  url: `${context.baseUrl ?? ROCALYTICS_API_BASE}/functions/v1/${endpoint}`,
+  init: {
+    method: "POST",
+    headers: rocalyticsHeaders(context),
+    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+  },
+});
+
+/** `/identify`. The payload is sent as given: drop null identifiers first (the client does). */
+export function buildIdentifyRequest(context: RequestContext, payload: Partial<IdentifyParams>): RocalyticsRequest {
+  return post(context, "identify", payload);
+}
+
+export interface TrackRequestInput {
+  name: string;
+  properties: Record<string, unknown>;
+  deviceContext: Record<string, unknown> | null;
+  /** Defaults to `${rocaId}-${name}`. */
+  deduplicationId?: string;
+  /** A custom event is not stored as an analytics event: the API passes it on to drive automations. */
+  customEvent?: boolean;
+}
+
+/** `/track`. */
+export function buildTrackRequest(context: RequestContext, input: TrackRequestInput): RocalyticsRequest {
+  return post(context, "track", {
+    name: input.name,
+    deduplication_id: input.deduplicationId ?? `${context.rocaId}-${input.name}`,
+    properties: input.properties,
+    device_context: input.deviceContext,
+    ...(input.customEvent ? { custom_event: true } : {}),
+  });
+}
+
+/** `/onboarding-response`. */
+export function buildOnboardingResponseRequest(context: RequestContext, payload: OnboardingResponsePayload): RocalyticsRequest {
+  return post(context, "onboarding-response", payload);
+}
+
+/** `/demand-score`. The body is optional server-side, so none is sent without signals. */
+export function buildDemandScoreRequest(context: RequestContext, signals?: DemandScoreSignals): RocalyticsRequest {
+  return post(context, "demand-score", signals && Object.keys(signals).length > 0 ? signals : undefined);
+}
+
+/**
+ * Sends a request and resolves its response, or rejects with
+ * `[ROCALYTICS] <endpoint> failed: <status>` (plus ` (<detail>)` when given)
+ * when the status is not 2xx.
+ */
+export async function sendRocalyticsRequest(
+  fetch: FetchLike,
+  request: RocalyticsRequest,
+  endpoint: string,
+  detail?: string,
+): Promise<FetchResponseLike> {
+  const response = await fetch(request.url, request.init);
+  if (!response.ok) {
+    throw new Error(`[ROCALYTICS] ${endpoint} failed: ${response.status}${detail ? ` (${detail})` : ""}`);
+  }
+  return response;
+}
+
+/**
+ * The cross-network event id for an event, or `undefined` when its properties
+ * carry no transaction identifier: `${name}-${originalTransactionIdentifier}`.
+ *
+ * Use it as the `event_id` (Meta CAPI or Pixel, TikTok Events API) or
+ * `callback_id` (Adjust S2S) when the app also fires the conversion to those
+ * networks itself. Rocalytics derives the same id when it forwards the event,
+ * so the network deduplicates the two.
+ */
+export function getEventId(name: string, properties?: Record<string, unknown> | null): string | undefined {
+  if (!properties) return undefined;
+  const txId =
+    (properties.original_transaction_identifier as string | undefined) ??
+    (properties.originalTransactionIdentifier as string | undefined) ??
+    (properties.transaction as { originalTransactionIdentifier?: string } | undefined)?.originalTransactionIdentifier;
+  if (!txId) return undefined;
+  return `${name}-${txId}`;
+}
+
+/** `/paywall-presentations` (I3): the body is the bare snapshot; identity is in the headers `post` sets. */
+export function buildPaywallPresentationRequest(context: RequestContext, snapshot: PaywallPresentationSnapshot): RocalyticsRequest {
+  return post(context, "paywall-presentations", snapshot);
+}

package/src/client/types.ts

@@ -0,0 +1,198 @@
+// Wire types of the Rocalytics API, as the client sends and reads them.
+
+/**
+ * Event names `track` accepts. The union of every name the copied clients
+ * allowed; the API rejects a name it does not know. Any other name goes
+ * through `trackCustomEvent`, which the API forwards instead of storing.
+ */
+export type TrackEventName = "install" | "onboarding_completed" | "purchase" | "subscription_started" | "trial_started";
+
+/** Adjust attribution, as the Adjust SDK reports it. */
+export type AdjustAttribution = {
+  trackerToken?: string | null;
+  trackerName?: string | null;
+  network?: string | null;
+  campaign?: string | null;
+  adgroup?: string | null;
+  creative?: string | null;
+  clickLabel?: string | null;
+  adid?: string | null;
+  costType?: string | null;
+  costAmount?: number | null;
+  costCurrency?: string | null;
+  fbInstallReferrer?: string | null;
+};
+
+/** Identifiers for `identify`. Null and undefined values are dropped before sending. */
+export type IdentifyParams = {
+  revenue_cat_id?: string | null;
+  qonversion_id?: string | null;
+  adjust_id?: string | null;
+  adjust_attribution?: AdjustAttribution | null;
+  user_id?: string | null;
+  email?: string | null;
+  amplitude_device_id?: string | null;
+  idfa?: string | null;
+  idfv?: string | null;
+  android_id?: string | null;
+  customerio_id?: string | null;
+  segment_id?: string | null;
+  gaid?: string | null;
+  /** BCP 47 tag of the language the app is shown in. */
+  locale?: string | null;
+};
+
+/**
+ * A store product, from any purchase SDK. Forwarded whole under
+ * `experimental.product`; its `productIdentifier` is the product id when
+ * `productId` is not given.
+ */
+export type PurchaseProduct = object;
+
+/** A store transaction, from any purchase SDK. Forwarded whole under `experimental.transaction`. */
+export type PurchaseTransaction = object;
+
+export type TrackPurchaseParams = {
+  isTrial: boolean;
+  /** The price charged: 0 for a free trial. */
+  value: number;
+  /** ISO 4217 code. */
+  currency: string;
+  /** Links renewals to the first purchase, and keys the event's deduplication id. */
+  originalTransactionIdentifier: string;
+  /** The store product id. Defaults to `product.productIdentifier`. */
+  productId?: string;
+  product?: PurchaseProduct;
+  transaction?: PurchaseTransaction;
+  /** A web-checkout redemption result, for a purchase made outside the store. Forwarded under `experimental.redemption_result`. */
+  redemptionResult?: unknown;
+};
+
+/** Answers given on one onboarding step, by question or element id. */
+export type OnboardingStepAnswers = Record<string, unknown>;
+
+/** Free-form context about which onboarding was shown, e.g. `onboarding_id`, `audience_id`, `deployment_id`. */
+export type OnboardingMetadata = Record<string, unknown>;
+
+export type OnboardingStepResponse = {
+  step_id: string;
+  entered_at: string;
+  /** Null while the user is still on the step. */
+  exited_at: string | null;
+  answers: OnboardingStepAnswers;
+};
+
+/** The body of `/onboarding-response`: every step seen so far, resent whole on each call. */
+export type OnboardingResponsePayload = {
+  onboarding_metadata?: OnboardingMetadata;
+  /** When the snapshot was produced. The API ignores a snapshot older than the one it has. */
+  sent_at: string;
+  responses: OnboardingStepResponse[];
+};
+
+/** Device facts sent with every tracked event. */
+export type DeviceContext = {
+  ip: string | null;
+  user_agent: string;
+  device_model: string | null;
+  device_brand: string | null;
+  device_manufacturer: string | null;
+  os_name: string | null;
+  os_version: string | null;
+  screen_width: number;
+  screen_height: number;
+  screen_scale: number;
+  timezone: string;
+  locale: string;
+  app_version: string | null;
+  app_build: string | null;
+};
+
+/**
+ * Optional client-side signals for the demand score. Anything omitted falls
+ * back server-side or drops out of the score, so send only what the app has;
+ * never invent a value.
+ */
+export type DemandScoreSignals = {
+  /** Native model identifier, e.g. `iPhone15,3`. */
+  device_model?: string;
+  /** Hardware release year. */
+  device_release_year?: number;
+  /** OS version, e.g. `17.4`. Only the major number is read. */
+  os_version?: string;
+  connection_type?: "wifi" | "cellular" | "other";
+  /** Two-letter storefront country, e.g. `US`. */
+  store_country?: string;
+  app_open_count?: number;
+  /** Send 0 only for a real zero: the server reads its own 0 as "not tracked". */
+  paywall_view_count?: number;
+  /** BCP 47 locale, e.g. `en-US`. */
+  locale?: string;
+};
+
+export type DemandScoreSignalScore = {
+  signal: string;
+  /** Normalized 0 to 1 sub-score; null when the signal was unavailable. */
+  value: number | null;
+  weight: number;
+  /** Contribution to the final score after weight renormalization. */
+  weighted: number;
+};
+
+/** Scoring models the endpoint computes. */
+export type DemandScoreVersion = "v1" | "v2";
+
+/** v1: a weighted-signal model over behavioural history and device context. */
+export type DemandScoreV1 = {
+  /** Integer 1 to 100. */
+  score: number;
+  /** True when the identity has no event history yet. */
+  coldStart: boolean;
+  signals: DemandScoreSignalScore[];
+};
+
+export type DemandScoreV2Signal = {
+  signal: string;
+  /** The level looked up, after normalization. */
+  level: string;
+  /** Smoothed conversion rate for that level. */
+  rate: number;
+  /** Contribution to the total, in log-odds. */
+  logOdds: number;
+  /** False when the level was absent from the rates table and the fallback was used. */
+  matched: boolean;
+};
+
+/** v2: a learned-rates scorecard, calibrated to a percentile. */
+export type DemandScoreV2 = {
+  /** Integer 1 to 100. */
+  score: number;
+  /** Raw additive score before calibration. */
+  logOdds: number;
+  /** How many scorecard fields resolved to a known level. */
+  matchedSignals: number;
+  /** `app` when scored with this app's own rates, `portfolio` when it fell back to the pooled table. */
+  ratesSource: "app" | "portfolio";
+  signals: DemandScoreV2Signal[];
+};
+
+/**
+ * The demand score response. `selectedVersion` and `versions` are optional,
+ * and `signals` is kept, so a response from before the score was versioned
+ * still fits.
+ */
+export type DemandScoreResult = {
+  /** Integer 1 to 100: the likelihood this install converts to a paying customer. Mirrors `versions[selectedVersion].score`. */
+  demandScore: number;
+  /** Which version `demandScore` mirrors: a server-side setting. */
+  selectedVersion?: DemandScoreVersion;
+  /** True when the identity has no event history yet. */
+  coldStart: boolean;
+  versions?: {
+    v1: DemandScoreV1;
+    /** Absent when no rates table exists for the app or the portfolio. */
+    v2?: DemandScoreV2;
+  };
+  /** The unversioned response's breakdown. */
+  signals?: DemandScoreSignalScore[];
+};

package/src/core/context.ts

@@ -0,0 +1,69 @@
+import { codePointLength } from "./text";
+
+/**
+ * Device and app facts for a run, supplied by the host (the core reads no
+ * platform API). Captured once when a run starts.
+ */
+export interface RunContextInput {
+  /** Marketing version, e.g. `2.4.0`. */
+  appVersion: string;
+  /** Build number, or null on a platform with none. */
+  build: string | null;
+  platform: "ios" | "android" | "web";
+  /** OS version, or null when the platform cannot report one. */
+  osVersion: string | null;
+  /** BCP 47 tag of the language the flow is shown in, e.g. `fr-FR`. */
+  locale: string;
+  /** IANA time zone, e.g. `Europe/Paris`. */
+  timezone: string;
+}
+
+/** The context in its wire form. Country is deliberately absent: the server derives it. */
+export interface WireRunContext {
+  app_version: string;
+  build: string | null;
+  platform: "ios" | "android" | "web";
+  os_version: string | null;
+  locale: string;
+  timezone: string;
+  library_version?: string;
+}
+
+const LOCALE = /^[A-Za-z]{2,3}(-[A-Za-z0-9]{1,8})*$/;
+const TIMEZONE = /^[A-Za-z][A-Za-z0-9_+-]*(\/[A-Za-z0-9_+-]+)*$/;
+const shortText = (v: unknown) => typeof v === "string" && codePointLength(v) >= 1 && codePointLength(v) <= 32;
+
+/**
+ * Maps the host's context to its wire form, copying only the known fields.
+ * Returns the list of problems instead when a field would fail the schema.
+ */
+export function captureRunContext(
+  input: RunContextInput,
+  libraryVersion: string,
+): { ok: true; context: WireRunContext } | { ok: false; errors: string[] } {
+  const errors: string[] = [];
+  if (!input || typeof input !== "object") return { ok: false, errors: ["context is not an object"] };
+  if (!shortText(input.appVersion)) errors.push("appVersion must be 1 to 32 characters");
+  if (input.build !== null && !shortText(input.build)) errors.push("build must be null or 1 to 32 characters");
+  if (input.platform !== "ios" && input.platform !== "android" && input.platform !== "web") {
+    errors.push("platform must be ios, android or web");
+  }
+  if (input.osVersion !== null && !shortText(input.osVersion)) errors.push("osVersion must be null or 1 to 32 characters");
+  if (typeof input.locale !== "string" || !LOCALE.test(input.locale)) errors.push("locale must be a BCP 47 tag");
+  if (typeof input.timezone !== "string" || input.timezone.length > 64 || !TIMEZONE.test(input.timezone)) {
+    errors.push("timezone must be an IANA name of at most 64 characters");
+  }
+  if (errors.length) return { ok: false, errors };
+  return {
+    ok: true,
+    context: {
+      app_version: input.appVersion,
+      build: input.build,
+      platform: input.platform,
+      os_version: input.osVersion,
+      locale: input.locale,
+      timezone: input.timezone,
+      library_version: libraryVersion,
+    },
+  };
+}