@getuserfeedback/protocol 0.1.0

package/dist/host/command-dispatch.d.ts

@@ -0,0 +1,26 @@
+import type { CommandEnvelope, PublicCommandPayload } from "./sdk-types.js";
+/**
+ * A command input: the pure payload with `kind` and command-specific fields.
+ * Distributes over the PublicCommandPayload union so discriminant
+ * narrowing is preserved (e.g. `{ kind: "open", flowId }` type-checks).
+ */
+export type CommandInput = PublicCommandPayload extends infer C ? C extends PublicCommandPayload ? C : never : never;
+type DispatchOptions = {
+    idempotencyKey?: string;
+};
+/**
+ * Creates a dispatch function that wraps a command payload in an envelope,
+ * pushes it into the queue, and returns a promise that settles when the
+ * runtime acknowledges it.
+ *
+ * Request IDs are generated automatically.
+ *
+ * @example
+ * ```ts
+ * const dispatch = createCommandDispatch((env) => queue.push(env));
+ * await dispatch({ kind: "open", flowId: "f1", flowHandleId: "h1" });
+ * ```
+ */
+export declare const createCommandDispatch: (push: (envelope: CommandEnvelope) => void) => ((input: CommandInput, options?: DispatchOptions) => Promise<void>);
+export {};
+//# sourceMappingURL=command-dispatch.d.ts.map

package/dist/host/command-dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-dispatch.d.ts","sourceRoot":"","sources":["../../src/host/command-dispatch.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAE5E;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,oBAAoB,SAAS,MAAM,CAAC,GAC5D,CAAC,SAAS,oBAAoB,GAC7B,CAAC,GACD,KAAK,GACN,KAAK,CAAC;AAET,KAAK,eAAe,GAAG;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,GACjC,MAAM,CAAC,QAAQ,EAAE,eAAe,KAAK,IAAI,KACvC,CAAC,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,CAgBpE,CAAC"}

package/dist/host/command-dispatch.js

@@ -0,0 +1,39 @@
+import { waitForCommandSettlement } from "./command-settlement.js";
+import { createCommandRequestId } from "./request-id.js";
+/**
+ * Creates a dispatch function that wraps a command payload in an envelope,
+ * pushes it into the queue, and returns a promise that settles when the
+ * runtime acknowledges it.
+ *
+ * Request IDs are generated automatically.
+ *
+ * @example
+ * ```ts
+ * const dispatch = createCommandDispatch((env) => queue.push(env));
+ * await dispatch({ kind: "open", flowId: "f1", flowHandleId: "h1" });
+ * ```
+ */
+export const createCommandDispatch = (push) => {
+    return async (input, options) => {
+        const requestId = createCommandRequestId();
+        const idempotencyKey = resolveIdempotencyKey(options?.idempotencyKey);
+        const envelope = {
+            version: "1",
+            requestId,
+            idempotencyKey: idempotencyKey ?? requestId,
+            command: input,
+        };
+        push(envelope);
+        await waitForCommandSettlement({ requestId });
+    };
+};
+const resolveIdempotencyKey = (value) => {
+    if (value === undefined) {
+        return null;
+    }
+    const idempotencyKey = value.trim();
+    if (!idempotencyKey) {
+        throw new Error("idempotencyKey must be a non-empty string");
+    }
+    return idempotencyKey;
+};

package/dist/host/command-settlement.d.ts

@@ -0,0 +1,32 @@
+import { type CommandSettledDetail } from "./host-event-contract.js";
+type WaitForCommandSettlementInput = {
+    requestId: string;
+    windowRef?: Window;
+    timeoutMs?: number;
+};
+export declare const COMMAND_SETTLEMENT_TIMEOUT_CODE: "COMMAND_SETTLEMENT_TIMEOUT";
+export declare class CommandSettlementError extends Error {
+    readonly code?: string;
+    readonly requestId: string;
+    readonly kind: string;
+    readonly instanceId: string | null;
+    constructor(input: {
+        requestId: string;
+        kind: string;
+        instanceId: string | null;
+        message: string;
+        code?: string;
+    });
+}
+type CommandSettledFailureDetail = Extract<CommandSettledDetail, {
+    ok: false;
+}>;
+export declare const toCommandSettlementError: (detail: CommandSettledFailureDetail) => CommandSettlementError;
+export declare class CommandSettlementTimeoutError extends Error {
+    readonly code: "COMMAND_SETTLEMENT_TIMEOUT";
+    readonly requestId: string;
+    constructor(requestId: string);
+}
+export declare const waitForCommandSettlement: (input: WaitForCommandSettlementInput) => Promise<CommandSettledDetail>;
+export {};
+//# sourceMappingURL=command-settlement.d.ts.map

package/dist/host/command-settlement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-settlement.d.ts","sourceRoot":"","sources":["../../src/host/command-settlement.ts"],"names":[],"mappings":"AACA,OAAO,EACN,KAAK,oBAAoB,EAEzB,MAAM,0BAA0B,CAAC;AAElC,KAAK,6BAA6B,GAAG;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAGF,eAAO,MAAM,+BAA+B,EAC3C,4BAAqC,CAAC;AAEvC,qBAAa,sBAAuB,SAAQ,KAAK;IAChD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;gBAEvB,KAAK,EAAE;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;QAC1B,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC;KACd;CAUD;AAED,KAAK,2BAA2B,GAAG,OAAO,CAAC,oBAAoB,EAAE;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC,CAAC;AAEhF,eAAO,MAAM,wBAAwB,GACpC,QAAQ,2BAA2B,KACjC,sBAUF,CAAC;AAEF,qBAAa,6BAA8B,SAAQ,KAAK;IACvD,QAAQ,CAAC,IAAI,+BAAmC;IAChD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,SAAS,EAAE,MAAM;CAK7B;AASD,eAAO,MAAM,wBAAwB,GACpC,OAAO,6BAA6B,KAClC,OAAO,CAAC,oBAAoB,CAgD9B,CAAC"}

package/dist/host/command-settlement.js

@@ -0,0 +1,86 @@
+import { HOST_EVENT_KEYS, toHostEventName } from "./constants.js";
+import { isCommandSettledDetail, } from "./host-event-contract.js";
+const DEFAULT_SETTLEMENT_TIMEOUT_MS = 30_000;
+export const COMMAND_SETTLEMENT_TIMEOUT_CODE = "COMMAND_SETTLEMENT_TIMEOUT";
+export class CommandSettlementError extends Error {
+    code;
+    requestId;
+    kind;
+    instanceId;
+    constructor(input) {
+        super(input.message);
+        this.name = "CommandSettlementError";
+        this.requestId = input.requestId;
+        this.kind = input.kind;
+        this.instanceId = input.instanceId;
+        if (input.code) {
+            this.code = input.code;
+        }
+    }
+}
+export const toCommandSettlementError = (detail) => {
+    return new CommandSettlementError({
+        requestId: detail.requestId,
+        kind: detail.kind,
+        instanceId: detail.instanceId,
+        message: detail.error.message ??
+            `Command ${detail.kind} failed without an error payload`,
+        code: detail.error.code,
+    });
+};
+export class CommandSettlementTimeoutError extends Error {
+    code = COMMAND_SETTLEMENT_TIMEOUT_CODE;
+    requestId;
+    constructor(requestId) {
+        super(`Timed out waiting for command settlement: ${requestId}`);
+        this.name = "CommandSettlementTimeoutError";
+        this.requestId = requestId;
+    }
+}
+const eventHasDetail = (event) => {
+    if (typeof CustomEvent !== "undefined") {
+        return event instanceof CustomEvent;
+    }
+    return typeof event === "object" && event !== null && "detail" in event;
+};
+export const waitForCommandSettlement = (input) => {
+    const requestId = input.requestId;
+    if (!requestId) {
+        return Promise.reject(new Error("requestId must be a non-empty string"));
+    }
+    const targetWindow = input.windowRef ?? (typeof window === "undefined" ? undefined : window);
+    if (!targetWindow) {
+        return Promise.reject(new Error("Cannot await command settlement without window"));
+    }
+    const eventName = toHostEventName(HOST_EVENT_KEYS.INSTANCE_COMMAND_SETTLED);
+    const timeoutMs = Math.max(0, input.timeoutMs ?? DEFAULT_SETTLEMENT_TIMEOUT_MS);
+    return new Promise((resolve, reject) => {
+        const cleanup = () => {
+            if (typeof targetWindow.removeEventListener === "function") {
+                targetWindow.removeEventListener(eventName, handleEvent);
+            }
+        };
+        const timeoutId = setTimeout(() => {
+            cleanup();
+            reject(new CommandSettlementTimeoutError(requestId));
+        }, timeoutMs);
+        const handleEvent = (event) => {
+            if (!eventHasDetail(event)) {
+                return;
+            }
+            const raw = event.detail;
+            if (!isCommandSettledDetail(raw) || raw.requestId !== requestId) {
+                return;
+            }
+            const detail = raw;
+            cleanup();
+            clearTimeout(timeoutId);
+            if (detail.ok) {
+                resolve(detail);
+                return;
+            }
+            reject(toCommandSettlementError(detail));
+        };
+        targetWindow.addEventListener(eventName, handleEvent);
+    });
+};

