@encorekit/web-sdk 1.1.19 → 1.1.20

package/types/core/TransactionStore.d.ts

@@ -0,0 +1,35 @@
+/**
+ * TransactionStore
+ *
+ * Local persistence for the two-phase (transaction -> redeem) flow. Backed by
+ * StorageManager (localStorage-first), it holds:
+ *  - transactions:     transactionId -> Transaction
+ *  - placements: placementId -> transactionId  (the per-placement live-transaction map)
+ *  - latest:     transactionId of the most recently created transaction
+ *
+ * This is the fast path; the server transaction record (keyed by app_account_id, carrying
+ * placementId) is the durable source of truth for cross-page / post-localStorage-loss
+ * recovery. Expired or redeemed transactions are filtered out of the lookups.
+ */
+import type { Transaction } from '../types';
+import type { StorageManager } from './StorageManager';
+export declare class TransactionStore {
+    #private;
+    constructor(storage: StorageManager);
+    /** Persist a new transaction, updating the placement map and the latest pointer. */
+    save(transaction: Transaction): void;
+    /** Resolve a transaction by exact transaction id (any status). */
+    getByTransactionId(transactionId: string): Transaction | null;
+    /**
+     * Resolve the LIVE transaction made at a placement. Returns null if none/expired/redeemed —
+     * never crosses to another placement's transaction.
+     */
+    getByPlacement(placementId: string): Transaction | null;
+    /** Resolve the single most-recent LIVE transaction for this user (the flat redeem() fallback). */
+    getLatest(): Transaction | null;
+    /** Mark a transaction redeemed (idempotent). Frees its placement slot. */
+    markRedeemed(transactionId: string): void;
+    /** Clear all transactions (used by reset()). */
+    clear(): void;
+}
+//# sourceMappingURL=TransactionStore.d.ts.map

package/types/core/TransactionStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TransactionStore.d.ts","sourceRoot":"","sources":["../../src/core/TransactionStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAavD,qBAAa,gBAAgB;;gBAGf,OAAO,EAAE,cAAc;IAwBnC,oFAAoF;IACpF,IAAI,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI;IAepC,kEAAkE;IAClE,kBAAkB,CAAC,aAAa,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI;IAI7D;;;OAGG;IACH,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI;IAQvD,kGAAkG;IAClG,SAAS,IAAI,WAAW,GAAG,IAAI;IAa/B,0EAA0E;IAC1E,YAAY,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI;IA8BzC,gDAAgD;IAChD,KAAK,IAAI,IAAI;CAGd"}

package/types/core/version.d.ts

@@ -1,3 +1,3 @@
 /** SDK version — single source of truth (also kept in sync with package.json via scripts/update-version.sh) */
-export declare const SDK_VERSION = "1.1.19";
+export declare const SDK_VERSION = "1.1.20";
 //# sourceMappingURL=version.d.ts.map

package/types/experiments/ExperimentManager.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Owns NCL (Net Conversion Lift) cohort assignment + exposure logging for the web SDK.
+ *
+ * Cohort is deterministic in (appAccountId, assignmentVersion) — the same person
+ * gets the same cohort across devices and reloads (see `bucketing.ts` for the
+ * byte-exact cross-platform contract). Bumping `assignmentVersion` server-side
+ * re-buckets everyone (a clean epoch).
+ *
+ * Mirrors iOS `ExperimentManager.swift` / Android `ExperimentManager.kt`.
+ */
+import type { StorageManager } from '../core/StorageManager';
+import type { Cohort, NCLExperimentConfig, NCLExperimentState } from './types';
+import type { ExposureOutbox } from './ExposureOutbox';
+export declare class ExperimentManager {
+    #private;
+    constructor(storage: StorageManager, getAppAccountId: () => string | null, exposureOutbox: ExposureOutbox);
+    /** Route the remote config's `experiments.ncl` block into the manager. */
+    setConfig(config: NCLExperimentConfig | null | undefined): void;
+    /**
+     * Resolve the current NCL cohort. Returns `notEnrolled` (→ normal offer flow,
+     * no exposure) when there is no appAccountId, no NCL config, or the experiment
+     * is disabled. Any unexpected error also degrades to `notEnrolled`.
+     */
+    getCohort(): Promise<Cohort>;
+    /**
+     * Log the exposure for `treatment`/`control` at the offer trigger — the A/B
+     * denominator. No-op for `notEnrolled`. Deduped per assignment epoch so reloads
+     * don't double-count: emits once per (user, assignmentVersion), re-emitting only
+     * when the server bumps the epoch. (Deliberately stronger than mobile, which
+     * emits per show; web reloads would otherwise inflate the denominator.)
+     */
+    logExposure(cohort: Cohort): void;
+    /**
+     * Read-only diagnostic snapshot (host apps / the demo harness). Reports the
+     * authoritative `cohort` (via `getCohort`, so it reflects exactly what the
+     * offer flow uses) alongside the computed `bucket` and the per-epoch exposure
+     * marker. Recomputing the bucket re-runs the SHA-256 purely for display — it
+     * never logs exposure or alters the rollout. `bucket` is `null` whenever a
+     * cohort can't be bucketed (no appAccountId, disabled, or no WebCrypto).
+     */
+    getState(): Promise<NCLExperimentState>;
+}
+//# sourceMappingURL=ExperimentManager.d.ts.map

