@chatcops/server 0.5.0 → 0.7.0

package/dist/client-ip.js

@@ -0,0 +1,57 @@
+import { consoleLogger } from '@chatcops/core';
+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, logger = consoleLogger()) {
+    if (warned.has(key))
+        return;
+    warned.add(key);
+    logger.warn('client_ip', message, { key });
+}
+/** For tests. */
+export function resetClientIpWarnings() {
+    warned.clear();
+}
+/** The fetch handler for Vercel and other Fetch API runtimes. */
+export function fetchClientIp(request, resolver, logger) {
+    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', `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}`, logger);
+    return undefined;
+}
+/** Cloudflare sets CF-Connecting-IP on every request that reaches a Worker. */
+export function cloudflareClientIp(request, resolver, logger) {
+    if (resolver)
+        return cleanIp(resolver(request));
+    const ip = cleanIp(request.headers.get('cf-connecting-ip'));
+    if (!ip) {
+        warnOnce('cloudflare', 'A request had no CF-Connecting-IP header, so per-IP rate limits and budgets were skipped for it.', logger);
+    }
+    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, logger) {
+    if (req.headers?.['x-forwarded-for'] !== undefined && !req.app?.get?.('trust proxy')) {
+        warnOnce('express', "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).", logger);
+    }
+    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,OAAO,EAAE,aAAa,EAAe,MAAM,gBAAgB,CAAC;AAW5D,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,EAAE,SAAiB,aAAa,EAAE;IACrF,IAAI,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC;QAAE,OAAO;IAC5B,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChB,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;AAC7C,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,EAAE,MAAe;IACrG,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,0LAA0L,IAAI,EAAE,EAChM,MAAM,CACP,CAAC;IACF,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,kBAAkB,CAAC,OAAgB,EAAE,QAAsC,EAAE,MAAe;IAC1G,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,kGAAkG,EAAE,MAAM,CAAC,CAAC;IACrI,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AASD;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,GAAuB,EAAE,MAAe;IACtE,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,uQAAuQ,EACvQ,MAAM,CACP,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,23 @@
 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, Logger, 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;
+    /**
+     * Where the server writes startup notes, refused requests and every error
+     * it handles instead of throwing, each with a stable `event` name. Default
+     * `consoleLogger()`; `jsonLogger()` writes one JSON object per line.
+     */
+    logger?: Logger;
     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 +26,105 @@ 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;
+    /**
+     * Signed-in visitors. Your site signs a \`userToken\` (an HS256 JWT with
+     * \`sub\`, \`exp\` and an optional \`tier\`) with \`secret\`, and the widget
+     * sends it with \`/session\`. The user id is stored on the conversation, so
+     * the same user can resume it with a fresh token, and \`tiers\` gives a
+     * tier its own budgets (merged over \`budgets\`). Needs \`sessionSecrets\`.
+     */
+    identity?: {
+        secret: string;
+        tiers?: Record<string, Budgets>;
+    };
+    /**
+     * 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;
@@ -27,6 +132,10 @@ export interface ChatCopsServerConfig {
     };
 }
 export declare const MAX_USER_DATA_FIELDS = 50;
+/** `pageContext.data`, what a site adds with the widget's setContext(). */
+export declare const MAX_PAGE_DATA_FIELDS = 20;
+export declare const MAX_PAGE_DATA_KEY_LENGTH = 40;
+export declare const MAX_PAGE_DATA_VALUE_LENGTH = 500;
 export declare const MAX_USER_DATA_KEY_LENGTH = 100;
 /** Longer page URLs are still accepted, but only this much reaches the prompt. */
 export declare const MAX_PAGE_URL_LENGTH = 2000;
@@ -34,22 +143,35 @@ 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;
         description: z.ZodOptional<z.ZodString>;
         contentSnippet: z.ZodOptional<z.ZodString>;
+        data: z.ZodOptional<z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodString>, Record<string, string>, Record<string, string>>>;
     }, "strip", z.ZodTypeAny, {
         url: string;
         title: string;
         description?: string | undefined;
         contentSnippet?: string | undefined;
+        data?: Record<string, string> | undefined;
     }, {
         url: string;
         title: string;
         description?: string | undefined;
         contentSnippet?: string | undefined;
+        data?: Record<string, string> | undefined;
     }>>;
     locale: z.ZodOptional<z.ZodString>;
     userData: z.ZodOptional<z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodString>, Record<string, string>, Record<string, string>>>;
@@ -57,12 +179,15 @@ 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;
         description?: string | undefined;
         contentSnippet?: string | undefined;
+        data?: Record<string, string> | undefined;
     } | undefined;
     locale?: string | undefined;
     userData?: Record<string, string> | undefined;
@@ -70,12 +195,15 @@ 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;
         description?: string | undefined;
         contentSnippet?: string | undefined;
+        data?: Record<string, string> | undefined;
     } | undefined;
     locale?: string | undefined;
     userData?: Record<string, string> | undefined;

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":"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"}

package/dist/config.js

@@ -1,6 +1,10 @@
 import { z } from 'zod';
 // Everything in a request can end up in the system prompt, so every field has a ceiling.
 export const MAX_USER_DATA_FIELDS = 50;
