@stigmer/sdk 3.1.7 → 3.1.8

package/guest-auth.js

@@ -0,0 +1,227 @@
+import { createGrpcWebTransport } from "@connectrpc/connect-web";
+import { createClient } from "@connectrpc/connect";
+import { create } from "@bufbuild/protobuf";
+import { PlatformClientTokenController } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/token_pb";
+import { MintGuestTokenRequestSchema } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/token_pb";
+import { wrapError } from "./gen/errors.js";
+import { rpcMetadataInterceptor, errorStripInterceptor, } from "./internal/interceptors.js";
+/**
+ * How long before expiry a cached guest token is considered stale.
+ * Re-minting inside this window keeps long-lived streams from starting
+ * with a token that expires moments later.
+ */
+const EXPIRY_SKEW_MS = 60_000;
+/** Storage key prefix for the persisted guest id, namespaced per org. */
+const GUEST_ID_STORAGE_PREFIX = "stigmer:guest-id:";
+/**
+ * Guest token-minting helper for shared-agent pages.
+ *
+ * A minimal, purpose-built companion to the main Stigmer client: it
+ * lazily mints short-lived guest JWTs via the public `mintGuestToken`
+ * RPC, caches them in memory until just before expiry, and persists
+ * the server-issued guest id so the same browser resolves to the same
+ * guest across visits.
+ *
+ * Wire {@link getAccessToken} into a `Stigmer` client — the SDK calls
+ * it per request, so refresh is automatic and no token ever needs to
+ * be stored outside memory.
+ *
+ * Failure semantics: when minting fails (e.g. sharing was revoked —
+ * the server answers NOT_FOUND, indistinguishable from "no such
+ * agent"), {@link getAccessToken} rejects with a `StigmerError`, which
+ * fails the triggering request with the real cause instead of sending
+ * it unauthenticated.
+ *
+ * @example
+ * ```typescript
+ * const guestAuth = createGuestAuth({
+ *   baseUrl: "https://api.stigmer.ai",
+ *   org: "acme",
+ *   slug: "support-agent",
+ * });
+ *
+ * const client = new Stigmer({
+ *   baseUrl: "https://api.stigmer.ai",
+ *   getAccessToken: guestAuth.getAccessToken,
+ * });
+ * ```
+ */
+export class GuestAuth {
+    tokenClient;
+    org;
+    slug;
+    storage;
+    storageKey;
+    embedOrigin;
+    linkToken;
+    cached = null;
+    pendingMint = null;
+    /** @internal Use {@link createGuestAuth} instead. */
+    constructor(config) {
+        this.org = config.org;
+        this.slug = config.slug;
+        this.storage = config.storage ?? resolveDefaultStorage();
+        this.storageKey = `${GUEST_ID_STORAGE_PREFIX}${config.org}`;
+        this.embedOrigin = config.embedOrigin ?? "";
+        this.linkToken = config.linkToken ?? "";
+        const transport = createGrpcWebTransport({
+            baseUrl: config.baseUrl,
+            interceptors: [rpcMetadataInterceptor, errorStripInterceptor],
+        });
+        this.tokenClient = createClient(PlatformClientTokenController, transport);
+    }
+    /**
+     * The visitor's persisted guest id, or `null` before the first
+     * successful mint in this browser.
+     */
+    get guestCookieId() {
+        return safeGetItem(this.storage, this.storageKey);
+    }
+    /**
+     * Token provider for `StigmerConfig.getAccessToken`.
+     *
+     * Returns the cached guest JWT while it has more than a minute of
+     * life left; otherwise mints a fresh one. Concurrent callers during
+     * a mint share the same in-flight request (single-flight).
+     *
+     * Defined as an arrow property so it can be passed detached:
+     * `new Stigmer({ ..., getAccessToken: guestAuth.getAccessToken })`.
+     *
+     * @throws {StigmerError} with code `"not-found"` when the agent is
+     *   not shared (or sharing was revoked — the server keeps the two
+     *   indistinguishable by design)
+     * @throws {StigmerError} with code `"permission-denied"` when
+     *   `embedOrigin` is not in the agent's `allowed_origins` — embeds
+     *   should hide the widget on this code rather than surface an error
+     * @throws {StigmerError} with code `"invalid-argument"` when org or
+     *   slug is malformed
+     */
+    getAccessToken = async () => {
+        if (this.cached && this.cached.expiresAt - Date.now() > EXPIRY_SKEW_MS) {
+            return this.cached.accessToken;
+        }
+        // Single-flight: the provider is invoked once per request, so a
+        // burst at page load (registry fetches + profile resolution) must
+        // collapse into one mint — both for latency and because concurrent
+        // first mints would otherwise race to persist different guest ids.
+        this.pendingMint ??= this.mint().finally(() => {
+            this.pendingMint = null;
+        });
+        return this.pendingMint;
+    };
+    async mint() {
+        try {
+            const response = await this.tokenClient.mintGuestToken(create(MintGuestTokenRequestSchema, {
+                org: this.org,
+                slug: this.slug,
+                guestCookieId: safeGetItem(this.storage, this.storageKey) ?? "",
+                embedOrigin: this.embedOrigin,
+                linkToken: this.linkToken,
+            }));
+            safeSetItem(this.storage, this.storageKey, response.guestCookieId);
+            this.cached = {
+                accessToken: response.accessToken,
+                expiresAt: Date.now() + response.expiresIn * 1000,
+            };
+            return response.accessToken;
+        }
+        catch (e) {
+            throw wrapError(e);
+        }
+    }
+}
+/**
+ * `localStorage` when usable, otherwise an in-memory fallback.
+ *
+ * Access is probed inside try/catch because merely touching
+ * `localStorage` can throw (e.g. sandboxed iframes with storage
+ * blocked). With the fallback, the chat still works — the visitor
+ * just gets a fresh guest identity per page load.
+ *
+ * `globalThis` is typed structurally because this package compiles
+ * without DOM libs (it is also consumed from Node, where
+ * `localStorage` does not exist).
+ */
+function resolveDefaultStorage() {
+    try {
+        const { localStorage: storage } = globalThis;
+        if (storage) {
+            const probeKey = "stigmer:storage-probe";
+            storage.setItem(probeKey, "1");
+            storage.removeItem(probeKey);
+            return storage;
+        }
+    }
+    catch {
+        // Fall through to the in-memory storage below.
+    }
+    const memory = new Map();
+    return {
+        getItem: (key) => memory.get(key) ?? null,
+        setItem: (key, value) => {
+            memory.set(key, value);
+        },
+    };
+}
+/**
+ * Storage reads/writes never fail the mint: the guest id is a
+ * convenience (stable identity across visits), not a requirement —
+ * the server issues a fresh id when none is presented.
+ */
+function safeGetItem(storage, key) {
+    try {
+        return storage.getItem(key);
+    }
+    catch {
+        return null;
+    }
+}
+function safeSetItem(storage, key, value) {
+    try {
+        storage.setItem(key, value);
+    }
+    catch {
+        // Persisting the id is best-effort; see safeGetItem.
+    }
+}
+/**
+ * Create a guest token-minting helper for a shared agent's hosted page
+ * or embed.
+ *
+ * This is the browser-side counterpart of `createPlatformClientAuth`:
+ * it involves **no credentials** — the server gates minting on the
+ * agent's `spec.sharing.enabled` and issues a short-lived guest JWT
+ * scoped to the sharing org. Pass {@link GuestAuth.getAccessToken} to
+ * a `Stigmer` client and every request authenticates as this visitor.
+ *
+ * @example
+ * ```typescript
+ * import { Stigmer, createGuestAuth } from "@stigmer/sdk";
+ *
+ * const guestAuth = createGuestAuth({
+ *   baseUrl: "https://api.stigmer.ai",
+ *   org: "acme",
+ *   slug: "support-agent",
+ * });
+ *
+ * const client = new Stigmer({
+ *   baseUrl: "https://api.stigmer.ai",
+ *   getAccessToken: guestAuth.getAccessToken,
+ * });
+ * ```
+ *
+ * @throws {Error} if `baseUrl`, `org`, or `slug` is missing or empty
+ */
+export function createGuestAuth(config) {
+    if (!config.baseUrl) {
+        throw new Error("createGuestAuth: baseUrl is required (e.g., \"https://api.stigmer.ai\")");
+    }
+    if (!config.org) {
+        throw new Error("createGuestAuth: org is required — the organization slug from the share URL");
+    }
+    if (!config.slug) {
+        throw new Error("createGuestAuth: slug is required — the agent slug from the share URL");
+    }
+    return new GuestAuth(config);
+}
+//# sourceMappingURL=guest-auth.js.map

