@encorekit/web-sdk 2.0.2 → 2.0.4

package/types/analytics/DiagnosticsOutbox.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Reliable delivery for the `show()` choke-point diagnostics: `sdk_show_entered`,
+ * `sdk_show_aborted`, and the terminal `sdk_placement_resolved`.
+ *
+ * ONE outbox for all three, matching iOS, where every diagnostic goes through
+ * `Encore.shared.services.outbox` (`OfferSheetCoordinator.enqueueDiagnostic`).
+ * They share a delivery guarantee for the same reason: each one is the only
+ * evidence of an exit that produces no other event, so a row that only sometimes
+ * survives the tab closing is worse than none — the loss is invisible *and*
+ * biased toward the exits that close the page.
+ *
+ * Sharing one queue also means one set of page-lifecycle listeners for the whole
+ * diagnostic family rather than one per event type.
+ *
+ * See `ReliableOutbox` for the mechanism.
+ */
+import { ReliableOutbox } from './ReliableOutbox';
+import type { StorageManager } from '../core/StorageManager';
+export declare class DiagnosticsOutbox extends ReliableOutbox {
+    constructor(apiKey: string, analyticsBaseURL: string, storage: StorageManager);
+}
+//# sourceMappingURL=DiagnosticsOutbox.d.ts.map

package/types/analytics/DiagnosticsOutbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DiagnosticsOutbox.d.ts","sourceRoot":"","sources":["../../src/analytics/DiagnosticsOutbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAI7D,qBAAa,iBAAkB,SAAQ,cAAc;gBACvC,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc;CAG9E"}

package/types/analytics/ReliableOutbox.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Reliable delivery for analytics events that must survive tab-close — 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).
+ *
+ * Extracted from ExposureOutbox, which was the first consumer of this pattern:
+ * every consumer gets its own instance (and its own storage key), so multiple
+ * ReliableOutbox instances bind independent lifecycle listeners — harmless
+ * duplication, not worth a shared coordinator for a small number of consumers.
+ */
+import type { AnalyticsEvent } from './models';
+import type { StorageManager } from '../core/StorageManager';
+export declare class ReliableOutbox {
+    #private;
+    constructor(apiKey: string, analyticsBaseURL: string, storage: StorageManager, storageKey: string);
+    /**
+     * Persist an 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 event.
+     */
+    enqueue(event: AnalyticsEvent, eventId: string): boolean;
+    /** Replay every persisted envelope (init recovery + unload flush). */
+    flush(): void;
+}
+//# sourceMappingURL=ReliableOutbox.d.ts.map

package/types/analytics/ReliableOutbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReliableOutbox.d.ts","sourceRoot":"","sources":["../../src/analytics/ReliableOutbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAiB,MAAM,UAAU,CAAC;AAE9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAG7D,qBAAa,cAAc;;gBAOb,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM;IAQjG;;;;;;;OAOG;IACH,OAAO,CAAC,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO;IAaxD,sEAAsE;IACtE,KAAK,IAAI,IAAI;CAoDd"}

package/types/analytics/events.d.ts

