@wireai/activation 0.11.0 → 0.12.1

package/src/revenuecat/index.ts

@@ -0,0 +1,55 @@
+/**
+ * revenuecat - the drop-in RevenueCat to Wire activation path.
+ *
+ * Re-exported from the main `@wireai/activation` barrel (no separate subpath): it is a pure,
+ * dependency-free mapping layer with no UI, so it costs an analytics-only consumer nothing.
+ *
+ * Adopting it is a constructor plus your existing paywall call sites:
+ *
+ *   import { createAnalytics, createRevenueCatBridge, activationJoinContext } from "@wireai/activation";
+ *
+ *   const analytics = createAnalytics({ serverUrl, apiKey, storage, userContext: { deviceKey } });
+ *   const revenuecat = createRevenueCatBridge({ analytics, entitlementId: "pro" });
+ *
+ *   revenuecat.paywallShown(offering, { source: variant });
+ *   revenuecat.checkoutStarted(pkg, { source: variant });
+ *   const entitled = revenuecat.purchaseCompleted(customerInfo, pkg, { source: variant });
+ *
+ * And the join that makes the numbers real, on the onboarding side:
+ *
+ *   <WireOnboarding userContext={activationJoinContext(deviceKey)} ... />
+ *
+ * See `revenueCatBridge.ts` for why that key is `device_key` and never `session_id`.
+ */
+
+// ─── The bridge (the thing you wire) ──────────────────────────────────────────
+export { createRevenueCatBridge } from "./revenueCatBridge";
+export type {
+  RevenueCatBridge,
+  RevenueCatBridgeConfig,
+  PurchaseProps,
+} from "./revenueCatBridge";
+
+// ─── Canonical purchase-funnel names + the pure mappers behind the bridge ─────
+export {
+  WIRE_PURCHASE_EVENTS,
+  PLAN_TIER_CONTEXT_KEY,
+  activeEntitlement,
+  describeEntitlement,
+  describeFailure,
+  describePackage,
+  isUserCancelled,
+  resolvePlanTier,
+} from "./purchaseEvents";
+export type { WirePurchaseEventName, PlanTier } from "./purchaseEvents";
+
+// ─── Structural mirrors of the react-native-purchases shapes (no native dep) ──
+export type {
+  RevenueCatCustomerInfoLike,
+  RevenueCatEntitlementLike,
+  RevenueCatErrorLike,
+  RevenueCatOfferingLike,
+  RevenueCatPackageLike,
+  RevenueCatProductLike,
+  RevenueCatSink,
+} from "./types";

package/src/revenuecat/purchaseEvents.ts