package/guest-auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guest-auth.js","sourceRoot":"","sources":["../src/guest-auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,EAAE,YAAY,EAAe,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,6BAA6B,EAAE,MAAM,2DAA2D,CAAC;AAC1G,OAAO,EAAE,2BAA2B,EAAE,MAAM,2DAA2D,CAAC;AACxG,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EACL,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,4BAA4B,CAAC;AA+EpC;;;;GAIG;AACH,MAAM,cAAc,GAAG,MAAM,CAAC;AAE9B,yEAAyE;AACzE,MAAM,uBAAuB,GAAG,mBAAmB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,OAAO,SAAS;IACH,WAAW,CAA+C;IAC1D,GAAG,CAAS;IACZ,IAAI,CAAS;IACb,OAAO,CAAiB;IACxB,UAAU,CAAS;IACnB,WAAW,CAAS;IACpB,SAAS,CAAS;IAE3B,MAAM,GAAsD,IAAI,CAAC;IACjE,WAAW,GAA2B,IAAI,CAAC;IAEnD,qDAAqD;IACrD,YAAY,MAAuB;QACjC,IAAI,CAAC,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC;QACtB,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;QACxB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,IAAI,qBAAqB,EAAE,CAAC;QACzD,IAAI,CAAC,UAAU,GAAG,GAAG,uBAAuB,GAAG,MAAM,CAAC,GAAG,EAAE,CAAC;QAC5D,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,WAAW,IAAI,EAAE,CAAC;QAC5C,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,IAAI,EAAE,CAAC;QAExC,MAAM,SAAS,GAAG,sBAAsB,CAAC;YACvC,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,YAAY,EAAE,CAAC,sBAAsB,EAAE,qBAAqB,CAAC;SAC9D,CAAC,CAAC;QAEH,IAAI,CAAC,WAAW,GAAG,YAAY,CAAC,6BAA6B,EAAE,SAAS,CAAC,CAAC;IAC5E,CAAC;IAED;;;OAGG;IACH,IAAI,aAAa;QACf,OAAO,WAAW,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IACpD,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACM,cAAc,GAAG,KAAK,IAA4B,EAAE;QAC3D,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,cAAc,EAAE,CAAC;YACvE,OAAO,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC;QACjC,CAAC;QAED,gEAAgE;QAChE,kEAAkE;QAClE,mEAAmE;QACnE,mEAAmE;QACnE,IAAI,CAAC,WAAW,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE;YAC5C,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;QAC1B,CAAC,CAAC,CAAC;QAEH,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC,CAAC;IAEM,KAAK,CAAC,IAAI;QAChB,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,cAAc,CACpD,MAAM,CAAC,2BAA2B,EAAE;gBAClC,GAAG,EAAE,IAAI,CAAC,GAAG;gBACb,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,aAAa,EAAE,WAAW,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE;gBAC/D,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC7B,SAAS,EAAE,IAAI,CAAC,SAAS;aAC1B,CAAC,CACH,CAAC;YAEF,WAAW,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,aAAa,CAAC,CAAC;YACnE,IAAI,CAAC,MAAM,GAAG;gBACZ,WAAW,EAAE,QAAQ,CAAC,WAAW;gBACjC,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,CAAC,SAAS,GAAG,IAAI;aAClD,CAAC;YACF,OAAO,QAAQ,CAAC,WAAW,CAAC;QAC9B,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,SAAS,CAAC,CAAC,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;CACF;AAED;;;;;;;;;;;GAWG;AACH,SAAS,qBAAqB;IAC5B,IAAI,CAAC;QACH,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,GAAG,UAEjC,CAAC;QACF,IAAI,OAAO,EAAE,CAAC;YACZ,MAAM,QAAQ,GAAG,uBAAuB,CAAC;YACzC,OAAO,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;YAC/B,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;YAC7B,OAAO,OAAO,CAAC;QACjB,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,+CAA+C;IACjD,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,OAAO;QACL,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI;QACzC,OAAO,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE;YACtB,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACzB,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,WAAW,CAAC,OAAuB,EAAE,GAAW;IACvD,IAAI,CAAC;QACH,OAAO,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAAC,OAAuB,EAAE,GAAW,EAAE,KAAa;IACtE,IAAI,CAAC;QACH,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,qDAAqD;IACvD,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,eAAe,CAAC,MAAuB;IACrD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CACb,yEAAyE,CAC1E,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CACb,6EAA6E,CAC9E,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CACb,uEAAuE,CACxE,CAAC;IACJ,CAAC;IAED,OAAO,IAAI,SAAS,CAAC,MAAM,CAAC,CAAC;AAC/B,CAAC"}