package/types/experiments/ExperimentManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExperimentManager.d.ts","sourceRoot":"","sources":["../../src/experiments/ExperimentManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAK7D,OAAO,KAAK,EAAE,MAAM,EAAiB,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAC9F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AASvD,qBAAa,iBAAiB;;gBAO1B,OAAO,EAAE,cAAc,EACvB,eAAe,EAAE,MAAM,MAAM,GAAG,IAAI,EACpC,cAAc,EAAE,cAAc;IAOhC,0EAA0E;IAG1E,SAAS,CAAC,MAAM,EAAE,mBAAmB,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI;IAI/D;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC;IAmDlC;;;;;;OAMG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAgCjC;;;;;;;OAOG;IACG,QAAQ,IAAI,OAAO,CAAC,kBAAkB,CAAC;CA+B9C"}

package/types/experiments/ExposureOutbox.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Reliable delivery for the NCL exposure event — the A/B denominator.
+ *
+ * Exposure MUST survive tab-close, so unlike the fire-and-forget AnalyticsClient
+ * this path is storage-backed and retried.
+ *
+ * Delivery primitive: `fetch(url, { keepalive: true })` — NOT `navigator.sendBeacon`.
+ * The ingest endpoint authenticates on the `X-Analytics-Key` request header, and
+ * sendBeacon cannot set headers (a beacon would arrive unauthenticated). keepalive
+ * fetch survives document unload like a beacon AND carries the auth header.
+ *
+ * Reliability model:
+ *   - enqueue: persist the envelope, then keepalive-POST; remove on 2xx.
+ *   - flush:   replay every persisted envelope (on SDK init + on pagehide /
+ *              visibilitychange:hidden) so a send that died with the tab retries.
+ *   - envelopes carry a STABLE event_id → retries are idempotent backend-side.
+ *   - an in-memory in-flight set avoids duplicate concurrent sends.
+ *   - all storage / window / document access is SSR- and failure-guarded (fail-open).
+ */
+import type { AnalyticsEvent } from '../analytics/models';
+import type { StorageManager } from '../core/StorageManager';
+export declare class ExposureOutbox {
+    #private;
+    constructor(apiKey: string, analyticsBaseURL: string, storage: StorageManager);
+    /**
+     * Persist an exposure event and attempt delivery. `eventId` must be stable for a
+     * given (user, epoch) so retries de-duplicate backend-side. Returns whether the
+     * envelope durably landed in the configured storage tier: a quota-driven
+     * fallback-to-memory write is invisible to a fresh read, so the caller can avoid
+     * marking the epoch logged (and re-enqueue on the next trigger) instead of
+     * silently dropping the exposure.
+     */
+    enqueue(event: AnalyticsEvent, eventId: string): boolean;
+    /** Replay every persisted envelope (init recovery + unload flush). */
+    flush(): void;
+}
+//# sourceMappingURL=ExposureOutbox.d.ts.map