@@ -0,0 +1,167 @@
+/**
+ * purchaseEvents - the canonical Wire names for a subscription funnel, plus the PURE mappers that
+ * turn a RevenueCat snapshot into small, non-PII event props.
+ *
+ * Same job `analyticsEvent.ts` does for the onboarding funnel: every app was naming these events
+ * itself (`PURCHASE`, `purchase_success`, `AI_PAYWALL_VIEW`), so the same funnel read differently
+ * per tenant and no cross-app report was possible. These are the ONE set of names; the mappers are
+ * the ONE definition of which RevenueCat fields are safe to send.
+ *
+ * PURE + dependency-free: no React, no React Native, no `react-native-purchases`, no transport.
+ * Every function tolerates a malformed or absent snapshot and returns a defined value instead of
+ * throwing, because a paywall must never break on an analytics mapping.
+ */
+import type {
+  RevenueCatCustomerInfoLike,
+  RevenueCatEntitlementLike,
+  RevenueCatPackageLike,
+} from "./types";
+
+/**
+ * The canonical purchase-funnel event names. These are `app_event` `question_key` values on the
+ * wire, so they are ALSO the exact strings a review / questionnaire firing trigger matches on.
+ * Never rename one: a rename silently unfires every trigger configured against the old string.
+ */
+export const WIRE_PURCHASE_EVENTS = {
+  /** The paywall became visible (offerings loaded). */
+  paywallShown: "wire_paywall_shown",
+  /** The user tapped buy; the store sheet is about to open. */
+  checkoutStarted: "wire_checkout_started",
+  /** The store confirmed the purchase AND the entitlement is now active. */
+  purchased: "wire_purchase_completed",
+  /** The purchase did not land: a user cancel or a real store/network error (see `reason`). */
+  purchaseFailed: "wire_purchase_failed",
+  /** A restore ran (whether or not it produced an entitlement; see `plan_tier`). */
+  restored: "wire_purchase_restored",
+} as const;
+
+export type WirePurchaseEventName =
+  (typeof WIRE_PURCHASE_EVENTS)[keyof typeof WIRE_PURCHASE_EVENTS];
+
+/**
+ * The user-context key the bridge writes the tier to. It lands NAMESPACED as
+ * `user_context["custom.plan_tier"]` (host extras are always prefixed), which is the flattened
+ * dimension the server report can break the funnel down by.
+ */
+export const PLAN_TIER_CONTEXT_KEY = "plan_tier";
+
+/** The three tiers the kit models. Anything richer belongs in the host's own analytics. */
+export type PlanTier = "paid" | "trial" | "free";
+
+/** Read a plain record field defensively (the snapshot comes from a native bridge). */
+const asRecord = (value: unknown): Record<string, unknown> | undefined =>
+  typeof value === "object" && value !== null ? (value as Record<string, unknown>) : undefined;
+
+/**
+ * The ACTIVE entitlement matching `entitlementId`, or `undefined`. Returns `undefined` for a
+ * missing key, an explicitly inactive entry, and any malformed snapshot.
+ */
+export const activeEntitlement = (
+  info: RevenueCatCustomerInfoLike | undefined,
+  entitlementId: string,
+): RevenueCatEntitlementLike | undefined => {
+  const active = asRecord(asRecord(asRecord(info)?.entitlements)?.active);
+  const found = active?.[entitlementId];
+  const entitlement = asRecord(found) as RevenueCatEntitlementLike | undefined;
+  if (!entitlement) return undefined;
+  // `isActive` is always present on the real type; treat an explicit `false` as not entitled and a
+  // missing value as entitled, because the key only appears in `entitlements.active` at all when
+  // RevenueCat considers it granted.
+  return entitlement.isActive === false ? undefined : entitlement;
+};
+
+/** True when RevenueCat says this entitlement is a free trial rather than a paid period. */
+const isTrial = (entitlement: RevenueCatEntitlementLike): boolean =>
+  typeof entitlement.periodType === "string" && entitlement.periodType.toUpperCase() === "TRIAL";
+
+/** `paid` / `trial` / `free` for the configured entitlement. Never throws. */
+export const resolvePlanTier = (
+  info: RevenueCatCustomerInfoLike | undefined,
+  entitlementId: string,
+): PlanTier => {
+  const entitlement = activeEntitlement(info, entitlementId);
+  if (!entitlement) return "free";
+  return isTrial(entitlement) ? "trial" : "paid";
+};
+
+/**
+ * Non-PII props for an offering package: which package, which product, what it costs. Every field
+ * is optional on the wire, so a missing one is OMITTED rather than sent empty or invented.
+ */
+export const describePackage = (
+  pkg: RevenueCatPackageLike | undefined,
+): Record<string, string | number> => {
+  const props: Record<string, string | number> = {};
+  if (!pkg) return props;
+  if (typeof pkg.identifier === "string") props.package_id = pkg.identifier;
+  if (typeof pkg.packageType === "string") props.package_type = pkg.packageType;
+  if (typeof pkg.offeringIdentifier === "string") props.offering_id = pkg.offeringIdentifier;
+  const product = asRecord(pkg.product) as RevenueCatProductFields | undefined;
+  if (product) {
+    if (typeof product.identifier === "string") props.product_id = product.identifier;
+    if (typeof product.price === "number" && Number.isFinite(product.price)) {
+      props.price = product.price;
+    }
+    if (typeof product.currencyCode === "string") props.currency = product.currencyCode;
+  }
+  return props;
+};
+
+/** The product fields `describePackage` reads, narrowed after the defensive record check. */
+type RevenueCatProductFields = {
+  identifier?: unknown;
+  price?: unknown;
+  currencyCode?: unknown;
+};
+
+/**
+ * Non-PII props for the entitlement state after a purchase or a restore. Always carries
+ * `entitlement` + `plan_tier` so a "restore that granted nothing" is still a queryable row; the
+ * rest of the fields only appear when the entitlement is actually active.
+ */
+export const describeEntitlement = (
+  info: RevenueCatCustomerInfoLike | undefined,
+  entitlementId: string,
+): Record<string, string | number | boolean> => {
+  const entitlement = activeEntitlement(info, entitlementId);
+  const props: Record<string, string | number | boolean> = {
+    entitlement: entitlementId,
+    plan_tier: entitlement ? (isTrial(entitlement) ? "trial" : "paid") : "free",
+  };
+  if (!entitlement) return props;
+  if (typeof entitlement.periodType === "string") props.period_type = entitlement.periodType;
+  props.is_trial = isTrial(entitlement);
+  if (typeof entitlement.willRenew === "boolean") props.will_renew = entitlement.willRenew;
+  if (typeof entitlement.store === "string") props.store = entitlement.store;
+  if (typeof entitlement.productIdentifier === "string") {
+    props.product_id = entitlement.productIdentifier;
+  }
+  if (typeof entitlement.isSandbox === "boolean") props.is_sandbox = entitlement.isSandbox;
+  return props;
+};
+
+/** RevenueCat's `PURCHASES_ERROR_CODE.PURCHASE_CANCELLED_ERROR`. A STRING enum, value `"1"`. */
+const PURCHASE_CANCELLED_CODE = "1";
+
+/**
+ * True when the rejection is the user backing out of the store sheet rather than a real failure.
+ * Reads BOTH signals the SDK exposes: the current `code` and the deprecated-but-still-populated
+ * `userCancelled` flag. Anything else (including a plain `Error`) is a genuine failure.
+ */
+export const isUserCancelled = (error: unknown): boolean => {
+  const record = asRecord(error);
+  if (!record) return false;
+  if (record.userCancelled === true) return true;
+  return record.code === PURCHASE_CANCELLED_CODE;
+};
+
+/**
+ * A short, stable, non-PII failure descriptor. The store's `message` is DELIBERATELY dropped: it is
+ * localized, unbounded, and occasionally echoes the account it failed for, so it is not something
+ * the kit forwards to a shared analytics backend. The RevenueCat `code` is the stable handle.
+ */
+export const describeFailure = (error: unknown): { reason: string; code: string } => {
+  const record = asRecord(error);
+  const code = typeof record?.code === "string" ? record.code : "unknown";
+  return { reason: isUserCancelled(error) ? "cancelled" : "error", code };
+};

