@chatcops/server 0.5.0 → 0.6.0

package/dist/client-ip.js

@@ -0,0 +1,62 @@
+/**
+ * The visitor's IP, for per-IP rate limits and budgets. Only headers a
+ * platform sets itself are read, never ones a visitor can send. When the IP
+ * can't be told, per-IP limits are skipped for that request (with one
+ * warning) instead of every visitor sharing one bucket.
+ */
+const DOCS = 'https://chat.codercops.com/server/fetch-runtimes/#the-visitors-ip';
+// IPv4, IPv6 (including IPv4-mapped) and nothing else, so a header can't
+// carry an arbitrary counter key.
+const IP_PATTERN = /^[0-9A-Fa-f:.]{2,45}$/;
+export function cleanIp(value) {
+    const ip = value?.split(',')[0]?.trim();
+    return ip && IP_PATTERN.test(ip) ? ip : undefined;
+}
+/** Vercel overwrites these headers, so a visitor can't set them there. */
+export function onVercel() {
+    return typeof process !== 'undefined' && Boolean(process.env?.VERCEL);
+}
+const warned = new Set();
+export function warnOnce(key, message) {
+    if (warned.has(key))
+        return;
+    warned.add(key);
+    console.warn(message);
+}
+/** For tests. */
+export function resetClientIpWarnings() {
+    warned.clear();
+}
+/** The fetch handler for Vercel and other Fetch API runtimes. */
+export function fetchClientIp(request, resolver) {
+    if (resolver)
+        return cleanIp(resolver(request));
+    if (onVercel()) {
+        const headers = request.headers;
+        return cleanIp(headers.get('x-vercel-forwarded-for')) ?? cleanIp(headers.get('x-real-ip')) ?? cleanIp(headers.get('x-forwarded-for'));
+    }
+    warnOnce('fetch', `[chatcops] Not running on Vercel, so the visitor's IP isn't read from X-Forwarded-For, which a visitor can set themselves. Per-IP rate limits and budgets are off until you set \`clientIp\`. See ${DOCS}`);
+    return undefined;
+}
+/** Cloudflare sets CF-Connecting-IP on every request that reaches a Worker. */
+export function cloudflareClientIp(request, resolver) {
+    if (resolver)
+        return cleanIp(resolver(request));
+    const ip = cleanIp(request.headers.get('cf-connecting-ip'));
+    if (!ip) {
+        warnOnce('cloudflare', '[chatcops] A request had no CF-Connecting-IP header, so per-IP rate limits and budgets were skipped for it.');
+    }
+    return ip;
+}
+/**
+ * Express's `req.ip` follows its `trust proxy` setting. Behind a proxy with
+ * that setting off, every visitor gets the proxy's address and shares one
+ * rate limit and budget, so that case gets a warning.
+ */
+export function expressClientIp(req) {
+    if (req.headers?.['x-forwarded-for'] !== undefined && !req.app?.get?.('trust proxy')) {
+        warnOnce('express', "[chatcops] A request had X-Forwarded-For, but Express's `trust proxy` setting is off, so the connection's IP is used. Behind a proxy that means every visitor gets the proxy's IP and shares one rate limit and budget. With one proxy in front, call app.set('trust proxy', 1).");
+    }
+    return cleanIp(req.ip ?? req.socket?.remoteAddress);
+}
+//# sourceMappingURL=client-ip.js.map

