@encorekit/web-sdk 1.1.21 → 2.0.0

package/types/analytics/events.d.ts

@@ -3,11 +3,65 @@
  * Event definitions matching cross-platform analytics spec
  */
 import type { AnalyticsEvent } from './models';
+import type { UseCase } from '../types';
+/**
+ * `properties.reason` on `sdk_offer_presentation_failed`. These strings are the
+ * cross-SDK vocabulary, not local names: the backend pins them in
+ * `packages/core/src/canonical/analytics/index.ts`
+ * (`SDKPresentationFailedReason`), iOS produces them from
+ * `NotPresentedReason.wireValue`, and Android from `OfferPresentationFailedEvent`.
+ *
+ * `NO_OFFER_AVAILABLE` is the one this SDK used to get wrong — web emitted
+ * camelCase `noOffersAvailable` for the identical condition iOS reports as
+ * `no_offer_available`, so every dashboard grouping by reason split one
+ * condition across two buckets. The backend registry documents the split
+ * explicitly and matches BOTH spellings as a workaround; this constant is the
+ * emitter-side fix that lets it eventually match one.
+ *
+ * `NO_TEMPLATE` deliberately keeps web's existing spelling: `no_template` is the
+ * name the BACKEND registry canonicalises (`SDKPresentationFailedReason.NoTemplate`),
+ * so web is already correct here and Android's `use_case_unavailable` is the
+ * outlier. Aligning that one is an Android change, not a web change.
+ */
+export declare const PresentationFailedReason: {
+    readonly NO_OFFER_AVAILABLE: "no_offer_available";
+    readonly EXPERIMENT_CONTROL: "experiment_control";
+    readonly NO_TEMPLATE: "no_template";
+};
+/**
+ * `properties.reason` on `sdk_offer_claim_failed` — the failure twin of
+ * `sdk_offer_claimed`. Values match iOS's `ClaimFailureReason`, plus one
+ * browser-only member: `POPUP_BLOCKED` has no native analogue because only a
+ * browser can refuse to open the destination the user just asked for. It is the
+ * single most common way a web claim dies and today it only produces a
+ * `logger.warn` nobody reads.
+ */
+export declare const ClaimFailureReason: {
+    readonly MANAGER_UNAVAILABLE: "manager_unavailable";
+    readonly TRANSACTION_START_FAILED: "transaction_start_failed";
+    readonly MISSING_DESTINATION_URL: "missing_destination_url";
+    readonly INVALID_DESTINATION_URL: "invalid_destination_url";
+    readonly POPUP_BLOCKED: "popup_blocked";
+};
+/**
+ * Translate an SDK-internal decline reason to its wire value.
+ *
+ * Takes the STRING form only. `NotGrantedReason`'s `{type:'error'}` member
+ * is a public RESULT shape that never reaches an analytics call site — the flow
+ * passes the literal `'error'` for that case (see `endPresentation('error', …)`
+ * in Encore.ts) — so accepting the object here would be dead code pretending to
+ * be defensive.
+ *
+ * A reason with no mapping falls back to its raw value rather than being
+ * dropped: an unmapped bucket is visible in the warehouse and can be fixed; a
+ * missing one is invisible.
+ */
+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): AnalyticsEvent;
-export declare function offerPresentationFailed(distinctId: string, reason: string, presentationId: string, variantId?: string): AnalyticsEvent;
-export declare function offerPresentationSuccess(distinctId: string, presentationId: string, offerCount: number, variantId?: string): 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 offerPresented(distinctId: string, params: {
     campaignId: string;
     creativeId: string;
@@ -18,6 +72,7 @@ export declare function offerPresented(distinctId: string, params: {
     presentationTrigger?: string;
     presentationId: string;
     variantId?: string;
+    useCase?: UseCase;
 }): AnalyticsEvent;
 export declare function offerClaimed(distinctId: string, params: {
     campaignId: string;
@@ -29,6 +84,7 @@ export declare function offerClaimed(distinctId: string, params: {
     totalOffers: number;
     presentationId: string;
     variantId?: string;
+    useCase?: UseCase;
 }): AnalyticsEvent;
 export declare function offerDeclined(distinctId: string, params: {
     campaignId: string;
@@ -40,6 +96,7 @@ export declare function offerDeclined(distinctId: string, params: {
     declineReason?: string;
     presentationId: string;
     variantId?: string;
+    useCase?: UseCase;
 }): AnalyticsEvent;
 export declare function offerSheetDismissed(distinctId: string, params: {
     presentationId: string;
@@ -48,6 +105,7 @@ export declare function offerSheetDismissed(distinctId: string, params: {
     offersViewed: number;
     declineReason?: string;
     variantId?: string;
+    useCase?: UseCase;
 }): AnalyticsEvent;
 /**
  * Primer-screen (post-claim activation handoff) outcomes. The two events are what
@@ -60,12 +118,14 @@ export declare function offerActivationContinue(distinctId: string, params: {
     campaignId: string;
     presentationId: string;
     variantId?: string;
+    useCase?: UseCase;
 }): AnalyticsEvent;
 export declare function offerActivationDismissed(distinctId: string, params: {
     transactionId: string;
     campaignId: string;
     presentationId: string;
     variantId?: string;
+    useCase?: UseCase;
 }): AnalyticsEvent;
 export declare function offerTimeSpent(distinctId: string, params: {
     campaignId: string;
@@ -75,6 +135,140 @@ export declare function offerTimeSpent(distinctId: string, params: {
     totalOffers: number;
     presentationId: string;
     variantId?: string;
+    useCase?: UseCase;
+}): AnalyticsEvent;
+/**
+ * The offer identity every claim-funnel and advertiser-handoff event carries —
+ * the same field set iOS threads as `OfferAnalyticsContext`, so a row from web
+ * joins a row from iOS on identical keys.
+ *
+ * Only `campaignId` is required. The presentation-scoped fields are optional
+ * because `redeem()` legitimately runs on a LATER page load, with only the
+ * stored transaction in hand and no live presentation: there is no impression or
+ * presentation id to report, and minting one would be worse than omitting it —
+ * `impression_id` is the warehouse's primary claim↔completion join key, so a
+ * fabricated value joins against nothing while looking like real coverage.
+ * Those rows join on `transaction_id` instead, the documented fallback. Same
+ * rule iOS applies to its cross-launch `OfferVerifiedEvent`: absent context
+ * fields stay absent, never fabricated.
+ */
+export interface OfferEventContext {
+    campaignId: string;
+    creativeId?: string;
+    advertiserName?: string;
+    impressionId?: string;
+    offerIndex?: number;
+    totalOffers?: number;
+    presentationId?: string;
+    variantId?: string;
+    useCase?: UseCase;
+}
+/**
+ * The claim TAP, emitted before any guard can fail — the advertiser funnel's
+ * true denominator. `sdk_offer_claimed` fires only once a transaction exists, so
+ * on its own it cannot distinguish "nobody tapped Claim" from "everybody tapped
+ * and the transaction call failed". Mirrors iOS `OfferClaimTappedEvent`.
+ */
+export declare function offerClaimTapped(distinctId: string, ctx: OfferEventContext): AnalyticsEvent;
+/**
+ * A claim tap that never reached the advertiser — the failure twin of
+ * `sdk_offer_claimed`. Together they make every claim outcome observable, so a
+ * regression like a silently-rejected transaction shows up as a failure rather
+ * than as users who simply didn't tap. Mirrors iOS `OfferClaimFailedEvent`.
+ *
+ * `errorDescription` is the caught error's message, included only for
+ * `transaction_start_failed` to separate network from server-side reject. It is
+ * an SDK-produced message, never publisher data.
+ */
+export declare function offerClaimFailed(distinctId: string, ctx: OfferEventContext, params: {
+    reason: string;
+    errorDescription?: string;
+    transactionId?: string;
+}): AnalyticsEvent;
+/**
+ * The user came back to the host page from the advertiser. iOS reads this off
+ * the in-app Safari dismissal; web reads the equivalent moment — the host
+ * document regaining focus/visibility after the advertiser tab was opened. It is
+ * the one signal that separates "we handed the user off" from "the user actually
+ * engaged and returned". Mirrors iOS `OfferClaimReturnedEvent`.
+ */
+export declare function offerClaimReturned(distinctId: string, ctx: OfferEventContext, params: {
+    transactionId?: string;
+}): AnalyticsEvent;
+/**
+ * Web's advertiser handoff is a browser tab, not an embedded webview, so these
+ * keep iOS's event NAMES (the warehouse funnel is keyed on them) while reporting
+ * only what a browser can actually observe. `docs/architecture/analytics-events.md`
+ * lists the two members of the iOS funnel this SDK deliberately does NOT emit
+ * (`_load_success` and `_initial_redirect` — both need to see inside the
+ * cross-origin advertiser context).
+ *
+ * `url` / `urlHost` describe the ADVERTISER destination the SDK itself composed —
+ * never the host page's own URL, which can carry publisher query data.
+ */
+export declare function offerWebviewAttemptingOpen(distinctId: string, ctx: OfferEventContext, params: {
+    url: string;
+    urlHost: string;
+}): AnalyticsEvent;
+/** The advertiser window handle was obtained and navigated to the destination. */
+export declare function offerWebviewOpened(distinctId: string, ctx: OfferEventContext, params: {
+    url: string;
+    urlHost: string;
+    openedAt: string;
+}): AnalyticsEvent;
+/**
+ * The handoff failed — on web this is overwhelmingly a blocked popup. Carries
+ * `loadSuccess: false` for wire-shape parity with iOS's load_failed row.
+ */
+export declare function offerWebviewLoadFailed(distinctId: string, ctx: OfferEventContext, params: {
+    url: string;
+    urlHost: string;
+    reason: string;
+}): AnalyticsEvent;
+/** Dwell at the advertiser, measured from handoff to the host page regaining focus. */
+export declare function offerWebviewDismissed(distinctId: string, ctx: OfferEventContext, params: {
+    timeSpentSeconds: number;
+}): AnalyticsEvent;
+/**
+ * The server-assigned variant landed and the sheet will render it.
+ *
+ * Web has no server-driven-UI RENDERER (see `UseCase` in types.ts), but it is
+ * served by the same variant assignment as iOS/Android: `/config` returns
+ * `ui.variantId` plus the variant's copy. So the variant dimension is real here
+ * and this event is the one that makes it readable — without it, a web row's
+ * `variant_id` has no denominator saying how many users the variant reached.
+ *
+ * `loadSource` is the cross-SDK frozen vocabulary; web can only ever report
+ * `'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.
+ */
+export declare function sduiConfigLoaded(distinctId: string, params: {
+    variantId?: string;
+    loadSource: 'remote' | 'fallback';
+    loadDurationMs: number;
+    presentationId?: string;
+}): AnalyticsEvent;
+/**
+ * A control in the offer sheet was activated. `actionType` uses iOS's action
+ * vocabulary so the same query reads both platforms.
+ */
+export declare function sduiButtonTapped(distinctId: string, params: {
+    variantId?: string;
+    actionType: 'close' | 'claimOffer' | 'openUrl' | 'next' | 'previous';
+    presentationId: string;
+    currentState: string;
+}): AnalyticsEvent;
+/**
+ * The user moved through the offer carousel. `scrollAxis` is genuinely
+ * bi-modal on web: the carousel is horizontal on desktop and a vertical list on
+ * mobile, and which one a user got is a real analysis dimension iOS does not have.
+ */
+export declare function sduiScroll(distinctId: string, params: {
+    variantId?: string;
+    scrollAxis: 'horizontal' | 'vertical';
+    scrollPosition: number;
+    presentationId: 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/transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/analytics/transport.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAI9D;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,EAAE,OAAO,GAAE,MAAuB,GAAG,aAAa,CAcpG;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,aAAa,EACvB,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,GAChC,OAAO,CAAC,QAAQ,CAAC,CAWnB"}
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/analytics/transport.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAiD9D;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,EAAE,OAAO,GAAE,MAAuB,GAAG,aAAa,CAcpG;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,aAAa,EACvB,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,GAChC,OAAO,CAAC,QAAQ,CAAC,CAWnB"}

package/types/api/APIClient.d.ts

@@ -3,7 +3,7 @@
  * Low-level HTTP client using native fetch with retries, timeout, and deduplication
  * Also provides high-level methods for specific API endpoints
  */
-import type { UserAttributes, Entitlement, VerificationStatus } from '../types';
+import type { UserAttributes, Entitlement, VerificationStatus, UseCase } from '../types';
 import type { StartTransactionResponse, InitUserResponse, IdentifyUserResponse, RemoteConfigResponse, OfferModel, BackendVerificationStatus } from './models';
 interface RequestOptions {
     method: 'GET' | 'POST' | 'PATCH';
@@ -36,15 +36,26 @@ export declare class APIClient {
      */
     patch<T>(endpoint: string, body?: unknown, options?: Partial<RequestOptions>): Promise<T>;
     /**
-     * Fetch offers for a user
+     * Fetch offers for a user. `placementId` is best-effort analytics context (max 64
+     * chars per contract) — stamped server-side onto sdk_offer_requested; omitted for
+     * an auto-generated/absent placement id (buckets as '(unlabeled)' server-side).
+     *
+     * Truncated client-side to the contract's own limit (`z.string().max(64)` on
+     * `/offers/search` — see backend `offers/dto.ts`) rather than sent verbatim: the
+     * backend rejects the WHOLE request with a 400 on an oversized value, which would
+     * 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.
      */
-    fetchOffers(userId: string, attributes: UserAttributes): Promise<{
+    fetchOffers(userId: string, attributes: UserAttributes, placementId?: string): Promise<{
         offers: OfferModel[];
     }>;
     /**
-     * Start a transaction for an offer
+     * Start a transaction for an offer. `useCase` is omitted for 'churn-intervention' (the
+     * contract's own default) rather than sent explicitly, keeping the wire payload
+     * byte-identical to before this dimension existed for every existing caller.
      */
-    startTransaction(campaignId: string, userId: string): Promise<StartTransactionResponse>;
+    startTransaction(campaignId: string, userId: string, useCase?: UseCase): Promise<StartTransactionResponse>;
     /**
      * Send grant signal (provisional or final)
      */
@@ -75,9 +86,23 @@ export declare class APIClient {
         name?: string;
     }): Promise<IdentifyUserResponse>;
     /**
-     * Fetch remote config
+     * Fetch remote config.
+     *
+     * `useCase` selects which SURFACE the response's `ui` block resolves, and the
+     * response echoes it back as `ui.useCase`. It is deliberately OMITTED for both
+     * `undefined` and an explicit `'churn-intervention'`, so the eager
+     * configure()-time fetch stays byte-identical to every pre-use-case SDK — the
+     * same convention `startTransaction` already uses for this dimension.
+     *
+     * Two callers, two very different requests:
+     *  - The EAGER fetch (once, at configure()) passes no use case. Its response
+     *    carries churn-intervention in `ui` PLUS the `useCases` prefetch block.
+     *  - The LAZY fetch (at most once per use case, only when the block did not
+     *    carry it) passes one. Its response resolves that surface in `ui`
+     *    INCLUDING experiments — which the prefetch block, carrying only default
+     *    variants, cannot do.
      */
-    fetchConfig(userId: string, sdkVersion: string): Promise<RemoteConfigResponse>;
+    fetchConfig(userId: string, sdkVersion: string, useCase?: UseCase): Promise<RemoteConfigResponse>;
     /**
      * Report a client error (fire-and-forget)
      */

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

@@ -1 +1 @@
-{"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,MAAM,UAAU,CAAC;AAE7F,OAAO,KAAK,EAEV,wBAAwB,EAIxB,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,EACpB,UAAU,EACV,yBAAyB,EAC1B,MAAM,UAAU,CAAC;AAQlB,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;;OAEG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,cAAc,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,UAAU,EAAE,CAAA;KAAE,CAAC;IAwEhG;;OAEG;IACG,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,CAAC;IAa7F;;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;;OAEG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAYpF;;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"}
+{"version":3,"file":"APIClient.d.ts","sourceRoot":"","sources":["../../src/api/APIClient.ts"],"names":[],"mappings":"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"}