package/index.d.ts

@@ -1,6 +1,8 @@
 export { Stigmer } from "./stigmer.js";
 export { type RunnerAdapter, type RunnerWorkerHost, createRunnerAdapter, } from "./runner-adapter.js";
 export { type StigmerConfig, type TokenProvider } from "./config.js";
+export { createGuestAuth, GuestAuth, type GuestAuthConfig, type GuestIdStorage, } from "./guest-auth.js";
+export { MAX_ALLOWED_ORIGINS, LINK_TOKEN_PARAM, validateOrigin, chatPath, buildChatUrl, appendLinkToken, buildEmbedLoaderUrl, buildEmbedSnippet, } from "./sharing.js";
 export { StigmerError, type ErrorCode, isNotFound, isUnauthenticated, isPermissionDenied, isRetryable, type ErrorCategory, isConnectError, classifyError, isRetryableError, isTransientStreamError, getUserMessage, type RpcErrorMetadata, annotateRpcError, getRpcMetadata, } from "./errors.js";
 export { type DeploymentMode, isResourceAvailable, } from "./resource-availability.js";
 export { getGrantableRoles, hasGrantableRoles, isRoleGrantable, } from "./authorization-config.js";

package/index.d.ts.map

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

package/index.js

@@ -3,6 +3,10 @@
 export { Stigmer } from "./stigmer.js";
 // Runner adapter
 export { createRunnerAdapter, } from "./runner-adapter.js";