@@ -59,9 +59,9 @@ export declare const ClaimFailureReason: {
 export declare function declineReasonWireValue(reason: string | undefined): string | undefined;
 export declare function sdkInitialized(distinctId: string, sdkVersion: string, appBundleId: string): AnalyticsEvent;
 export declare function userIdentified(distinctId: string, userId: string, appBundleId: string, attributes?: Record<string, unknown>): AnalyticsEvent;
-export declare function offerPresentationTriggered(distinctId: string, presentationId: string, variantId?: string, useCase?: UseCase): AnalyticsEvent;
-export declare function offerPresentationFailed(distinctId: string, reason: string, presentationId: string, variantId?: string, useCase?: UseCase): AnalyticsEvent;
-export declare function offerPresentationSuccess(distinctId: string, presentationId: string, offerCount: number, variantId?: string, useCase?: UseCase): AnalyticsEvent;
+export declare function offerPresentationTriggered(distinctId: string, presentationId: string, variantId?: string, useCase?: UseCase, placementId?: string): AnalyticsEvent;
+export declare function offerPresentationFailed(distinctId: string, reason: string, presentationId: string, variantId?: string, useCase?: UseCase, placementId?: string): AnalyticsEvent;
+export declare function offerPresentationSuccess(distinctId: string, presentationId: string, offerCount: number, variantId?: string, useCase?: UseCase, placementId?: string): AnalyticsEvent;
 export declare function offerPresented(distinctId: string, params: {
     campaignId: string;
     creativeId: string;
@@ -73,6 +73,7 @@ export declare function offerPresented(distinctId: string, params: {
     presentationId: string;
     variantId?: string;
     useCase?: UseCase;
+    placementId?: string;
 }): AnalyticsEvent;
 export declare function offerClaimed(distinctId: string, params: {
     campaignId: string;
@@ -85,6 +86,7 @@ export declare function offerClaimed(distinctId: string, params: {
     presentationId: string;
     variantId?: string;
     useCase?: UseCase;
+    placementId?: string;
 }): AnalyticsEvent;
 export declare function offerDeclined(distinctId: string, params: {
     campaignId: string;
@@ -97,6 +99,7 @@ export declare function offerDeclined(distinctId: string, params: {
     presentationId: string;
     variantId?: string;
     useCase?: UseCase;
+    placementId?: string;
 }): AnalyticsEvent;
 export declare function offerSheetDismissed(distinctId: string, params: {
     presentationId: string;
@@ -106,6 +109,7 @@ export declare function offerSheetDismissed(distinctId: string, params: {
     declineReason?: string;
     variantId?: string;
     useCase?: UseCase;
+    placementId?: string;
 }): AnalyticsEvent;
 export declare function offerTimeSpent(distinctId: string, params: {
     campaignId: string;
@@ -116,6 +120,7 @@ export declare function offerTimeSpent(distinctId: string, params: {
     presentationId: string;
     variantId?: string;
     useCase?: UseCase;
+    placementId?: string;
 }): AnalyticsEvent;
 /**
  * The offer identity every claim-funnel and advertiser-handoff event carries —
@@ -141,6 +146,8 @@ export interface OfferEventContext {
     presentationId?: string;
     variantId?: string;
     useCase?: UseCase;
+    /** The publisher's placement label, when they supplied one. See `placementProperty`. */
+    placementId?: string;
 }
 /**
  * The claim TAP, emitted before any guard can fail — the advertiser funnel's
@@ -208,6 +215,106 @@ export declare function offerWebviewLoadFailed(distinctId: string, ctx: OfferEve
 export declare function offerWebviewDismissed(distinctId: string, ctx: OfferEventContext, params: {
     timeSpentSeconds: number;
 }): AnalyticsEvent;
+/**
+ * A strict-unlock claim confirmed by the advertiser's postback. Mirrors iOS
+ * `OfferVerifiedEvent`, including its two shapes: with the presentation context
+ * when the claim verified inside the session that made it, and with the
+ * transaction id ALONE when a later page load reconciled it.
+ *
+ * The context is optional for exactly that second case, and absent fields stay
+ * absent rather than being reconstructed — the same rule `OfferEventContext`
+ * states above. A reconciled claim genuinely has no impression or presentation in
+ * scope (the page that held them is gone), and `impression_id` is the warehouse's
+ * primary claim↔completion join key: a fabricated one joins against nothing while
+ * looking like coverage, where an absent one falls through to the documented
+ * `transaction_id` fallback and joins correctly.
+ *
+ * 🔴 `use_case` and `placement_id` are the exception, and they are NOT
+ * presentation-scoped. They describe the claim, which is the thing being verified, so
+ * they survive the page that made it — persisted on the pending record precisely so
+ * the reconciled shape can still carry them (`StrictUnlockReconciler.PendingClaim`,
+ * mirroring swift#123). Without them a strict-mode verification is the one conversion
+ * signal that falls outside every per-use-case and per-placement split, which is the
+ * comparison strict mode exists to be judged on. The bare shape is bare of
+ * PRESENTATION identity — `impression_id`, `presentation_id`, `variant_id` — not of
+ * every dimension.
+ *
+ * Only ever emitted in `unlockMode: 'strict'` — optimistic mode does no
+ * verification, so it has nothing to report.
+ */
+export declare function offerVerified(distinctId: string, params: {
+    transactionId: string;
+    useCase?: UseCase;
+    placementId?: string;
+}, ctx?: OfferEventContext): AnalyticsEvent;
+/**
+ * Why a `show()` exited before `sdk_offer_presentation_triggered` fired.
+ *
+ * The cross-SDK vocabulary, matching iOS's `ShowAbortReason` — not extended with
+ * web-only members. Two of web's pre-trigger exits (an invalid `useCase` value, a
+ * use case with no resolved copy) have no member here and therefore emit no
+ * `sdk_show_aborted`; both are fully described by `sdk_placement_resolved`'s
+ * `not_presented_reason`. Adding values to a frozen cross-SDK vocabulary is a
+ * cross-SDK decision, not a web one.
+ *
+ * `unsupported_os` exists on iOS and can never occur here — a browser that runs
+ * this bundle can render the sheet.
+ */
+export declare const ShowAbortReason: {
+    readonly NOT_CONFIGURED: "not_configured";
+    readonly ALREADY_PRESENTING: "already_presenting";
+    readonly EXPERIMENT_CONTROL: "experiment_control";
+};
+export type ShowAbortReasonValue = (typeof ShowAbortReason)[keyof typeof ShowAbortReason];
+/**
+ * `show()` was called — emitted at the very top, before any gate.
+ *
+ * The only evidence the SDK was reached at all on an attempt that then exits
+ * somewhere with nothing else to say. `sdk_placement_resolved` covers every exit
+ * *after* configuration; this one is what makes "the host called `show()`"
+ * observable independently of what happened next.
+ *
+ * `layer` distinguishes the SDK that emitted it, since the React Native and
+ * Flutter bridges sit on top of this one and emit their own.
+ *
+ * No `variant_id`: at this point the SDK has not resolved which variant this
+ * attempt will render, and stamping the paywall's variant on what turns out to be
+ * a reward presentation is precisely the mis-attribution the per-use-case variant
+ * resolution exists to prevent.
+ *
+ * `use_case` IS known, however, because the caller asked for it, and it is stamped
+ * from the base property set rather than through the conditional `useCaseProperty`
+ * the offer-funnel events use. Required in the params type for the same reason: this
+ * dimension partitions a backend alarm (see `showAborted`), and a property that can
+ * be omitted eventually is.
+ */
+export declare function showEntered(distinctId: string, params: {
+    presentationId: string;
+    useCase: UseCase;
+    placementId?: string;
+}): AnalyticsEvent;
+/**
+ * A `show()` that exited at a pre-trigger gate. The taxonomy iOS draws and this
+ * mirrors: `sdk_show_aborted` means the attempt never entered the presentation
+ * funnel, `sdk_offer_presentation_failed` means it entered and did not reach
+ * presented.
+ *
+ * 🔴 `use_case` is REQUIRED and stamped from the base property set, never through the
+ * conditional `useCaseProperty`. Backend #443 counts `control_suppressions` off this
+ * event PARTITIONED BY use case, as the input to the D-6 bypass alarm — so a row
+ * without the dimension is not merely a thinner row, it is a suppression that lands
+ * in a NULL bucket and goes uncounted by the alarm it was supposed to feed. A
+ * conditional spread would make that the behaviour of whichever abort reason happened
+ * to be missing a use case; required-and-unconditional makes it unreachable. iOS
+ * (swift#123) and Android (android#55) stamp it the same way, off a non-optional enum.
+ */
+export declare function showAborted(distinctId: string, params: {
+    reason: ShowAbortReasonValue;
+    presentationId: string;
+    useCase: UseCase;
+    placementId?: string;
+    variantId?: string;
+}): AnalyticsEvent;
 /**
  * The server-assigned variant landed and the sheet will render it.
  *
@@ -221,6 +328,12 @@ export declare function offerWebviewDismissed(distinctId: string, ctx: OfferEven
  * `'remote'` (config resolved) or `'fallback'` (it did not, and the bundled copy
  * rendered). It never reports `'cache'` — web persists no variant/template pair,
  * so claiming a cache tier would describe a mechanism this SDK does not have.
+ *
+ * Deliberately carries NEITHER `use_case` NOR `placement_id`, unlike the other two
+ * `sdk_sdui_*` events. This one fires at CONFIG-FETCH time, not inside a presentation:
+ * there is no placement yet, and the fetch covers every use case at once. Stamping
+ * either would be inventing a value, which is the one thing the placement dimension
+ * must never contain.
  */
 export declare function sduiConfigLoaded(distinctId: string, params: {
     variantId?: string;
@@ -237,6 +350,8 @@ export declare function sduiButtonTapped(distinctId: string, params: {
     actionType: 'close' | 'claimOffer' | 'openUrl' | 'next' | 'previous';
     presentationId: string;
     currentState: string;
+    useCase?: UseCase;
+    placementId?: string;
 }): AnalyticsEvent;
 /**
  * The user moved through the offer carousel. `scrollAxis` is genuinely
@@ -248,6 +363,8 @@ export declare function sduiScroll(distinctId: string, params: {
     scrollAxis: 'horizontal' | 'vertical';
     scrollPosition: number;
     presentationId: string;
+    useCase?: UseCase;
+    placementId?: string;
 }): AnalyticsEvent;
 /**
  * Exposure at the offer trigger — logged for BOTH treatment and control to

package/types/analytics/events.d.ts.map

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

package/types/analytics/placementResolved.d.ts

@@ -0,0 +1,150 @@
+/**
+ * `sdk_placement_resolved` — the terminal record for one `show()` attempt, in
+ * iOS/Android's frozen outcome vocabulary (`PresentationResult.swift`).
+ *
+ * Exactly one row per attempt, whatever happened: not configured, use case not
+ * enabled, control cohort, no offers, claimed, dismissed, or blown up. That is the
+ * whole point of it — every OTHER event in the funnel exists only on the path that
+ * produces it, so a funnel built from them has no denominator that survives the
+ * early exits. Delivered through `DiagnosticsOutbox` (reliable, not
+ * fire-and-forget), and built from exactly one call site: `#recordPlacementResolved`
+ * in `Encore.ts`, which `show()`'s outer wrapper calls once.
+ *
+ * Two shape decisions worth stating up front, because both look like omissions:
+ *
+ * `advertiser_outcome` never carries `'verified'` on web. iOS's sheet blocks on the
+ * strict-unlock verification poll and can therefore fold the result into its terminal
+ * record; web's poll runs detached so it cannot race the modal's own close listeners
+ * (docs/architecture/platform-divergence/web.md #3). The fact is not lost — it is
+ * reported by `sdk_offer_verified`, joinable back on `presentation_id` in session or
+ * `transaction_id` across sessions. A cross-platform dashboard segmenting on
+ * `advertiser_outcome` alone will see web permanently at 0% verified; that is the
+ * documented shape, not a bug.
+ *
+ * `publisher_outcome` is REQUIRED and always `'not_attempted'`. The record reports
+ * what Encore did at the moment its flow ended, and Encore did not attempt a
+ * purchase — whether because web has no purchase controller at all, or because this
+ * particular flow did not use one, or because the use case is a reward. All three are
+ * the same observable fact here. Making it optional would smuggle in a second "does
+ * this platform even have the capability" dimension the record is not meant to carry.
+ */
+import type { AnalyticsEvent } from './models';
+import type { ShowResult } from '../types';
+import type { WireUseCase } from '../core/useCase';
+/**
+ * NOT `'verified'` (see the file header). NOT `'cooldown'` either: the
+ * provisional-cooldown mechanism it describes is still unmerged backend-side, so a
+ * value for it would name something that cannot happen yet.
+ */
+export type AdvertiserOutcome = 'not_attempted' | 'claimed' | 'failed';
+/** iOS/Android's wire values verbatim. Web emits only the first — see the header. */
+export type PublisherOutcome = 'not_attempted' | 'purchased' | 'cancelled' | 'pending' | 'failed';
+export type Resolution = 'not_presented' | 'presented';
+export type NotPresentedReason = 
+/**
+ * Mapped from the `notConfigured` result, though no row can actually carry it:
+ * the outbox does not exist before configure(), so that path produces nothing to
+ * deliver. Mapped anyway so the translation is correct the day a diagnostic
+ * channel exists that early — iOS has the same blind spot, its enqueue being a
+ * no-op while services are nil.
+ */
+'not_configured' | 'already_presenting' | 'no_offer_available' | 'experiment_control' | 'use_case_unavailable'
+/** `error.<ErrorCode>`, lowercased. */
+ | `error.${string}`;
+export type Dismissal = 
+/** `userClosedModal` — the × and Escape. */
+'close_button'
+/**
+ * `userClickedOutside`. iOS's generic catch-all, not `swipe_dismiss`: that names a
+ * mobile gesture a browser backdrop tap is not.
+ */
+ | 'dismissed'
+/** `userDeclinedLastOffer`. */
+ | 'last_offer_declined'
+/** A claim succeeded and the sheet closed itself. */
+ | 'flow_completed'
+/** An unexpected failure after the sheet was already in play. */
+ | 'interrupted';
+/**
+ * The three independent axes of a presented flow — iOS's
+ * `PresentationResult.Outcome` (`PresentationResult.swift:141`), field for field.
+ *
+ * All three are REQUIRED together. `'not_attempted'` is a real value meaning "the
+ * funnel was open and nothing entered it", which is a different fact from the axis
+ * being absent — and absent is not a state a presented row has. A row missing one
+ * of these is not a smaller row, it is an unreadable one: a dashboard cannot tell
+ * "nothing happened on this axis" from "the SDK forgot to say".
+ */
+export interface PresentedOutcome {
+    advertiserOutcome: AdvertiserOutcome;
+    /** Always `'not_attempted'` on web today — see the file header. */
+    publisherOutcome: PublisherOutcome;
+    dismissal: Dismissal;
+}
+/** Identity of what was claimed, carried only when the advertiser funnel got there. */
+interface ClaimIdentity {
+    campaignId?: string;
+    offerId?: string;
+    transactionId?: string;
+}
+/**
+ * The outcome half of the record, as a discriminated union rather than a bag of
+ * optionals — so the three-axis invariant is a compile error to break, not a
+ * convention to remember. Mirrors iOS's `enum PresentationResult { case
+ * notPresented(reason); case presented(Outcome) }`.
+ *
+ * The two branches share NO outcome fields: a `not_presented` row carries a reason
+ * and nothing else, exactly as iOS's wire assembly does
+ * (`OfferEvents+Outbox.swift:76-90`). Publishing `publisher_outcome:
+ * 'not_attempted'` on a row where no sheet ever appeared would be reporting on a
+ * funnel that never opened.
+ */
+export type PlacementOutcomeFields = {
+    resolution: 'not_presented';
+    notPresentedReason: NotPresentedReason;
+} | ({
+    resolution: 'presented';
+} & PresentedOutcome & ClaimIdentity);
+/** The record's identity fields, present on every row regardless of resolution. */
+export interface PlacementResolvedContext {
+    placementId?: string;
+    presentationId: string;
+    useCase: WireUseCase;
+    unlockMode: 'strict' | 'optimistic';
+    variantId?: string;
+}
+export type PlacementResolvedProperties = PlacementResolvedContext & PlacementOutcomeFields;
+export declare function placementResolved(distinctId: string, properties: PlacementResolvedProperties): AnalyticsEvent;
+/**
+ * What a resolving site must state explicitly, because the public `ShowResult`
+ * collapses it and no mapper can recover it:
+ *
+ * - `{status:'unavailable'}` is deliberately overloaded — no eligible offers, NCL
+ *   control cohort, and use case not enabled all share it, so an integrator cannot
+ *   reverse-engineer the incrementality experiment from a return value. The record
+ *   still needs to tell them apart.
+ * - `UNKNOWN_ERROR` is produced by three structurally different sites: a failure
+ *   before the sheet ever rendered, a rendering failure with no claim attempted, and
+ *   a claim whose transaction write failed. The code alone cannot distinguish them.
+ *
+ * Every other case — a claim, a string `NotGrantedReason`, a distinctly-coded error —
+ * is fully derivable, and an override for those is unnecessary though harmless: it
+ * always wins.
+ */
+export interface PlacementResolutionOverride {
+    notPresentedReason?: NotPresentedReason;
+    advertiserOutcome?: AdvertiserOutcome;
+    dismissal?: Dismissal;
+}
+export type DerivedPlacementResolvedFields = PlacementOutcomeFields;
+/**
+ * Pure mapper: a `ShowResult` (plus a disambiguating override where the result
+ * collapses one) to the record's outcome fields.
+ *
+ * `ShowResult`'s claimed member already carries `campaignId`/`offerId`/
+ * `transactionId` inline, so nothing else has to be threaded here to identify what
+ * was claimed.
+ */
+export declare function deriveResolvedFields(result: ShowResult, override?: PlacementResolutionOverride): DerivedPlacementResolvedFields;
+export {};
+//# sourceMappingURL=placementResolved.d.ts.map

package/types/analytics/placementResolved.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"placementResolved.d.ts","sourceRoot":"","sources":["../../src/analytics/placementResolved.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,KAAK,EAA+B,UAAU,EAAE,MAAM,UAAU,CAAC;AACxE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAGnD;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,eAAe,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEvE,qFAAqF;AACrF,MAAM,MAAM,gBAAgB,GAAG,eAAe,GAAG,WAAW,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC;AAElG,MAAM,MAAM,UAAU,GAAG,eAAe,GAAG,WAAW,CAAC;AAEvD,MAAM,MAAM,kBAAkB;AAC5B;;;;;;GAMG;AACD,gBAAgB,GAChB,oBAAoB,GACpB,oBAAoB,GACpB,oBAAoB,GACpB,sBAAsB;AACxB,uCAAuC;GACrC,SAAS,MAAM,EAAE,CAAC;AAEtB,MAAM,MAAM,SAAS;AACnB,4CAA4C;AAC1C,cAAc;AAChB;;;GAGG;GACD,WAAW;AACb,+BAA+B;GAC7B,qBAAqB;AACvB,qDAAqD;GACnD,gBAAgB;AAClB,iEAAiE;GAC/D,aAAa,CAAC;AAElB;;;;;;;;;GASG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iBAAiB,EAAE,iBAAiB,CAAC;IACrC,mEAAmE;IACnE,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,SAAS,EAAE,SAAS,CAAC;CACtB;AAED,uFAAuF;AACvF,UAAU,aAAa;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,sBAAsB,GAC9B;IAAE,UAAU,EAAE,eAAe,CAAC;IAAC,kBAAkB,EAAE,kBAAkB,CAAA;CAAE,GACvE,CAAC;IAAE,UAAU,EAAE,WAAW,CAAA;CAAE,GAAG,gBAAgB,GAAG,aAAa,CAAC,CAAC;AAErE,mFAAmF;AACnF,MAAM,WAAW,wBAAwB;IACvC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,WAAW,CAAC;IACrB,UAAU,EAAE,QAAQ,GAAG,YAAY,CAAC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,2BAA2B,GAAG,wBAAwB,GAAG,sBAAsB,CAAC;AAE5F,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,2BAA2B,GACtC,cAAc,CAchB;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,2BAA2B;IAC1C,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAYD,MAAM,MAAM,8BAA8B,GAAG,sBAAsB,CAAC;AAsBpE;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,UAAU,EAClB,QAAQ,CAAC,EAAE,2BAA2B,GACrC,8BAA8B,CAyEhC"}

package/types/api/APIClient.d.ts

@@ -46,8 +46,14 @@ export declare class APIClient {
      * turn this best-effort label into a hard failure of the entire offers fetch for
      * a publisher who simply named their placement something long. Truncating keeps
      * the analytics label degraded-but-present instead of losing the offer entirely.
+     *
+     * `maxPostbackTimeMs` is strict-unlock mode's offer filter — only campaigns whose
+     * postback latency fits the verification window. It is a fixed SDK constant
+     * (`StrictUnlock.MAX_POSTBACK_TIME_MS`), never publisher input, so unlike
+     * `placementId` there is nothing to bound here: the contract's own 1000..120000
+     * range (`offers/dto.ts`) cannot be violated by a caller.
      */
-    fetchOffers(userId: string, attributes: UserAttributes, placementId?: string): Promise<{
+    fetchOffers(userId: string, attributes: UserAttributes, placementId?: string, maxPostbackTimeMs?: number): Promise<{
         offers: OfferModel[];
     }>;
     /**

package/types/api/APIClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"APIClient.d.ts","sourceRoot":"","sources":["../../src/api/APIClient.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"APIClient.d.ts","sourceRoot":"","sources":["../../src/api/APIClient.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAe,cAAc,EAAE,WAAW,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAEtG,OAAO,KAAK,EAEV,wBAAwB,EAIxB,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,EACpB,UAAU,EACV,yBAAyB,EAC1B,MAAM,UAAU,CAAC;AAUlB,UAAU,cAAc;IACtB,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAQD,qBAAa,SAAS;;gBAKR,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;IAM3C;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAI/B;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAIjC;;OAEG;IACG,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAW7E;;OAEG;IACG,IAAI,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAY9F;;OAEG;IACG,KAAK,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAiP/F;;;;;;;;;;;;;;;;;OAiBG;IACG,WAAW,CACf,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,cAAc,EAC1B,WAAW,CAAC,EAAE,MAAM,EACpB,iBAAiB,CAAC,EAAE,MAAM,GACzB,OAAO,CAAC;QAAE,MAAM,EAAE,UAAU,EAAE,CAAA;KAAE,CAAC;IA+EpC;;;;;;;OAOG;IACG,gBAAgB,CACpB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,OAAO,GAChB,OAAO,CAAC,wBAAwB,CAAC;IAcpC;;OAEG;IACG,eAAe,CACnB,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,aAAa,GAAG,OAAO,GACjC,OAAO,CAAC,OAAO,CAAC;IAanB;;OAEG;IACG,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAyE/D;;OAEG;IACG,uBAAuB,CAC3B,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC;QAAE,MAAM,EAAE,kBAAkB,CAAC;QAAC,GAAG,EAAE,yBAAyB,GAAG,IAAI,CAAA;KAAE,CAAC;IAcjF;;OAEG;IACG,QAAQ,CACZ,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAC7C,OAAO,CAAC,gBAAgB,CAAC;IAa5B;;OAEG;IACG,YAAY,CAChB,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAC7C,OAAO,CAAC,oBAAoB,CAAC;IAchC;;;;;;;;;;;;;;;;;OAiBG;IACG,WAAW,CACf,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,OAAO,GAChB,OAAO,CAAC,oBAAoB,CAAC;IAehC;;OAEG;IACG,WAAW,CAAC,MAAM,EAAE;QACxB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;QAClD,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACnC,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBjB;;OAEG;IACG,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAW3D"}

package/types/api/generated/types.d.ts

@@ -317,7 +317,7 @@ export interface paths {
                          * @description SDUI variant ID from frontend config fetch. If provided, filters creatives by variant assignment. If not provided, no variant filtering is applied.
                          */
                         variantId?: string;
-                        /** @description Publisher-defined surface label for where the offer is shown (e.g. 'paywall', 'onboarding', 'settings'). Best-effort analytics context: when supplied it is stamped onto the sdk_offer_requested event so publisher analytics can break the funnel out by placement. Max 64 chars; omit for auto-generated/absent ids (they bucket as '(unlabeled)'). */
+                        /** @description Publisher-defined surface label for where the offer is shown (e.g. 'paywall', 'onboarding', 'settings'). Best-effort analytics context: when supplied it is stamped onto the sdk_offer_requested event so publisher analytics can break the funnel out by placement. Max 64 chars. SDKs may send their own auto-generated `placement_<8 hex>` id when the publisher supplied none — that is expected and is folded into the '(unlabeled)' bucket at read time; do NOT substitute '(unlabeled)' or an empty string yourself. */
                         placementId?: string;
                         /** @description Strict unlock mode: only include campaigns whose postback latency is less than or equal to this value (in milliseconds). Omit for no filtering. Bounded 1000..120000. */
                         maxPostbackTimeMs?: number;
@@ -2991,6 +2991,11 @@ export interface paths {
                          * @description Client-issued UUID v4 used as the conversion attribution id; substituted into the sponsor URL at email-send time.
                          */
                         transactionId: string;
+                        /**
+                         * @description Which Encore surface the user claimed from. Persisted on the transaction this route creates, so the server-side completion — built from that row alone, with no client context — can be split by use case, along with the payout booked on it. Absent means 'churn-intervention'.
+                         * @enum {string}
+                         */
+                        useCase?: "churn-intervention" | "post-action-reward";
                     };
                 };
             };