@encorekit/web-sdk 1.1.19 → 1.1.21

package/types/core/Encore.d.ts

@@ -2,14 +2,15 @@
  * Main Encore SDK Class
  * Singleton class that serves as the public API entry point
  */
-import type { EncoreConfig, UserAttributes, EntitlementType, EntitlementScope, EventHandler, Unsubscribe, PresentationOptions, PresentationResult, PlacementOptions, VerificationStatus, PlacementBuilder as IPlacementBuilder } from '../types';
+import type { EncoreConfig, UserAttributes, EntitlementType, EntitlementScope, EventHandler, Unsubscribe, PresentationOptions, PresentationResult, PlacementOptions, VerificationStatus, PlacementBuilder as IPlacementBuilder, Transaction, ShowResult, RedeemOptions, RedeemResult } from '../types';
+import type { NCLExperimentState } from '../experiments/types';
 export declare class EncoreSDK {
     #private;
     constructor();
     /**
      * Configure the SDK with API key and options
      */
-    configure(config: EncoreConfig): void;
+    configure(config: EncoreConfig): boolean;
     /**
      * Identify user with custom user ID and optionally set attributes
      */
@@ -18,6 +19,17 @@ export declare class EncoreSDK {
      * Get current user ID
      */
     getCurrentUserId(): string | null;
+    /**
+     * The persistent account identity this user's transactions, exposures, and
+     * subscription events are bound to (the deferred-redemption join key).
+     *
+     * Resolves to the `identify()`-provided stable id if set, otherwise a
+     * persistent anonymous UUID kept in localStorage (surviving reloads and
+     * same-origin navigations). It is the same value the backend joins on as
+     * `app_account_id` / `iap_links.appTransactionId`. Call `identify(stableId)`
+     * for cross-navigation / cross-device robustness.
+     */
+    getAppAccountId(): string | null;
     /**
      * Reset SDK state (clear user ID, attributes, entitlements, storage)
      */
@@ -26,6 +38,33 @@ export declare class EncoreSDK {
      * Get SDK version
      */
     getVersion(): string;
+    /**
+     * Whether configure() has been called successfully.
+     */
+    isConfigured(): boolean;
+    /**
+     * Read-only snapshot of the live configuration, or null if not configured.
+     * Lets a host app/harness show what the SDK is actually using (vs. what a
+     * form is about to apply) and which endpoints the environment resolves to.
+     */
+    getConfiguration(): {
+        apiKey: string;
+        environment: string;
+        baseURL: string;
+        analyticsBaseURL: string;
+        logLevel: string;
+        redemptionMode: 'deferred' | 'immediate';
+    } | null;
+    /**
+     * Read-only snapshot of the NCL (Net Conversion Lift) experiment state, or
+     * `null` if the SDK is not configured. Lets a host app or harness observe the
+     * deterministic cohort assignment — the config epoch, the user's bucket and
+     * cohort, and whether the A/B exposure has been logged this epoch — without
+     * affecting it (no exposure is logged, no rollout is changed). Reports
+     * `enabled: false` / `cohort: 'notEnrolled'` when no NCL experiment is active
+     * for this app. Async because deterministic bucketing uses WebCrypto SHA-256.
+     */
+    getExperimentState(): Promise<NCLExperimentState | null>;
     /**
      * Set log level
      */
@@ -43,10 +82,44 @@ export declare class EncoreSDK {
      */
     getUserAttributes(): UserAttributes;
     /**
-     * Present offer to user
-     * Supports both callback and promise-based API
+     * Show offers to the user — phase 1 of the two-phase flow.
+     *
+     * Resolves when the user CLAIMS an offer. In 'deferred' mode (default) a transaction
+     * record is created and returned with NO redirect — call redeem() after your own
+     * conversion to send the user to the advertiser. In 'immediate' mode the legacy
+     * one-step flow runs (redirect + success screen inline). Resolves 'dismissed' if
+     * the user closes the carousel, or 'unavailable' if there are no eligible offers.
+     *
+     * @param placementId Optional placement key — recorded on the transaction so
+     *   `placement(id).redeem()` can resolve exactly this transaction later.
+     */
+    show(options?: PresentationOptions, placementOptions?: PlacementOptions, placementId?: string): Promise<ShowResult>;
+    /**
+     * @deprecated Use `show()` (and `redeem()` for the deferred flow). Kept for
+     * back-compat; maps the new `ShowResult` onto the legacy `PresentationResult`.
+     * In 'deferred' mode a transaction resolves here as not-granted (no redirect yet) —
+     * migrate to `show()`/`redeem()` for the two-phase flow.
      */
     presentOffer(options?: PresentationOptions, placementOptions?: PlacementOptions): Promise<PresentationResult>;
+    /**
+     * Redeem a previously-claimed offer — phase 2 of the two-phase flow. Call this
+     * after your own conversion succeeds. Renders the redemption screen for the
+     * pending transaction; on the user's CTA tap it sends them to the advertiser (the
+     * redirect fires inside that gesture, dodging popup blockers) and emits the
+     * provisional grant.
+     *
+     * Transaction resolution (internal — no handle crosses the API): `placement`
+     * resolves the transaction made at THAT placement (never crossing placements →
+     * `none` if absent); else the single most-recent transaction for this user.
+     */
+    redeem(options?: RedeemOptions): Promise<RedeemResult>;
+    /**
+     * The pending (unredeemed) transaction for this user, resolved like redeem() but
+     * without showing any UI — lets a host check whether there's something to redeem
+     * and render its own CTA. Local-only for P0 (server recovery by app_account_id
+     * lands in P1). Pass a placement id to scope to that placement's transaction.
+     */
+    getPendingTransaction(placementId?: string): Transaction | null;
     /**
      * @deprecated Client-side entitlement validation removed for security.
      * Check entitlements on your server by calling Encore's server-side API.

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

@@ -1 +1 @@
-{"version":3,"file":"Encore.d.ts","sourceRoot":"","sources":["../../src/core/Encore.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EAEhB,kBAAkB,EAElB,gBAAgB,IAAI,iBAAiB,EACtC,MAAM,UAAU,CAAC;AAuBlB,qBAAa,SAAS;;;IAuBpB;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI;IAqHrC;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,cAAc,GAAG,IAAI;IAoD3D;;OAEG;IACH,gBAAgB,IAAI,MAAM,GAAG,IAAI;IAIjC;;OAEG;IACH,KAAK,IAAI,IAAI;IAqDb;;OAEG;IACH,UAAU,IAAI,MAAM;IAIpB;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI;IAI1C;;OAEG;IACG,kBAAkB,IAAI,OAAO,CAAC,OAAO,CAAC;IAgB5C;;OAEG;IACH,iBAAiB,CAAC,UAAU,EAAE,cAAc,GAAG,IAAI;IAwBnD;;OAEG;IACH,iBAAiB,IAAI,cAAc;IAInC;;;OAGG;IACG,YAAY,CAAC,OAAO,CAAC,EAAE,mBAAmB,EAAE,gBAAgB,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA0EnH;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,gBAAgB,GAAG,OAAO;IAQ3E;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI;IAiBtE;;;OAGG;IACG,mBAAmB,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAqC/F;;;;OAIG;IACH,EAAE,CAAC,MAAM,EAAE,oBAAoB,EAAE,QAAQ,EAAE,YAAY,CAAC,OAAO,CAAC,GAAG,WAAW;IAS9E;;;;OAIG;IACH,kBAAkB,CAChB,YAAY,EAAE,eAAe,EAC7B,MAAM,CAAC,EAAE,gBAAgB,GACxB;QACD,SAAS,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,IAAI,KAAK,WAAW,CAAC;KACnE;IAaD;;;;;;;;OAQG;IACH,SAAS,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,gBAAgB,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,iBAAiB;CAmalG;AAGD,eAAO,MAAM,MAAM,WAAkB,CAAC"}
+{"version":3,"file":"Encore.d.ts","sourceRoot":"","sources":["../../src/core/Encore.ts"],"names":[],"mappings":"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"}

package/types/core/PlacementBuilder.d.ts

@@ -2,15 +2,12 @@
  * Placement Builder
  * Fluent API for configuring and presenting offers
  */
-import type { PlacementBuilder as IPlacementBuilder, PlacementOptions, PresentationResult, EntitlementType, NotGrantedReason } from '../types';
-export type PresentationExecutor = (options?: PlacementOptions) => Promise<PresentationResult>;
+import type { PlacementBuilder as IPlacementBuilder, PlacementOptions, ShowResult, RedeemResult, NotGrantedReason, ShowOptions } from '../types';
+export type PresentationExecutor = (options?: PlacementOptions, showOptions?: ShowOptions) => Promise<ShowResult>;
+export type RedeemExecutor = (placementId: string) => Promise<RedeemResult>;
 export declare class PlacementBuilder implements IPlacementBuilder {
     #private;
-    constructor(id: string, executor: PresentationExecutor, options?: PlacementOptions);
-    /**
-     * Set callback for when entitlement is granted
-     */
-    onGranted(callback: (entitlement: EntitlementType) => void): PlacementBuilder;
+    constructor(id: string, executor: PresentationExecutor, options?: PlacementOptions, redeemExecutor?: RedeemExecutor);
     /**
      * Set callback for when user declines or offer not granted
      */
@@ -20,8 +17,16 @@ export declare class PlacementBuilder implements IPlacementBuilder {
      */
     onLoadingStateChange(callback: (isLoading: boolean) => void): PlacementBuilder;
     /**
-     * Show the offer and execute the presentation flow
+     * Show the offer and execute the presentation flow.
+     *
+     * @param options Per-call show options (e.g. the `receipt` for the 'thankYou' layout).
+     */
+    show(options?: ShowOptions): Promise<ShowResult>;
+    /**
+     * Redeem the claim made at THIS placement — phase 2 of the two-phase flow.
+     * Resolves the claim recorded for this placement id, renders the redemption
+     * screen, and fires the advertiser redirect on the user's CTA. See Encore.redeem().
      */
-    show(): Promise<PresentationResult>;
+    redeem(): Promise<RedeemResult>;
 }
 //# sourceMappingURL=PlacementBuilder.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"PlacementBuilder.d.ts","sourceRoot":"","sources":["../../src/core/PlacementBuilder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,gBAAgB,IAAI,iBAAiB,EACrC,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EACjB,MAAM,UAAU,CAAC;AAIlB,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,CAAC,EAAE,gBAAgB,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;AAE/F,qBAAa,gBAAiB,YAAW,iBAAiB;;gBAQ5C,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,oBAAoB,EAAE,OAAO,CAAC,EAAE,gBAAgB;IAMlF;;OAEG;IACH,SAAS,CAAC,QAAQ,EAAE,CAAC,WAAW,EAAE,eAAe,KAAK,IAAI,GAAG,gBAAgB;IAK7E;;OAEG;IACH,YAAY,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,GAAG,gBAAgB;IAK5E;;OAEG;IACH,oBAAoB,CAAC,QAAQ,EAAE,CAAC,SAAS,EAAE,OAAO,KAAK,IAAI,GAAG,gBAAgB;IAK9E;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,kBAAkB,CAAC;CAsD1C"}
+{"version":3,"file":"PlacementBuilder.d.ts","sourceRoot":"","sources":["../../src/core/PlacementBuilder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,gBAAgB,IAAI,iBAAiB,EACrC,gBAAgB,EAChB,UAAU,EACV,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACZ,MAAM,UAAU,CAAC;AAIlB,MAAM,MAAM,oBAAoB,GAAG,CACjC,OAAO,CAAC,EAAE,gBAAgB,EAC1B,WAAW,CAAC,EAAE,WAAW,KACtB,OAAO,CAAC,UAAU,CAAC,CAAC;AACzB,MAAM,MAAM,cAAc,GAAG,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;AAE5E,qBAAa,gBAAiB,YAAW,iBAAiB;;gBAStD,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,CAAC,EAAE,gBAAgB,EAC1B,cAAc,CAAC,EAAE,cAAc;IAQjC;;OAEG;IACH,YAAY,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,GAAG,gBAAgB;IAK5E;;OAEG;IACH,oBAAoB,CAAC,QAAQ,EAAE,CAAC,SAAS,EAAE,OAAO,KAAK,IAAI,GAAG,gBAAgB;IAK9E;;;;OAIG;IACG,IAAI,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAoDtD;;;;OAIG;IACG,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC;CAgBtC"}

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.21";
 //# 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"}