@boldare/askdare 0.0.0-stage → 0.1.0-rc.0

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import { C as VisitorIdentity, S as ThemeVariants, _ as ColorScheme, a as BotContext, b as PresetName, c as BotSecurity, d as WidgetConfig, f as defineBot, g as defineTool, h as ToolDefinition, i as Bot, l as KnowledgeConfig, m as ToolContext, n as RateLimitStore, o as BotDefinition, p as Tool, r as AttachmentConfig, s as BotLimits, t as CounterHit, u as VoiceConfig, v as ThemeDefinition, x as ThemeTokens, y as defineTheme } from "./store.js";
+/**
+ * Version of the SSE wire protocol between the askdare server and its clients.
+ * Bumped on any breaking change to event names or payloads (ADR-0006).
+ */
+export declare const PROTOCOL_VERSION: 1;
+export { type AttachmentConfig, type Bot, type BotContext, type BotDefinition, type BotLimits, type BotSecurity, type ColorScheme, type CounterHit, type KnowledgeConfig, type PresetName, type RateLimitStore, type ThemeDefinition, type ThemeTokens, type ThemeVariants, type Tool, type ToolContext, type ToolDefinition, type VisitorIdentity, type VoiceConfig, type WidgetConfig, defineBot, defineTheme, defineTool };

package/dist/index.js