package/dist/host/constants.d.ts

@@ -0,0 +1,35 @@
+export declare const TELEMETRY_EVENTS: {
+    readonly INSTANCE_READY: "instance_ready";
+    readonly VIEW_DISPLAYED: "view_displayed";
+    readonly VIEW_CLOSED: "view_closed";
+    readonly FLOW_DISPLAYED: "flow_displayed";
+    readonly FLOW_CLOSED: "flow_closed";
+};
+export type TelemetryEventName = (typeof TELEMETRY_EVENTS)[keyof typeof TELEMETRY_EVENTS];
+export declare const WIDGET_SELECTOR: "[data-gx-widget]";
+export declare const PARENT_ORIGIN_PARAM: "gx_parent_origin";
+export declare const HOST_EVENT_PREFIX: "getuserfeedback:";
+export declare const HOST_EVENT_KEYS: {
+    readonly INSTANCE_FLOW_STATE_CHANGED: "instance:flow:state-changed";
+    readonly INSTANCE_FLOW_STATE_CHANGED_INSTANCE: "instance:flow:state-changed:instance";
+    readonly INSTANCE_COMMAND_SETTLED: "instance:command:settled";
+    readonly INSTANCE_HANDLE_INVALIDATED: "instance:handle:invalidated";
+    readonly INSTANCE_OPEN_REQUESTED: "instance:open:requested";
+    readonly INSTANCE_COMMAND_UNSUPPORTED: "instance:command:unsupported";
+    readonly INSTANCE_READY: "instance:ready";
+    readonly INSTANCE_BRIDGE_MOUNTED: "instance:bridge:mounted";
+    readonly INSTANCE_BRIDGE_UNMOUNTED: "instance:bridge:unmounted";
+    readonly INSTANCE_IFRAME_READY: "instance:iframe:ready";
+    readonly INSTANCE_ERROR: "instance:error";
+    readonly INSTANCE_APP_EVENT: "instance:app-event";
+};
+/**
+ * Stable capability tokens announced by the browser SDK during init.
+ * These are versioned and namespaced to support forward-compatible negotiation.
+ */
+export declare const SDK_PROTOCOL_CAPABILITIES: readonly ["gx.protocol.public.v1", "gx.command.configure.v1", "gx.command.open.v1", "gx.command.prefetch.v1", "gx.command.prerender.v1", "gx.command.identify.v1", "gx.command.setContainer.v1", "gx.command.close.v1", "gx.command.reset.v1", "gx.command.setDefaultContainerPolicy.v1"];
+export type SdkProtocolCapability = (typeof SDK_PROTOCOL_CAPABILITIES)[number];
+export declare const LOADER_RUNTIME_GLOBAL_KEY: "__getuserfeedback_runtime";
+export declare const LOADER_RUNTIME_PROTOCOL_VERSION: "v1";
+export declare const toHostEventName: (key: string) => string;
+//# sourceMappingURL=constants.d.ts.map

package/dist/host/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/host/constants.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,gBAAgB;;;;;;CAMnB,CAAC;AAEX,MAAM,MAAM,kBAAkB,GAC7B,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,OAAO,gBAAgB,CAAC,CAAC;AAI1D,eAAO,MAAM,eAAe,EAAG,kBAA2B,CAAC;AAE3D,eAAO,MAAM,mBAAmB,EAAG,kBAA2B,CAAC;AAI/D,eAAO,MAAM,iBAAiB,EAAG,kBAA2B,CAAC;AAE7D,eAAO,MAAM,eAAe;;;;;;;;;;;;;CAalB,CAAC;AAgDX;;;GAGG;AACH,eAAO,MAAM,yBAAyB,2RAG5B,CAAC;AAEX,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,yBAAyB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/E,eAAO,MAAM,yBAAyB,EAAG,2BAAoC,CAAC;AAC9E,eAAO,MAAM,+BAA+B,EAAG,IAAa,CAAC;AAG7D,eAAO,MAAM,eAAe,GAAI,KAAK,MAAM,KAAG,MACjB,CAAC"}

package/dist/host/constants.js

@@ -0,0 +1,62 @@
+export const TELEMETRY_EVENTS = {
+    INSTANCE_READY: "instance_ready",
+    VIEW_DISPLAYED: "view_displayed",
+    VIEW_CLOSED: "view_closed",
+    FLOW_DISPLAYED: "flow_displayed",
+    FLOW_CLOSED: "flow_closed",
+};
+// Data attribute used to anchor widget styles & root element. Shared so build
+// scripts, runtime code and tests stay in sync.
+export const WIDGET_SELECTOR = "[data-gx-widget]";
+export const PARENT_ORIGIN_PARAM = "gx_parent_origin";
+// Host event names (DOM events emitted by widget for external consumption)
+// Uses prefix "getuserfeedback:" for namespacing
+export const HOST_EVENT_PREFIX = "getuserfeedback:";
+export const HOST_EVENT_KEYS = {
+    INSTANCE_FLOW_STATE_CHANGED: "instance:flow:state-changed",
+    INSTANCE_FLOW_STATE_CHANGED_INSTANCE: "instance:flow:state-changed:instance",
+    INSTANCE_COMMAND_SETTLED: "instance:command:settled",
+    INSTANCE_HANDLE_INVALIDATED: "instance:handle:invalidated",
+    INSTANCE_OPEN_REQUESTED: "instance:open:requested",
+    INSTANCE_COMMAND_UNSUPPORTED: "instance:command:unsupported",
+    INSTANCE_READY: "instance:ready",
+    INSTANCE_BRIDGE_MOUNTED: "instance:bridge:mounted",
+    INSTANCE_BRIDGE_UNMOUNTED: "instance:bridge:unmounted",
+    INSTANCE_IFRAME_READY: "instance:iframe:ready",
+    INSTANCE_ERROR: "instance:error",
+    INSTANCE_APP_EVENT: "instance:app-event",
+};
+const SDK_COMMAND_CAPABILITY_BY_KIND = {
+    configure: "gx.command.configure.v1",
+    open: "gx.command.open.v1",
+    prefetch: "gx.command.prefetch.v1",
+    prerender: "gx.command.prerender.v1",
+    identify: "gx.command.identify.v1",
+    setContainer: "gx.command.setContainer.v1",
+    close: "gx.command.close.v1",
+    reset: "gx.command.reset.v1",
+    setDefaultContainerPolicy: "gx.command.setDefaultContainerPolicy.v1",
+};
+const SDK_COMMAND_CAPABILITIES = [
+    SDK_COMMAND_CAPABILITY_BY_KIND.configure,
+    SDK_COMMAND_CAPABILITY_BY_KIND.open,
+    SDK_COMMAND_CAPABILITY_BY_KIND.prefetch,
+    SDK_COMMAND_CAPABILITY_BY_KIND.prerender,
+    SDK_COMMAND_CAPABILITY_BY_KIND.identify,
+    SDK_COMMAND_CAPABILITY_BY_KIND.setContainer,
+    SDK_COMMAND_CAPABILITY_BY_KIND.close,
+    SDK_COMMAND_CAPABILITY_BY_KIND.reset,
+    SDK_COMMAND_CAPABILITY_BY_KIND.setDefaultContainerPolicy,
+];
+/**
+ * Stable capability tokens announced by the browser SDK during init.
+ * These are versioned and namespaced to support forward-compatible negotiation.
+ */
+export const SDK_PROTOCOL_CAPABILITIES = [
+    "gx.protocol.public.v1",
+    ...SDK_COMMAND_CAPABILITIES,
+];
+export const LOADER_RUNTIME_GLOBAL_KEY = "__getuserfeedback_runtime";
+export const LOADER_RUNTIME_PROTOCOL_VERSION = "v1";
+// Helper to construct full event name with prefix
+export const toHostEventName = (key) => `${HOST_EVENT_PREFIX}${key}`;

