@getuserfeedback/protocol 0.2.0 → 0.2.2

package/README.md

@@ -0,0 +1,48 @@
+# `@getuserfeedback/protocol`
+
+Public contract surface for host integrations that load and control the getuserfeedback widget.
+
+## Lifecycle contract
+
+This package defines the public shapes for:
+
+- init-time widget configuration
+- post-load widget commands
+- host SDK types and settlement helpers
+
+## What hosts can do after init
+
+After the widget has been initialized, a public host integration may:
+
+- identify the current user with `identify`
+- update consent with `configure({ consent })`
+- update theme with `configure({ colorScheme })`
+- update auth with `configure({ auth })`
+- open, prefetch, prerender, close, or reset flows
+
+## Identification
+
+Public identification is already supported.
+
+Use one of these public command shapes:
+
+- `{ kind: "identify", userId, traits? }`
+- `{ kind: "identify", traits }`
+
+`identify` is a post-init lifecycle operation. The public root contract does not currently accept identity inside `init` or `configure`.
+
+## Navigation updates
+
+Explicit public navigation update commands are not part of the current public contract.
+
+There is no public `navigate`, `updatePage`, or `hostContextUpdated` command in `@getuserfeedback/protocol`. Hosts should not invent private navigation bridges on top of internal loader or core commands.
+
+Loader-driven integrations may still observe browser URL changes internally for targeting and telemetry, but that behavior is internal runtime behavior, not a stable public contract yet.
+
+## GTM and other adapters
+
+Adapters built on top of this package should only bridge capabilities that exist in this public contract.
+
+- Use `identify` only because it is public and supported.
+- Keep consent and theme updates mapped to `configure`.
+- Do not expose custom navigation-update fields until this package defines a public navigation contract.

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

@@ -1 +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"}
+{"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,CAapE,CAAC"}

package/dist/host/command-dispatch.js

@@ -1,5 +1,5 @@
+import { createCommandEnvelope } from "./command-envelope.js";
 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
@@ -15,16 +15,12 @@ import { createCommandRequestId } from "./request-id.js";
  */
 export const createCommandDispatch = (push) => {
     return async (input, options) => {
-        const requestId = createCommandRequestId();
-        const idempotencyKey = resolveIdempotencyKey(options?.idempotencyKey);
-        const envelope = {
-            version: "1",
-            requestId,
-            idempotencyKey: idempotencyKey ?? requestId,
+        const envelope = createCommandEnvelope({
             command: input,
-        };
+            idempotencyKey: resolveIdempotencyKey(options?.idempotencyKey) ?? undefined,
+        });
         push(envelope);
-        await waitForCommandSettlement({ requestId });
+        await waitForCommandSettlement({ requestId: envelope.requestId });
     };
 };
 const resolveIdempotencyKey = (value) => {

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

@@ -0,0 +1,10 @@
+import type { ClientMeta, CommandEnvelope, PublicCommandPayload } from "./sdk-types.js";
+export type CreateCommandEnvelopeInput = {
+    command: PublicCommandPayload;
+    requestId?: string | undefined;
+    idempotencyKey?: string | undefined;
+    instanceId?: string | undefined;
+    clientMeta?: ClientMeta | undefined;
+};
+export declare const createCommandEnvelope: (input: CreateCommandEnvelopeInput) => CommandEnvelope;
+//# sourceMappingURL=command-envelope.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"command-envelope.d.ts","sourceRoot":"","sources":["../../src/host/command-envelope.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACX,UAAU,EACV,eAAe,EACf,oBAAoB,EACpB,MAAM,gBAAgB,CAAC;AAExB,MAAM,MAAM,0BAA0B,GAAG;IACxC,OAAO,EAAE,oBAAoB,CAAC;IAC9B,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,UAAU,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;CACpC,CAAC;AAUF,eAAO,MAAM,qBAAqB,GACjC,OAAO,0BAA0B,KAC/B,eAeF,CAAC"}

package/dist/host/command-envelope.js

@@ -0,0 +1,21 @@
+import { createCommandRequestId } from "./request-id.js";
+const normalizeOptionalString = (value) => {
+    if (value === undefined) {
+        return undefined;
+    }
+    const normalized = value.trim();
+    return normalized.length > 0 ? normalized : undefined;
+};
+export const createCommandEnvelope = (input) => {
+    const requestId = normalizeOptionalString(input.requestId) ?? createCommandRequestId();
+    const idempotencyKey = normalizeOptionalString(input.idempotencyKey) ?? requestId;
+    const instanceId = normalizeOptionalString(input.instanceId);
+    return {
+        version: "1",
+        command: input.command,
+        requestId,
+        idempotencyKey,
+        ...(instanceId !== undefined ? { instanceId } : {}),
+        ...(input.clientMeta !== undefined ? { clientMeta: input.clientMeta } : {}),
+    };
+};

package/dist/host/index.d.ts

@@ -2,6 +2,7 @@
  * Host-page / npm SDK protocol surface (Zod-free).
  */
 export * from "./command-dispatch.js";
+export * from "./command-envelope.js";
 export * from "./command-settlement.js";
 export * from "./constants.js";
 export * from "./host-event-contract.js";

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

@@ -1 +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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/host/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,uBAAuB,CAAC;AACtC,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

@@ -2,6 +2,7 @@
  * Host-page / npm SDK protocol surface (Zod-free).
  */
 export * from "./command-dispatch.js";
+export * from "./command-envelope.js";
 export * from "./command-settlement.js";
 export * from "./constants.js";
 export * from "./host-event-contract.js";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@getuserfeedback/protocol",
-	"version": "0.2.0",
+	"version": "0.2.2",
 	"description": "getuserfeedback widget protocol — host surface and (later) wire protocol",
 	"keywords": [
 		"getuserfeedback",