dewee-webchat 0.3.0 → 0.4.1-beta.2

package/dist/handler-DunrbnSD.d.ts

@@ -0,0 +1,307 @@
+import { A as AgentInfo } from './protocol-CLbGE9Ns.js';
+
+interface VisitorClaims {
+    /** Visitor id (random, 22 chars; derived from the principal for a signed-in user). */
+    v: string;
+    /** Expiry, epoch ms. */
+    exp: number;
+    /**
+     * Signed-in users only: the Dewee identity session token. In the signed token it is encrypted
+     * (AES-256-GCM), so the browser only ever holds an opaque value; these claims carry it decrypted.
+     */
+    ids?: string;
+    /** Signed-in users only: the agent the identity session is bound to. */
+    ida?: string;
+    /**
+     * Signed-in users only: a keyed digest of the host's subject (see {@link subjectDigest}). Sealed
+     * together with `ids`, so the browser never sees the subject or its digest.
+     */
+    sub?: string;
+    /**
+     * CCP transport only: the CCP edge session token (`dws1.…`). In the signed token it is encrypted
+     * (AES-256-GCM, its own key label), so the browser never holds the raw value.
+     */
+    es?: string;
+    /** CCP transport only: expiry of `es` as CCP reported it, epoch ms on this server's clock. */
+    ese?: number;
+}
+/** Signs a visitor bearer token. */
+declare function signVisitorToken(secret: string, claims: VisitorClaims): Promise<string>;
+/** Verifies a visitor bearer token. A reuse hint (or any token with a purpose label) is refused. */
+declare function verifyVisitorToken(secret: string, token: string): Promise<VisitorClaims | null>;
+/**
+ * Rate-limit buckets: `session` (new visitor sessions, per IP), `chat` (messages, per visitor and IP),
+ * and with signed-in users `preauth` (calls to the host's `authenticate`, per IP), `verified`
+ * (signed-in `/session` calls, per user) and `link` (link starts, per user).
+ */
+type RateLimitBucket = "session" | "chat" | "preauth" | "verified" | "link";
+/** Returns true when the key may proceed. Implementations may be async (KV, DO, Redis…). */
+type RateLimiter = (key: string, bucket: RateLimitBucket) => boolean | Promise<boolean>;
+/**
+ * `[max, windowMs]` per bucket. `preauth` defaults to 120 per minute; `verified` and `link` fall back to
+ * the `session` limit when not set.
+ */
+interface MemoryRateLimits {
+    chat: [number, number];
+    session: [number, number];
+    preauth?: [number, number];
+    verified?: [number, number];
+    link?: [number, number];
+}
+/**
+ * Fixed-window in-memory limiter. Good enough for a single Node process; on serverless
+ * runtimes each isolate keeps its own counters, so pass a shared limiter for hard limits.
+ */
+declare function memoryRateLimiter(limits: MemoryRateLimits): RateLimiter;
+
+/** Validated CCP endpoint options (see {@link parseCcpOptions}). */
+interface CcpOptions {
+    /**
+     * The full ingress base the CCP "Website chat" page prints as `DEWEE_CCP_CHAT_URL`, e.g.
+     * `https://app.dewee.sh/api/public/webchat/v1/wci_…`. Must be https, except plain http to a
+     * loopback host (`localhost`, `127.0.0.1`, `[::1]`) for local development.
+     */
+    chatUrl: string;
+    /** `DEWEE_WEBCHAT_INTEGRATION_ID` (`wci_…`); must equal the id at the end of `chatUrl`. */
+    integrationId: string;
+    /** `DEWEE_WEBCHAT_INTEGRATION_SECRET` (`dwc_…`). Server-only; never sent to a browser or another origin. */
+    integrationSecret: string;
+    /** Custom fetch (tests, instrumented hosts). Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+}
+/**
+ * A refusal or failure of the ingress. `code` is the contract's public code (`integration_unauthorized`,
+ * `rate_limited`, an identity code…), or a local one: `ccp_unreachable` (network), `ccp_redirect`
+ * (a redirect was refused), `ccp_bad_response` (not the contract's shape). `message` is CCP's text and
+ * is for logs only; it is never sent to a browser.
+ */
+declare class CcpError extends Error {
+    status: number;
+    code: string;
+    retryAfterSeconds?: number | undefined;
+    remediation?: {
+        action: string;
+        audience: string;
+    } | undefined;
+    constructor(status: number, code: string, message: string, retryAfterSeconds?: number | undefined, remediation?: {
+        action: string;
+        audience: string;
+    } | undefined);
+}
+
+/**
+ * A signed-in user of the host app, as `identity.authenticate` reports it. Scopes are not part of
+ * the session exchange: report scope changes with `lifecycle({ event: "scopes_changed" })` from
+ * `@dewee/identity`.
+ */
+interface AuthenticatedUser {
+    /** Your stable, opaque user id. Never an email address (an id containing "@" is refused). */
+    subject: string;
+}
+/** A private JWK whose public half is published in the application's `jwks_url`. */
+interface IdentityPrivateJwk {
+    kty: string;
+    kid: string;
+    d: string;
+    alg?: string;
+    [key: string]: unknown;
+}
+/** Partner assertion signer, the shape `@dewee/identity` takes. */
+type IdentitySigner = {
+    applicationId: string;
+    issuer: string;
+    secret: string;
+} | {
+    applicationId: string;
+    issuer: string;
+    privateKeyJwk: IdentityPrivateJwk;
+    algorithm?: "RS256" | "ES256" | "EdDSA";
+};
+/**
+ * The two `@dewee/identity` calls the handler uses. Pass `deweeIdentitySdk` from
+ * `dewee-webchat/server/identity`; it is a separate entry so that only hosts that sign users in
+ * need the SDK installed and bundled.
+ */
+interface DeweeIdentitySdk {
+    exchangeSession(opts: {
+        gatewayUrl: string;
+        allowInsecureHttp?: boolean;
+        signer: IdentitySigner;
+        subject: string;
+        agent: string;
+        ttlSeconds?: number;
+    }): Promise<{
+        sessionToken: string;
+        principalId: string;
+        expiresAt: Date;
+    }>;
+    startLink(opts: {
+        gatewayUrl: string;
+        allowInsecureHttp?: boolean;
+        sessionToken: string;
+        idempotencyKey?: string;
+    }): Promise<{
+        proofCode: string;
+        expiresAt: Date;
+        deepLinks: Array<{
+            channelType: string;
+            channelInstanceId: string;
+            name: string;
+            displayName?: string;
+        }>;
+    }>;
+    /**
+     * Signs a partner assertion. Used by `transport: "ccp"`, where the website signs and CCP exchanges.
+     * `deweeIdentitySdk` provides it.
+     */
+    createAssertion?(opts: {
+        purpose: "session";
+        subject: string;
+        applicationId: string;
+        issuer: string;
+        secret?: string;
+        privateKeyJwk?: IdentityPrivateJwk;
+        algorithm?: "RS256" | "ES256" | "EdDSA";
+    }): Promise<string>;
+}
+/**
+ * Verified signed-in users through a Dewee identity session exchange. The host passes one
+ * server-side callback; the handler exchanges the user for a short-lived Dewee identity session bound
+ * to one agent, and the gateway derives the user from it.
+ */
+interface DeweeIdentityOptions {
+    /** `deweeIdentitySdk` from `dewee-webchat/server/identity`. */
+    sdk: DeweeIdentitySdk;
+    /**
+     * Reads your own login (cookie, header…). Return null for a visitor who is not signed in. Throwing
+     * means the login could not be read: the visitor gets `503 SOURCE_UNAVAILABLE`, never an anonymous
+     * session. Keep it cheap or cached: it runs on every `/session` (every page load) and, with
+     * `rebindEachRequest`, on every `/chat`, `/history` and `/link`, behind a generous per-IP cap only.
+     */
+    authenticate(req: Request): Promise<AuthenticatedUser | null>;
+    /** Dewee application id (`dewee identity setup` prints it). */
+    appId: string;
+    /** The issuer configured on the application, exactly. */
+    issuer: string;
+    /** Optional check: must equal `dewee:<appId>`, the audience Dewee issued the application. */
+    audience?: string;
+    /** Assertion secret of an `hmac` application. Exactly one of this or `privateKeyJwk`. */
+    assertionSecret?: string;
+    /** Private signing key of a `jwks` application (RS256, ES256 or EdDSA, with `kid`). */
+    privateKeyJwk?: IdentityPrivateJwk;
+    /** Algorithm of `privateKeyJwk`; defaults to its `alg`. */
+    algorithm?: "RS256" | "ES256" | "EdDSA";
+    /**
+     * The agent identity sessions are bound to. Default: `defaultAgent`, else the first of `agents`
+     * (with `transport: "ccp"`: the integration's default agent).
+     */
+    agent?: string;
+    /**
+     * Refuse visitors who are not signed in (no anonymous fallback). Default false: a visitor for whom
+     * `authenticate` returns null chats anonymously exactly as without this option.
+     */
+    required?: boolean;
+    /**
+     * Check the signed-in user again on every `/chat`, `/history` and `/link`: `authenticate(req)` must
+     * return the same subject the session was issued for, else the request is `401 IDENTITY_REQUIRED`
+     * (the widget then asks `/session` again); if it throws, `503 SOURCE_UNAVAILABLE`. Recommended when
+     * your login is a cookie: a widget token replayed under another user's cookie is then useless.
+     * Default false.
+     */
+    rebindEachRequest?: boolean;
+    /** Identity session lifetime, 60 to 43200 seconds. Default: the gateway default (3600). */
+    sessionTtlSeconds?: number;
+    /** Allow plain http to a gateway that is not loopback (private networks only). */
+    allowInsecureHttp?: boolean;
+}
+/** How this backend reaches Dewee. */
+type DeweeTransport = "ccp" | "legacy-gateway";
+interface DeweeHandlerOptions {
+    /**
+     * `"ccp"`: the CCP-managed public webchat ingress, configured with `ccp` (recommended).
+     * `"legacy-gateway"`: a direct Gateway WebSocket with `gatewayUrl` + `token` (deprecated).
+     * Default: `"ccp"` when `ccp` is set, else `"legacy-gateway"`. Setting both `ccp` and the gateway
+     * options is a startup error, so a credential is never sent to an origin it was not meant for.
+     */
+    transport?: DeweeTransport;
+    /**
+     * The CCP integration (`DEWEE_CCP_CHAT_URL`, `DEWEE_WEBCHAT_INTEGRATION_ID`,
+     * `DEWEE_WEBCHAT_INTEGRATION_SECRET` from the CCP "Website chat" page). The integration decides the
+     * agents, sign-in mode and whether reasoning and tool activity are shown, so `agents`,
+     * `defaultAgent`, `tenantId` and `allowClientCredentials` do not apply to it.
+     */
+    ccp?: CcpOptions;
+    /** Legacy gateway transport: Gateway runtime origin. Required unless every request brings its own credentials. */
+    gatewayUrl?: string;
+    /** Legacy gateway transport: Gateway token or operator API key (server-side only). */
+    token?: string;
+    /** Legacy gateway transport. */
+    tenantId?: string;
+    /** HMAC secret for visitor tokens (>= 32 random chars). */
+    secret?: string;
+    /** Legacy gateway transport: agents visitors may talk to. The first is the default. `"*"` = every active agent. */
+    agents?: Array<string | AgentInfo> | "*";
+    defaultAgent?: string;
+    /** Let the widget switch between allowed agents. Default: true when more than one agent. */
+    allowAgentSwitch?: boolean;
+    /** Cross-origin sites allowed to call this backend. Same-origin is always allowed. */
+    allowedOrigins?: string[] | "*";
+    /**
+     * Legacy gateway transport: let visitors bring their own gateway URL + token (sent per request, never stored).
+     * Meant for playgrounds. `allowedHosts` restricts which gateways may be targeted.
+     */
+    allowClientCredentials?: boolean | {
+        allowedHosts?: string[];
+    };
+    /** Cloudflare Turnstile. When set, issuing a visitor session requires a valid challenge. */
+    turnstile?: {
+        siteKey: string;
+        secretKey: string;
+    };
+    /**
+     * Custom limiter, or false to disable. Default (in memory): 20 messages/min per visitor and IP,
+     * 10 new sessions/10 min per IP and, with `identity`, 120 `authenticate` calls/min per IP,
+     * 30 signed-in sessions/10 min per user and 5 link starts/10 min per user. Defense in depth: the
+     * Dewee gateway owns the shared message limit and refuses with `RATE_LIMITED` (forwarded typed).
+     */
+    rateLimit?: RateLimiter | false;
+    maxMessageLength?: number;
+    /** Prefix for the per-visitor gateway user id. */
+    userIdPrefix?: string;
+    sessionTtlMs?: number;
+    /** Max duration of one agent run. */
+    timeoutMs?: number;
+    /** Observe traffic (logging/analytics). Errors thrown here are ignored. */
+    onChat?: (info: {
+        visitorId: string;
+        agent: string;
+        message: string;
+        reply?: string;
+        error?: string;
+    }) => void;
+    /**
+     * Verified signed-in users through Dewee (needs the `@dewee/identity` package). Absent: every
+     * visitor is anonymous, exactly as before. Cannot be combined with `allowClientCredentials`.
+     */
+    identity?: DeweeIdentityOptions;
+}
+/** The backend: one function for every route, plus the logout hook of signed-in users. */
+interface DeweeHandler {
+    (request: Request): Promise<Response>;
+    /**
+     * Call from your logout: ends the Dewee identity sessions this backend holds for `subject` (every
+     * bound agent) and forgets them, so the next `/session` exchanges again. With `transport: "ccp"` they
+     * are revoked at CCP (`identity/revoke`). Pass the logout request so CCP sees the visitor's origin
+     * and IP (without it, the origin of the request the session was issued for is used). `token` is the
+     * widget's reuse hint (`reuseHint()`) or visitor token, sent along by your logout page: its identity
+     * session is revoked too when it belongs to `subject`, so a host that keeps no memory between
+     * requests still ends the exact session. Best effort: never throws. Other sessions held only by
+     * other instances end at their expiry (`sessionTtlSeconds`). Without `identity` it does nothing.
+     */
+    revoke(subject: string, request?: Request, token?: string): Promise<void>;
+}
+declare function createDeweeHandler(options: DeweeHandlerOptions): DeweeHandler;
+/** Reads options from environment variables (process.env, Workers env, import.meta.env…). */
+declare function optionsFromEnv(env: Record<string, string | undefined>, overrides?: Partial<DeweeHandlerOptions>): DeweeHandlerOptions;
+
+export { type AuthenticatedUser as A, CcpError as C, type DeweeIdentitySdk as D, type IdentityPrivateJwk as I, type MemoryRateLimits as M, type RateLimitBucket as R, type VisitorClaims as V, type CcpOptions as a, type DeweeHandler as b, type DeweeHandlerOptions as c, type DeweeIdentityOptions as d, type DeweeTransport as e, type IdentitySigner as f, type RateLimiter as g, createDeweeHandler as h, memoryRateLimiter as m, optionsFromEnv as o, signVisitorToken as s, verifyVisitorToken as v };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { b as ActionSensitivity, P as PublicConfig, S as SessionResponse, H as HistoryMessage, c as ChatRequestBody, C as ChatStreamEvent } from './protocol-B72Ry-fY.js';
-export { a as ActionManifestEntry, A as AgentInfo, T as ToolCallView } from './protocol-B72Ry-fY.js';
+import { d as ActionSensitivity, P as PublicConfig, S as SessionResponse, L as LinkResponse, H as HistoryMessage, e as ChatRequestBody, C as ChatStreamEvent, R as Remediation } from './protocol-CLbGE9Ns.js';
+export { a as ActionManifestEntry, b as AdmissionErrorCode, A as AgentInfo, I as IdentityErrorCode, f as LinkTarget, T as ToolCallView } from './protocol-CLbGE9Ns.js';
 
 type ActionResultStatus = "ok" | "denied" | "error";
 interface ActionResult {
@@ -39,9 +39,19 @@ type ActionConfirmHook = (action: PageActionInfo & {
 }, args: Record<string, unknown>) => boolean | Promise<boolean>;
 type ActionCallStatus = "pending" | "awaiting-confirmation" | "running" | "done" | "denied" | "error";
 
+/** The only launch data allowed to reach the browser. Never an identity session. */
+interface JobAccessLaunch {
+    bootstrap_url: string;
+    launch_token: string;
+    expires_at: string;
+}
+
 /** Extra request headers: a static map, or a function evaluated before every request. */
 type RequestHeadersOption = Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
-/** Headers the widget owns; `headers` cannot override them (compared case-insensitively). */
+/**
+ * Headers the widget owns; `headers` cannot override them (compared case-insensitively). The
+ * session bearer token, signed-in or anonymous, travels in `authorization`.
+ */
 declare const RESERVED_HEADERS: readonly string[];
 interface ApiClientOptions {
     /** Backend base URL, e.g. "/api/dewee" or "https://example.com/api/dewee". */
@@ -59,7 +69,10 @@ interface ApiClientOptions {
 declare class ApiError extends Error {
     status: number;
     code?: string | undefined;
-    constructor(message: string, status: number, code?: string | undefined);
+    remediation?: Remediation | undefined;
+    retryAfterMs?: number | undefined;
+    /** `retryAfterMs`: how long to wait before sending again (`RATE_LIMITED`). */
+    constructor(message: string, status: number, code?: string | undefined, remediation?: Remediation | undefined, retryAfterMs?: number | undefined);
 }
 declare class ApiClient {
     private o;
@@ -69,17 +82,56 @@ declare class ApiClient {
     constructor(o: ApiClientOptions);
     private url;
     private get storageKey();
-    /** Session reuse: refresh once less than 10% of the token lifetime (at most 24 h, at least 30 s) remains. */
-    private fresh;
+    private get reuseKey();
+    /**
+     * The tab's reuse hint for signed-in sessions, or null (none sent by this backend). A logout page can
+     * send it to the backend's logout route, whose `handler.revoke(subject, request, hint)` then ends
+     * exactly that session.
+     */
+    reuseHint(): string | null;
     private request;
     private headers;
     private parse;
     getConfig(force?: boolean): Promise<PublicConfig>;
+    /** When each signed-in session should be refreshed, on this browser's clock. */
+    private refreshAt;
+    /**
+     * Session reuse. A signed-in session follows its schedule (see `scheduleRefresh`). An anonymous
+     * token is refreshed once less than 10% of its lifetime (at most 24 h, at least 30 s) remains; a
+     * stored token from before `obtainedAt` existed uses the 24 h margin. When the backend reports the
+     * lifetime (`expiresIn`), it is counted from receipt, so a skewed browser clock does not matter.
+     */
+    private fresh;
+    /**
+     * A signed-in session is refreshed `min(60s, lifetime/2)` before it ends, with the lifetime the
+     * backend reports (`expiresIn`) counted from receipt, so a short lifetime is not refreshed on every
+     * request and a skewed browser clock does not matter.
+     */
+    private scheduleRefresh;
+    /** The stored anonymous visitor session, if any. Signed-in sessions are never stored. */
+    private stored;
     /** Returns a valid visitor session, creating or refreshing it when needed. */
     ensureSession(): Promise<SessionResponse>;
+    private loadSession;
     private createSession;
+    /** Drops the session; the next request creates a new one. A stored anonymous visitor is kept for a signed-in session. */
     forgetSession(): void;
+    /**
+     * Asks the backend for a new session now (after a sign-in or sign-out on the host page). The
+     * stored anonymous visitor id is kept, so an anonymous visitor's history survives.
+     */
+    renewSession(): Promise<SessionResponse>;
+    /** Requests a single-use launch ticket. Does not refresh or swap the signed-in session after refusal. */
+    jobAccess(signal: AbortSignal): Promise<JobAccessLaunch>;
+    /** Starts a web-first link of a chat account for the signed-in user (identity backends only). */
+    link(): Promise<LinkResponse>;
     history(agent: string, conversationId: string): Promise<HistoryMessage[]>;
+    /**
+     * Sends a request with the current session. A signed-in session the backend refuses (expired,
+     * revoked, or another user signed in) is dropped and renewed once, as chat() does. An anonymous
+     * visitor's 401 is final, and its stored visitor is kept.
+     */
+    private signedInRequest;
     /** Sends a message and calls `onEvent` for every streamed event. Resolves when the run ends. */
     chat(input: ChatRequestBody & {
         agent: string;
@@ -177,6 +229,7 @@ declare class DeweeChatElement extends ElementBase {
     private conversationId;
     private messages;
     private running;
+    private jobAccessLaunch;
     private activated;
     private strings;
     private mql;
@@ -184,6 +237,8 @@ declare class DeweeChatElement extends ElementBase {
     private propActionNames;
     private hooks;
     private acks;
+    /** Pause after a RATE_LIMITED refusal; send stays disabled until it ends. */
+    private cooldown;
     private els;
     constructor();
     /** Current effective configuration (attributes merged with `configure()` overrides). */
@@ -222,6 +277,25 @@ declare class DeweeChatElement extends ElementBase {
     private showNotice;
     /** Stops the running reply. */
     stop(): void;
+    /**
+     * Call after the visitor signs in or out on the host page: the next message uses a session for
+     * the current user, and the conversation is reloaded for them.
+     */
+    renewSession(): Promise<void>;
+    /**
+     * The tab's signed-in reuse hint, or null. Not a credential: send it to your logout route for
+     * `handler.revoke(subject, request, hint)`, which then ends exactly that session.
+     */
+    reuseHint(): string | null;
+    /**
+     * Web-first linking for a signed-in user: shows a proof code and the chat apps to send it to
+     * ("Continue on Telegram"). The user never types an account id. Resolves null on failure (the
+     * error is shown in the chat and emitted as `dewee:error`).
+     */
+    startLink(): Promise<LinkResponse | null>;
+    /** Opens the hosted permission review; the verified session stays on the backend. */
+    openJobAccess(): Promise<void>;
+    private renderLink;
     /** Starts a fresh conversation with the current agent. */
     newConversation(): void;
     connectedCallback(): void;
@@ -236,6 +310,10 @@ declare class DeweeChatElement extends ElementBase {
     private renderShell;
     private autosize;
     private updateSendButton;
+    /** Disables sending for `ms` and announces it; the visible countdown is not read out every second. */
+    private startCooldown;
+    private renderCooldown;
+    private endCooldown;
     private setRunning;
     private renderSubtitle;
     /** Loads backend config and the persisted conversation once. */
@@ -257,6 +335,12 @@ declare class DeweeChatElement extends ElementBase {
     private nearBottom;
     private scrollToBottom;
     private showError;
+    /**
+     * An admission refusal: the visitor's message never reached the agent, so it goes back to an empty
+     * composer to edit or resend. `POLICY_DENIED` is shown next to that message instead of as an empty
+     * reply. Returns true when the error was shown here.
+     */
+    private refuseInline;
     /** Renders a Turnstile challenge in light DOM (slotted) and resolves with its token. */
     private challenge;
 }
@@ -274,4 +358,4 @@ declare global {
     }
 }
 
-export { type ActionCallStatus, type ActionCallView, type ActionConfirmHook, type ActionEventDetail, type ActionResult, type ActionResultStatus, ActionSensitivity, ApiClient, type ApiClientOptions, ApiError, ChatRequestBody, ChatStreamEvent, type DeweeChatConfig, DeweeChatElement, HistoryMessage, type JsonSchema, type PageAction, type PageActionContext, type PageActionInfo, PublicConfig, RESERVED_HEADERS, type RequestHeadersOption, SessionResponse, defineDeweeChat, mount, renderMarkdown };
+export { type ActionCallStatus, type ActionCallView, type ActionConfirmHook, type ActionEventDetail, type ActionResult, type ActionResultStatus, ActionSensitivity, ApiClient, type ApiClientOptions, ApiError, ChatRequestBody, ChatStreamEvent, type DeweeChatConfig, DeweeChatElement, HistoryMessage, type JsonSchema, LinkResponse, type PageAction, type PageActionContext, type PageActionInfo, PublicConfig, RESERVED_HEADERS, Remediation, type RequestHeadersOption, SessionResponse, defineDeweeChat, mount, renderMarkdown };

package/dist/index.js

@@ -6,8 +6,8 @@ import {
   defineDeweeChat,
   mount,
   renderMarkdown
-} from "./chunk-ZTVGWFXL.js";
-import "./chunk-W6A4HVFB.js";
+} from "./chunk-2NRPUV6T.js";
+import "./chunk-PUIN5ZCQ.js";
 export {
   ApiClient,
   ApiError,

package/dist/protocol-CLbGE9Ns.d.ts

@@ -0,0 +1,170 @@
+/** Server-Sent Events emitted by `POST {basePath}/chat`. */
+type ChatStreamEvent = {
+    type: "start";
+    runId?: string;
+    conversationId: string;
+    agent: string;
+    actionsHash?: string;
+} | {
+    type: "thinking";
+    text: string;
+} | {
+    type: "delta";
+    text: string;
+} | {
+    type: "tool_call";
+    id: string;
+    name: string;
+    arguments?: unknown;
+} | {
+    type: "tool_result";
+    id: string;
+    name: string;
+    isError: boolean;
+    result?: string;
+} | {
+    type: "done";
+    content: string;
+    usage?: Record<string, number>;
+} | {
+    type: "error";
+    message: string;
+    code?: string;
+    remediation?: Remediation;
+    retryAfterMs?: number;
+};
+/** The seven typed identity errors of the Dewee gateway, forwarded as `error.code` for signed-in users. */
+declare const IDENTITY_ERROR_CODES: readonly ["IDENTITY_REQUIRED", "IDENTITY_LINK_REQUIRED", "IDENTITY_CONFLICT", "LINK_EXPIRED", "LINK_REVOKED", "PERMISSION_DENIED", "SOURCE_UNAVAILABLE"];
+type IdentityErrorCode = (typeof IDENTITY_ERROR_CODES)[number];
+/**
+ * Admission refusals of the gateway for `chat.send`, forwarded as `error.code`: `POLICY_DENIED` (the
+ * message is outside the policy, e.g. too long; not retryable) and `RATE_LIMITED` (rate limit, a run
+ * still answering the previous message, or the counter backend unavailable; carries `retryAfterMs`).
+ * `CHALLENGE_REQUIRED` is reserved for the gateway challenge protocol and carries no payload yet.
+ */
+declare const ADMISSION_ERROR_CODES: readonly ["POLICY_DENIED", "RATE_LIMITED", "CHALLENGE_REQUIRED"];
+type AdmissionErrorCode = (typeof ADMISSION_ERROR_CODES)[number];
+declare function isAdmissionErrorCode(code: unknown): code is AdmissionErrorCode;
+/** What to do about an identity error: `action` (e.g. `reauthenticate`, `retry_later`) and who acts (`end_user`, `operator`, `integrator`). */
+interface Remediation {
+    action: string;
+    audience: string;
+}
+/**
+ * Error body of every JSON route. `remediation` is present for identity errors only, `retryAfterMs`
+ * for `RATE_LIMITED` refusals of the gateway (also sent as the `Retry-After` header, in seconds).
+ */
+interface ErrorBody {
+    error: {
+        message: string;
+        code: string;
+        remediation?: Remediation;
+        retryAfterMs?: number;
+    };
+}
+interface AgentInfo {
+    id: string;
+    name?: string;
+    description?: string;
+}
+/** Response of `GET {basePath}/config` — safe to expose publicly. */
+interface PublicConfig {
+    agents: AgentInfo[];
+    defaultAgent: string;
+    allowAgentSwitch: boolean;
+    allowClientCredentials: boolean;
+    turnstileSiteKey?: string;
+    maxMessageLength: number;
+    version: string;
+    /** Present (true) when the backend signs users in through Dewee: the widget then asks `/session` on every page load. */
+    identity?: boolean;
+    /**
+     * Present (true) when a returning visitor's `/session` refresh (a valid anonymous `token` in the
+     * body) needs no Turnstile token (ccp transport); only new visitors are challenged then. With
+     * `identity` the widget still challenges: a signed-in user's `/session` always needs a token.
+     */
+    refreshWithoutTurnstile?: boolean;
+}
+/** Response of `POST {basePath}/session`. */
+interface SessionResponse {
+    visitorId: string;
+    token: string;
+    /**
+     * When the widget should come back to `/session` (refreshing with `token`). With the ccp transport
+     * this is when the CCP edge session sealed in the token ends, earlier than the token itself.
+     */
+    expiresAt: number;
+    /**
+     * Present (true) when the session carries a verified Dewee identity. Such sessions are short-lived and
+     * are used from memory only.
+     */
+    verified?: boolean;
+    /**
+     * ccp transport, verified sessions only: an opaque token that lets a later page load of this tab
+     * reuse the session instead of exchanging a new one. It is no bearer token (every route but
+     * `/session` refuses it), and `/session` uses it only for the user the host authenticates at that
+     * moment. The widget keeps it in `sessionStorage` and sends it back as `reuseHint`; it stores
+     * nothing when the answer has none (legacy gateway, PHP).
+     */
+    reuseHint?: string;
+    /**
+     * Verified sessions, and every session of the ccp transport: milliseconds until `expiresAt`, counted
+     * from when the response is received. The widget refreshes from this rather than `expiresAt`, so a
+     * skewed browser clock does not matter.
+     */
+    expiresIn?: number;
+}
+/** A chat account the proof code of a web-first link can be sent to. */
+interface LinkTarget {
+    /** e.g. `telegram`, `discord`, `zalo`. */
+    channelType: string;
+    channelInstanceId: string;
+    name: string;
+    displayName?: string;
+}
+/** Response of `POST {basePath}/link`. */
+interface LinkResponse {
+    /** Show it exactly as given; the user sends it in a direct chat from the account to link. */
+    proofCode: string;
+    /** Epoch ms. */
+    expiresAt: number;
+    deepLinks: LinkTarget[];
+}
+interface ToolCallView {
+    id: string;
+    name: string;
+    arguments?: unknown;
+    result?: string;
+    isError?: boolean;
+    status: "running" | "done" | "error";
+}
+/** A transcript message as returned by `GET {basePath}/history`. */
+interface HistoryMessage {
+    role: "user" | "assistant";
+    content: string;
+    thinking?: string;
+    toolCalls?: ToolCallView[];
+    createdAt?: string;
+}
+/** How much an agent-invoked page action can change. `mutate`/`destructive` always need user approval. */
+type ActionSensitivity = "read" | "navigate" | "mutate" | "destructive";
+/** What the backend (and the agent) learns about a page action. Handlers never leave the browser. */
+interface ActionManifestEntry {
+    name: string;
+    description: string;
+    /** JSON Schema subset describing `args` (object). */
+    parameters: Record<string, unknown>;
+    sensitivity: ActionSensitivity;
+}
+/** Body of `POST {basePath}/chat`. `actions`/`actionsHash`/`pageContext` are optional (page actions). */
+interface ChatRequestBody {
+    message: string;
+    agent?: string;
+    conversationId?: string;
+    actions?: ActionManifestEntry[];
+    /** Hash from the `start` event of the last completed turn; the manifest is re-sent to the agent only when it differs. */
+    actionsHash?: string;
+    pageContext?: unknown;
+}
+
+export { type AgentInfo as A, type ChatStreamEvent as C, type ErrorBody as E, type HistoryMessage as H, type IdentityErrorCode as I, type LinkResponse as L, type PublicConfig as P, type Remediation as R, type SessionResponse as S, type ToolCallView as T, type ActionManifestEntry as a, type AdmissionErrorCode as b, ADMISSION_ERROR_CODES as c, type ActionSensitivity as d, type ChatRequestBody as e, type LinkTarget as f, isAdmissionErrorCode as i };

package/dist/react.d.ts

@@ -2,7 +2,7 @@ import * as react from 'react';
 import { CSSProperties } from 'react';
 import { DeweeChatConfig, ActionEventDetail, DeweeChatElement } from './index.js';
 export { ActionConfirmHook, PageAction, PageActionContext, RequestHeadersOption } from './index.js';
-import './protocol-B72Ry-fY.js';
+import './protocol-CLbGE9Ns.js';
 
 interface DeweeChatProps extends Partial<DeweeChatConfig> {
     className?: string;

package/dist/react.js

@@ -1,7 +1,7 @@
 import {
   defineDeweeChat
-} from "./chunk-ZTVGWFXL.js";
-import "./chunk-W6A4HVFB.js";
+} from "./chunk-2NRPUV6T.js";
+import "./chunk-PUIN5ZCQ.js";
 
 // src/react.ts
 import { createElement, forwardRef, useEffect, useImperativeHandle, useRef } from "react";