package/dist/client-ip.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-ip.js","sourceRoot":"","sources":["../src/client-ip.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,MAAM,IAAI,GAAG,mEAAmE,CAAC;AAEjF,yEAAyE;AACzE,kCAAkC;AAClC,MAAM,UAAU,GAAG,uBAAuB,CAAC;AAE3C,MAAM,UAAU,OAAO,CAAC,KAAgC;IACtD,MAAM,EAAE,GAAG,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;IACxC,OAAO,EAAE,IAAI,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AACpD,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,QAAQ;IACtB,OAAO,OAAO,OAAO,KAAK,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;AACxE,CAAC;AAED,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAC;AAEjC,MAAM,UAAU,QAAQ,CAAC,GAAW,EAAE,OAAe;IACnD,IAAI,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC;QAAE,OAAO;IAC5B,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChB,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AACxB,CAAC;AAED,iBAAiB;AACjB,MAAM,UAAU,qBAAqB;IACnC,MAAM,CAAC,KAAK,EAAE,CAAC;AACjB,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,aAAa,CAAC,OAAgB,EAAE,QAAsC;IACpF,IAAI,QAAQ;QAAE,OAAO,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;IAChD,IAAI,QAAQ,EAAE,EAAE,CAAC;QACf,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAChC,OAAO,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,wBAAwB,CAAC,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC;IACxI,CAAC;IACD,QAAQ,CACN,OAAO,EACP,qMAAqM,IAAI,EAAE,CAC5M,CAAC;IACF,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,kBAAkB,CAAC,OAAgB,EAAE,QAAsC;IACzF,IAAI,QAAQ;QAAE,OAAO,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;IAChD,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC,CAAC;IAC5D,IAAI,CAAC,EAAE,EAAE,CAAC;QACR,QAAQ,CAAC,YAAY,EAAE,6GAA6G,CAAC,CAAC;IACxI,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AASD;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,GAAuB;IACrD,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC,iBAAiB,CAAC,KAAK,SAAS,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,aAAa,CAAC,EAAE,CAAC;QACrF,QAAQ,CACN,SAAS,EACT,kRAAkR,CACnR,CAAC;IACJ,CAAC;IACD,OAAO,OAAO,CAAC,GAAG,CAAC,EAAE,IAAI,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AACtD,CAAC"}

package/dist/config.d.ts

@@ -1,11 +1,17 @@
 import { z } from 'zod';