package/src/revenuecat/revenueCatBridge.ts

@@ -0,0 +1,221 @@
+/**
+ * revenueCatBridge - the short, first-class path from RevenueCat to Wire activation.
+ *
+ *   const revenuecat = createRevenueCatBridge({ analytics, entitlementId: "pro" });
+ *   revenuecat.paywallShown(offering, { source: variant });
+ *   revenuecat.checkoutStarted(pkg, { source: variant });
+ *   const entitled = revenuecat.purchaseCompleted(customerInfo, pkg, { source: variant });
+ *
+ * WHAT IT REPLACES: every consumer was hand-rolling the same four things around its paywall,
+ * differently: its own event names, its own idea of which RevenueCat fields are safe to send, its
+ * own entitlement check duplicated at the purchase and the restore site, and its own plan-tier
+ * user property. This owns all four, so adopting the purchase funnel is a constructor plus five
+ * call sites.
+ *
+ * ── THE JOIN KEY (read this before you wire it) ───────────────────────────────────────────────
+ * A purchase event is only worth anything if it can be joined to the SAME user's onboarding. The
+ * key that does that is `user_context.device_key`, NOT `session_id`:
+ *
+ *   • Purchase side: this bridge reports through a kit sink (`createAnalytics` or
+ *     `createWireActivation`). Both auto-mint a stable, persisted, per-install `device_key` and
+ *     stamp it on every event (see `context/deviceId.ts`).
+ *   • Onboarding side: `<WireOnboarding userContext={activationJoinContext(deviceKey)} />`. The kit
+ *     forwards `userContext` verbatim into the A2A session-start metadata, and the server records
+ *     it on the session's `session_started` event, where the SAME `device_key` lookup reads it.
+ *
+ * Pass the SAME `deviceKey` to both. `session_id` is NOT a join key across these two families: the
+ * onboarding session id is the A2A `contextId`, the app-event session id is the per-open id, and
+ * they live in disjoint spaces on purpose. Intersecting them yields zero rows, every time.
+ *
+ * PURE + dependency-free: no React, no React Native, no `react-native-purchases`. Fire-and-forget
+ * throughout, so an analytics failure can never take the paywall down with it.
+ */
+import type { Analytics } from "../analytics/analyticsFacade";
+import type { WireActivation } from "../activation/wireActivation";
+import {
+  PLAN_TIER_CONTEXT_KEY,
+  WIRE_PURCHASE_EVENTS,
+  describeEntitlement,
+  describeFailure,
+  describePackage,
+  resolvePlanTier,
+  type PlanTier,
+} from "./purchaseEvents";
+import type {
+  RevenueCatCustomerInfoLike,
+  RevenueCatOfferingLike,
+  RevenueCatPackageLike,
+  RevenueCatSink,
+} from "./types";
+
+/**
+ * COMPILE-TIME PROOF that both kit sinks satisfy {@link RevenueCatSink}, so a host can pass the
+ * analytics instance it already holds with no adapter of its own. Type-only (erased at build), and
+ * `tsc --noEmit` fails here the day either surface drifts. This lives in source, not the test file,
+ * because `tsconfig.json` excludes tests from the typecheck.
+ */
+type AssertIsSink<T extends RevenueCatSink> = T;
+type _AnalyticsIsASink = AssertIsSink<Analytics>;
+type _WireActivationIsASink = AssertIsSink<WireActivation>;
+
+/** Small, non-PII extras a host merges onto a purchase event (paywall variant, entry point, ...). */
+export type PurchaseProps = Record<string, string | number | boolean>;
+
+/** Inputs for {@link createRevenueCatBridge}. */
+export interface RevenueCatBridgeConfig {
+  /**
+   * Where events go: the `createAnalytics(...)` instance (offline-first queue) or the
+   * `createWireActivation(...)` instance (awaitable POST). Both already carry the `device_key` this
+   * funnel joins on, so pass the one the app already holds rather than creating a second.
+   */
+  analytics: RevenueCatSink;
+  /**
+   * The entitlement identifier that means "paid" in THIS app, exactly as configured in the
+   * RevenueCat dashboard (e.g. `"pro"`). The bridge reads `customerInfo.entitlements.active[id]`.
+   */
+  entitlementId: string;
+  /** Non-PII props merged into EVERY event from this bridge. A per-call prop of the same name wins. */
+  commonProps?: PurchaseProps;
+  /**
+   * Whether entitlement changes also update the bound user context with `plan_tier`
+   * (`user_context["custom.plan_tier"]`), so the whole funnel can be sliced paid vs trial vs free.
+   * Default `true`. Requires a sink with `setUserContext` (`createAnalytics`); a no-op otherwise.
+   */
+  writePlanTier?: boolean;
+}
+
+/** The bridge surface. Every method is fire-and-forget and never throws. */
+export interface RevenueCatBridge {
+  /**
+   * The paywall became visible. Pass the RevenueCat offering you just loaded and the bridge derives
+   * `offering_id` + `packages_count`. Fires even with no offering, because a paywall that reached
+   * the user with nothing to sell is exactly the failure you want in the funnel.
+   */
+  paywallShown(offering?: RevenueCatOfferingLike, props?: PurchaseProps): void;
+  /** The user tapped buy and the store sheet is opening. */
+  checkoutStarted(pkg: RevenueCatPackageLike, props?: PurchaseProps): void;
+  /**
+   * The store returned from a purchase. Fires `wire_purchase_completed` when the configured
+   * entitlement is now active, and `wire_purchase_failed` with `reason: "not_entitled"` when the
+   * store confirmed but nothing was granted (the case hosts usually drop on the floor). Syncs
+   * `plan_tier` either way. Returns whether the user is entitled now, so the caller can navigate.
+   */
+  purchaseCompleted(
+    customerInfo: RevenueCatCustomerInfoLike | undefined,
+    pkg?: RevenueCatPackageLike,
+    props?: PurchaseProps,
+  ): boolean;
+  /** The purchase call rejected. Separates a user cancel from a real store error via `reason`. */
+  purchaseFailed(error: unknown, pkg?: RevenueCatPackageLike, props?: PurchaseProps): void;
+  /** A restore finished. Reports the resulting tier and returns whether the user is entitled now. */
+  purchasesRestored(
+    customerInfo: RevenueCatCustomerInfoLike | undefined,
+    props?: PurchaseProps,
+  ): boolean;
+  /**
+   * Write the current tier to the bound user context WITHOUT emitting an event. Call it once at
+   * launch with a `getCustomerInfo()` snapshot so returning subscribers are segmented correctly
+   * from their first event of the session. Returns the tier it resolved.
+   */
+  syncPlanTier(customerInfo: RevenueCatCustomerInfoLike | undefined): PlanTier;
+}
+
+/**
+ * Create a bridge bound to one sink and one entitlement. Pure, React-free, and safe to create at
+ * module scope next to the paywall.
+ */
+export const createRevenueCatBridge = (config: RevenueCatBridgeConfig): RevenueCatBridge => {
+  const { analytics, entitlementId } = config;
+  const writeTier = config.writePlanTier !== false;
+
+  /**
+   * Send one event. Swallows a throwing sink AND a rejected promise from an awaitable one, so an
+   * analytics failure is never visible at the paywall and never becomes an unhandled rejection.
+   */
+  const emit = (event: string, props: Record<string, unknown>): void => {
+    try {
+      const result = analytics.track(event, { ...config.commonProps, ...props });
+      if (result && typeof (result as Promise<boolean>).catch === "function") {
+        void (result as Promise<boolean>).catch(() => {});
+      }
+    } catch {
+      /* analytics must never break a purchase */
+    }
+  };
+
+  const syncPlanTier = (customerInfo: RevenueCatCustomerInfoLike | undefined): PlanTier => {
+    const tier = resolvePlanTier(customerInfo, entitlementId);
+    if (!writeTier) return tier;
+    try {
+      analytics.setUserContext?.({ extra: { [PLAN_TIER_CONTEXT_KEY]: tier } });
+    } catch {
+      /* a sink without a usable context writer is not a purchase failure */
+    }
+    return tier;
+  };
+
+  const paywallShown = (offering?: RevenueCatOfferingLike, props?: PurchaseProps): void => {
+    const shown: Record<string, unknown> = {
+      packages_count: offering?.availablePackages?.length ?? 0,
+    };
+    if (typeof offering?.identifier === "string") shown.offering_id = offering.identifier;
+    emit(WIRE_PURCHASE_EVENTS.paywallShown, { ...shown, ...props });
+  };
+
+  const checkoutStarted = (pkg: RevenueCatPackageLike, props?: PurchaseProps): void => {
+    emit(WIRE_PURCHASE_EVENTS.checkoutStarted, { ...describePackage(pkg), ...props });
+  };
+
+  const purchaseCompleted = (
+    customerInfo: RevenueCatCustomerInfoLike | undefined,
+    pkg?: RevenueCatPackageLike,
+    props?: PurchaseProps,
+  ): boolean => {
+    const tier = syncPlanTier(customerInfo);
+    const entitled = tier !== "free";
+    if (entitled) {
+      emit(WIRE_PURCHASE_EVENTS.purchased, {
+        ...describePackage(pkg),
+        ...describeEntitlement(customerInfo, entitlementId),
+        ...props,
+      });
+      return true;
+    }
+    // The store said yes but the entitlement is not active: a product/entitlement mapping problem,
+    // the single most common silent paywall defect. Report it rather than returning quietly.
+    emit(WIRE_PURCHASE_EVENTS.purchaseFailed, {
+      ...describePackage(pkg),
+      reason: "not_entitled",
+      code: "unknown",
+      entitlement: entitlementId,
+      ...props,
+    });
+    return false;
+  };
+
+  const purchaseFailed = (
+    error: unknown,
+    pkg?: RevenueCatPackageLike,
+    props?: PurchaseProps,
+  ): void => {
+    emit(WIRE_PURCHASE_EVENTS.purchaseFailed, {
+      ...describePackage(pkg),
+      ...describeFailure(error),
+      ...props,
+    });
+  };
+
+  const purchasesRestored = (
+    customerInfo: RevenueCatCustomerInfoLike | undefined,
+    props?: PurchaseProps,
+  ): boolean => {
+    const tier = syncPlanTier(customerInfo);
+    emit(WIRE_PURCHASE_EVENTS.restored, {
+      ...describeEntitlement(customerInfo, entitlementId),
+      ...props,
+    });
+    return tier !== "free";
+  };
+
+  return { paywallShown, checkoutStarted, purchaseCompleted, purchaseFailed, purchasesRestored, syncPlanTier };
+};

