@encorekit/web-sdk 2.3.0 → 2.4.0

package/types/triggers/host/types.d.ts

@@ -0,0 +1,278 @@
+/**
+ * The trigger plug-in interface. INTERNAL: triggers ship inside the SDK and are
+ * registered by id; a host app only names the id (`Encore.triggers.mount(id, ...)`).
+ *
+ * The host (TriggerHost.ts) owns everything every trigger shares: the unknown-id
+ * no-op, the pre-config gate, the `/config` request and envelope check, visibility and
+ * the `sdk_trigger_*` events, the dismiss store, identity and language re-runs, and
+ * never throwing into the page. A plug-in owns only what is its own: what it needs
+ * before asking for a variant, how it reads its template, what one render shows, what
+ * a tap does, and how it draws.
+ *
+ * Same shape as iOS and Android (generic-contract.md, "Plug-in interface"), with one
+ * web difference: `onTap` STARTS synchronously, because a browser only opens a tab
+ * from inside the click that asked for it, so a sheet is presented before its first
+ * await. It may return a promise (a sheet that must close first).
+ */
+import type { AppearanceConfig, PublisherReward, ShowResult, UseCase } from '../../types';
+import type { TriggerRequest, TriggerState } from '../request';
+import type { NotShownReason } from './wire';
+import type { TriggerPortalTheme } from './theme';
+/** The mount's free-form options (`mount(id, el, { options })`), for future plug-ins. */
+export type TriggerOptionValues = Readonly<Record<string, string>>;
+/**
+ * What a plug-in remembers for one mount and one identity (a plug-in is shared by every
+ * mount). Empty again after an identity change; kept across a language change, so a
+ * decision (an automatic pop already made) survives it. Null prototype.
+ */
+export type TriggerMountState = Record<string, unknown>;
+/**
+ * Whether the sheet a trigger opens would open with offers for this user, by the SDK's
+ * own path (its config, then an offer search held for the tap): `offers` names the
+ * campaigns it holds; `sheet_unavailable` when the server says the sheet has nothing to
+ * serve; `none` for no offers or any failure.
+ */
+export type SheetCheck = {
+    status: 'offers';
+    campaignIds: ReadonlySet<string>;
+    /** The held offers in sheet order, with what a trigger may show of each. */
+    offers?: readonly HeldOffer[];
+} | {
+    status: 'none';
+} | {
+    status: 'sheet_unavailable';
+};
+/** One offer the sheet holds, as a trigger may show it. */
+export interface HeldOffer {
+    campaignId: string;
+    advertiserName?: string;
+    logoUrl?: string;
+}
+export interface TriggerPrepareContext {
+    now: number;
+    /** What this mount asks for: its use case, a pinned layout, its auto-open opt-out. */
+    request: TriggerRequest;
+    /** This trigger's dismissed content keys on this device. */
+    dismissed: ReadonlySet<string>;
+    options: TriggerOptionValues;
+    /** The mount's placement id, as the host app passed it. */
+    placement: string | undefined;
+    mountState: TriggerMountState;
+    /** Another trigger's dismissed content keys on this device (the reminder a GiftsButton spot may draw). */
+    dismissedOf(triggerId: string): ReadonlySet<string>;
+}
+export interface TriggerPrepareContextWithReport extends TriggerPrepareContext {
+    /**
+     * Search afresh rather than read a held set: a sheet a trigger opened just closed
+     * with a claim, so a held set may still list the claimed offer.
+     */
+    fresh: boolean;
+    /**
+     * The user reached this trigger and it would have shown, but `reason` stops it
+     * (e.g. the sheet it opens has nothing to serve). Return null after calling it. The host reports it
+     * once per (trigger, placement, reason) per local day on this device.
+     */
+    notShown(reason: NotShownReason): void;
+    /**
+     * Nothing to show until `at` (epoch ms), say the next local day: the host reads again
+     * then, while the page is visible (a hidden page reads on its return anyway). Only
+     * the newest read's request stands.
+     */
+    readAgainAt(at: number): void;
+}
+export interface TriggerPresentContext extends TriggerPrepareContext {
+    /** The publisher's colours. They beat the app's portal theme, the look's, and the default. */
+    appearance: AppearanceConfig | undefined;
+    /** The app's theme set in the portal, as `/config` serves it in `ui.values`. Empty when unset. */
+    portal: TriggerPortalTheme;
+    /** The mount's `icon` option, as passed (unchecked). */
+    icon: unknown;
+    /**
+     * The user can be at the placement now (page visible, mount attached) and this present
+     * follows a fresh read, not the clock. A plug-in acts on its own (an `autoTap`) only then.
+     */
+    canAutoTap: boolean;
+    /**
+     * The mount's own `values` for `${values.K}` (already checked: at most 16 keys, plain
+     * text). They go over the look's defaults, are filled on the device, and are never
+     * sent, logged or stored.
+     */
+    lookValues: Readonly<Record<string, string>>;
+    /**
+     * Read again (not only present) at `at`: what was read no longer fits the served look,
+     * so the device state should be worked out afresh. The earliest ask of a read stands.
+     */
+    readAgainAt(at: number): void;
+}
+/** What a plug-in adds to the host's common event fields. */
+export interface TriggerEventFields {
+    transactionId?: string;
+    campaignId?: string;
+    /** The layout actually drawn. */
+    layout?: string;
+    /**
+     * Text slots the look declares that this presentation does not draw (a reminder's headline on a
+     * branch that draws another title): left out of `text_slots`, so it names only lines on screen.
+     */
+    undrawnSlots?: readonly string[];
+}
+/** One render: what to draw, and what the host needs to know about it. */
+export interface TriggerPresentation<Model> {
+    model: Model;
+    /** Identifies what is shown: viewed once per key per mount, and the key a dismiss stores. */
+    contentKey: string;
+    eventFields: TriggerEventFields;
+    dismissible: boolean;
+    /** Epoch ms at which the host must present again (a countdown's end), if any. */
+    refreshAt?: number;
+    /**
+     * A target the host taps by itself once, right after drawing this presentation
+     * (a GiftsButton look whose behavior says `autoOpen: on` pops the sheet with `auto`). Not
+     * repeated on an in-place update.
+     */
+    autoTap?: string;
+    /**
+     * The user was eligible for something this presentation does not show (GiftsButton
+     * drawing the pill because another mount already popped today): the host reports the
+     * counterfactual with this reason once. What is drawn counts its impressions as usual.
+     */
+    notShownReason?: NotShownReason;
+    /** The counterfactual's own fields when they differ from what is drawn (default `eventFields`). */
+    notShownEventFields?: TriggerEventFields;
+    /**
+     * The trigger this presentation draws, when it is not the mounted one (the reminder look
+     * a GiftsButton request was answered with). Its events name it as `trigger`, with the
+     * mounted one as `host_trigger`.
+     */
+    drawnTrigger?: string;
+    /**
+     * What a dismiss hides: these content keys in `drawnTrigger`'s dismiss store (every claim
+     * a reminder in a GiftsButton spot shows). Default: `contentKey` in the mounted trigger's.
+     */
+    dismissKeys?: readonly string[];
+}
+/** What a tap leaves behind. `refresh` re-runs `prepare` (the content may have changed). */
+export type TriggerTapOutcome = 'keep' | 'refresh';
+/** Present the SDK's own sheet, exactly as the host app's `placement().useCase().show()` would. */
+export interface TriggerSheetRequest {
+    /** A public use case name (`rewardUsers`, ...). An unknown one resolves without presenting. */
+    useCase: UseCase;
+    placement: string | undefined;
+    /** Called once if and when the sheet actually opens (never when it does not). */
+    onPresented?: () => void;
+}
+/** What the host adds to a plug-in's sheet request: the id, the mount's prize, and liveness. */
+export interface HostSheetRequest extends TriggerSheetRequest {
+    presentationId: string;
+    /** The trigger opened this sheet by itself: if the mount goes before it shows, it never shows. */
+    automatic?: boolean;
+    publisherReward?: PublisherReward;
+    /** False once the mount is gone or restarted; a sheet still waiting to open then does not. */
+    isCurrent: () => boolean;
+}
+export interface TriggerTapContext {
+    options: TriggerOptionValues;
+    mountState: TriggerMountState;
+    /**
+     * The id the host minted for the sheet this tap opens (`opensSheet` said yes), already
+     * reported on `sdk_trigger_clicked` as `presentation_id`. Absent otherwise.
+     */
+    presentationId?: string;
+    /**
+     * Present the Encore sheet under `presentationId`. Resolves when it closes (never
+     * rejects). Returning the continuation from `onTap` keeps the tap in flight until then.
+     */
+    presentSheet(request: TriggerSheetRequest): Promise<ShowResult>;
+}
+/** Handed to `render`: how the drawn view reports user actions to the host. */
+export interface TriggerRenderScope {
+    /** A tap on `target` (a trigger-defined name, e.g. `card` or `arrow`). */
+    tapped(target: string): void;
+    /** The user dismissed what is shown. */
+    dismissed(): void;
+    /** The clock the view draws its countdowns against. Absent: the device clock (the live host). */
+    now?(): number;
+}
+export interface TriggerView<Model> {
+    root: HTMLElement;
+    /**
+     * Show `model` in place (same content key, e.g. a countdown tick). Return false when
+     * it cannot be shown in place, and the host draws it afresh.
+     */
+    update(model: Model): boolean;
+    /** Whether any of the view is on screen (to pause motion offscreen). */
+    setOnScreen?(onScreen: boolean): void;
+    /** A tap is in flight (true) or settled (false): dim and ignore presses meanwhile (motion keeps running). */
+    setBusy?(busy: boolean): void;
+}
+export interface TriggerPlugin<Content, Config, Model> {
+    /** The trigger id, as variant files name it (`template.trigger`). */
+    readonly id: string;
+    /** The gate before `/config`: null means nothing to show, and no request is sent. */
+    prepare(context: TriggerPrepareContextWithReport): Promise<Content | null>;
+    /**
+     * The strict pre-check on the raw served template (trigger SDUI contract §5): the
+     * first thing this build must not render, or undefined. A failure draws nothing and
+     * reports `unrenderable`; `decode` is not called.
+     */
+    precheck?(template: Record<string, unknown>): {
+        reason: string;
+        path: string;
+    } | undefined;
+    /** `ui.template` as this trigger reads it. Null renders nothing. */
+    decode(template: Record<string, unknown>): Config | null;
+    /**
+     * Other triggers whose looks may answer this trigger's request (TRIGGER_ALLOW.renders):
+     * a GiftsButton spot may be answered with the reminder look. `precheck`, `decode` and
+     * `present` then see that trigger's template; anything else is unrenderable.
+     */
+    readonly alsoDraws?: readonly string[];
+    /**
+     * What happened on the device for this content (§2.8), sent as `state` on the one
+     * `/config` request: `claimOpen` (an eligible open claim) or `completed` (an offer
+     * finished today, none claimed since, its thanks not tapped). The host asks again when
+     * it changes. Null: none.
+     */
+    requestState?(content: Content): TriggerState | null;
+    /**
+     * The completion a `completed` state is about (its claim's id), so a behavior's hide is
+     * reported once per completion. Null otherwise.
+     */
+    completionOf?(content: Content): string | null;
+    /** What to draw now. Null renders nothing. */
+    present(content: Content, config: Config, context: TriggerPresentContext): TriggerPresentation<Model> | null;
+    /**
+     * Whether this tap opens the Encore sheet. Asked before the tap is reported: a yes
+     * makes the host mint the sheet's presentation id and put it on the tapped event.
+     */
+    opensSheet?(model: Model, target: string): boolean;
+    /**
+     * The tap's side effect, STARTED synchronously inside the click (a browser opens a
+     * tab only there). Return a promise to keep the tap in flight until it settles (a
+     * sheet that must close first); the host takes no other tap meanwhile.
+     */
+    onTap(model: Model, target: string, context: TriggerTapContext): TriggerTapOutcome | Promise<TriggerTapOutcome>;
+    render(model: Model, scope: TriggerRenderScope): TriggerView<Model>;
+    /**
+     * An automatic tap (`autoTap`) held behind another sheet never ran: the sheet stayed up
+     * for a minute, nothing was drawn when it closed, the identity changed, or the mount
+     * was unmounted. The plug-in gives back what it reserved for it (`model` is the one the
+     * tap was accepted on); the host presents again unless the mount is going away.
+     */
+    autoTapAbandoned?(model: Model, target: string, context: TriggerAbandonContext): void;
+}
+export interface TriggerAbandonContext {
+    mountState: TriggerMountState;
+    placement: string | undefined;
+}
+/** Erased form the registry stores. */
+export type AnyTriggerPlugin = TriggerPlugin<any, any, any>;
+/**
+ * A trigger as the registry holds it: its id, and how to load its plug-in. Plug-ins
+ * load on first mount, so an app that never mounts one never downloads it.
+ */
+export interface TriggerEntry {
+    readonly id: string;
+    load(): Promise<AnyTriggerPlugin>;
+}
+//# sourceMappingURL=types.d.ts.map