package/dist/host/host-event-contract.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Types and type guards for flow state and lifecycle events.
+ */
+/** Current state of the flow: whether it is open, loading, and its dimensions (if known). */
+export interface FlowState {
+    /** True when the flow is visible. */
+    isOpen: boolean;
+    /** True when the flow is loading (e.g. fetching or rendering). */
+    isLoading: boolean;
+    /** Flow width in pixels when known. */
+    width?: number;
+    /** Flow height in pixels when known. */
+    height?: number;
+}
+export interface FlowStateChangedDetail extends FlowState {
+    instanceId: string;
+    flowHandleId: string;
+}
+export interface InstanceFlowStateChangedDetail extends FlowState {
+    instanceId: string;
+}
+export interface OpenRequestedDetail {
+    instanceId: string;
+    source: "command" | "targeting";
+    flowId: string;
+    flowHandleId?: string;
+    hideCloseButton?: boolean;
+}
+export declare const HANDLE_INVALIDATED_REASON_CODES: readonly [
+    "RESET",
+    "CLOSED",
+    "STALE_HANDLE",
+    "OWNERSHIP_CONFLICT",
+    "OWNER_DISPOSED",
+    "UPSTREAM_INVALIDATED",
+    "INTERNAL"
+];
+export type HandleInvalidatedReasonCode = (typeof HANDLE_INVALIDATED_REASON_CODES)[number];
+export declare const HANDLE_INVALIDATED_SOURCES: readonly ["loader", "core"];
+export type HandleInvalidatedSource = (typeof HANDLE_INVALIDATED_SOURCES)[number];
+/** Generic handle lifecycle event emitted when a previously issued handle is invalidated upstream. */
+export interface HandleInvalidatedDetail {
+    instanceId: string;
+    handleKind: string;
+    handleId: string;
+    reasonCode: HandleInvalidatedReasonCode;
+    reasonMessage?: string;
+    relatedRequestId?: string;
+    source: HandleInvalidatedSource;
+    at: number;
+}
+export declare function isFlowStateChangedDetail(detail: unknown): detail is FlowStateChangedDetail;
+export declare function isInstanceFlowStateChangedDetail(detail: unknown): detail is InstanceFlowStateChangedDetail;
+export declare function isOpenRequestedDetail(detail: unknown): detail is OpenRequestedDetail;
+export declare function isHandleInvalidatedDetail(detail: unknown): detail is HandleInvalidatedDetail;
+export interface CommandSettledSuccessDetail {
+    requestId: string;
+    instanceId: string | null;
+    kind: string;
+    ok: true;
+    result?: unknown;
+}
+export interface CommandSettledFailureDetail {
+    requestId: string;
+    instanceId: string | null;
+    kind: string;
+    ok: false;
+    error: {
+        message: string;
+        code?: string;
+    };
+}
+export type CommandSettledDetail = CommandSettledSuccessDetail | CommandSettledFailureDetail;
+export declare function isCommandSettledDetail(detail: unknown): detail is CommandSettledDetail;
+/** Result of extracting a flow handle from a successful open/prerender/prefetch settlement. */
+export type FlowHandleFromSettlement = {
+    flowHandleId: string;
+    flowRunId?: string;
+};
+/**
+ * Host-facing handle result: same shape as FlowHandleFromSettlement.
+ * Used when projecting instance:command:settled so the SDK receives flowHandleId (and flowRunId when present).
+ */
+export type HostHandleSettlementResult = FlowHandleFromSettlement;
+/**
+ * Return the host-facing handle result for a command settlement, or null.
+ * Use in the loader when projecting instance:command:settled; keeps the host contract in one place (no zod).
+ */
+export declare function getHostHandleResultFromSettlement(detail: {
+    ok: boolean;
+    kind: string;
+    result?: unknown;
+}): HostHandleSettlementResult | null;
+/**
+ * Extract flow handle from a successful command settlement when the command
+ * is one that can return a handle (open, prerender, prefetch). Uses plain
+ * checks only (no Zod). Returns null if detail is not ok, kind is not one of
+ * those, or result does not contain a non-empty flowHandleId.
+ */
+export declare function getFlowHandleFromSettlementDetail(detail: {
+    ok: boolean;
+    kind: string;
+    result?: unknown;
+}): FlowHandleFromSettlement | null;
+//# sourceMappingURL=host-event-contract.d.ts.map

package/dist/host/host-event-contract.d.ts.map

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

package/dist/host/host-event-contract.js

@@ -0,0 +1,125 @@
+/**
+ * Types and type guards for flow state and lifecycle events.
+ */
+export const HANDLE_INVALIDATED_REASON_CODES = [
+    "RESET",
+    "CLOSED",
+    "STALE_HANDLE",
+    "OWNERSHIP_CONFLICT",
+    "OWNER_DISPOSED",
+    "UPSTREAM_INVALIDATED",
+    "INTERNAL",
+];
+export const HANDLE_INVALIDATED_SOURCES = [
+    "loader",
+    "core",
+];
+const isNonEmptyString = (v) => typeof v === "string" && v.trim().length > 0;
+const isRecord = (v) => typeof v === "object" && v !== null;
+const HANDLE_INVALIDATED_REASON_CODE_SET = new Set(HANDLE_INVALIDATED_REASON_CODES);
+const isHandleInvalidatedReasonCode = (v) => typeof v === "string" && HANDLE_INVALIDATED_REASON_CODE_SET.has(v);
+const HANDLE_INVALIDATED_SOURCE_SET = new Set(HANDLE_INVALIDATED_SOURCES);
+const isHandleInvalidatedSource = (v) => typeof v === "string" && HANDLE_INVALIDATED_SOURCE_SET.has(v);
+export function isFlowStateChangedDetail(detail) {
+    if (!isRecord(detail))
+        return false;
+    const { instanceId, isOpen, isLoading, width, height, flowHandleId } = detail;
+    return (isNonEmptyString(instanceId) &&
+        typeof isOpen === "boolean" &&
+        typeof isLoading === "boolean" &&
+        (typeof width === "undefined" || typeof width === "number") &&
+        (typeof height === "undefined" || typeof height === "number") &&
+        isNonEmptyString(flowHandleId));
+}
+export function isInstanceFlowStateChangedDetail(detail) {
+    if (!isRecord(detail))
+        return false;
+    const { instanceId, isOpen, isLoading, width, height } = detail;
+    return (isNonEmptyString(instanceId) &&
+        typeof isOpen === "boolean" &&
+        typeof isLoading === "boolean" &&
+        (typeof width === "undefined" || typeof width === "number") &&
+        (typeof height === "undefined" || typeof height === "number"));
+}
+export function isOpenRequestedDetail(detail) {
+    if (!isRecord(detail))
+        return false;
+    const { instanceId, source, flowId, flowHandleId, hideCloseButton } = detail;
+    return (isNonEmptyString(instanceId) &&
+        (source === "command" || source === "targeting") &&
+        isNonEmptyString(flowId) &&
+        (typeof flowHandleId === "undefined" || isNonEmptyString(flowHandleId)) &&
+        (typeof hideCloseButton === "undefined" ||
+            typeof hideCloseButton === "boolean"));
+}
+export function isHandleInvalidatedDetail(detail) {
+    if (!isRecord(detail))
+        return false;
+    const { instanceId, handleKind, handleId, reasonCode, reasonMessage, relatedRequestId, source, at, } = detail;
+    return (isNonEmptyString(instanceId) &&
+        isNonEmptyString(handleKind) &&
+        isNonEmptyString(handleId) &&
+        isHandleInvalidatedReasonCode(reasonCode) &&
+        (typeof reasonMessage === "undefined" ||
+            typeof reasonMessage === "string") &&
+        (typeof relatedRequestId === "undefined" ||
+            isNonEmptyString(relatedRequestId)) &&
+        isHandleInvalidatedSource(source) &&
+        typeof at === "number" &&
+        Number.isFinite(at));
+}
+export function isCommandSettledDetail(detail) {
+    if (!isRecord(detail))
+        return false;
+    const { requestId, instanceId, kind, ok, error } = detail;
+    if (!isNonEmptyString(requestId) ||
+        (typeof instanceId !== "string" && instanceId !== null) ||
+        typeof kind !== "string" ||
+        typeof ok !== "boolean") {
+        return false;
+    }
+    if (ok === true) {
+        return true;
+    }
+    if (ok === false && isRecord(error)) {
+        return typeof error.message === "string";
+    }
+    return false;
+}
+/**
+ * Return the host-facing handle result for a command settlement, or null.
+ * Use in the loader when projecting instance:command:settled; keeps the host contract in one place (no zod).
+ */
+export function getHostHandleResultFromSettlement(detail) {
+    return getFlowHandleFromSettlementDetail(detail);
+}
+const HANDLE_RETURNING_KINDS = [
+    "open",
+    "prerender",
+    "prefetch",
+];
+const HANDLE_RETURNING_KIND_SET = new Set(HANDLE_RETURNING_KINDS);
+const isHandleReturningKind = (kind) => HANDLE_RETURNING_KIND_SET.has(kind);
+/**
+ * Extract flow handle from a successful command settlement when the command
+ * is one that can return a handle (open, prerender, prefetch). Uses plain
+ * checks only (no Zod). Returns null if detail is not ok, kind is not one of
+ * those, or result does not contain a non-empty flowHandleId.
+ */
+export function getFlowHandleFromSettlementDetail(detail) {
+    if (!detail.ok || !isHandleReturningKind(detail.kind)) {
+        return null;
+    }
+    const result = detail.result;
+    if (!isRecord(result)) {
+        return null;
+    }
+    const { flowHandleId, flowRunId } = result;
+    if (!isNonEmptyString(flowHandleId)) {
+        return null;
+    }
+    return {
+        flowHandleId,
+        ...(isNonEmptyString(flowRunId) && { flowRunId }),
+    };
+}