+// Guest auth (shared-agent pages and embeds; browser-safe, credential-free)
+export { createGuestAuth, GuestAuth, } from "./guest-auth.js";
+// Agent sharing (hosted link + embed snippet; framework-free)
+export { MAX_ALLOWED_ORIGINS, LINK_TOKEN_PARAM, validateOrigin, chatPath, buildChatUrl, appendLinkToken, buildEmbedLoaderUrl, buildEmbedSnippet, } from "./sharing.js";
 // Error handling
 export { StigmerError, isNotFound, isUnauthenticated, isPermissionDenied, isRetryable, isConnectError, classifyError, isRetryableError, isTransientStreamError, getUserMessage, annotateRpcError, getRpcMetadata, } from "./errors.js";
 // Resource availability

package/index.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigmer/sdk",
-  "version": "3.1.7",
+  "version": "3.1.8",
   "description": "Stigmer TypeScript SDK — typed API client for all Stigmer platform resources",
   "license": "Apache-2.0",
   "type": "module",
@@ -44,6 +44,6 @@
   "peerDependencies": {
     "@bufbuild/protobuf": "^2.0.0",
     "@connectrpc/connect-node": "^2.0.0",
-    "@stigmer/protos": "3.1.7"
+    "@stigmer/protos": "3.1.8"
   }
 }

