@diegoaltoworks/chatter 0.31.0 → 0.32.0

package/dist/flows/types.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Flow engine types.
+ *
+ * A flow is a directory-loaded contract: `flow.json` (id/name/description/
+ * triggerKeywords/schema), `handler.ts` (an `execute` export) and
+ * `instructions.md` (the prompt fed to parameter extraction), with an
+ * optional `prefill.ts` (`prefillFromContext` export). This is the same
+ * on-disk shape the reference implementation used — existing flow
+ * directories load unchanged.
+ */
+export interface FlowSchemaProperty {
+    type: "string" | "number" | "boolean";
+    description?: string;
+}
+export interface FlowSchema {
+    type: "object";
+    properties: Record<string, FlowSchemaProperty>;
+    required: string[];
+}
+/** Parsed `flow.json`. */
+export interface FlowDefinition {
+    id: string;
+    name: string;
+    description: string;
+    triggerKeywords: string[];
+    schema: FlowSchema;
+}
+/** What a handler is given alongside the collected params. */
+export interface FlowHandlerContext {
+    /** Caller-chosen id for this conversation — a phone number, a WhatsApp JID, a web session id. Channel-agnostic by design. */
+    sessionKey: string;
+    /** Free-form channel label, when the caller knows one. Not interpreted by the engine. */
+    channel?: string;
+}
+/**
+ * What a flow hands back once its params are complete.
+ *
+ * Deliberately presentation-free: no per-channel text. A flow returns one
+ * message plus a structured `result`; rendering it for voice, SMS, WhatsApp
+ * or anything else is the calling plugin's job, not the engine's.
+ */
+export interface FlowHandlerResult {
+    /**
+     * Whether the flow itself completed successfully. `success: false` is for
+     * "something went wrong that the caller should treat generically" — a flow
+     * that wants its own in-persona message for an expected failure (validation,
+     * a caught upstream error) should still report `success: true`.
+     */
+    success: boolean;
+    message: string;
+    result?: unknown;
+}
+export type FlowHandler = (params: Record<string, unknown>, context: FlowHandlerContext) => Promise<FlowHandlerResult>;
+/** Seeds params from context before extraction runs — e.g. a caller id already known from the channel. */
+export type FlowPrefill = (sessionKey: string, context: Record<string, unknown>) => Record<string, unknown>;
+export interface LoadedFlow {
+    definition: FlowDefinition;
+    handler: FlowHandler;
+    instructionsPath: string;
+    prefill?: FlowPrefill;
+}
+export interface FlowExtractionResult {
+    extractedParams: Record<string, unknown>;
+    allParamsFilled: boolean;
+    nextPrompt?: string;
+}
+export interface IntentDetection {
+    intent: string;
+    confidence: number;
+    reasoning?: string;
+}
+/** Multi-turn state persisted between messages while a flow is collecting params. */
+export interface FlowSessionState {
+    flowId: string;
+    params: Record<string, unknown>;
+    attempts: number;
+    startedAt: number;
+}
+/**
+ * Structural dependency for session persistence — a host supplies an
+ * implementation (see `./session` for the shipped Turso binding). Must be
+ * safe under a multi-instance deployment: state written by one instance has
+ * to be visible to whichever instance handles the next message.
+ */
+export interface FlowSessionStore {
+    get(sessionKey: string): Promise<FlowSessionState | null>;
+    set(sessionKey: string, state: FlowSessionState): Promise<void>;
+    clear(sessionKey: string): Promise<void>;
+}
+export interface FlowResult {
+    isFlowActive: boolean;
+    message: string;
+    flowCompleted: boolean;
+    flowSuccess?: boolean;
+    result?: unknown;
+    /** The caller cancelled an active flow. */
+    cancelled?: boolean;
+    /** Flow processing failed (registry lookup, parameter extraction, or handler). */
+    error?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/flows/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/flows/types.ts"],"names":[],"mappings":"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"}

package/dist/flows/utils.d.ts

@@ -0,0 +1,4 @@
+/** Cancellation-phrase detection, kept separate because it's pure and cheap to check before any LLM call. */
+/** Whether `message` expresses wanting to exit the active flow. */
+export declare function shouldExitFlow(message: string, cancelKeywords?: string[]): boolean;
+//# sourceMappingURL=utils.d.ts.map

package/dist/flows/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/flows/utils.ts"],"names":[],"mappings":"AAAA,6GAA6G;AAa7G,mEAAmE;AACnE,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,cAAc,GAAE,MAAM,EAA4B,GACjD,OAAO,CAET"}

package/dist/flows/utils.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=utils.test.d.ts.map

package/dist/flows/utils.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.test.d.ts","sourceRoot":"","sources":["../../src/flows/utils.test.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegoaltoworks/chatter",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "Embeddable AI chatbot framework with RAG, authentication, and customizable widgets",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -45,6 +45,11 @@
       "import": "./dist/channels/index.mjs",
       "require": "./dist/channels/index.js"
     },