package/dist/host/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Host-page / npm SDK protocol surface (Zod-free).
+ */
+export * from "./command-dispatch.js";
+export * from "./command-settlement.js";
+export * from "./constants.js";
+export * from "./host-event-contract.js";
+export * from "./lazy-handle-client.js";
+export { createCommandRequestId } from "./request-id.js";
+export * from "./sdk-types.js";
+export { createUniqueId } from "./unique-id.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/host/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/host/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AACzD,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/host/index.js

@@ -0,0 +1,11 @@
+/**
+ * Host-page / npm SDK protocol surface (Zod-free).
+ */
+export * from "./command-dispatch.js";
+export * from "./command-settlement.js";
+export * from "./constants.js";
+export * from "./host-event-contract.js";
+export * from "./lazy-handle-client.js";
+export { createCommandRequestId } from "./request-id.js";
+export * from "./sdk-types.js";
+export { createUniqueId } from "./unique-id.js";

package/dist/host/lazy-handle-client.d.ts

@@ -0,0 +1,37 @@
+type Subscriber<THandleId extends string> = (handleId: THandleId) => void;
+type StageSubscriber<TStage extends string> = (stage: TStage) => void;
+type LifecycleStage = "uninitialized" | "ready" | "invalidated";
+type StageMap<TStage extends string> = {
+    uninitialized: TStage;
+    ready: TStage;
+    invalidated: TStage;
+};
+export type LazyHandleClient<THandleId extends string, TSettlement, TStage extends string = LifecycleStage> = {
+    runCommand<TPayload>(buildPayload: (handleId: THandleId | undefined) => TPayload, dispatchAndWait: (payload: TPayload) => Promise<TSettlement>): Promise<TSettlement>;
+    getHandleId(): THandleId | undefined;
+    subscribeHandle(subscriber: Subscriber<THandleId>): () => void;
+    getStage(): TStage;
+    setStage(stage: TStage): void;
+    subscribeStage(subscriber: StageSubscriber<TStage>): () => void;
+    reset(): void;
+    invalidate(): void;
+};
+export type CreateLazyHandleClientOptions<THandleId extends string, TSettlement, TStage extends string = LifecycleStage> = {
+    getHandleIdFromSettlement: (settlement: TSettlement) => THandleId | undefined;
+    stages?: StageMap<TStage>;
+    initialStage?: TStage;
+};
+type CreateLazyHandleClientDefaultOptions<THandleId extends string, TSettlement> = {
+    getHandleIdFromSettlement: (settlement: TSettlement) => THandleId | undefined;
+    initialStage?: LifecycleStage;
+    stages?: undefined;
+};
+type CreateLazyHandleClientCustomOptions<THandleId extends string, TSettlement, TStage extends string> = {
+    getHandleIdFromSettlement: (settlement: TSettlement) => THandleId | undefined;
+    stages: StageMap<TStage>;
+    initialStage?: TStage;
+};
+export declare function createLazyHandleClient<THandleId extends string, TSettlement>(options: CreateLazyHandleClientDefaultOptions<THandleId, TSettlement>): LazyHandleClient<THandleId, TSettlement, LifecycleStage>;
+export declare function createLazyHandleClient<THandleId extends string, TSettlement, TStage extends string>(options: CreateLazyHandleClientCustomOptions<THandleId, TSettlement, TStage>): LazyHandleClient<THandleId, TSettlement, TStage>;
+export {};
+//# sourceMappingURL=lazy-handle-client.d.ts.map

package/dist/host/lazy-handle-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lazy-handle-client.d.ts","sourceRoot":"","sources":["../../src/host/lazy-handle-client.ts"],"names":[],"mappings":"AAAA,KAAK,UAAU,CAAC,SAAS,SAAS,MAAM,IAAI,CAAC,QAAQ,EAAE,SAAS,KAAK,IAAI,CAAC;AAC1E,KAAK,eAAe,CAAC,MAAM,SAAS,MAAM,IAAI,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;AAEtE,KAAK,cAAc,GAAG,eAAe,GAAG,OAAO,GAAG,aAAa,CAAC;AAChE,KAAK,QAAQ,CAAC,MAAM,SAAS,MAAM,IAAI;IACtC,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACpB,CAAC;AAQF,MAAM,MAAM,gBAAgB,CAC3B,SAAS,SAAS,MAAM,EACxB,WAAW,EACX,MAAM,SAAS,MAAM,GAAG,cAAc,IACnC;IACH,UAAU,CAAC,QAAQ,EAClB,YAAY,EAAE,CAAC,QAAQ,EAAE,SAAS,GAAG,SAAS,KAAK,QAAQ,EAC3D,eAAe,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,OAAO,CAAC,WAAW,CAAC,GAC1D,OAAO,CAAC,WAAW,CAAC,CAAC;IACxB,WAAW,IAAI,SAAS,GAAG,SAAS,CAAC;IACrC,eAAe,CAAC,UAAU,EAAE,UAAU,CAAC,SAAS,CAAC,GAAG,MAAM,IAAI,CAAC;IAC/D,QAAQ,IAAI,MAAM,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,cAAc,CAAC,UAAU,EAAE,eAAe,CAAC,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC;IAChE,KAAK,IAAI,IAAI,CAAC;IACd,UAAU,IAAI,IAAI,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,6BAA6B,CACxC,SAAS,SAAS,MAAM,EACxB,WAAW,EACX,MAAM,SAAS,MAAM,GAAG,cAAc,IACnC;IACH,yBAAyB,EAAE,CAAC,UAAU,EAAE,WAAW,KAAK,SAAS,GAAG,SAAS,CAAC;IAC9E,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,KAAK,oCAAoC,CACxC,SAAS,SAAS,MAAM,EACxB,WAAW,IACR;IACH,yBAAyB,EAAE,CAAC,UAAU,EAAE,WAAW,KAAK,SAAS,GAAG,SAAS,CAAC;IAC9E,YAAY,CAAC,EAAE,cAAc,CAAC;IAC9B,MAAM,CAAC,EAAE,SAAS,CAAC;CACnB,CAAC;AAEF,KAAK,mCAAmC,CACvC,SAAS,SAAS,MAAM,EACxB,WAAW,EACX,MAAM,SAAS,MAAM,IAClB;IACH,yBAAyB,EAAE,CAAC,UAAU,EAAE,WAAW,KAAK,SAAS,GAAG,SAAS,CAAC;IAC9E,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAsHF,wBAAgB,sBAAsB,CAAC,SAAS,SAAS,MAAM,EAAE,WAAW,EAC3E,OAAO,EAAE,oCAAoC,CAAC,SAAS,EAAE,WAAW,CAAC,GACnE,gBAAgB,CAAC,SAAS,EAAE,WAAW,EAAE,cAAc,CAAC,CAAC;AAC5D,wBAAgB,sBAAsB,CACrC,SAAS,SAAS,MAAM,EACxB,WAAW,EACX,MAAM,SAAS,MAAM,EAErB,OAAO,EAAE,mCAAmC,CAAC,SAAS,EAAE,WAAW,EAAE,MAAM,CAAC,GAC1E,gBAAgB,CAAC,SAAS,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC"}

