dewee-webchat 0.2.0 → 0.4.1-beta.1

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

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

package/dist/react.js

@@ -1,7 +1,7 @@
 import {
   defineDeweeChat
-} from "./chunk-YV6PXYJZ.js";
-import "./chunk-JX6AH37X.js";
+} from "./chunk-7WT3JK64.js";
+import "./chunk-USXVB3AC.js";
 
 // src/react.ts
 import { createElement, forwardRef, useEffect, useImperativeHandle, useRef } from "react";
@@ -16,7 +16,7 @@ var EVENTS = {
 };
 var DeweeChat = forwardRef(function DeweeChat2(props, ref) {
   const el = useRef(null);
-  const { className, style, onReady, onSend, onReply, onError, onOpen, onClose, onAction, actions, confirm, getPageContext, ...config } = props;
+  const { className, style, onReady, onSend, onReply, onError, onOpen, onClose, onAction, actions, confirm, getPageContext, headers, fetch, ...config } = props;
   const handlers = { onReady, onSend, onReply, onError, onOpen, onClose, onAction };
   const handlersRef = useRef(handlers);
   handlersRef.current = handlers;
@@ -28,7 +28,7 @@ var DeweeChat = forwardRef(function DeweeChat2(props, ref) {
   }, [configKey]);
   useEffect(() => {
     defineDeweeChat();
-    el.current?.configure({ actions, confirm, getPageContext });
+    el.current?.configure({ actions, confirm, getPageContext, headers, fetch });
   });
   useEffect(() => {
     const node = el.current;

package/dist/server-identity.d.ts

@@ -0,0 +1,6 @@
+import { D as DeweeIdentitySdk } from './handler-DunrbnSD.js';
+import './protocol-CLbGE9Ns.js';
+
+declare const deweeIdentitySdk: DeweeIdentitySdk;
+
+export { DeweeIdentitySdk, deweeIdentitySdk };

package/dist/server-identity.js

@@ -0,0 +1,6 @@
+// src/server/identity.ts
+import { createAssertion, exchangeSession, startLink } from "@dewee/identity";
+var deweeIdentitySdk = { exchangeSession, startLink, createAssertion };
+export {
+  deweeIdentitySdk
+};

package/dist/server.d.ts

@@ -1,74 +1,7 @@
-import { A as AgentInfo, H as HistoryMessage, C as ChatStreamEvent, a as ActionManifestEntry } from './protocol-B72Ry-fY.js';
-export { b as ActionSensitivity, c as ChatRequestBody, P as PublicConfig, S as SessionResponse } from './protocol-B72Ry-fY.js';
+export { A as AuthenticatedUser, C as CcpError, a as CcpOptions, b as DeweeHandler, c as DeweeHandlerOptions, d as DeweeIdentityOptions, D as DeweeIdentitySdk, e as DeweeTransport, I as IdentityPrivateJwk, f as IdentitySigner, M as MemoryRateLimits, R as RateLimitBucket, g as RateLimiter, V as VisitorClaims, h as createDeweeHandler, m as memoryRateLimiter, o as optionsFromEnv, s as signVisitorToken, v as verifyVisitorToken } from './handler-DunrbnSD.js';
 import { IncomingMessage, ServerResponse } from 'node:http';
-
-interface VisitorClaims {
-    /** Visitor id (random, 22 chars). */
-    v: string;
-    /** Expiry, epoch ms. */
-    exp: number;
-}
-declare function signVisitorToken(secret: string, claims: VisitorClaims): Promise<string>;
-declare function verifyVisitorToken(secret: string, token: string): Promise<VisitorClaims | null>;
-/** Returns true when the key may proceed. Implementations may be async (KV, DO, Redis…). */
-type RateLimiter = (key: string, bucket: "session" | "chat") => boolean | Promise<boolean>;
-/**
- * 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: {
-    chat: [number, number];
-    session: [number, number];
-}): RateLimiter;
-
-interface DeweeHandlerOptions {
-    /** Gateway runtime origin. Required unless every request brings its own credentials. */
-    gatewayUrl?: string;
-    /** Gateway token or operator API key (server-side only). */
-    token?: string;
-    tenantId?: string;
-    /** HMAC secret for visitor tokens (>= 32 random chars). */
-    secret?: string;
-    /** 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[] | "*";
-    /**
-     * 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 msgs/min, 10 sessions/10 min per IP. */
-    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;
-}
-type Handler = (request: Request) => Promise<Response>;
-declare function createDeweeHandler(options: DeweeHandlerOptions): Handler;
-/** Reads options from environment variables (process.env, Workers env, import.meta.env…). */
-declare function optionsFromEnv(env: Record<string, string | undefined>, overrides?: Partial<DeweeHandlerOptions>): DeweeHandlerOptions;
+import { R as Remediation, H as HistoryMessage, A as AgentInfo, C as ChatStreamEvent, a as ActionManifestEntry, b as AdmissionErrorCode } from './protocol-CLbGE9Ns.js';
+export { c as ADMISSION_ERROR_CODES, d as ActionSensitivity, e as ChatRequestBody, E as ErrorBody, I as IdentityErrorCode, L as LinkResponse, f as LinkTarget, P as PublicConfig, S as SessionResponse, i as isAdmissionErrorCode } from './protocol-CLbGE9Ns.js';
 
 type FetchHandler = (request: Request) => Promise<Response>;
 /** Wraps a fetch-style handler for `http.createServer`, Express (`app.all("/api/dewee/*", ...)`), etc. */
@@ -85,9 +18,19 @@ interface GatewayCredentials {
     /** Optional tenant id/slug for multi-tenant gateways. */
     tenantId?: string;
 }
+/**
+ * Who a connection acts as: a gateway user id chosen by this server (anonymous visitors), or a Dewee
+ * identity session, in which case the gateway derives the user and no `user_id` is sent.
+ */
+type GatewayActor = string | {
+    identitySession: string;
+};
 declare class GatewayError extends Error {
     code?: string | undefined;
-    constructor(message: string, code?: string | undefined);
+    remediation?: Remediation | undefined;
+    retryAfterMs?: unknown | undefined;
+    /** `retryAfterMs` is the gateway's raw value for retryable refusals (`RATE_LIMITED`), unvalidated. */
+    constructor(message: string, code?: string | undefined, remediation?: Remediation | undefined, retryAfterMs?: unknown | undefined);
 }
 /** One authenticated gateway connection. Short-lived: one per chat turn or lookup. */
 declare class GatewayConnection {
@@ -97,7 +40,7 @@ declare class GatewayConnection {
     private listeners;
     private closed;
     private constructor();
-    static connect(creds: GatewayCredentials, userId: string, timeoutMs?: number): Promise<GatewayConnection>;
+    static connect(creds: GatewayCredentials, actor: GatewayActor, timeoutMs?: number): Promise<GatewayConnection>;
     call<T = any>(method: string, params: unknown, timeoutMs?: number): Promise<T>;
     onEvent(cb: (event: string, payload: any) => void): () => void;
     close(): void;
@@ -107,7 +50,12 @@ declare class GatewayConnection {
 declare function buildSessionKey(agent: string, conversationId: string): string;
 interface StreamChatOptions {
     creds: GatewayCredentials;
-    userId: string;
+    /** Gateway user id (anonymous visitors). Ignored when `identitySession` or `connection` is set. */
+    userId?: string;
+    /** Dewee identity session: the gateway derives the user; no `user_id` is sent. */
+    identitySession?: string;
+    /** An already connected connection to use (and close) instead of opening one. */
+    connection?: GatewayConnection;
     agent: string;
     sessionKey: string;
     message: string;
@@ -117,7 +65,7 @@ interface StreamChatOptions {
 /** Runs one chat turn and yields normalized stream events until the run ends. */
 declare function streamChat(opts: StreamChatOptions): AsyncGenerator<ChatStreamEvent>;
 /** Fetches a session transcript and folds tool calls/results into assistant turns. */
-declare function fetchHistory(creds: GatewayCredentials, userId: string, agent: string, sessionKey: string): Promise<HistoryMessage[]>;
+declare function fetchHistory(creds: GatewayCredentials, actor: GatewayActor, agent: string, sessionKey: string): Promise<HistoryMessage[]>;
 declare function foldHistory(raw: any[]): HistoryMessage[];
 /** Lists agents via the gateway REST API. */
 declare function listAgents(creds: GatewayCredentials): Promise<AgentInfo[]>;
@@ -146,4 +94,14 @@ declare function buildPageBlock(p: PageBlockInput): string;
 /** Removes a leading page block from a stored user message (history display). */
 declare function stripPageBlock(content: string): string;
 
-export { ACTION_LIMITS, ActionManifestEntry, AgentInfo, ChatStreamEvent, type DeweeHandlerOptions, GatewayConnection, type GatewayCredentials, GatewayError, HistoryMessage, type RateLimiter, type StreamChatOptions, buildPageBlock, buildSessionKey, createDeweeHandler, fetchHistory, foldHistory, hashManifest, listAgents, memoryRateLimiter, normalizeManifest, optionsFromEnv, signVisitorToken, streamChat, stripPageBlock, toNodeHandler, verifyVisitorToken };
+/** Cooldown when a `RATE_LIMITED` refusal carries no usable `retryAfterMs`. */
+declare const DEFAULT_RETRY_AFTER_MS = 5000;
+/** Upper bound of the cooldown passed to the browser, so a bogus value cannot lock the widget for long. */
+declare const MAX_RETRY_AFTER_MS = 600000;
+type AdmissionErrorEvent = Extract<ChatStreamEvent, {
+    type: "error";
+}>;
+/** The SSE `error` event of an admission refusal. Only `RATE_LIMITED` carries `retryAfterMs`. */
+declare function admissionErrorEvent(code: AdmissionErrorCode, retryAfterMs?: unknown, gatewayReason?: string): AdmissionErrorEvent;
+
+export { ACTION_LIMITS, ActionManifestEntry, AdmissionErrorCode, AgentInfo, ChatStreamEvent, DEFAULT_RETRY_AFTER_MS, type GatewayActor, GatewayConnection, type GatewayCredentials, GatewayError, HistoryMessage, MAX_RETRY_AFTER_MS, Remediation, type StreamChatOptions, admissionErrorEvent, buildPageBlock, buildSessionKey, fetchHistory, foldHistory, hashManifest, listAgents, normalizeManifest, streamChat, stripPageBlock, toNodeHandler };