package/sharing.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Agent-sharing helpers — the single source of truth for the hosted chat
+ * URL shape, the embed snippet, and client-side `allowed_origins`
+ * validation. Framework-free by design: consumed by the web console and
+ * desktop app (via `@stigmer/react`), the `stigmer` CLI, and any platform
+ * builder that wants to construct share links or embed snippets itself.
+ *
+ * The canonical URL shape is `<app-origin>/chat/<org>/<slug>` (a T01
+ * design decision), and `embed.js` is served from the root of that same
+ * app origin (T04). Callers supply the origin — resolving it is a host
+ * concern (the console knows its `appUrl`, the CLI resolves it from the
+ * backend type) — while the path and snippet shapes live here so every
+ * surface emits byte-identical output.
+ */
+/** Maximum number of allowed origins (proto: `repeated.max_items = 32`). */
+export declare const MAX_ALLOWED_ORIGINS = 32;
+/**
+ * Validate a single `allowed_origins` entry.
+ *
+ * Returns `null` when valid, or a user-facing message explaining what
+ * to fix (DD-006: errors state what happened and what to do).
+ */
+export declare function validateOrigin(value: string): string | null;
+/**
+ * Query parameter carrying the share-link token on a locked link:
+ * `/chat/<org>/<slug>?k=<token>`. Short by design — the token rides every
+ * copied link, and `k` (for "key") is the platform's one-character
+ * convention, mirrored by the hosted page and the embed widget.
+ */
+export declare const LINK_TOKEN_PARAM = "k";
+/**
+ * The hosted chat page path for a shared agent: `/chat/<org>/<slug>`,
+ * plus `?k=<token>` when the share link is locked with a rotatable token
+ * (`agent.status.shareLinkToken`).
+ *
+ * Useful on its own when the caller renders relative to the current
+ * origin (e.g. a host that never configured an absolute app URL).
+ */
+export declare function chatPath(org: string, slug: string, linkToken?: string): string;
+/**
+ * The absolute hosted chat URL for a shared agent:
+ * `<appOrigin>/chat/<org>/<slug>[?k=<token>]`.
+ *
+ * A trailing slash on `appOrigin` is tolerated so callers can pass
+ * user-configured values verbatim. An empty `appOrigin` degrades to the
+ * relative {@link chatPath} — the same graceful fallback a host without a
+ * configured public origin gets in the share dialog.
+ */
+export declare function buildChatUrl(appOrigin: string, org: string, slug: string, linkToken?: string): string;
+/**
+ * Append the share-link token to an already-built chat URL.
+ *
+ * For hosts that construct the base URL through their own callback (the
+ * share dialog's `buildShareUrl` prop) rather than {@link buildChatUrl}.
+ * A `null`/empty token returns the URL unchanged, so callers can pass
+ * `agent.status?.shareLinkToken` straight through. Emits the identical
+ * `?k=` shape as {@link chatPath} — one URL grammar across every surface.
+ */
+export declare function appendLinkToken(url: string, linkToken: string | null | undefined): string;
+/**
+ * The embed loader URL: `embed.js` lives at the root of the app origin
+ * (the loader derives the chat-page origin from its own script URL, so
+ * the two must share an origin). An empty `appOrigin` degrades to the
+ * relative `/embed.js`.
+ */
+export declare function buildEmbedLoaderUrl(appOrigin: string): string;
+/**
+ * The two-line embed snippet an owner pastes into any website: the
+ * loader script plus the `<stigmer-agent>` element where the widget
+ * renders. A locked share link adds the `token` attribute, which the
+ * widget forwards as `?k=` on its iframe URL. Every surface (share
+ * dialog, CLI, docs) emits exactly this.
+ */
+export declare function buildEmbedSnippet(appOrigin: string, org: string, slug: string, linkToken?: string): string;
+//# sourceMappingURL=sharing.d.ts.map