package/dist/host/lazy-handle-client.js

@@ -0,0 +1,114 @@
+const DEFAULT_LIFECYCLE_STAGES = {
+    uninitialized: "uninitialized",
+    ready: "ready",
+    invalidated: "invalidated",
+};
+/**
+ * Serializes commands for a lazily initialized handle.
+ * Each command payload is built only when its turn runs, so it always sees
+ * the latest settled handle id from prior commands.
+ */
+const createLazyHandleClientWithStages = (input) => {
+    let handleId;
+    let tail = Promise.resolve();
+    let isIdle = true;
+    let epoch = 0;
+    const { stages } = input;
+    let stage = input.initialStage ?? stages.uninitialized;
+    const subscribers = new Set();
+    const stageSubscribers = new Set();
+    const setStage = (nextStage) => {
+        if (stage === nextStage) {
+            return;
+        }
+        if (stage === stages.invalidated && nextStage !== stages.invalidated) {
+            return;
+        }
+        stage = nextStage;
+        stageSubscribers.forEach((subscriber) => {
+            subscriber(nextStage);
+        });
+    };
+    const publishHandle = (nextHandleId) => {
+        if (stage === stages.invalidated) {
+            return;
+        }
+        handleId = nextHandleId;
+        setStage(stages.ready);
+        subscribers.forEach((subscriber) => {
+            subscriber(nextHandleId);
+        });
+    };
+    const runCommand = (buildPayload, dispatchAndWait) => {
+        const execute = async () => {
+            if (stage === stages.invalidated) {
+                throw new Error("Handle client is invalidated");
+            }
+            const commandEpoch = epoch;
+            const payload = buildPayload(handleId);
+            const settlement = await dispatchAndWait(payload);
+            const settledHandleId = input.getHandleIdFromSettlement(settlement);
+            if (settledHandleId && commandEpoch === epoch) {
+                publishHandle(settledHandleId);
+            }
+            return settlement;
+        };
+        const run = isIdle ? execute() : tail.then(execute, execute);
+        isIdle = false;
+        tail = run.then(() => {
+            isIdle = true;
+        }, () => {
+            isIdle = true;
+        });
+        return run;
+    };
+    return {
+        runCommand,
+        getHandleId: () => handleId,
+        subscribeHandle: (subscriber) => {
+            subscribers.add(subscriber);
+            if (handleId) {
+                subscriber(handleId);
+            }
+            return () => {
+                subscribers.delete(subscriber);
+            };
+        },
+        getStage: () => stage,
+        setStage,
+        subscribeStage: (subscriber) => {
+            stageSubscribers.add(subscriber);
+            subscriber(stage);
+            return () => {
+                stageSubscribers.delete(subscriber);
+            };
+        },
+        reset: () => {
+            epoch += 1;
+            handleId = undefined;
+            stage = stages.uninitialized;
+            stageSubscribers.forEach((subscriber) => {
+                subscriber(stage);
+            });
+        },
+        invalidate: () => {
+            epoch += 1;
+            handleId = undefined;
+            setStage(stages.invalidated);
+        },
+    };
+};
+export function createLazyHandleClient(options) {
+    if ("stages" in options && options.stages) {
+        return createLazyHandleClientWithStages({
+            getHandleIdFromSettlement: options.getHandleIdFromSettlement,
+            stages: options.stages,
+            initialStage: options.initialStage,
+        });
+    }
+    return createLazyHandleClientWithStages({
+        getHandleIdFromSettlement: options.getHandleIdFromSettlement,
+        stages: DEFAULT_LIFECYCLE_STAGES,
+        initialStage: options.initialStage,
+    });
+}

package/dist/host/request-id.d.ts

@@ -0,0 +1,2 @@
+export declare const createCommandRequestId: () => string;
+//# sourceMappingURL=request-id.d.ts.map

package/dist/host/request-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-id.d.ts","sourceRoot":"","sources":["../../src/host/request-id.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,sBAAsB,QAAO,MAA+B,CAAC"}

package/dist/host/request-id.js

@@ -0,0 +1,2 @@
+import { createUniqueId } from "./unique-id.js";
+export const createCommandRequestId = () => createUniqueId("req");

package/dist/host/sdk-types.d.ts