package/src/revenuecat/types.ts

@@ -0,0 +1,95 @@
+/**
+ * types - STRUCTURAL mirrors of the `react-native-purchases` shapes this adapter READS.
+ *
+ * WHY structural and not an import: `react-native-purchases` is a NATIVE module. Importing it
+ * (even as an optional peer) would put a native rebuild in the kit's dependency story, which the
+ * kit's hard rule forbids. Every field below is a subset of the real 9.6.x typings
+ * (`@revenuecat/purchases-typescript-internal`: `CustomerInfo`, `PurchasesEntitlementInfo`,
+ * `PurchasesPackage`, `PurchasesStoreProduct`, `PurchasesError`), declared as plain `string` /
+ * `number` / `boolean` so a host can pass its REAL RevenueCat objects straight in: RevenueCat's
+ * `Store`, `PACKAGE_TYPE`, `PERIOD_TYPE` and `PURCHASES_ERROR_CODE` are all STRING enums, and a
+ * string enum member is assignable to `string`.
+ *
+ * The adapter only ever reads. It never constructs a RevenueCat object and never calls the SDK.
+ */
+
+/** One entitlement as RevenueCat reports it (subset of `PurchasesEntitlementInfo`). */
+export interface RevenueCatEntitlementLike {
+  /** The entitlement identifier configured in the RevenueCat dashboard, e.g. `"pro"`. */
+  readonly identifier: string;
+  /** True while the customer has access. */
+  readonly isActive: boolean;
+  /** `"NORMAL" | "INTRO" | "TRIAL" | "PREPAID"` on the real type; compared case-insensitively. */
+  readonly periodType?: string;
+  /** True when the underlying subscription renews at the end of the period. */
+  readonly willRenew?: boolean;
+  /** The store the entitlement was unlocked from, e.g. `"APP_STORE"`. */
+  readonly store?: string;
+  /** The product id that unlocked the entitlement. */
+  readonly productIdentifier?: string;
+  /** False when the purchase is a production one. */
+  readonly isSandbox?: boolean;
+}
+
+/** The customer snapshot RevenueCat returns from a purchase, a restore, or `getCustomerInfo`. */
+export interface RevenueCatCustomerInfoLike {
+  readonly entitlements: {
+    /** Active entitlements keyed by identifier. Missing key means "not entitled". */
+    readonly active: { readonly [key: string]: RevenueCatEntitlementLike | undefined };
+  };
+  /** Product ids of the customer's active subscriptions. */
+  readonly activeSubscriptions?: readonly string[];
+}
+
+/** The purchasable product on a package (subset of `PurchasesStoreProduct`). */
+export interface RevenueCatProductLike {
+  readonly identifier: string;
+  /** Price in the local currency, as a number. */
+  readonly price?: number;
+  /** ISO currency code of `price`, e.g. `"EUR"`. */
+  readonly currencyCode?: string;
+}
+
+/** One offering package (subset of `PurchasesPackage`). */
+export interface RevenueCatPackageLike {
+  readonly identifier: string;
+  /** `"ANNUAL" | "MONTHLY" | ...` on the real type. */
+  readonly packageType?: string;
+  readonly product: RevenueCatProductLike;
+  /** The offering this package belongs to. */
+  readonly offeringIdentifier?: string;
+}
+
+/** The current offering a paywall renders (subset of `PurchasesOffering`). */
+export interface RevenueCatOfferingLike {
+  readonly identifier?: string;
+  readonly availablePackages?: readonly RevenueCatPackageLike[];
+}
+
+/** The rejected value of a RevenueCat purchase call (subset of `PurchasesError`). */
+export interface RevenueCatErrorLike {
+  /** `PURCHASES_ERROR_CODE`, a STRING enum; `"1"` is `PURCHASE_CANCELLED_ERROR`. */
+  readonly code?: string;
+  readonly message?: string;
+  /** Deprecated on the real type but still populated by 9.6.x. */
+  readonly userCancelled?: boolean | null;
+}
+
+/**
+ * The Wire sink the bridge reports through. Deliberately STRUCTURAL so BOTH kit surfaces satisfy
+ * it with no adapter of their own:
+ *   - `createAnalytics(...)` (offline-first queue) matches `track` + `setUserContext`;
+ *   - `createWireActivation(...)` (awaitable `wire.track`) matches `track`.
+ *
+ * Both auto-mint and stamp `user_context.device_key` on every event, which is the join key this
+ * adapter's whole design rests on (see `joinKey.md` in the module docs / the README section).
+ */
+export interface RevenueCatSink {
+  /** Report an in-app event. Returns `void` (queued) or `Promise<boolean>` (awaited POST). */
+  track(event: string, props?: Record<string, unknown>): void | Promise<boolean>;
+  /**
+   * Optional: update the bound user context. Present on `createAnalytics`, absent on
+   * `createWireActivation` (its config is captured immutably), so entitlement sync is a no-op there.
+   */
+  setUserContext?(partial: { extra?: Record<string, string | number | boolean> }): void;
+}