@@ -0,0 +1,193 @@
+import { a as themeDefinitionSchema, c as TEXT_KEYS, f as textsFor, i as resolveTheme, n as PROTOCOL_VERSION, o as themeWarnings, r as defineTheme, s as PRESET_NAMES, u as canonicalLocale } from "./version.js";
+import { z } from "zod";
+// src/bot/define-bot.ts
+const DEFAULT_LIMITS = {
+	maxOutputTokens: 1024,
+	maxInputChars: 4e3,
+	maxSteps: 5,
+	turnTimeoutMs: 12e4,
+	dailyTokens: 2e6,
+	dailyTokensPerIp: 2e5,
+	sessionsPerIpPerHour: 30,
+	conversationsPerIpPerHour: 20,
+	messagesPerVisitorPerMinute: 10,
+	messagesPerIpPerMinute: 30,
+	maxTurns: 50,
+	uploadsPerVisitorPerHour: 20,
+	uploadsPerIpPerHour: 60,
+	uploadsPerDay: 500,
+	transcriptionsPerVisitorPerHour: 30,
+	voiceSecondsPerDay: 3600,
+	voiceSecondsPerIpPerDay: 600
+};
+/** An https URL or a path on your app (no protocol-relative URLs). */
+const LINK = /^(https:\/\/[^\s"'<>\\]{1,500}|\/(?![/\\])[^\s"'<>\\]{0,500})$/;
+/** A same-origin path (served by your app, allowed by the iframe CSP) or a small raster data URL. */
+const AVATAR = /^(\/(?!\/)[\w\-./%]{1,200}|data:image\/(png|jpeg|webp|gif);base64,[A-Za-z0-9+/=]{1,90000})$/;
+const origin = z.string().refine((value) => {
+	try {
+		const url = new URL(value);
+		return (url.protocol === "https:" || url.protocol === "http:" && /^(localhost|127\.0\.0\.1|\[::1\]|.+\.localhost)$/.test(url.hostname)) && url.origin === value && /^[a-z0-9.-]+$|^\[[0-9a-f:]+\]$/i.test(url.hostname);
+	} catch {
+		return false;
+	}
+}, "must be an https origin like https://www.example.com (no path or wildcard; http only for localhost)");
+const definitionSchema = z.object({
+	id: z.string().regex(/^[a-z0-9][a-z0-9-]{0,47}$/, "use 1-48 lowercase letters, digits or dashes"),
+	model: z.string().trim().min(1, "is required"),
+	instructions: z.union([z.string().trim().min(1, "must not be empty"), z.function()]),
+	limits: z.object({
+		maxOutputTokens: z.number().int().min(16).max(128e3).optional(),
+		maxInputChars: z.number().int().min(1).max(1e5).optional(),
+		maxSteps: z.number().int().min(1).max(20).optional(),
+		turnTimeoutMs: z.number().int().min(1e3).max(9e5).optional(),
+		dailyTokens: z.number().int().min(1e3).optional(),
+		dailyTokensPerIp: z.number().int().min(100).optional(),
+		sessionsPerIpPerHour: z.number().int().min(1).max(1e4).optional(),
+		conversationsPerIpPerHour: z.number().int().min(1).max(1e4).optional(),
+		messagesPerVisitorPerMinute: z.number().int().min(1).max(1e3).optional(),
+		messagesPerIpPerMinute: z.number().int().min(1).max(1e4).optional(),
+		maxTurns: z.number().int().min(1).max(1e3).optional(),
+		uploadsPerVisitorPerHour: z.number().int().min(1).max(1e3).optional(),
+		uploadsPerIpPerHour: z.number().int().min(1).max(1e4).optional(),
+		uploadsPerDay: z.number().int().min(1).max(1e6).optional(),
+		transcriptionsPerVisitorPerHour: z.number().int().min(1).max(1e3).optional(),
+		voiceSecondsPerDay: z.number().int().min(60).optional(),
+		voiceSecondsPerIpPerDay: z.number().int().min(60).optional()
+	}).optional(),
+	tools: z.array(z.custom((value) => typeof value === "object" && value !== null && "execute" in value, "must be created with defineTool()")).max(64).refine((tools) => new Set(tools.map((tool) => tool.name)).size === tools.length, "must have unique names").refine((tools) => tools.every((tool) => tool.name !== "file_search"), "must not use the reserved name file_search").optional(),
+	pageContext: z.boolean().optional(),
+	knowledge: z.object({
+		vectorStoreId: z.string().regex(/^vs_[A-Za-z0-9_-]+$/, "must be a vector store ID like vs_…"),
+		maxResults: z.number().int().min(1).max(50).optional()
+	}).optional(),
+	attachments: z.object({
+		images: z.boolean().optional(),
+		pdf: z.boolean().optional(),
+		maxBytes: z.number().int().min(1e3).max(2e7).optional(),
+		maxPerMessage: z.number().int().min(1).max(10).optional(),
+		maxPdfPages: z.number().int().min(1).max(500).optional()
+	}).refine((value) => value.images !== false || value.pdf !== false, "must allow images or pdf").optional(),
+	voice: z.object({
+		model: z.string().trim().min(1, "is required"),
+		maxSeconds: z.number().int().min(5).max(300).optional()
+	}).optional(),
+	security: z.object({ allowedOrigins: z.array(origin).max(50).optional() }).optional(),
+	widget: z.object({
+		title: z.string().trim().min(1).max(80).optional(),
+		greeting: z.string().trim().min(1).max(500).optional(),
+		placeholder: z.string().trim().min(1).max(120).optional(),
+		locale: z.string().refine((value) => value === "auto" || canonicalLocale(value) !== void 0, "must be auto or a BCP 47 tag like en or pl-PL").optional(),
+		texts: z.partialRecord(z.enum(TEXT_KEYS), z.string().trim().min(1).max(300)).optional(),
+		disclosure: z.union([z.literal(false), z.object({ privacyUrl: z.string().regex(LINK, "must be an https URL or a path like /privacy").optional() }).strict()]).optional(),
+		css: z.string().max(5e4).optional(),
+		subtitle: z.string().trim().min(1).max(120).optional(),
+		starters: z.array(z.string().trim().min(1).max(80)).max(4).optional(),
+		avatar: z.string().regex(AVATAR, "must be a path like /avatar.png or a PNG, JPEG, WebP or GIF data URL").optional(),
+		launcherLabel: z.string().trim().min(1).max(40).optional(),
+		theme: z.union([z.enum(PRESET_NAMES), themeDefinitionSchema]).optional(),
+		colorScheme: z.enum([
+			"auto",
+			"light",
+			"dark"
+		]).optional()
+	}).optional()
+});
+/**
+* Declares a chatbot. Validates eagerly so misconfiguration fails at startup, not on the first
+* visitor's message.
+*/
+function defineBot(definition) {
+	const parsed = definitionSchema.safeParse(definition);
+	if (!parsed.success) {
+		const issues = parsed.error.issues.map((issue) => `${issue.path.join(".") || "(root)"} ${issue.message}`).join("; ");
+		const hint = parsed.error.issues.some((issue) => issue.path.join(".") === "model") ? " Set the model in the bot definition, usually as model: process.env.ASKDARE_MODEL with ASKDARE_MODEL in .env.local and in every environment that builds or runs the app (on Vercel: Production and Preview)." : "";
+		throw new TypeError(`[askdare] Invalid bot "${String(definition.id)}": ${issues}.${hint}`);
+	}
+	const { instructions } = definition;
+	const widget = definition.widget ?? {};
+	const locale = widget.locale ?? "en";
+	const overrides = Object.freeze({
+		...widget.texts,
+		...widget.title ? { "header.title": widget.title } : {},
+		...widget.greeting ? { "welcome.greeting": widget.greeting } : {},
+		...widget.placeholder ? { "composer.placeholder": widget.placeholder } : {},
+		...widget.launcherLabel ? { "launcher.label": widget.launcherLabel } : {}
+	});
+	const texts = textsFor(locale === "auto" ? "en" : locale, overrides);
+	const theme = resolveTheme(definition.widget?.theme, definition.widget?.colorScheme ?? "auto");
+	if (typeof definition.widget?.theme === "object" && globalThis.process?.env?.["NODE_ENV"] !== "production") for (const warning of themeWarnings(theme)) console.warn(`[askdare] Bot "${definition.id}" theme: ${warning}.`);
+	return Object.freeze({
+		id: definition.id,
+		model: definition.model.trim(),
+		instructions: typeof instructions === "string" ? () => instructions : instructions,
+		limits: Object.freeze({
+			...DEFAULT_LIMITS,
+			...definition.limits
+		}),
+		tools: Object.freeze([...definition.tools ?? []]),
+		pageContext: definition.pageContext ?? false,
+		knowledge: definition.knowledge ? Object.freeze({
+			vectorStoreId: definition.knowledge.vectorStoreId,
+			maxResults: definition.knowledge.maxResults ?? 5
+		}) : void 0,
+		attachments: definition.attachments ? Object.freeze({
+			images: definition.attachments.images ?? true,
+			pdf: definition.attachments.pdf ?? true,
+			maxBytes: definition.attachments.maxBytes ?? 4e6,
+			maxPerMessage: definition.attachments.maxPerMessage ?? 3,
+			maxPdfPages: definition.attachments.maxPdfPages ?? 50
+		}) : void 0,
+		voice: definition.voice ? Object.freeze({
+			model: definition.voice.model.trim(),
+			maxSeconds: definition.voice.maxSeconds ?? 60
+		}) : void 0,
+		security: Object.freeze({ allowedOrigins: Object.freeze([...new Set(definition.security?.allowedOrigins ?? [])]) }),
+		widget: Object.freeze({
+			title: texts["header.title"] ?? "",
+			subtitle: widget.subtitle ?? "",
+			greeting: texts["welcome.greeting"] ?? "",
+			placeholder: texts["composer.placeholder"] ?? "",
+			locale,
+			starters: Object.freeze([...widget.starters ?? []]),
+			avatar: widget.avatar,
+			launcherLabel: texts["launcher.label"] ?? "",
+			texts: overrides,
+			disclosure: widget.disclosure === false ? false : Object.freeze({ privacyUrl: widget.disclosure?.privacyUrl }),
+			css: widget.css ?? "",
+			theme
+		})
+	});
+}
+// src/tools/define-tool.ts
+const TOOL_NAME = /^[a-zA-Z0-9_-]{1,64}$/;
+/** Finds fields OpenAI strict mode would reject, so they fail at startup instead of mid-chat. */
+function strictModeProblems(schema, path) {
+	if (schema instanceof z.ZodOptional || schema instanceof z.ZodDefault) return [`${path || "(root)"} is optional; use .nullable() so the field is always present`];
+	if (schema instanceof z.ZodNullable) return strictModeProblems(schema.unwrap(), path);
+	if (schema instanceof z.ZodArray) return strictModeProblems(schema.element, `${path}[]`);
+	if (schema instanceof z.ZodObject) return Object.entries(schema.shape).flatMap(([key, value]) => strictModeProblems(value, path ? `${path}.${key}` : key));
+	return [];
+}
+/**
+* Declares a server-side function the model may call. Arguments are validated with the schema
+* before `execute` runs; failures are reported to the model, never to the visitor.
+*/
+function defineTool(definition) {
+	const problems = [];
+	if (!TOOL_NAME.test(definition.name)) problems.push("name must be 1-64 letters, digits, \"_\" or \"-\"");
+	if (definition.description.trim() === "") problems.push("description must not be empty");
+	if (!(definition.input instanceof z.ZodObject)) problems.push("input must be a z.object schema");
+	else problems.push(...strictModeProblems(definition.input, ""));
+	const timeoutMs = definition.timeoutMs ?? 1e4;
+	if (!Number.isInteger(timeoutMs) || timeoutMs < 100 || timeoutMs > 12e4) problems.push("timeoutMs must be an integer between 100 and 120000");
+	if (problems.length > 0) throw new TypeError(`[askdare] Invalid tool "${definition.name}": ${problems.join("; ")}`);
+	return Object.freeze({
+		name: definition.name,
+		description: definition.description.trim(),
+		input: definition.input,
+		execute: definition.execute,
+		timeoutMs
+	});
+}
+export { PROTOCOL_VERSION, defineBot, defineTheme, defineTool };

package/dist/next.d.ts

@@ -0,0 +1,86 @@
+import { i as Bot, n as RateLimitStore } from "./store.js";
+/**
+ * Which proxy to trust when reading the client IP:
+ * - `vercel`: Vercel overwrites `x-forwarded-for` and sets `x-real-ip`, so both are reliable.
+ * - `heroku`: Heroku's router appends the client IP, so the last entry is reliable and anything to
+ *   its left may be spoofed.
+ * - a number `n`: there are `n` trusted proxies; take the n-th entry from the right.
+ * - `auto` (default): `vercel` when `VERCEL` is set, otherwise one trusted proxy.
+ *
+ * Never expose `next start` without a proxy in front: the client then controls these headers.
+ */
+type TrustProxy = "auto" | "vercel" | "heroku" | number;
+/** Stable error codes sent to clients. The accompanying message never contains internals. */
+declare const ERROR_CODES: readonly ["invalid_input", "unauthorized", "session_expired", "not_found", "rate_limited", "budget_exceeded", "bot_unavailable", "content_blocked", "timeout", "upstream_error", "internal_error"];
+type ErrorCode = (typeof ERROR_CODES)[number];
+interface ChatHandlerOptions {
+  readonly bots: readonly Bot[];
+  /** Path of the catch-all route. Default `/api/chat` (route file `app/api/chat/[...path]/route.ts`). */
+  readonly basePath?: string;
+  /** Default `process.env.OPENAI_API_KEY`. */
+  readonly openaiApiKey?: string;
+  /** Token secret, at least 32 characters. Default `process.env.CHAT_SECRET`. */
+  readonly secret?: string;
+  /** Former secrets still accepted during rotation. Default: comma-separated `process.env.CHAT_SECRET_PREVIOUS`. */
+  readonly previousSecrets?: readonly string[];
+  /**
+   * Secret the site's backend signs identity tokens with, for `askdare('identify')` (ADR-0009).
+   * At least 32 random characters, different from `secret`. Default `process.env.IDENTITY_SECRET`;
+   * without one, identity is off.
+   */
+  readonly identitySecret?: string;
+  readonly limits?: ChatHandlerLimitsOptions;
+  /**
+   * Called for every server error (status 500 and up), for an error that ends a streamed answer,
+   * and once a day when a bot-wide or the global budget runs out, for your monitoring, such as Sentry.
+   * Defaults to one `console.error` line with a pointer to the troubleshooting guide. Never
+   * receives message contents or API keys.
+   */
+  readonly onError?: (report: ChatErrorReport) => void;
+  /**
+   * Serves the state gallery: `/embed/<bot>?gallery=<state>&preset=<preset>&scheme=<scheme>`
+   * renders fixture states without calling the model. For development and visual tests; leave
+   * it off in production.
+   */
+  readonly gallery?: boolean;
+}
+/** One server error, as `onError` receives it. */
+interface ChatErrorReport {
+  /** The stable code the widget also receives, such as `bot_unavailable` or `upstream_error`. */
+  readonly code: ErrorCode;
+  /** What went wrong, for you: a missing key, a model the project can't use. Never shown to visitors. */
+  readonly message: string;
+  /** The underlying error, with any API key cut down to its prefix. */
+  readonly cause?: unknown;
+}
+interface ChatHandlerLimitsOptions {
+  /**
+   * Counter storage for rate limits and budgets. Defaults to per-process memory, which is weak when
+   * several instances serve traffic; use `@boldare/askdare-upstash` there.
+   */
+  readonly store?: RateLimitStore;
+  /** How to read the client IP behind your proxy. Default `auto` (Vercel, otherwise one proxy). */
+  readonly trustProxy?: TrustProxy;
+  /** Input plus output tokens per UTC day across all bots. Unlimited by default. */
+  readonly globalDailyTokens?: number;
+}
+type RouteHandler = (request: Request) => Promise<Response>;
+interface ChatHandlers {
+  readonly GET: RouteHandler;
+  readonly POST: RouteHandler;
+  readonly DELETE: RouteHandler;
+}
+/**
+ * Creates the Next.js route handlers for askdare. Mount them in a catch-all route:
+ *
+ * ```ts
+ * // app/api/chat/[...path]/route.ts
+ * export const maxDuration = 300;
+ * export const { GET, POST, DELETE } = createChatHandler({ bots });
+ * ```
+ *
+ * Secrets are read on the first request, so importing the route (for example during
+ * `next build`) never requires them.
+ */
+export declare function createChatHandler(options: ChatHandlerOptions): ChatHandlers;
+export type { ChatErrorReport, ChatHandlerLimitsOptions, ChatHandlerOptions, ChatHandlers, RouteHandler, TrustProxy };