package/sharing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharing.d.ts","sourceRoot":"","sources":["../src/sharing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,4EAA4E;AAC5E,eAAO,MAAM,mBAAmB,KAAK,CAAC;AActC;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAO3D;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAK9E;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,CAER;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAIzF;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,CAMR"}

package/sharing.js

@@ -0,0 +1,116 @@
+/**
+ * Agent-sharing helpers — the single source of truth for the hosted chat
+ * URL shape, the embed snippet, and client-side `allowed_origins`
+ * validation. Framework-free by design: consumed by the web console and
+ * desktop app (via `@stigmer/react`), the `stigmer` CLI, and any platform
+ * builder that wants to construct share links or embed snippets itself.
+ *
+ * The canonical URL shape is `<app-origin>/chat/<org>/<slug>` (a T01
+ * design decision), and `embed.js` is served from the root of that same
+ * app origin (T04). Callers supply the origin — resolving it is a host
+ * concern (the console knows its `appUrl`, the CLI resolves it from the
+ * backend type) — while the path and snippet shapes live here so every
+ * surface emits byte-identical output.
+ */
+/** Maximum number of allowed origins (proto: `repeated.max_items = 32`). */
+export const MAX_ALLOWED_ORIGINS = 32;
+/**
+ * Exact web origin: scheme://host[:port] — no path, query, fragment, or
+ * trailing slash. Mirrors the CEL expression `allowed_origins.format` on
+ * `AgentSharing` (`apis/ai/stigmer/agentic/agent/v1/spec.proto`).
+ *
+ * The proto is the source of truth — if the CEL expression changes, this
+ * pattern must change with it. Mirroring it client-side gives immediate
+ * feedback instead of a round-trip rejection.
+ */
+const ORIGIN_PATTERN = /^https?:\/\/[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?(\.[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?)*(:[0-9]{1,5})?$/;
+/**
+ * Validate a single `allowed_origins` entry.
+ *
+ * Returns `null` when valid, or a user-facing message explaining what
+ * to fix (DD-006: errors state what happened and what to do).
+ */
+export function validateOrigin(value) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        return "Enter an origin, like https://example.com";
+    if (!ORIGIN_PATTERN.test(trimmed)) {
+        return "Must be an exact web origin like https://example.com — no path, query, or trailing slash";
+    }
+    return null;
+}
+/**
+ * Query parameter carrying the share-link token on a locked link:
+ * `/chat/<org>/<slug>?k=<token>`. Short by design — the token rides every
+ * copied link, and `k` (for "key") is the platform's one-character
+ * convention, mirrored by the hosted page and the embed widget.
+ */
+export const LINK_TOKEN_PARAM = "k";
+/**
+ * The hosted chat page path for a shared agent: `/chat/<org>/<slug>`,
+ * plus `?k=<token>` when the share link is locked with a rotatable token
+ * (`agent.status.shareLinkToken`).
+ *
+ * Useful on its own when the caller renders relative to the current
+ * origin (e.g. a host that never configured an absolute app URL).
+ */
+export function chatPath(org, slug, linkToken) {
+    const path = `/chat/${org}/${slug}`;
+    return linkToken
+        ? `${path}?${LINK_TOKEN_PARAM}=${encodeURIComponent(linkToken)}`
+        : path;
+}
+/**
+ * The absolute hosted chat URL for a shared agent:
+ * `<appOrigin>/chat/<org>/<slug>[?k=<token>]`.
+ *
+ * A trailing slash on `appOrigin` is tolerated so callers can pass
+ * user-configured values verbatim. An empty `appOrigin` degrades to the
+ * relative {@link chatPath} — the same graceful fallback a host without a
+ * configured public origin gets in the share dialog.
+ */
+export function buildChatUrl(appOrigin, org, slug, linkToken) {
+    return stripTrailingSlash(appOrigin) + chatPath(org, slug, linkToken);
+}
+/**
+ * Append the share-link token to an already-built chat URL.
+ *
+ * For hosts that construct the base URL through their own callback (the
+ * share dialog's `buildShareUrl` prop) rather than {@link buildChatUrl}.
+ * A `null`/empty token returns the URL unchanged, so callers can pass
+ * `agent.status?.shareLinkToken` straight through. Emits the identical
+ * `?k=` shape as {@link chatPath} — one URL grammar across every surface.
+ */
+export function appendLinkToken(url, linkToken) {
+    if (!linkToken)
+        return url;
+    const separator = url.includes("?") ? "&" : "?";
+    return `${url}${separator}${LINK_TOKEN_PARAM}=${encodeURIComponent(linkToken)}`;
+}
+/**
+ * The embed loader URL: `embed.js` lives at the root of the app origin
+ * (the loader derives the chat-page origin from its own script URL, so
+ * the two must share an origin). An empty `appOrigin` degrades to the
+ * relative `/embed.js`.
+ */
+export function buildEmbedLoaderUrl(appOrigin) {
+    return `${stripTrailingSlash(appOrigin)}/embed.js`;
+}
+/**
+ * The two-line embed snippet an owner pastes into any website: the
+ * loader script plus the `<stigmer-agent>` element where the widget
+ * renders. A locked share link adds the `token` attribute, which the
+ * widget forwards as `?k=` on its iframe URL. Every surface (share
+ * dialog, CLI, docs) emits exactly this.
+ */
+export function buildEmbedSnippet(appOrigin, org, slug, linkToken) {
+    const tokenAttribute = linkToken ? ` token="${linkToken}"` : "";
+    return [
+        `<script src="${buildEmbedLoaderUrl(appOrigin)}" async></script>`,
+        `<stigmer-agent org="${org}" agent="${slug}"${tokenAttribute}></stigmer-agent>`,
+    ].join("\n");
+}
+function stripTrailingSlash(origin) {
+    return origin.endsWith("/") ? origin.slice(0, -1) : origin;
+}
+//# sourceMappingURL=sharing.js.map

package/sharing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharing.js","sourceRoot":"","sources":["../src/sharing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,4EAA4E;AAC5E,MAAM,CAAC,MAAM,mBAAmB,GAAG,EAAE,CAAC;AAEtC;;;;;;;;GAQG;AACH,MAAM,cAAc,GAClB,8GAA8G,CAAC;AAEjH;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,CAAC,OAAO;QAAE,OAAO,2CAA2C,CAAC;IACjE,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAClC,OAAO,0FAA0F,CAAC;IACpG,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAEpC;;;;;;;GAOG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAW,EAAE,IAAY,EAAE,SAAkB;IACpE,MAAM,IAAI,GAAG,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC;IACpC,OAAO,SAAS;QACd,CAAC,CAAC,GAAG,IAAI,IAAI,gBAAgB,IAAI,kBAAkB,CAAC,SAAS,CAAC,EAAE;QAChE,CAAC,CAAC,IAAI,CAAC;AACX,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAC1B,SAAiB,EACjB,GAAW,EACX,IAAY,EACZ,SAAkB;IAElB,OAAO,kBAAkB,CAAC,SAAS,CAAC,GAAG,QAAQ,CAAC,GAAG,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;AACxE,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW,EAAE,SAAoC;IAC/E,IAAI,CAAC,SAAS;QAAE,OAAO,GAAG,CAAC;IAC3B,MAAM,SAAS,GAAG,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;IAChD,OAAO,GAAG,GAAG,GAAG,SAAS,GAAG,gBAAgB,IAAI,kBAAkB,CAAC,SAAS,CAAC,EAAE,CAAC;AAClF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,SAAiB;IACnD,OAAO,GAAG,kBAAkB,CAAC,SAAS,CAAC,WAAW,CAAC;AACrD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAC/B,SAAiB,EACjB,GAAW,EACX,IAAY,EACZ,SAAkB;IAElB,MAAM,cAAc,GAAG,SAAS,CAAC,CAAC,CAAC,WAAW,SAAS,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAChE,OAAO;QACL,gBAAgB,mBAAmB,CAAC,SAAS,CAAC,mBAAmB;QACjE,uBAAuB,GAAG,YAAY,IAAI,IAAI,cAAc,mBAAmB;KAChF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,SAAS,kBAAkB,CAAC,MAAc;IACxC,OAAO,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;AAC7D,CAAC"}

package/src/__tests__/errors.test.ts

@@ -11,6 +11,62 @@ import {
   type ErrorCategory,
 } from "../errors";
 
+/**
+ * Guest launch-gate refusal contract (shared-agent abuse controls).
+ *
+ * The cloud backend resolves owner-customizable refusal copy server-side and
+ * carries it in the gRPC status description; the SDK must surface that copy
+ * VERBATIM through getUserMessage — no client-side mapping exists by design.
+ * These tests pin the two halves of that contract:
+ *
+ * 1. RESOURCE_EXHAUSTED / FAILED_PRECONDITION descriptions pass through
+ *    getUserMessage untouched.
+ * 2. The platform-default copy (mirrors GuestLimitReason in the cloud
+ *    backend) never collides with the sanitizer's rewrite patterns.
+ */
+describe("guest launch-gate refusal copy passthrough", () => {
+  // Mirrors GuestLimitReason default copy in the cloud stigmer-service.
+  // If those strings change, update here — this guardrail exists to catch a
+  // default that a sanitizer pattern would silently rewrite.
+  const platformDefaultCopy = [
+    "You\u2019re sending messages too quickly. Please wait a moment before sending another.",
+    "This agent is currently unavailable. Please check back later.",
+    "This conversation has ended. Please start a new conversation to continue.",
+    "This agent can\u2019t be embedded on this site.",
+  ];
+
+  const refusalCodes: Array<[string, Code]> = [
+    ["ResourceExhausted (rate limit)", Code.ResourceExhausted],
+    ["FailedPrecondition (fail-closed / bounds)", Code.FailedPrecondition],
+    ["PermissionDenied (embed origin)", Code.PermissionDenied],
+  ];
+
+  it.each(refusalCodes)(
+    "surfaces a %s status description verbatim",
+    (_label, code) => {
+      for (const copy of platformDefaultCopy) {
+        expect(getUserMessage(new ConnectError(copy, code))).toBe(copy);
+      }
+    },
+  );
+
+  it("surfaces owner-customized copy verbatim", () => {
+    const ownerCopy = "Whoa, slow down! Try again in a minute or two.";
+    expect(
+      getUserMessage(new ConnectError(ownerCopy, Code.ResourceExhausted)),
+    ).toBe(ownerCopy);
+  });
+
+  it("classifies rate-limit refusals as retryable and bounds refusals as not", () => {
+    expect(
+      isRetryableError(new ConnectError("copy", Code.ResourceExhausted)),
+    ).toBe(true);
+    expect(
+      isRetryableError(new ConnectError("copy", Code.FailedPrecondition)),
+    ).toBe(false);
+  });
+});
+
 describe("classifyError", () => {
   const stigmerMappings: Array<[string, ErrorCategory]> = [
     ["unauthenticated", "auth"],