+/** `pageContext.data`, what a site adds with the widget's setContext(). */
+export const MAX_PAGE_DATA_FIELDS = 20;
+export const MAX_PAGE_DATA_KEY_LENGTH = 40;
+export const MAX_PAGE_DATA_VALUE_LENGTH = 500;
 export const MAX_USER_DATA_KEY_LENGTH = 100;
 /** Longer page URLs are still accepted, but only this much reaches the prompt. */
 export const MAX_PAGE_URL_LENGTH = 2000;
@@ -8,12 +12,22 @@ 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),
         description: z.string().max(1000).optional(),
         contentSnippet: z.string().max(2000).optional(),
+        data: z
+            .record(z.string().max(MAX_PAGE_DATA_KEY_LENGTH), z.string().max(MAX_PAGE_DATA_VALUE_LENGTH))
+            .refine((data) => Object.keys(data).length <= MAX_PAGE_DATA_FIELDS, {
+            message: `pageContext.data can have at most ${MAX_PAGE_DATA_FIELDS} fields`,
+        })
+            .optional(),
     }).optional(),
     locale: z.string().max(10).optional(),
     userData: z

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;AAuIxB,yFAAyF;AACzF,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAC;AACvC,2EAA2E;AAC3E,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAC;AACvC,MAAM,CAAC,MAAM,wBAAwB,GAAG,EAAE,CAAC;AAC3C,MAAM,CAAC,MAAM,0BAA0B,GAAG,GAAG,CAAC;AAC9C,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;QAC/C,IAAI,EAAE,CAAC;aACJ,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,wBAAwB,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAC;aAC5F,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,IAAI,oBAAoB,EAAE;YAClE,OAAO,EAAE,qCAAqC,oBAAoB,SAAS;SAC5E,CAAC;aACD,QAAQ,EAAE;KACd,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/examples/cloudflare-worker.js

@@ -15,7 +15,7 @@ function getHandler(env) {
             apiKey: env.ANTHROPIC_API_KEY,
         },
         systemPrompt: 'You are a helpful assistant.',
-        cors: '*',
+        allowedOrigins: ['*'],
     });
     return handler;
 }

package/dist/examples/cloudflare-worker.js.map

@@ -1 +1 @@
-{"version":3,"file":"cloudflare-worker.js","sourceRoot":"","sources":["../../src/examples/cloudflare-worker.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAE7D,6EAA6E;AAC7E,+EAA+E;AAC/E,2EAA2E;AAC3E,IAAI,OAAiE,CAAC;AACtE,SAAS,UAAU,CAAC,GAA2B;IAC7C,OAAO,KAAK,yBAAyB,CAAC;QACpC,QAAQ,EAAE;YACR,IAAI,EAAE,QAAQ;YACd,MAAM,EAAE,GAAG,CAAC,iBAAiB;SAC9B;QACD,YAAY,EAAE,8BAA8B;QAC5C,IAAI,EAAE,GAAG;KACV,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,eAAe;IACb,KAAK,CAAC,KAAK,CAAC,OAAgB,EAAE,GAA2B;QACvD,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC;IAClC,CAAC;CACF,CAAC"}
+{"version":3,"file":"cloudflare-worker.js","sourceRoot":"","sources":["../../src/examples/cloudflare-worker.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAE7D,6EAA6E;AAC7E,+EAA+E;AAC/E,2EAA2E;AAC3E,IAAI,OAAiE,CAAC;AACtE,SAAS,UAAU,CAAC,GAA2B;IAC7C,OAAO,KAAK,yBAAyB,CAAC;QACpC,QAAQ,EAAE;YACR,IAAI,EAAE,QAAQ;YACd,MAAM,EAAE,GAAG,CAAC,iBAAiB;SAC9B;QACD,YAAY,EAAE,8BAA8B;QAC5C,cAAc,EAAE,CAAC,GAAG,CAAC;KACtB,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,eAAe;IACb,KAAK,CAAC,KAAK,CAAC,OAAgB,EAAE,GAA2B;QACvD,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC;IAClC,CAAC;CACF,CAAC"}

package/dist/handler.d.ts

@@ -1,9 +1,60 @@
+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 logger the handler writes to, for adapters to use as well. */
+    logger: import("@chatcops/core").Logger;
 };
+/** 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,EAQL,KAAK,cAAc,EAgBnB,KAAK,WAAW,EAChB,KAAK,OAAO,EAIZ,KAAK,WAAW,EAChB,KAAK,aAAa,EAElB,KAAK,QAAQ,EACd,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,oBAAoB,EAAwB,MAAM,aAAa,CAAC;AAS9E,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,oBAAoB;uBAqMpD,OAAO,aACF,MAAM,YACR;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,KAChC,cAAc,CAAC,MAAM,CAAC;sBAtGM,OAAO,aAAa,MAAM,YAAW,gBAAgB,KAAQ,OAAO,CAAC,SAAS,CAAC;6BAiTtE,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAc5D,yFAAyF;IACzF,2EAA2E;0BAEhE,OAAO,UAAU,MAAM,GAAG,IAAI,aAAa,MAAM;;;;;;IAG5D,uFAAuF;;6BAhPnD;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,KAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;;IAoPnG,qEAAqE;;EAGxE;AAED,kGAAkG;AAClG,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAQpD,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"}