package/types/triggers/host/types.d.ts.map

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

package/types/triggers/host/wire.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Trigger event names and the counterfactual's reasons: the only place they are
+ * spelled; changing them here changes every emitter.
+ */
+export declare const TRIGGER_EVENT: Readonly<{
+    readonly impression: "sdk_trigger_impression";
+    readonly clicked: "sdk_trigger_clicked";
+    readonly autoOpened: "sdk_trigger_auto_opened";
+    readonly dismissed: "sdk_trigger_dismissed";
+    readonly eligibleNotShown: "sdk_trigger_eligible_not_shown";
+}>;
+/** Why a trigger the user reached was not shown. "Nothing to show" is not one of them. */
+export declare const NOT_SHOWN_REASON: Readonly<{
+    /** The trigger's /config came back with no template AND an experiment: held out. */
+    readonly holdout: "holdout";
+    /**
+     * The sheet the trigger opens would not open for this user: the server's answer for
+     * that sheet has nothing this SDK can serve (no copy, or another use case's answer).
+     * A null template with servable copy still opens web's hand-written sheet, so it is
+     * not this. No offers or a 409 is "nothing to show", never this.
+     */
+    readonly sheetUnavailable: "sheet_unavailable";
+    /** GiftsButton opening by itself: eligible, but another mount popped at this placement today. */
+    readonly autoHeld: "auto_held";
+    /**
+     * The served tree uses something this build does not render (an element, field,
+     * style key, action or symbol outside `sdui/precheck.ts`'s allow-list), so the
+     * trigger draws nothing rather than drawing wrong and counting an impression.
+     */
+    readonly unrenderable: "unrenderable";
+    /**
+     * The look's behavior hid the spot after a completed offer (`ui.step` afterComplete with
+     * no template): the exposure for that step, once per completion, never `holdout`.
+     */
+    readonly afterCompleteHide: "after_complete_hide";
+    /**
+     * No template, with a `ui.step` this build does not know (a newer server's step): drawn
+     * as nothing, stamped with the raw step, never `holdout`.
+     */
+    readonly unknownStep: "unknown_step";
+}>;
+export type NotShownReason = (typeof NOT_SHOWN_REASON)[keyof typeof NOT_SHOWN_REASON];
+/** The device-local record of reported reasons: `{ "<placement>|<reason>": "YYYY-MM-DD" }`. */
+export declare function notShownStorageKey(triggerId: string): string;
+/**
+ * The custom-UI handle's behavior-only trigger (`Encore.claim`): it asks for rules only
+ * (`layout: behavior`, never drawn) and reports its events with layout `custom`.
+ */
+export declare const CUSTOM_CLAIM_ID = "customClaim";
+/** Trigger ids this SDK ships (the registry's keys, as variant files name them). */
+export declare const TRIGGER_ID: Readonly<{
+    readonly claimReminder: "claimReminder";
+    readonly giftsButton: "giftsButton";
+}>;
+//# sourceMappingURL=wire.d.ts.map