package/types/experiments/ExposureOutbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExposureOutbox.d.ts","sourceRoot":"","sources":["../../src/experiments/ExposureOutbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAiB,MAAM,qBAAqB,CAAC;AAEzE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAK7D,qBAAa,cAAc;;gBAMb,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc;IAO7E;;;;;;;OAOG;IACH,OAAO,CAAC,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO;IAaxD,sEAAsE;IACtE,KAAK,IAAI,IAAI;CAoDd"}

package/types/experiments/bucketing.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Deterministic NCL cohort bucketing — the byte-exact cross-platform core.
+ *
+ * Same (appAccountId, assignmentVersion) MUST land in the same bucket on web,
+ * iOS, and Android, or the NCL revenue-lift math breaks cross-platform.
+ *
+ * Verified byte-for-byte against:
+ *   - iOS    Encore/.../Experiments/ExperimentManager.swift:81-87
+ *   - Android features/experiments/ExperimentManager.kt:88-98
+ *   - Fixture android/.../ExperimentManagerTest.kt:40-75 (15 reference pairs)
+ *
+ * Algorithm:
+ *   input  = "<appAccountId>:<version>"            (UTF-8)
+ *   digest = SHA-256(input)                        (via crypto.subtle)
+ *   hash64 = digest[0..7] as big-endian UInt64     (BigInt — Number can't hold it)
+ *   bucket = hash64 mod 100                         (∈ [0, 99])
+ */
+import type { Cohort } from './types';
+/**
+ * Compute the deterministic bucket [0, 99] for (appAccountId, version).
+ *
+ * Uses BigInt for the 64-bit accumulation: the top 8 bytes of a SHA-256 digest
+ * routinely exceed `Number.MAX_SAFE_INTEGER` (2^53), so a plain `number` would
+ * silently lose precision and diverge from iOS/Android. This is the footgun the
+ * BigInt path exists to avoid.
+ */
+export declare function computeBucket(appAccountId: string, version: number): Promise<number>;
+/**
+ * Classify a bucket into a cohort: `bucket < rolloutPct` → treatment, else control.
+ * (rolloutPct 0 → always control, 100 → always treatment.)
+ */
+export declare function cohortForBucket(bucket: number, rolloutPct: number): Cohort;
+//# sourceMappingURL=bucketing.d.ts.map

package/types/experiments/bucketing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bucketing.d.ts","sourceRoot":"","sources":["../../src/experiments/bucketing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAEtC;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAU1F;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAE1E"}

package/types/experiments/types.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Experiment domain types (NCL — Net Conversion Lift A/B).
+ *
+ * Cohort string values are the cross-platform BigQuery join literals and MUST
+ * match iOS/Android verbatim ('treatment' | 'control' | 'notEnrolled').
+ */
+import type * as Contract from '../api/contract';
+/**
+ * NCL cohort assignment.
+ *
+ * - `treatment`: user sees the Encore offer (normal flow).
+ * - `control`: Ghost Trigger — no UI shown, exposure logged (the A/B denominator).
+ * - `notEnrolled`: experiment disabled, config unavailable, or no appAccountId —
+ *   falls back to normal behaviour (offers shown, NO exposure logged).
+ */
+export type Cohort = 'treatment' | 'control' | 'notEnrolled';
+/**
+ * The `experiments.ncl` block of the remote config response.
+ * `enabled === false` makes the manager a no-op (everyone notEnrolled → normal flow).
+ *
+ * Derived from the contract (not hand-declared): it is fed verbatim from
+ * fetchConfig().experiments.ncl with no mapping, so a field going optional/
+ * nullable in the backend contract should surface here as a compile error rather
+ * than silent drift. `null` (contract "not configured") is handled by consumers.
+ */
+export type NCLExperimentConfig = NonNullable<NonNullable<Contract.ConfigResponse['experiments']>['ncl']>;
+/**
+ * Persisted assignment cache. Cohort is a pure function of
+ * (appAccountId, assignmentVersion); this only avoids re-hashing on every show.
+ * Both keys are stored so a mismatch on EITHER forces a re-bucket: a bumped
+ * `assignmentVersion` (new epoch) or a changed `appAccountId` (e.g. an anonymous
+ * visitor calling `identify()` mid-session — web storage is per-origin and
+ * shared across identities, unlike the device-stable mobile id).
+ */
+export interface NCLAssignment {
+    cohort: Cohort;
+    appAccountId: string;
+    assignmentVersion: number;
+}
+/**
+ * Read-only diagnostic snapshot of the NCL experiment state, surfaced by
+ * `Encore.getExperimentState()` for host apps and the demo harness. Exposes the
+ * full deterministic chain — the config epoch (`assignmentVersion`, `rolloutPct`),
+ * the resolved `appAccountId`, its computed `bucket` ∈ [0, 99], the resulting
+ * `cohort`, and whether the A/B `exposure` has been logged this epoch — without
+ * mutating any of it. `enabled: false` / `cohort: 'notEnrolled'` when no NCL
+ * experiment is active for the app. `bucket` is `null` when it can't be computed
+ * (no appAccountId, experiment disabled, or an insecure context with no WebCrypto).
+ */
+export interface NCLExperimentState {
+    experiment: string;
+    enabled: boolean;
+    rolloutPct: number | null;
+    assignmentVersion: number | null;
+    appAccountId: string | null;
+    bucket: number | null;
+    cohort: Cohort;
+    exposureLogged: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/types/experiments/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/experiments/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,KAAK,QAAQ,MAAM,iBAAiB,CAAC;AAEjD;;;;;;;GAOG;AACH,MAAM,MAAM,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,aAAa,CAAC;AAE7D;;;;;;;;GAQG;AACH,MAAM,MAAM,mBAAmB,GAAG,WAAW,CAC3C,WAAW,CAAC,QAAQ,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,CAC3D,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,OAAO,CAAC;CACzB"}

package/types/index.d.ts

@@ -7,4 +7,5 @@ export { Encore, Encore as default } from './core/Encore';
 export type * from './types';
 export type * from './api/models';
 export type { EntitlementChangedEvent, EntitlementEventMap } from './core/EntitlementManager';
+export type { Cohort, NCLExperimentState } from './experiments/types';
 //# sourceMappingURL=index.d.ts.map

package/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,MAAM,EAAE,MAAM,IAAI,OAAO,EAAE,MAAM,eAAe,CAAC;AAG1D,mBAAmB,SAAS,CAAC;AAG7B,mBAAmB,cAAc,CAAC;AAGlC,YAAY,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,MAAM,EAAE,MAAM,IAAI,OAAO,EAAE,MAAM,eAAe,CAAC;AAG1D,mBAAmB,SAAS,CAAC;AAG7B,mBAAmB,cAAc,CAAC;AAGlC,YAAY,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAG9F,YAAY,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC"}

package/types/react.d.ts

@@ -2,9 +2,7 @@ import { type ReactNode } from 'react';
 import type { EncoreConfig } from '@encorekit/web-sdk';
 type EncoreProviderProps = {
     children: ReactNode;
-} & Omit<EncoreConfig, 'userId'> & {
-    userId?: string;
-};
+} & EncoreConfig;
 export declare function EncoreProvider({ children, ...config }: EncoreProviderProps): import("react/jsx-runtime").JSX.Element;
 export declare function useEncore(): import("./core/Encore").EncoreSDK;
 export { Encore } from '@encorekit/web-sdk';

package/types/react.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAqC,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAE1E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,KAAK,mBAAmB,GAAG;IACzB,QAAQ,EAAE,SAAS,CAAC;CACrB,GAAG,IAAI,CAAC,YAAY,EAAE,QAAQ,CAAC,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAIvD,wBAAgB,cAAc,CAAC,EAAE,QAAQ,EAAE,GAAG,MAAM,EAAE,EAAE,mBAAmB,2CAa1E;AAED,wBAAgB,SAAS,sCAExB;AAGD,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,mBAAmB,oBAAoB,CAAC"}
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAqC,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAE1E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,KAAK,mBAAmB,GAAG;IACzB,QAAQ,EAAE,SAAS,CAAC;CACrB,GAAG,YAAY,CAAC;AAIjB,wBAAgB,cAAc,CAAC,EAAE,QAAQ,EAAE,GAAG,MAAM,EAAE,EAAE,mBAAmB,2CAa1E;AAED,wBAAgB,SAAS,sCAExB;AAGD,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,mBAAmB,oBAAoB,CAAC"}

package/types/types.d.ts

@@ -71,6 +71,18 @@ export type NotGrantedReason = 'userClosedModal' | 'userClickedOutside' | 'userD
  */
 export interface PresentationResult {
     granted: boolean;
+    /**
+     * Human-readable reward text for display only (e.g. "3 months of Ahead free"),
+     * derived from the campaign's UI copy. NEVER use this for access control —
+     * entitlements are server-authoritative (verify on your backend).
+     */
+    reward?: string;
+    /**
+     * @deprecated Web entitlements are server-authoritative. Verify access on your backend via
+     * Encore's server-side entitlements API (`/entitlements/server`, HMAC-signed) — not from the
+     * client. This field is no longer populated from a trusted source and will be removed in the
+     * next major version. For display, use `reward`.
+     */
     entitlement?: EntitlementType;
     reason?: NotGrantedReason;
 }
@@ -83,29 +95,101 @@ export interface AppearanceConfig {
     accentColor?: string;
 }
 /**
- * Options for placement configuration
+ * `'thankYou'`-only priming copy shown ABOVE the offers — the lead-in pair between
+ * the payment status and the carousel, context for why offers are being shown (never
+ * any one offer's own copy). Ignored by the `'list'` layout, whose top heading is
+ * `header` instead: one name means one thing in every layout.
  */
-export interface OfferConfig {
+export interface OfferContextConfig {
     title?: string;
+    /**
+     * Context subtitle. When the active offer's campaign carries a `perk` line (e.g.
+     * "Enjoy 30 days of Apple Music free") the perk takes this slot and follows the
+     * carousel as it pages; this value is the per-placement fallback.
+     */
     subtitle?: string;
 }
-export interface CompletionConfig {
+/**
+ * Layout template for a placement presentation.
+ * - `'list'` (default): today's offer sheet — header copy + offer carousel.
+ * - `'thankYou'`: post-purchase success composition — status check + payment-status
+ *   header + intro copy + carousel + optional trust footer.
+ */
+export type PlacementLayout = 'list' | 'thankYou';
+/**
+ * The sheet's top heading block — in EVERY layout. In `'list'` it is the modal
+ * title/subtitle above the offers (local override of the remote copy); in
+ * `'thankYou'` it is the payment-status block (check + title + subtitle). The host
+ * supplies the copy — the SDK never invents payment facts.
+ */
+export interface PlacementHeaderConfig {
+    /**
+     * Status icon (`'thankYou'` only). `'success'` (default) renders a green-circle
+     * check; `'none'` hides it. Ignored by `'list'`.
+     */
+    icon?: 'success' | 'none';
+    /**
+     * Heading title. In `'list'` the sheet title (falls back to remote copy when
+     * omitted); in `'thankYou'` the status title, e.g. "Payment Successful"
+     * (omitted → not rendered).
+     */
     title?: string;
+    /**
+     * Heading subtitle (a plain constant string). In `'list'` the sheet subtitle; in
+     * `'thankYou'` the muted status line, where a `receipt` passed to `show()` takes
+     * precedence over this slot.
+     */
     subtitle?: string;
-    buttonText?: string;
-    typeText?: string;
-    amountText?: string;
+}
+/** Trust footer for the `'thankYou'` layout. Omitted → not rendered. */
+export interface PlacementFooterConfig {
+    /** Small muted centered line, e.g. "🔒 Secured by Acme". */
+    text?: string;
 }
 export interface PlacementOptions {
     appearance?: AppearanceConfig;
-    offer?: OfferConfig;
-    completion?: CompletionConfig;
+    /** Priming pair above the offers — `'thankYou'` only; ignored by `'list'`. */
+    offerContext?: OfferContextConfig;
+    /** Layout template. Defaults to `'list'` (today's UI, unchanged). */
+    layout?: PlacementLayout;
+    /** Top heading block: modal title in `'list'`, payment status in `'thankYou'`. */
+    header?: PlacementHeaderConfig;
+    /** Trust footer — used by the `'thankYou'` layout only. */
+    footer?: PlacementFooterConfig;
+}
+/**
+ * Per-transaction receipt details for the `'thankYou'` layout. Rendered by the SDK as
+ * "You paid {amount} for {purpose}" (or "You paid {amount}" without a purpose) in the
+ * payment-status subtitle slot. Values are rendered verbatim as text — pre-format the
+ * currency on your side.
+ */
+export interface Receipt {
+    /** Pre-formatted amount, e.g. "NGN 100". */
+    amount: string;
+    /** What was paid for, e.g. "Demo". */
+    purpose?: string;
+}
+/**
+ * Per-call options for show().
+ */
+export interface ShowOptions {
+    /**
+     * Per-transaction receipt for the `'thankYou'` layout. When provided it owns the
+     * payment-status subtitle (overriding `header.subtitle`). Ignored by `'list'`.
+     */
+    receipt?: Receipt;
 }
 /**
- * Optional callbacks for presentation events
+ * Presentation callbacks and show-time options
  */
-export interface PresentationOptions {
-    onGranted?: (entitlement: EntitlementType) => void;
+export interface PresentationOptions extends ShowOptions {
+    /**
+     * Fires when the user completes the offer flow (provisional grant). The argument is the
+     * deprecated, display-derived entitlement and may be `undefined`.
+     * @deprecated The structured `entitlement` argument is no longer trustworthy. Read
+     * `PresentationResult.reward` for display, and verify real access server-side. Removed next major.
+     */
+    onGranted?: (entitlement?: EntitlementType) => void;
     onNotGranted?: (reason: NotGrantedReason) => void;
     onError?: (error: EncoreError) => void;
 }
@@ -113,10 +197,13 @@ export interface PresentationOptions {
  * Builder pattern for placement API
  */
 export interface PlacementBuilder {
-    onGranted(callback: (entitlement: EntitlementType) => void): PlacementBuilder;
+    /** Fires when the sheet closes without a claim — carries the dismissal reason. */
     onNotGranted(callback: (reason: NotGrantedReason) => void): PlacementBuilder;
     onLoadingStateChange(callback: (isLoading: boolean) => void): PlacementBuilder;
-    show(): Promise<PresentationResult>;
+    /** Same bare ShowResult contract as Encore.show(). Never rejects. */
+    show(options?: ShowOptions): Promise<ShowResult>;
+    /** Redeem the transaction made at this placement — phase 2 of the two-phase flow. */
+    redeem(): Promise<RedeemResult>;
 }
 /**
  * Error codes used throughout the SDK
@@ -148,7 +235,9 @@ export interface EncoreError {
  */
 export type VerificationStatus = 'pending' | 'verified' | 'failed' | 'timeout' | 'cancelled';
 /**
- * UI Configuration options
+ * Presentation copy slots consumed by the offer UI. Populated from the remote
+ * /config payload and overridden per-call via placement options — NOT part of
+ * EncoreConfig (configure() is connection/behavior settings only).
  */
 export interface UIConfiguration {
     titleText?: string;
@@ -162,17 +251,140 @@ export interface UIConfiguration {
     creditClaimedTitleText?: string;
     creditClaimedSubtitleText?: string;
     applyCreditsButtonText?: string;
+    /** App name for reward template substitution (e.g. "Tinder Plus"). Display only. */
+    appName?: string;
+    /** Reward value for template substitution (e.g. "3"). Display only — not an entitlement. */
+    entitlementValue?: string;
+    /** Reward unit for template substitution (e.g. "months"). Display only — not an entitlement. */
+    entitlementUnit?: string;
 }
 /**
  * Main SDK configuration options
  */
 export interface EncoreConfig {
     apiKey: string;
-    userId?: string | undefined;
-    baseURL?: string;
     environment?: 'production' | 'development' | 'staging' | 'localhost';
     logLevel?: 'none' | 'debug';
-    uiConfiguration?: UIConfiguration;
+    /**
+     * Redemption flow:
+     * - 'deferred' (default): show() resolves when the user CLAIMS an offer (a transaction
+     *   record is created, NO redirect). The host runs its own conversion, then calls
+     *   redeem() to render the redemption screen + send the user to the advertiser.
+     * - 'immediate': the legacy one-step flow — claiming an offer redirects to the
+     *   advertiser and shows the success screen inline (no separate redeem() call).
+     * This is a control-flow contract (it changes what host code must call), so it is
+     * a LOCAL config value, not remote.
+     */
+    redemptionMode?: 'deferred' | 'immediate';
+}
+/**
+ * Offer descriptor carried on a transaction — enough to render the redemption screen AND
+ * to rebuild the advertiser redirect at redeem() time (so the deferred flow never
+ * needs the live offer again). `advertiserUrl` may contain a TRANSACTION_ID
+ * placeholder, substituted with the transaction id when the redemption fires.
+ */
+export interface OfferRef {
+    id: string;
+    campaignId: string;
+    advertiserUrl: string;
+    trackingParameters?: Record<string, string>;
+    advertiserName?: string;
+    /** Display-only reward copy (e.g. "30 days of Apple Music"). NOT an entitlement. */
+    reward?: string;
+    imageUrl?: string;
+    logoUrl?: string;
+}
+/**
+ * A claimed offer awaiting redemption. Claiming starts a transaction, and the
+ * returned `transactionId` is this transaction's durable handle (the same id used by
+ * `didGrant`, `waitForVerification`, and the backend).
+ */
+export interface Transaction {
+    id: string;
+    /** The persistent account identity this transaction is bound to (app_account_id). */
+    appAccountId: string;
+    /** The placement the offer was claimed at, if any (keys the local placement->transaction map). */
+    placementId?: string;
+    offer: OfferRef;
+    status: 'claimed' | 'redeemed';
+    /** ISO-8601 timestamps. */
+    createdAt: string;
+    expiresAt: string;
+    redeemedAt?: string;
+}
+/** Result of `show()` / `present()`. */
+export type ShowResult = 
+/**
+ * The user claimed an offer. A transaction was recorded SDK-side, and in
+ * 'immediate' mode the advertiser was also opened in a new tab; the SDK
+ * renders nothing after a claim — the host owns that moment. Deliberately
+ * NOT a conversion claim: advertiser conversion is asynchronous and
+ * server-authoritative; check it server-side by user (never from the client).
+ * In 'deferred' mode, call redeem() after your own conversion work — the SDK
+ * resolves the pending transaction internally; no handle needed.
+ */
+{
+    status: 'claimed';
+}
+/** The user dismissed the carousel without claiming. */
+ | {
+    status: 'dismissed';
+    reason?: NotGrantedReason;
+}
+/** No eligible offers (or a control-cohort ghost trigger). */
+ | {
+    status: 'unavailable';
+};
+/** Options for `redeem()`. */
+export interface RedeemOptions {
+    /**
+     * Resolve the transaction made at this placement (the local placement->transaction map). When
+     * passed via Encore.placement(id).redeem() this is the placement id. If no transaction
+     * exists for the placement, resolves `none` — it never crosses to another placement.
+     */
+    placement?: string;
+    /** Optional host product card to render as "Active" above the pending offer. */
+    host?: {
+        name: string;
+        status?: string;
+        logoUrl?: string;
+    };
+}
+/** Result of `redeem()`. */
+export type RedeemResult = 
+/** The advertiser redirect was performed for the pending transaction. */
+{
+    status: 'redeemed';
+}
+/**
+ * The sheet closed without redeeming. `reason` mirrors show(): user-driven
+ * closes carry no reason or a user reason; internal failures carry
+ * `{ type: 'error', error }` — redeem() never rejects. On an error the pending
+ * transaction is untouched, so calling redeem() again later is safe.
+ */
+ | {
+    status: 'dismissed';
+    reason?: NotGrantedReason;
+} | {
+    status: 'expired';
+}
+/** STRICTLY "no pending transaction to redeem" — never an error disguise. */
+ | {
+    status: 'none';
+};
+/**
+ * A subscription/conversion event forwarded from the host (Tier-1 client signal).
+ * NON-AUTHORITATIVE — posted via the pk-authed analytics channel, never the HMAC
+ * webhook. Use server-to-server webhooks (apple/google/revenuecat/superwall/encore)
+ * for authoritative revenue truth.
+ */
+export interface SubscriptionEvent {
+    type: 'did_subscribe' | 'did_renew' | 'did_cancel' | 'did_convert' | (string & {});
+    plan?: string;
+    price?: number;
+    currency?: string;
+    productId?: string;
+    [key: string]: unknown;
 }
 /**
  * Event handler function type

package/types/types.d.ts.map

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

package/types/ui/OfferCarousel.d.ts

@@ -4,6 +4,15 @@
  */
 import type { OfferModel as Offer } from '../api/models';
 import type { UIConfiguration } from '../types';
+export interface OfferCarouselOptions {
+    /**
+     * 'responsive' (default): today's behavior — horizontal carousel on desktop, vertical
+     * full-screen list on mobile (viewport-derived).
+     * 'paged' (thankYou layout): always-horizontal, one-card-per-view, scroll-snap paged
+     * carousel at every breakpoint, with chevron nav bubbles.
+     */
+    mode?: 'responsive' | 'paged';
+}
 interface CarouselEventMap extends Record<string, unknown> {
     offerClaim: {
         offer: Offer;
@@ -22,7 +31,7 @@ interface CarouselEventMap extends Record<string, unknown> {
 }
 export declare class OfferCarousel {
     #private;
-    constructor(offers: Offer[], uiConfig?: UIConfiguration);
+    constructor(offers: Offer[], uiConfig?: UIConfiguration, options?: OfferCarouselOptions);
     /**
      * Render the carousel
      */
@@ -40,11 +49,13 @@ export declare class OfferCarousel {
      */
     getTotalOffers(): number;
     /**
-     * Navigate to next offer
+     * Navigate to next offer. A user INTENT: commits domain state immediately (so
+     * semantic UI updates once, and rapid clicks chain naturally), then runs the
+     * scroll as an effect. The highlight is not touched — it follows the motion.
      */
     next(): void;
     /**
-     * Navigate to previous offer
+     * Navigate to previous offer — see next().
      */
     previous(): void;
     /**

package/types/ui/OfferCarousel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OfferCarousel.d.ts","sourceRoot":"","sources":["../../src/ui/OfferCarousel.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,UAAU,IAAI,KAAK,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAMhD,UAAU,gBAAiB,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACxD,UAAU,EAAE;QAAE,KAAK,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,YAAY,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAChC,SAAS,EAAE;QAAE,KAAK,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C,QAAQ,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;CAChC;AAED,qBAAa,aAAa;;gBAaZ,MAAM,EAAE,KAAK,EAAE,EAAE,QAAQ,CAAC,EAAE,eAAe;IAavD;;OAEG;IACH,MAAM,IAAI,WAAW;IAoDrB;;OAEG;IACH,EAAE,CAAC,CAAC,SAAS,MAAM,gBAAgB,EACjC,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,CAAC,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,KAAK,IAAI,GAC9C,MAAM,IAAI;IAIb;;OAEG;IACH,eAAe,IAAI,MAAM;IAIzB;;OAEG;IACH,cAAc,IAAI,MAAM;IAIxB;;OAEG;IACH,IAAI,IAAI,IAAI;IAUZ;;OAEG;IACH,QAAQ,IAAI,IAAI;IA+ShB;;OAEG;IACH,OAAO,IAAI,IAAI;CAkBhB"}
+{"version":3,"file":"OfferCarousel.d.ts","sourceRoot":"","sources":["../../src/ui/OfferCarousel.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,UAAU,IAAI,KAAK,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAMhD,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,IAAI,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC;CAC/B;AAED,UAAU,gBAAiB,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACxD,UAAU,EAAE;QAAE,KAAK,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,YAAY,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAChC,SAAS,EAAE;QAAE,KAAK,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C,QAAQ,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;CAChC;AAED,qBAAa,aAAa;;gBAgDZ,MAAM,EAAE,KAAK,EAAE,EAAE,QAAQ,CAAC,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,oBAAoB;IAcvF;;OAEG;IACH,MAAM,IAAI,WAAW;IAgLrB;;OAEG;IACH,EAAE,CAAC,CAAC,SAAS,MAAM,gBAAgB,EACjC,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,CAAC,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,KAAK,IAAI,GAC9C,MAAM,IAAI;IAIb;;OAEG;IACH,eAAe,IAAI,MAAM;IAIzB;;OAEG;IACH,cAAc,IAAI,MAAM;IAIxB;;;;OAIG;IACH,IAAI,IAAI,IAAI;IAUZ;;OAEG;IACH,QAAQ,IAAI,IAAI;IA+YhB;;OAEG;IACH,OAAO,IAAI,IAAI;CAqBhB"}