-import type { ChatTool, KnowledgeSource, WebhookConfig, ProviderConfig, LocaleStrings, ConversationStore } from '@chatcops/core';
+import type { ClientIpResolver } from './client-ip.js';
+import type { TurnstileConfig } from './security/turnstile.js';
+import type { AIProvider, Budgets, ChatCopsStorage, ChatTool, ConversationStore, KnowledgeSource, LocaleStrings, ProviderConfig, WebhookConfig } from '@chatcops/core';
 export interface ChatCopsServerConfig {
-    provider: ProviderConfig;
+    /**
+     * Which model to use: a config like `{ type: 'claude', apiKey }`, or a
+     * provider object you built yourself (anything with `step()` or `chat()`).
+     */
+    provider: ProviderConfig | AIProvider;
     systemPrompt: string;
     tools?: ChatTool[];
     toolTimeoutMs?: number;
-    /** Most tokens in one reply. Defaults to 1024. */
+    /** Most tokens in one reply. Defaults to 4096 (`DEFAULT_MAX_TOKENS` in @chatcops/core). */
     maxTokens?: number;
     /** Sampling temperature. Defaults to the provider's own; the allowed range depends on the provider. */
     temperature?: number;
@@ -14,12 +20,94 @@ export interface ChatCopsServerConfig {
         maxRequests: number;
         windowMs: number;
     };
+    /**
+     * Token, reply and dollar limits per conversation, per IP per day and
+     * overall per day, counted in `storage` so they hold across instances. A
+     * reply that would go over ends with an error instead of calling the model.
+     * On by default (`DEFAULT_BUDGETS`: 200 replies per conversation, 2M tokens
+     * per IP per day). A scope you set replaces its default, `false` turns a
+     * scope off, and `budgets: false` turns them all off.
+     */
+    budgets?: Budgets | false;
+    /**
+     * The pre-chat form fields to keep (the `name`s in the widget's
+     * `preChatForm.fields`). Other fields a request sends are dropped. Unset
+     * keeps every field. Answers are stored with the conversation from its
+     * first message and can't change after that.
+     */
+    preChatFields?: string[];
     webhooks?: WebhookConfig[];
     analytics?: boolean;
-    /** Storage backend for conversation history. Defaults to an in-memory store (`MemoryStore`). */
+    /** Bearer token required to read the analytics endpoint. When unset, the endpoint is public. */
+    analyticsToken?: string;
+    /**
+     * Where conversations (and, with stores that have them, counters, turn
+     * locks and events) live: `postgresStorage(...)`, `redisStorage(...)` and
+     * so on. Defaults to memory, which doesn't survive a restart and isn't
+     * shared between serverless instances.
+     */
+    storage?: ChatCopsStorage;
+    /**
+     * @deprecated Use `storage`. A conversation store on its own, as in 0.4.
+     * Setting both is an error.
+     */
     conversationStore?: ConversationStore;
-    /** Allowed CORS origin. Defaults to `'*'`. */
+    /**
+     * How long to keep conversations. `purge()` on the handler deletes older
+     * ones; call it on a schedule (a cron job, a Workers cron trigger).
+     */
+    retention?: {
+        conversationsDays?: number;
+    };
+    /**
+     * The sites that can use the chat: exact origins (`'https://acme.com'`) or
+     * subdomain wildcards (`'https://*.acme.com'`). A browser request from any
+     * other page gets 403 `origin_not_allowed` before the model is called.
+     * Requests without an `Origin` header (curl, your own server) pass: this
+     * stops other sites embedding your bot, not scripts. Defaults to `['*']`.
+     */
+    allowedOrigins?: string[];
+    /** @deprecated Use `allowedOrigins`. Read as a one-item `allowedOrigins`. */
     cors?: string;
+    /**
+     * Reads the visitor's IP for per-IP rate limits and budgets, in the fetch
+     * handlers (`chatcopsVercelHandler`, `chatcopsCloudflareHandler`). Needed
+     * where the handler can't tell on its own: any host other than Vercel or
+     * Cloudflare. Read only a header your platform or proxy sets, never one a
+     * visitor can send. Return `undefined` to skip per-IP limits for a request.
+     * Express uses `req.ip`, which follows its `trust proxy` setting.
+     */
+    clientIp?: ClientIpResolver;
+    /**
+     * Turns on session tokens. `POST <chat url>/session` gives the widget a
+     * token bound to its origin and one conversation, and chat requests send
+     * it as `Authorization: Bearer <token>`, so a guessed conversation id is
+     * useless. Sign with the first secret and verify with all of them, so a
+     * new secret goes first and the old one stays until its tokens expire.
+     * Each needs at least 32 bytes (`openssl rand -base64 32`). Keep them
+     * server side, never in a client bundle.
+     */
+    sessionSecrets?: string[];
+    /** How long a session token lasts, in seconds. Defaults to 900. */
+    sessionTtlSec?: number;
+    /**
+     * Refuse chat requests without a session token (401 `session_required`).
+     * Defaults to true when `sessionSecrets` is set. Set false while widgets
+     * older than 0.6, which don't send tokens, are still out there.
+     */
+    requireSession?: boolean;
+    /**
+     * Cloudflare Turnstile when a session token is issued: `/session` needs a
+     * Turnstile token and checks it with Cloudflare before signing. Refreshing
+     * a session with its previous token skips it. Needs `sessionSecrets`, and
+     * the widget's `turnstileSiteKey`.
+     */
+    turnstile?: TurnstileConfig;
+    /**
+     * Adds the reply's token usage to the `finish` part of protocol v1
+     * streams. Off by default, since visitors can read the stream.
+     */
+    exposeUsage?: boolean;
     /** @deprecated The server ignores this. Set the widget's text with its `strings` option. */
     i18n?: {
         defaultLocale: string;
@@ -34,7 +122,17 @@ export declare const chatRequestSchema: z.ZodObject<{
     conversationId: z.ZodString;
     message: z.ZodString;
     messageId: z.ZodOptional<z.ZodString>;
-    regenerate: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * `{ assistantMessageId }` replaces that reply. `true` (the 0.5 form)
+     * replaces the reply to `messageId`, or the latest one.
+     */
+    regenerate: z.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodObject<{
+        assistantMessageId: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        assistantMessageId: string;
+    }, {
+        assistantMessageId: string;
+    }>]>>;
     pageContext: z.ZodOptional<z.ZodObject<{
         url: z.ZodString;
         title: z.ZodString;
@@ -57,7 +155,9 @@ export declare const chatRequestSchema: z.ZodObject<{
     conversationId: string;
     message: string;
     messageId?: string | undefined;
-    regenerate?: boolean | undefined;
+    regenerate?: boolean | {
+        assistantMessageId: string;
+    } | undefined;
     pageContext?: {
         url: string;
         title: string;
@@ -70,7 +170,9 @@ export declare const chatRequestSchema: z.ZodObject<{
     conversationId: string;
     message: string;
     messageId?: string | undefined;
-    regenerate?: boolean | undefined;
+    regenerate?: boolean | {
+        assistantMessageId: string;
+    } | undefined;
     pageContext?: {
         url: string;
         title: string;

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,aAAa,EAAE,cAAc,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEjI,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,cAAc,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uGAAuG;IACvG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,eAAe,EAAE,CAAC;IAC9B,SAAS,CAAC,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IACtD,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAC;IAC3B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,gGAAgG;IAChG,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC,8CAA8C;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4FAA4F;IAC5F,IAAI,CAAC,EAAE;QAAE,aAAa,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;KAAE,CAAC;CAC1E;AAGD,eAAO,MAAM,oBAAoB,KAAK,CAAC;AACvC,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAC5C,kFAAkF;AAClF,eAAO,MAAM,mBAAmB,OAAO,CAAC;AAExC,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkB5B,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,KAAK,EACV,UAAU,EACV,OAAO,EACP,eAAe,EACf,QAAQ,EACR,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,cAAc,EACd,aAAa,EACd,MAAM,gBAAgB,CAAC;AAExB,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,QAAQ,EAAE,cAAc,GAAG,UAAU,CAAC;IACtC,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2FAA2F;IAC3F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uGAAuG;IACvG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,eAAe,EAAE,CAAC;IAC9B,SAAS,CAAC,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IACtD;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,OAAO,GAAG,KAAK,CAAC;IAC1B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAC;IAC3B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,gGAAgG;IAChG,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC;;;OAGG;IACH,SAAS,CAAC,EAAE;QAAE,iBAAiB,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,mEAAmE;IACnE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,4FAA4F;IAC5F,IAAI,CAAC,EAAE;QAAE,aAAa,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;KAAE,CAAC;CAC1E;AAGD,eAAO,MAAM,oBAAoB,KAAK,CAAC;AACvC,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAC5C,kFAAkF;AAClF,eAAO,MAAM,mBAAmB,OAAO,CAAC;AAExC,eAAO,MAAM,iBAAiB;;;;IAI5B;;;OAGG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAeH,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC"}

package/dist/config.js

@@ -8,7 +8,11 @@ export const chatRequestSchema = z.object({
     conversationId: z.string().min(1).max(128),
     message: z.string().min(1).max(10000),
     messageId: z.string().min(1).max(128).optional(),
-    regenerate: z.boolean().optional(),
+    /**
+     * `{ assistantMessageId }` replaces that reply. `true` (the 0.5 form)
+     * replaces the reply to `messageId`, or the latest one.
+     */
+    regenerate: z.union([z.boolean(), z.object({ assistantMessageId: z.string().min(1).max(128) })]).optional(),
     pageContext: z.object({
         url: z.string().url(),
         title: z.string().max(500),

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAwBxB,yFAAyF;AACzF,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAC;AACvC,MAAM,CAAC,MAAM,wBAAwB,GAAG,GAAG,CAAC;AAC5C,kFAAkF;AAClF,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,CAAC;AAExC,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;IAC1C,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC;IACrC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;IAChD,UAAU,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAClC,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;QACrB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC;QAC1B,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE;QAC5C,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE;KAChD,CAAC,CAAC,QAAQ,EAAE;IACb,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE;IACrC,QAAQ,EAAE,CAAC;SACR,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,wBAAwB,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;SACrE,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,IAAI,oBAAoB,EAAE;QAClE,OAAO,EAAE,6BAA6B,oBAAoB,SAAS;KACpE,CAAC;SACD,QAAQ,EAAE;CACd,CAAC,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAwHxB,yFAAyF;AACzF,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAC;AACvC,MAAM,CAAC,MAAM,wBAAwB,GAAG,GAAG,CAAC;AAC5C,kFAAkF;AAClF,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,CAAC;AAExC,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;IAC1C,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC;IACrC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;IAChD;;;OAGG;IACH,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,kBAAkB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAC3G,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;QACrB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC;QAC1B,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE;QAC5C,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE;KAChD,CAAC,CAAC,QAAQ,EAAE;IACb,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE;IACrC,QAAQ,EAAE,CAAC;SACR,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,wBAAwB,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;SACrE,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,IAAI,oBAAoB,EAAE;QAClE,OAAO,EAAE,6BAA6B,oBAAoB,SAAS;KACpE,CAAC;SACD,QAAQ,EAAE;CACd,CAAC,CAAC"}

package/dist/handler.d.ts

@@ -1,9 +1,58 @@
+import { type AnalyticsStats, type BudgetScope, type Budgets, type LegacyChunk, type WireErrorBody, type WirePart } from '@chatcops/core';
 import type { ChatCopsServerConfig } from './config.js';
 export declare function createChatHandler(config: ChatCopsServerConfig): {
     handleChat: (body: unknown, clientIp?: string, options?: {
         signal?: AbortSignal;
     }) => AsyncGenerator<string>;
-    getAnalytics: () => import("@chatcops/core").AnalyticsStats | null;
+    startChat: (body: unknown, clientIp?: string, options?: StartChatOptions) => Promise<ChatStart>;
+    purge: (now?: number) => Promise<number | null>;
+    /** How many requests asked for each stream format, to tell when 0.5 widgets are gone. */
+    /** Answers `POST /session`, or `undefined` when session tokens are off. */
+    startSession: ((body: unknown, origin: string | null, clientIp?: string) => Promise<import("./security/sessions.js").SessionReply>) | undefined;
+    protocolStats: () => {
+        v1: number;
+        legacy: number;
+        "ai-sdk": number;
+    };
+    /** Stats from this process only. `analyticsStats()` reads the storage's event sink. */
+    getAnalytics: () => AnalyticsStats | null;
+    analyticsStats: (range?: {
+        from?: number;
+        to?: number;
+    }) => Promise<AnalyticsStats | null>;
     cleanup: () => void;
 };
+/** The stream a caller writes: protocol v1, the 0.5 chunks, or the AI SDK's UI message stream. */
+export type ChatFormat = 'v1' | 'legacy' | 'ai-sdk';
+export interface StartChatOptions {
+    signal?: AbortSignal;
+    /** Which stream the caller writes, for `protocolStats()`. Defaults to `'v1'`. */
+    format?: ChatFormat;
+    /** The request's `Authorization` header, for session tokens. */
+    authorization?: string | null;
+    /** The request's `Origin` header, which a session token is bound to. */
+    origin?: string | null;
+}
+/** A request the handler won't answer, or the reply's parts. */
+export type ChatStart = {
+    ok: true;
+    parts: AsyncGenerator<WirePart, void>;
+} | {
+    ok: false;
+    /** The HTTP status protocol v1 answers with. */
+    status: number;
+    error: WireErrorBody['error'];
+    /** The chunk a 0.5 widget gets instead, inside a 200 stream. */
+    legacy: LegacyChunk & {
+        details?: unknown;
+    };
+};
+export type ChatHandler = ReturnType<typeof createChatHandler>;
+/**
+ * Protocol v1 parts as 0.5 chunks (JSON strings). An error goes out last,
+ * after the turn has ended and lead webhooks have finished, as in 0.5.
+ */
+export declare function toLegacyStream(parts: AsyncIterable<WirePart>): AsyncGenerator<string>;
+/** The startup line, so the limits in force are never a surprise. */
+export declare function describeBudgets(budgets: Budgets, defaulted?: BudgetScope[]): string;
 //# sourceMappingURL=handler.d.ts.map

package/dist/handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../src/handler.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,oBAAoB,EAAwB,MAAM,aAAa,CAAC;AAM9E,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,oBAAoB;uBAsBpD,OAAO,aACF,MAAM,YACR;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,KAChC,cAAc,CAAC,MAAM,CAAC;;;EAiN1B"}
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../src/handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAOL,KAAK,cAAc,EAenB,KAAK,WAAW,EAChB,KAAK,OAAO,EAGZ,KAAK,WAAW,EAChB,KAAK,aAAa,EAElB,KAAK,QAAQ,EACd,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,oBAAoB,EAAwB,MAAM,aAAa,CAAC;AAQ9E,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,oBAAoB;uBAgLpD,OAAO,aACF,MAAM,YACR;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,KAChC,cAAc,CAAC,MAAM,CAAC;sBAlGM,OAAO,aAAa,MAAM,YAAW,gBAAgB,KAAQ,OAAO,CAAC,SAAS,CAAC;6BAwStE,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAc5D,yFAAyF;IACzF,2EAA2E;0BAEhE,OAAO,UAAU,MAAM,GAAG,IAAI,aAAa,MAAM;;;;;;IAG5D,uFAAuF;;6BA3OnD;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,KAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;;EAgPtG;AAED,kGAAkG;AAClG,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEpD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,iFAAiF;IACjF,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,gEAAgE;AAChE,MAAM,MAAM,SAAS,GACjB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,cAAc,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAA;CAAE,GACnD;IACE,EAAE,EAAE,KAAK,CAAC;IACV,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IAC9B,gEAAgE;IAChE,MAAM,EAAE,WAAW,GAAG;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CAC7C,CAAC;AAEN,MAAM,MAAM,WAAW,GAAG,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAU/D;;;GAGG;AACH,wBAAuB,cAAc,CAAC,KAAK,EAAE,aAAa,CAAC,QAAQ,CAAC,GAAG,cAAc,CAAC,MAAM,CAAC,CAc5F;AA+CD,qEAAqE;AACrE,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,GAAE,WAAW,EAAO,GAAG,MAAM,CAkBvF"}