package/types/triggers/host/wire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire.d.ts","sourceRoot":"","sources":["../../../src/triggers/host/wire.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,eAAO,MAAM,aAAa;;;;;;EAMf,CAAC;AAEZ,0FAA0F;AAC1F,eAAO,MAAM,gBAAgB;IAC3B,oFAAoF;;IAEpF;;;;;OAKG;;IAEH,iGAAiG;;IAEjG;;;;OAIG;;IAEH;;;OAGG;;IAEH;;;OAGG;;EAEM,CAAC;AAEZ,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,OAAO,gBAAgB,CAAC,CAAC;AAEtF,+FAA+F;AAC/F,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;GAGG;AACH,eAAO,MAAM,eAAe,gBAAgB,CAAC;AAE7C,oFAAoF;AACpF,eAAO,MAAM,UAAU;;;EAGZ,CAAC"}

package/types/triggers/preview.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The trigger half of `@encorekit/web-sdk/preview` (🔴 INTERNAL, admin portal only).
+ *
+ * Draws one trigger look (a GiftsButton or ClaimReminder variant file, as `/config`
+ * serves it in `ui.template`) with sample offers and claims, through the live plug-ins:
+ * the GiftsButton spot decodes it, `present` binds its values, times and lists exactly as
+ * on a device, and `render` draws it with the SDUI engine. Only the I/O is replaced:
+ * there is no `/config` or offer search, no storage, no analytics, and a tap or × does
+ * nothing.
+ *
+ * `state` is what happened on the device (§2.8). A look draws in the states Encore
+ * serves it for: a gifts look in any state, a reminder look only with an open claim
+ * (`claimOpen`), a thanks look only after a completion (`completed`). In any other state
+ * the preview draws nothing and says so (`empty`), as a device would.
+ */
+import type { TriggerAppearance, TriggerPortalTheme } from './host/theme';
+/** What happened on the device, as the spot tells Encore (`state=`); `default` is neither. */
+export type TriggerPreviewState = 'default' | 'claimOpen' | 'completed';
+/** One offer the sheet would hold: its logo is what the gifts looks draw. */
+export interface TriggerPreviewOffer {
+    advertiserName?: string;
+    logoUrl?: string;
+}
+/** One open claim, for the reminder looks. */
+export interface TriggerPreviewClaim {
+    advertiserName: string;
+    advertiserLogoUrl?: string | null;
+    /** Spoken only, never drawn. */
+    perk?: string;
+    /** ISO-8601. Absent: two hours before `now`. */
+    claimedAt?: string;
+}
+export interface TriggerPreviewInput {
+    /** The look as served (`ui.template`): its `trigger`, `layout`, colours, strings and `root`. */
+    template: Record<string, unknown>;
+    /** Default `default`. */
+    state?: TriggerPreviewState;
+    /** Default `dark`, as on a device where nobody chose. */
+    colorScheme?: 'light' | 'dark';
+    /** The publisher's colours (`appearance`), over the app's and the look's. */
+    appearance?: Omit<TriggerAppearance, 'colorScheme'>;
+    /** The app's portal theme: its accent and store icon. */
+    portal?: Pick<TriggerPortalTheme, 'accentColor' | 'appIconUrl'>;
+    /** The mount's `icon` option. Default `gift`. */
+    icon?: 'gift' | 'appIcon' | 'none';
+    /** The mount's `values` for `${values.K}`, over the look's own defaults. */
+    values?: Readonly<Record<string, string>>;
+    offers?: readonly TriggerPreviewOffer[];
+    /** Newest first or not: the reminder sorts them as on a device. */
+    claims?: readonly TriggerPreviewClaim[];
+    /** Epoch ms the countdowns count from. Default: now. The preview does not tick. */
+    now?: number;
+}
+export type TriggerPreviewResult = {
+    status: 'rendered';
+    trigger: string;
+    layout: string;
+}
+/** The look draws nothing in this state (or with these samples). */
+ | {
+    status: 'empty';
+}
+/** Not a look this build draws: an unknown trigger, or a tree outside the vocabulary. */
+ | {
+    status: 'unrenderable';
+    reason: string;
+};
+export interface TriggerPreviewHandle {
+    /** What the last render drew. */
+    readonly result: TriggerPreviewResult;
+    /** Draw `input` afresh in the same container. After destroy(), draws nothing. */
+    update(input: TriggerPreviewInput): TriggerPreviewResult;
+    /** Remove everything the preview added. Safe to call more than once. */
+    destroy(): void;
+}
+/** Mount a preview of the trigger look `input` describes in `container`. */
+export declare function renderTriggerPreview(container: HTMLElement | ShadowRoot, input: TriggerPreviewInput): TriggerPreviewHandle;
+//# sourceMappingURL=preview.d.ts.map