@@ -0,0 +1,311 @@
+/**
+ * getuserfeedback widget SDK public API.
+ *
+ * {@link FlowState} lives in `./host-event-contract` (re-exported from the `@getuserfeedback/protocol/host` barrel).
+ */
+/** Supported identity kinds for analytics and tracking. */
+export type AppEventIdentityType = "anonymousId" | "userId" | "traits.email" | "traits.phone" | "context.device.id" | "context.device.advertisingId" | "context.device.token";
+/** A single identity (e.g. userId or anonymousId) and its value. */
+export type AppEventIdentity = {
+    type: AppEventIdentityType;
+    value: string;
+};
+/** Page and device context you can attach to tracked events. */
+export type AppEventContext = {
+    page?: {
+        path?: string;
+        referrer?: string;
+        search?: string;
+    };
+    locale?: string;
+    userAgent?: string;
+};
+/** Optional fields shared by all flow lifecycle events (traits, identities, context, timing). */
+export type AppEventBase = {
+    traits?: Record<string, unknown> | undefined;
+    identities?: AppEventIdentity[] | undefined;
+    context?: AppEventContext | undefined;
+    messageId?: string | undefined;
+    timestamp?: number | undefined;
+};
+/** Reference to a specific survey/flow. */
+export type AppEventSurveyReference = {
+    surveyId: string;
+};
+/** Event payload when a flow is shown (Flow Viewed event). */
+export type FlowViewedPayload = AppEventBase & {
+    event: "Flow Viewed";
+    references: AppEventSurveyReference;
+};
+/** Event payload when a user dismisses a flow. */
+export type FlowDismissedPayload = AppEventBase & {
+    event: "Flow Dismissed";
+    references: AppEventSurveyReference;
+};
+/**
+ * Payload for {@link Client.track}. Use this to record when a flow is shown or dismissed.
+ * Discriminate on the `event` field (`"Flow Viewed"` or `"Flow Dismissed"`).
+ */
+export type AppEventPayload = FlowViewedPayload | FlowDismissedPayload;
+/** How the widget was loaded (e.g. via SDK, GTM, or a tag manager). */
+export type ClientMetaLoader = "sdk" | "gtm" | "segment" | "rudderstack" | "tealium" | "custom";
+/** Delivery method for the widget script (e.g. ESM, script tag). */
+export type ClientMetaTransport = "script-tag" | "esm" | "loader" | "tag-manager" | "snippet";
+/** Detected or configured front-end framework. */
+export type ClientMetaRuntimeFramework = "next" | "vite" | "webpack" | "plain";
+/** Runtime environment (browser or edge). */
+export type ClientMetaRuntimeEnv = "browser" | "edge";
+/** Metadata about the client and integration (e.g. loader, framework). Used for analytics and support. */
+export type ClientMeta = {
+    loader: ClientMetaLoader;
+    clientName?: string | undefined;
+    clientVersion?: string | undefined;
+    integrator?: {
+        name?: string | undefined;
+        version?: string | undefined;
+    } | undefined;
+    transport?: ClientMetaTransport | undefined;
+    runtime?: {
+        framework?: ClientMetaRuntimeFramework | undefined;
+        runtime?: ClientMetaRuntimeEnv | undefined;
+    } | undefined;
+    notes?: string | undefined;
+};
+export type RuntimeEndpoints = {
+    apiUrl?: string | undefined;
+    coreUrl?: string | undefined;
+};
+/**
+ * Use host attributes to auto-detect the color scheme ("light" by default). The widget observes these attributes on body and html elements,
+ *
+ * class="dark" or data-theme="dark" on html or body elements will set the widget to dark mode.
+ *
+ * class="light" or data-theme="light" will set the widget to light mode.
+ *
+ * class="system" or data-theme="system" will set the widget to follow the user's OS/browser preference (prefers-color-scheme).
+ */
+export type ColorSchemeAutoDetect = {
+    /** List of host attribute names (html or body) to observe for color scheme.
+     *
+     * Default: ["class", "data-theme"]
+     */
+    autoDetectColorScheme: string[];
+};
+/**
+ * Color scheme: either auto-detect from host html and body attributes (default) or provide an explicit value.
+ * - { autoDetectColorScheme: ["class", "data-theme"] }
+ * - "light" | "dark" | "system"
+ */
+export type ColorSchemeConfig = ColorSchemeAutoDetect | "light" | "dark" | "system";
+/** Whether telemetry is enabled. */
+export type TelemetryConfig = {
+    enabled?: boolean | undefined;
+};
+/** When true, prints debug logs to console. Narrow down with a namespace string/array eg. `["loader", "handshake"]`. Default `false`. */
+export type DebugConfig = boolean | string | string[];
+/** Status of a consent decision (pending, granted, denied, revoked). */
+export type ConsentStatus = "pending" | "granted" | "denied" | "revoked";
+/** Supported consent scope identifiers for explicit allow-list grants. */
+export type GrantScope = "analytics.storage" | "analytics.measurement" | "personalization.storage" | "ads.storage" | "ads.user_data" | "ads.personalization";
+/** Consent configuration. Use a single decision for all scopes, or provide an explicit allow-list of granted scopes. */
+export type ConsentConfig = ConsentStatus | GrantScope[];
+/** Auth configuration (e.g. JWT for authenticated flows). */
+export type AuthConfig = {
+    jwt?: {
+        token: string;
+    } | null | undefined;
+};
+/** Options for {@link Client.configure}: color scheme, consent, and auth. */
+export type ConfigureOptions = {
+    colorScheme?: ColorSchemeConfig | undefined;
+    consent?: ConsentConfig | undefined;
+    auth?: AuthConfig | undefined;
+};
+/** @internal Options when initializing the widget: API key, color scheme, disableTelemetry, enableDebug, defaultConsent, and optional capabilities. */
+export type InitOptions = {
+    apiKey: string;
+    colorScheme?: ColorSchemeConfig | undefined;
+    disableTelemetry?: boolean | undefined;
+    enableDebug?: DebugConfig | undefined;
+    defaultConsent?: ConsentConfig | undefined;
+    clientMeta?: ClientMeta | undefined;
+    capabilities?: string[] | undefined;
+    runtimeEndpoints?: RuntimeEndpoints | undefined;
+};
+export type ClientOptions = {
+    /** Your project API key. */
+    apiKey: string;
+    /** Color scheme config: host-driven (loader observes attributes) or explicit. */
+    colorScheme?: ColorSchemeConfig | undefined;
+    /** Consent settings compatible with common privacy frameworks (GDPR, CCPA, LGPD) and CMP flows.
+     *
+     * Default: `granted` (all scopes).
+     *
+     * Accepts either a single decision (`granted` | `denied` | `pending` | `revoked`)
+     * or an explicit allow-list of additional granted scopes (`GrantScope[]`).
+     *
+     * For strict privacy guarantees, use `pending` at init time and later call `client.configure({ consent })` after
+     * the user makes a consent choice via your CMP or UI.
+     *
+     * In array form, listed scopes are granted and all other non-essential scopes are denied.
+     *
+     * Essential baseline scopes are always granted for core widget operation and cannot be denied:
+     * - `functionality.storage`
+     * - `security.storage`
+     */
+    defaultConsent?: ConsentConfig | undefined;
+    /** When true, prints debug logs to console. Narrow down with a namespace string/array eg. ```["loader", "handshake"]```. Default `false`.
+     */
+    enableDebug?: DebugConfig | undefined;
+    /** When true, the widget does not load automatically; call `client.load()` when ready. Default `false` */
+    disableAutoLoad?: boolean;
+    /** Disable anonymous widget telemetry.
+     *
+     * When `true`, telemetry is not sent.
+     *
+     * This flag does not disable user targeting and reporting analytics. It's used (by us) for performance monitoring and error tracking.
+     *
+     * Included telemetry data when enabled: apiKey, ephemeral one-time session id,
+     * execution flow, event timestamps, and page origin (domain name).
+     *
+     * Excluded by default: user identity and detailed page fields (path/referrer/search).
+     */
+    disableTelemetry?: boolean | undefined;
+    _loaderUrl?: string | undefined;
+    _coreUrl?: string | undefined;
+    _apiUrl?: string | undefined;
+};
+/** Open a flow with a given instance. Omit flowHandleId for first open; core returns it in settlement. */
+export type OpenCommandPayload = {
+    kind: "open";
+    flowId: string;
+    flowHandleId?: string | undefined;
+    container?: HTMLElement | undefined;
+    /**
+     * @deprecated Simply use `container` directly instead.
+     */
+    containerRequirement?: "any" | "hostOnly" | undefined;
+    /**
+     * When `true`, the flow view does not show a close button.
+     * Useful for mobile or embedded contexts where the host handles dismissal (e.g. via a drawer or back gesture).
+     */
+    hideCloseButton?: boolean | undefined;
+};
+/** Prefetch a flow. Omit flowHandleId for first prefetch; core returns it in settlement. */
+export type PrefetchCommandPayload = {
+    kind: "prefetch";
+    flowId: string;
+    flowHandleId?: string | undefined;
+};
+/** Prerender a flow. Omit flowHandleId for first prerender; core returns it in settlement. */
+export type PrerenderCommandPayload = {
+    kind: "prerender";
+    flowId: string;
+    flowHandleId?: string | undefined;
+    /**
+     * When `true`, the prerendered view does not show a close button.
+     */
+    hideCloseButton?: boolean | undefined;
+};
+/** Identify with traits only (`client.identify(traits)`). */
+export type IdentifyTraitsOnlyCommandPayload = {
+    kind: "identify";
+    traits: Record<string, unknown>;
+};
+/** Identify with userId and optional traits (`client.identify(userId, traits?)`). */
+export type IdentifyUserCommandPayload = {
+    kind: "identify";
+    userId: string;
+    traits?: Record<string, unknown> | undefined;
+};
+/** Identify command payload: either traits-only or userId+traits shape. */
+export type IdentifyCommandPayload = IdentifyTraitsOnlyCommandPayload | IdentifyUserCommandPayload;
+/** Track a flow shown or dismissed event. */
+export type TrackCommandPayload = AppEventBase & {
+    kind: "track";
+    event: "Flow Viewed" | "Flow Dismissed";
+    references: AppEventSurveyReference;
+};
+/** Attach or detach a resolved flow handle from a host container. */
+export type SetContainerCommandPayload = {
+    kind: "setContainer";
+    flowHandleId: string;
+    container: HTMLElement | null;
+};
+/** Default container behavior for flows in an instance. */
+export type ContainerPolicy = {
+    kind: "floating";
+} | {
+    kind: "hostContainer";
+    host: HTMLElement | null;
+    sharing: "shared" | "perFlowRun";
+};
+/** Set the instance-level default container policy. */
+export type SetDefaultContainerPolicyCommandPayload = {
+    kind: "setDefaultContainerPolicy";
+    policy: ContainerPolicy;
+};
+/** Update color scheme, consent, and auth. */
+export type ConfigureCommandPayload = {
+    kind: "configure";
+    opts: ConfigureOptions;
+};
+/** Initialize the widget with options. */
+export type InitCommandPayload = {
+    kind: "init";
+    opts: InitOptions;
+};
+/** Close a flow. */
+export type CloseCommandPayload = {
+    kind: "close";
+    flowHandleId?: string | undefined;
+};
+/** Reset widget state. */
+export type ResetCommandPayload = {
+    kind: "reset";
+};
+/** Union of all widget action payloads (open, prefetch, identify, configure, etc.). */
+export type PublicCommandPayload = OpenCommandPayload | PrefetchCommandPayload | PrerenderCommandPayload | IdentifyCommandPayload | SetContainerCommandPayload | SetDefaultContainerPolicyCommandPayload | ConfigureCommandPayload | InitCommandPayload | CloseCommandPayload | ResetCommandPayload;
+/** Input for a single widget action; same shape as {@link PublicCommandPayload}. */
+export type Command = PublicCommandPayload;
+/** Wrapper for a widget action (version, request id, idempotency key, optional client metadata, and the action payload). */
+export type CommandEnvelope = {
+    version: "1";
+    instanceId?: string | undefined;
+    requestId: string;
+    idempotencyKey: string;
+    clientMeta?: ClientMeta | undefined;
+    command: PublicCommandPayload;
+};
+/** Identity kind for telemetry events; same as {@link AppEventIdentityType}. */
+export type TelemetryIdentityType = AppEventIdentityType;
+/**
+ * Event passed to the `beforeSend` hook in {@link Client.use}.
+ * When `debug` is true, identities and full page context are included; when false, no identities and page is origin-only.
+ * TODO(telemetry-contract-cleanup): Rename this SDK-facing type to
+ * WidgetTelemetryEvent in a coordinated SDK-facing change so we can retire the
+ * generic TelemetryEvent alias from shared telemetry.
+ */
+export type TelemetryEvent = {
+    type: string;
+    timestamp: number;
+    apiKey: string;
+    /** When true, identities and full page context are present; when false, no identities and page.origin only. */
+    debug: boolean;
+    identities: Array<{
+        type: TelemetryIdentityType;
+        value: string;
+    }>;
+    context: {
+        page: {
+            path?: string | null | undefined;
+            referrer?: string | null | undefined;
+            search?: string | null | undefined;
+            origin?: string | null | undefined;
+        };
+        widgetVersion: string;
+        clientMeta?: ClientMeta | undefined;
+    };
+    properties?: Record<string, unknown> | undefined;
+};
+//# sourceMappingURL=sdk-types.d.ts.map