+    "./flows": {
+      "types": "./dist/flows/index.d.ts",
+      "import": "./dist/flows/index.mjs",
+      "require": "./dist/flows/index.js"
+    },
     "./whatsapp": {
       "types": "./dist/channels/whatsapp/index.d.ts",
       "import": "./dist/channels/whatsapp/index.mjs",
@@ -58,7 +63,7 @@
   ],
   "scripts": {
     "dev": "bun --watch src/index.ts",
-    "build": "bun run build:clean && bun run build:types && bun run build:esm && bun run build:cjs && bun run build:mcp && bun run build:usage && bun run build:personas && bun run build:channels && bun run build:whatsapp && bun run build:bin && bun run build:client && bun run build:copy-client",
+    "build": "bun run build:clean && bun run build:types && bun run build:esm && bun run build:cjs && bun run build:mcp && bun run build:usage && bun run build:personas && bun run build:channels && bun run build:whatsapp && bun run build:flows && bun run build:bin && bun run build:client && bun run build:copy-client",
     "build:clean": "rm -rf dist",
     "build:types": "tsc --emitDeclarationOnly --outDir dist",
     "build:esm": "esbuild src/index.ts --bundle --format=esm --outfile=dist/index.mjs --external:hono --external:openai --external:@libsql/client --external:jose --platform=node --target=node24",
@@ -68,6 +73,7 @@
     "build:personas": "esbuild src/personas/index.ts --bundle --format=esm --outfile=dist/personas/index.mjs --platform=node --target=node24 && esbuild src/personas/index.ts --bundle --format=cjs --outfile=dist/personas/index.js --platform=node --target=node24",
     "build:channels": "esbuild src/channels/index.ts --bundle --format=esm --outfile=dist/channels/index.mjs --external:hono --external:openai --external:@libsql/client --platform=node --target=node24 && esbuild src/channels/index.ts --bundle --format=cjs --outfile=dist/channels/index.js --external:hono --external:openai --external:@libsql/client --platform=node --target=node24",
     "build:whatsapp": "esbuild src/channels/whatsapp/index.ts --bundle --format=esm --outfile=dist/channels/whatsapp/index.mjs --external:@libsql/client --external:@whiskeysockets/baileys --platform=node --target=node24 && esbuild src/channels/whatsapp/index.ts --bundle --format=cjs --outfile=dist/channels/whatsapp/index.js --external:@libsql/client --external:@whiskeysockets/baileys --platform=node --target=node24",
+    "build:flows": "esbuild src/flows/index.ts --bundle --format=esm --outfile=dist/flows/index.mjs --external:@libsql/client --external:openai --platform=node --target=node24 && esbuild src/flows/index.ts --bundle --format=cjs --outfile=dist/flows/index.js --external:@libsql/client --external:openai --platform=node --target=node24",
     "build:bin": "esbuild bin/create-apikey.ts --bundle --format=cjs --outfile=dist/bin/create-apikey.js --external:jose --platform=node --target=node18 --banner:js='#!/usr/bin/env node' && esbuild bin/wa-pair.ts --bundle --format=cjs --outfile=dist/bin/wa-pair.js --external:@libsql/client --external:@whiskeysockets/baileys --external:qrcode-terminal --platform=node --target=node18 --banner:js='#!/usr/bin/env node'",
     "build:client": "cd src/client && bun run build",
     "build:copy-client": "mkdir -p dist/static && cp src/client/dist/chatter.js src/client/dist/chatter.css dist/static/",