package/types/triggers/preview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../../src/triggers/preview.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AASH,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAI1E,8FAA8F;AAC9F,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,WAAW,GAAG,WAAW,CAAC;AAExE,6EAA6E;AAC7E,MAAM,WAAW,mBAAmB;IAClC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,8CAA8C;AAC9C,MAAM,WAAW,mBAAmB;IAClC,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,gCAAgC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,gGAAgG;IAChG,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,yBAAyB;IACzB,KAAK,CAAC,EAAE,mBAAmB,CAAC;IAC5B,yDAAyD;IACzD,WAAW,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC/B,6EAA6E;IAC7E,UAAU,CAAC,EAAE,IAAI,CAAC,iBAAiB,EAAE,aAAa,CAAC,CAAC;IACpD,yDAAyD;IACzD,MAAM,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,aAAa,GAAG,YAAY,CAAC,CAAC;IAChE,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;IACnC,4EAA4E;IAC5E,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC1C,MAAM,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACxC,mEAAmE;IACnE,MAAM,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACxC,mFAAmF;IACnF,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,oBAAoB,GAC5B;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AACzD,oEAAoE;GAClE;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE;AACrB,yFAAyF;GACvF;IAAE,MAAM,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/C,MAAM,WAAW,oBAAoB;IACnC,iCAAiC;IACjC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,iFAAiF;IACjF,MAAM,CAAC,KAAK,EAAE,mBAAmB,GAAG,oBAAoB,CAAC;IACzD,wEAAwE;IACxE,OAAO,IAAI,IAAI,CAAC;CACjB;AA4GD,4EAA4E;AAC5E,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,WAAW,GAAG,UAAU,EACnC,KAAK,EAAE,mBAAmB,GACzB,oBAAoB,CA8BtB"}