package/dist/host/sdk-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-types.d.ts","sourceRoot":"","sources":["../../src/host/sdk-types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,2DAA2D;AAC3D,MAAM,MAAM,oBAAoB,GAC7B,aAAa,GACb,QAAQ,GACR,cAAc,GACd,cAAc,GACd,mBAAmB,GACnB,8BAA8B,GAC9B,sBAAsB,CAAC;AAE1B,oEAAoE;AACpE,MAAM,MAAM,gBAAgB,GAAG;IAC9B,IAAI,EAAE,oBAAoB,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,gEAAgE;AAChE,MAAM,MAAM,eAAe,GAAG;IAC7B,IAAI,CAAC,EAAE;QACN,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,iGAAiG;AACjG,MAAM,MAAM,YAAY,GAAG;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAC7C,UAAU,CAAC,EAAE,gBAAgB,EAAE,GAAG,SAAS,CAAC;IAC5C,OAAO,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;IACtC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B,CAAC;AAEF,2CAA2C;AAC3C,MAAM,MAAM,uBAAuB,GAAG;IACrC,QAAQ,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,8DAA8D;AAC9D,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG;IAC9C,KAAK,EAAE,aAAa,CAAC;IACrB,UAAU,EAAE,uBAAuB,CAAC;CACpC,CAAC;AAEF,kDAAkD;AAClD,MAAM,MAAM,oBAAoB,GAAG,YAAY,GAAG;IACjD,KAAK,EAAE,gBAAgB,CAAC;IACxB,UAAU,EAAE,uBAAuB,CAAC;CACpC,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,iBAAiB,GAAG,oBAAoB,CAAC;AAIvE,uEAAuE;AACvE,MAAM,MAAM,gBAAgB,GACzB,KAAK,GACL,KAAK,GACL,SAAS,GACT,aAAa,GACb,SAAS,GACT,QAAQ,CAAC;AAEZ,oEAAoE;AACpE,MAAM,MAAM,mBAAmB,GAC5B,YAAY,GACZ,KAAK,GACL,QAAQ,GACR,aAAa,GACb,SAAS,CAAC;AAEb,kDAAkD;AAClD,MAAM,MAAM,0BAA0B,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;AAE/E,6CAA6C;AAC7C,MAAM,MAAM,oBAAoB,GAAG,SAAS,GAAG,MAAM,CAAC;AAEtD,0GAA0G;AAC1G,MAAM,MAAM,UAAU,GAAG;IACxB,MAAM,EAAE,gBAAgB,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,UAAU,CAAC,EACR;QACA,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAC1B,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KAC5B,GACD,SAAS,CAAC;IACb,SAAS,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;IAC5C,OAAO,CAAC,EACL;QACA,SAAS,CAAC,EAAE,0BAA0B,GAAG,SAAS,CAAC;QACnD,OAAO,CAAC,EAAE,oBAAoB,GAAG,SAAS,CAAC;KAC1C,GACD,SAAS,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC9B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B,CAAC;AAIF;;;;;;;;GAQG;AACH,MAAM,MAAM,qBAAqB,GAAG;IACnC;;;OAGG;IACH,qBAAqB,EAAE,MAAM,EAAE,CAAC;CAChC,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAC1B,qBAAqB,GACrB,OAAO,GACP,MAAM,GACN,QAAQ,CAAC;AAEZ,oCAAoC;AACpC,MAAM,MAAM,eAAe,GAAG;IAC7B,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC9B,CAAC;AAEF,yIAAyI;AACzI,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,EAAE,CAAC;AAEtD,wEAAwE;AACxE,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEzE,0EAA0E;AAC1E,MAAM,MAAM,UAAU,GACnB,mBAAmB,GACnB,uBAAuB,GACvB,yBAAyB,GACzB,aAAa,GACb,eAAe,GACf,qBAAqB,CAAC;AAEzB,wHAAwH;AACxH,MAAM,MAAM,aAAa,GAAG,aAAa,GAAG,UAAU,EAAE,CAAC;AAEzD,6DAA6D;AAC7D,MAAM,MAAM,UAAU,GAAG;IACxB,GAAG,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,GAAG,SAAS,CAAC;CAC3C,CAAC;AAEF,6EAA6E;AAC7E,MAAM,MAAM,gBAAgB,GAAG;IAC9B,WAAW,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;IAC5C,OAAO,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IACpC,IAAI,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;CAC9B,CAAC;AAEF,uJAAuJ;AACvJ,MAAM,MAAM,WAAW,GAAG;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;IAC5C,gBAAgB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,WAAW,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IACtC,cAAc,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IAC3C,UAAU,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IACpC,YAAY,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IACpC,gBAAgB,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;CAChD,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC3B,4BAA4B;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,WAAW,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;IAC5C;;;;;;;;;;;;;;;OAeG;IACH,cAAc,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IAC3C;OACG;IACH,WAAW,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IACtC,0GAA0G;IAC1G,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;;;;;;OAUG;IACH,gBAAgB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B,CAAC;AAIF,0GAA0G;AAC1G,MAAM,MAAM,kBAAkB,GAAG;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,SAAS,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IACpC;;OAEG;IACH,oBAAoB,CAAC,EAAE,KAAK,GAAG,UAAU,GAAG,SAAS,CAAC;IACtD;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACtC,CAAC;AAEF,4FAA4F;AAC5F,MAAM,MAAM,sBAAsB,GAAG;IACpC,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC,CAAC;AAEF,8FAA8F;AAC9F,MAAM,MAAM,uBAAuB,GAAG;IACrC,IAAI,EAAE,WAAW,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC;;OAEG;IACH,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACtC,CAAC;AAEF,6DAA6D;AAC7D,MAAM,MAAM,gCAAgC,GAAG;IAC9C,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC,CAAC;AAEF,qFAAqF;AACrF,MAAM,MAAM,0BAA0B,GAAG;IACxC,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;CAC7C,CAAC;AAEF,2EAA2E;AAC3E,MAAM,MAAM,sBAAsB,GAC/B,gCAAgC,GAChC,0BAA0B,CAAC;AAE9B,6CAA6C;AAC7C,MAAM,MAAM,mBAAmB,GAAG,YAAY,GAAG;IAChD,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,aAAa,GAAG,gBAAgB,CAAC;IACxC,UAAU,EAAE,uBAAuB,CAAC;CACpC,CAAC;AAEF,qEAAqE;AACrE,MAAM,MAAM,0BAA0B,GAAG;IACxC,IAAI,EAAE,cAAc,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,WAAW,GAAG,IAAI,CAAC;CAC9B,CAAC;AAEF,2DAA2D;AAC3D,MAAM,MAAM,eAAe,GACxB;IACA,IAAI,EAAE,UAAU,CAAC;CAChB,GACD;IACA,IAAI,EAAE,eAAe,CAAC;IACtB,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC;IACzB,OAAO,EAAE,QAAQ,GAAG,YAAY,CAAC;CAChC,CAAC;AAEL,uDAAuD;AACvD,MAAM,MAAM,uCAAuC,GAAG;IACrD,IAAI,EAAE,2BAA2B,CAAC;IAClC,MAAM,EAAE,eAAe,CAAC;CACxB,CAAC;AAEF,8CAA8C;AAC9C,MAAM,MAAM,uBAAuB,GAAG;IACrC,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,gBAAgB,CAAC;CACvB,CAAC;AAEF,0CAA0C;AAC1C,MAAM,MAAM,kBAAkB,GAAG;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,WAAW,CAAC;CAClB,CAAC;AAEF,oBAAoB;AACpB,MAAM,MAAM,mBAAmB,GAAG;IACjC,IAAI,EAAE,OAAO,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC,CAAC;AAEF,0BAA0B;AAC1B,MAAM,MAAM,mBAAmB,GAAG;IACjC,IAAI,EAAE,OAAO,CAAC;CACd,CAAC;AAEF,uFAAuF;AACvF,MAAM,MAAM,oBAAoB,GAC7B,kBAAkB,GAClB,sBAAsB,GACtB,uBAAuB,GACvB,sBAAsB,GACtB,0BAA0B,GAC1B,uCAAuC,GACvC,uBAAuB,GACvB,kBAAkB,GAClB,mBAAmB,GACnB,mBAAmB,CAAC;AAEvB,oFAAoF;AACpF,MAAM,MAAM,OAAO,GAAG,oBAAoB,CAAC;AAE3C,4HAA4H;AAC5H,MAAM,MAAM,eAAe,GAAG;IAC7B,OAAO,EAAE,GAAG,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IACpC,OAAO,EAAE,oBAAoB,CAAC;CAC9B,CAAC;AAIF,gFAAgF;AAChF,MAAM,MAAM,qBAAqB,GAAG,oBAAoB,CAAC;AAEzD;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,+GAA+G;IAC/G,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,qBAAqB,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClE,OAAO,EAAE;QACR,IAAI,EAAE;YACL,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;YACjC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;YACrC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;YACnC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;SACnC,CAAC;QACF,aAAa,EAAE,MAAM,CAAC;QACtB,UAAU,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;KACpC,CAAC;IACF,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;CACjD,CAAC"}

package/dist/host/sdk-types.js

@@ -0,0 +1,6 @@
+/**
+ * getuserfeedback widget SDK public API.
+ *
+ * {@link FlowState} lives in `./host-event-contract` (re-exported from the `@getuserfeedback/protocol/host` barrel).
+ */
+export {};

package/dist/host/sdk.d.ts

@@ -0,0 +1,10 @@
+/**
+ * SDK-facing protocol surface: types (from sdk-types) and values only.
+ * Does not re-export schema modules so SDK dist stays zod-free.
+ */
+export { createCommandDispatch } from "./command-dispatch.js";
+export { COMMAND_SETTLEMENT_TIMEOUT_CODE, CommandSettlementError, CommandSettlementTimeoutError, toCommandSettlementError, waitForCommandSettlement, } from "./command-settlement.js";
+export type { FlowHandleFromSettlement, FlowState, } from "./host-event-contract.js";
+export { getFlowHandleFromSettlementDetail, isFlowStateChangedDetail, isHandleInvalidatedDetail, isInstanceFlowStateChangedDetail, } from "./host-event-contract.js";
+export type { AppEventPayload, ClientMeta, ClientOptions, Command, CommandEnvelope, ConfigureOptions, ContainerPolicy, InitOptions, PublicCommandPayload, TelemetryEvent, } from "./sdk-types.js";
+//# sourceMappingURL=sdk.d.ts.map

package/dist/host/sdk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk.d.ts","sourceRoot":"","sources":["../../src/host/sdk.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EACN,+BAA+B,EAC/B,sBAAsB,EACtB,6BAA6B,EAC7B,wBAAwB,EACxB,wBAAwB,GACxB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACX,wBAAwB,EACxB,SAAS,GACT,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACN,iCAAiC,EACjC,wBAAwB,EACxB,yBAAyB,EACzB,gCAAgC,GAChC,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACX,eAAe,EACf,UAAU,EACV,aAAa,EACb,OAAO,EACP,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,oBAAoB,EAGpB,cAAc,GACd,MAAM,gBAAgB,CAAC"}

package/dist/host/sdk.js

@@ -0,0 +1,7 @@
+/**
+ * SDK-facing protocol surface: types (from sdk-types) and values only.
+ * Does not re-export schema modules so SDK dist stays zod-free.
+ */
+export { createCommandDispatch } from "./command-dispatch.js";
+export { COMMAND_SETTLEMENT_TIMEOUT_CODE, CommandSettlementError, CommandSettlementTimeoutError, toCommandSettlementError, waitForCommandSettlement, } from "./command-settlement.js";
+export { getFlowHandleFromSettlementDetail, isFlowStateChangedDetail, isHandleInvalidatedDetail, isInstanceFlowStateChangedDetail, } from "./host-event-contract.js";

package/dist/host/unique-id.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Generates a unique string ID. Uses crypto.randomUUID when available,
+ * otherwise falls back to a timestamp + random string.
+ *
+ * @param prefix - Optional prefix for the fallback format (e.g. "req", "err").
+ *                 Only affects fallback; UUIDs have no prefix.
+ */
+export declare function createUniqueId(prefix?: string): string;
+//# sourceMappingURL=unique-id.d.ts.map

package/dist/host/unique-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unique-id.d.ts","sourceRoot":"","sources":["../../src/host/unique-id.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAStD"}

package/dist/host/unique-id.js

@@ -0,0 +1,15 @@
+/**
+ * Generates a unique string ID. Uses crypto.randomUUID when available,
+ * otherwise falls back to a timestamp + random string.
+ *
+ * @param prefix - Optional prefix for the fallback format (e.g. "req", "err").
+ *                 Only affects fallback; UUIDs have no prefix.
+ */
+export function createUniqueId(prefix) {
+    if (typeof globalThis.crypto !== "undefined" &&
+        typeof globalThis.crypto.randomUUID === "function") {
+        return globalThis.crypto.randomUUID();
+    }
+    const fallback = `${Date.now()}_${Math.random().toString(36).slice(2)}`;
+    return prefix ? `${prefix}_${fallback}` : fallback;
+}

package/package.json

@@ -0,0 +1,73 @@
+{
+	"name": "@getuserfeedback/protocol",
+	"version": "0.1.0",
+	"description": "getuserfeedback widget protocol — host surface and (later) wire protocol",
+	"keywords": [
+		"getuserfeedback",
+		"widget",
+		"protocol"
+	],
+	"license": "MIT",
+	"publishConfig": {
+		"access": "public"
+	},
+	"type": "module",
+	"sideEffects": false,
+	"files": [
+		"dist"
+	],
+	"exports": {
+		"./host": {
+			"types": "./dist/host/index.d.ts",
+			"import": "./dist/host/index.js"
+		},
+		"./host/sdk-types": {
+			"types": "./dist/host/sdk-types.d.ts",
+			"import": "./dist/host/sdk-types.js"
+		},
+		"./host/host-event-contract": {
+			"types": "./dist/host/host-event-contract.d.ts",
+			"import": "./dist/host/host-event-contract.js"
+		},
+		"./host/constants": {
+			"types": "./dist/host/constants.d.ts",
+			"import": "./dist/host/constants.js"
+		},
+		"./host/command-dispatch": {
+			"types": "./dist/host/command-dispatch.d.ts",
+			"import": "./dist/host/command-dispatch.js"
+		},
+		"./host/command-settlement": {
+			"types": "./dist/host/command-settlement.d.ts",
+			"import": "./dist/host/command-settlement.js"
+		},
+		"./host/sdk": {
+			"types": "./dist/host/sdk.d.ts",
+			"import": "./dist/host/sdk.js"
+		},
+		"./host/request-id": {
+			"types": "./dist/host/request-id.d.ts",
+			"import": "./dist/host/request-id.js"
+		},
+		"./host/unique-id": {
+			"types": "./dist/host/unique-id.d.ts",
+			"import": "./dist/host/unique-id.js"
+		},
+		"./host/lazy-handle-client": {
+			"types": "./dist/host/lazy-handle-client.d.ts",
+			"import": "./dist/host/lazy-handle-client.js"
+		}
+	},
+	"scripts": {
+		"lint": "ultracite check .",
+		"build": "bun x rimraf dist tsconfig.tsbuildinfo && tsc -b tsconfig.json",
+		"typecheck": "tsc -b tsconfig.json",
+		"pack:verify": "node ../../scripts/pack-and-verify.cjs",
+		"publish:dry-run": "node ../../scripts/publish-package.cjs . -- --dry-run",
+		"publish:npm": "node ../../scripts/publish-package.cjs ."
+	},
+	"devDependencies": {
+		"rimraf": "^6.0.0",
+		"typescript": "^5.8.3"
+	}
+}