package/types/triggers/request.d.ts

@@ -0,0 +1,53 @@
+/**
+ * What a trigger mount asks the server for, read from its options once:
+ * the use case it serves, a pinned layout, and whether it forbids opening the sheet by itself.
+ *
+ * In the core bundle and free of the host, so `Encore.triggers.mount` can refuse a mount
+ * (churn, a layout that is not a name) before any chunk loads or request is sent.
+ */
+import type { UseCase } from '../types';
+/** A trigger's state look after a completed claim: never a publisher pin. */
+export declare const THANKS_LAYOUT_NAME = "thanks";
+/** What one mount asks for, resolved. */
+export interface TriggerRequest {
+    useCase: UseCase;
+    /** The layout pin sent as `layout=<pin>`. Absent: managed. A pinned mount never opens by itself. */
+    layout?: string;
+    /**
+     * Sent as `autoOpen=off`, only when the mount forbids Encore from opening the sheet by
+     * itself. Absent: allowed, and the served look's `behavior.autoOpen` decides.
+     */
+    autoOpen?: 'off';
+    /**
+     * What happened on the device, sent as `state=` (§2.8): the served look's behavior picks
+     * the step's look for it. Set by the host from the plug-in's `requestState`.
+     */
+    state?: TriggerState;
+}
+/**
+ * Whether a look served to this mount may open the sheet by itself: a trigger that can,
+ * on a mount that neither said off nor pinned a layout. The device's own bounds (once per
+ * mount and per placement per local day, never over another sheet, foreground only) still
+ * apply on top.
+ */
+export declare function mayOpenByItself(triggerId: string, request: TriggerRequest): boolean;
+/** A trigger request's device state (§2.8). */
+export type TriggerState = 'claimOpen' | 'completed';
+/** Test hook: log every warning again. */
+export declare function forgetRequestWarnings(): void;
+/**
+ * The request for mounting `triggerId` with `options`, or null to render nothing and
+ * send nothing: churn (not supported yet), a use case this SDK does not name, or a
+ * pinned layout that is not a name. Any name is a pin; the server decides the look.
+ */
+export declare function resolveTriggerRequest(triggerId: string, options: {
+    useCase?: unknown;
+    layout?: unknown;
+    autoOpen?: unknown;
+} | null | undefined): TriggerRequest | null;
+/**
+ * `Encore.claim` once took `afterClaim` and `afterComplete`; Encore decides both now (the
+ * customClaim rules). A caller still passing either is told once, and the value is ignored.
+ */
+export declare function warnRetiredClaimSteps(options: object | null | undefined): void;
+//# sourceMappingURL=request.d.ts.map

package/types/triggers/request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../src/triggers/request.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAexC,6EAA6E;AAC7E,eAAO,MAAM,kBAAkB,WAAW,CAAC;AAE3C,yCAAyC;AACzC,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,oGAAoG;IACpG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,QAAQ,CAAC,EAAE,KAAK,CAAC;IACjB;;;OAGG;IACH,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAEnF;AAED,+CAA+C;AAC/C,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,WAAW,CAAC;AAgBrD,0CAA0C;AAC1C,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,GACtF,cAAc,GAAG,IAAI,CAiEvB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAS9E"}