@diegoaltoworks/chatter 0.29.0 → 0.31.0

package/dist/personas/index.mjs

@@ -0,0 +1,177 @@
+// src/personas/greeter.ts
+function capitalize(name) {
+  return name.charAt(0).toUpperCase() + name.slice(1);
+}
+function createGreeter({
+  resolver,
+  templates,
+  random = Math.random
+}) {
+  return {
+    greet(contactId) {
+      try {
+        const contact = resolver.contactFor(contactId);
+        if (!contact?.name) return null;
+        const personaId = resolver.rollPersonaId(contactId) ?? resolver.defaultPersonaId();
+        const pool = personaId ? templates[personaId] : void 0;
+        if (!pool || pool.length === 0) return null;
+        const template = pool[Math.floor(random() * pool.length)];
+        if (!template) return null;
+        return template.replaceAll("{name}", capitalize(contact.name));
+      } catch {
+        return null;
+      }
+    }
+  };
+}
+
+// src/personas/resolver.ts
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+var DEFAULT_WINDOW_MINUTES = 10;
+var DEFAULT_PROBABILITY = 0.5;
+function interpolate(template, vars) {
+  return Object.entries(vars).reduce(
+    (acc, [key, value]) => acc.replaceAll(`{{${key}}}`, value),
+    template
+  );
+}
+function createPersonaResolver(options = {}) {
+  if (!options.registry && !options.registryPath) {
+    throw new Error("createPersonaResolver requires a registry or registryPath");
+  }
+  const random = options.random ?? Math.random;
+  const now = options.now ?? Date.now;
+  const vars = options.vars ?? {};
+  const promptsDir = options.promptsDir ?? (options.registryPath ? dirname(options.registryPath) : process.cwd());
+  let registry = options.registry;
+  let registryLoadError;
+  const promptCache = /* @__PURE__ */ new Map();
+  const window = /* @__PURE__ */ new Map();
+  const warned = /* @__PURE__ */ new Set();
+  function warnOnce(kind, message, error) {
+    if (warned.has(kind)) return;
+    warned.add(kind);
+    console.warn(message, error);
+  }
+  function loadRegistry() {
+    if (registry) return registry;
+    if (registryLoadError !== void 0) throw registryLoadError;
+    try {
+      registry = JSON.parse(readFileSync(options.registryPath, "utf-8"));
+      return registry;
+    } catch (error) {
+      registryLoadError = error;
+      warnOnce(
+        "registry",
+        `Persona registry load failed (${options.registryPath}); falling back to the default persona for every contact.`,
+        error
+      );
+      throw error;
+    }
+  }
+  function contactFor(contactId) {
+    try {
+      return loadRegistry().contacts?.[contactId];
+    } catch {
+      return void 0;
+    }
+  }
+  function rollPersonaId(contactId) {
+    try {
+      const reg = loadRegistry();
+      const nowMs = now();
+      const existing = window.get(contactId);
+      if (existing && existing.expiresAt > nowMs) {
+        return existing.personaId;
+      }
+      for (const [key, value] of window) {
+        if (value.expiresAt <= nowMs) window.delete(key);
+      }
+      const contact = reg.contacts?.[contactId];
+      let personaId = null;
+      const probability = contact?.probability ?? reg.personaProbability ?? DEFAULT_PROBABILITY;
+      if (contact && random() < probability) {
+        personaId = contact.persona === reg.defaultPersona ? null : contact.persona;
+      }
+      const windowMs = (reg.personaWindowMinutes ?? DEFAULT_WINDOW_MINUTES) * 60 * 1e3;
+      window.set(contactId, { personaId, expiresAt: nowMs + windowMs });
+      return personaId;
+    } catch {
+      return null;
+    }
+  }
+  function personaLayerFor(personaId) {
+    if (!personaId) return null;
+    try {
+      const definition = loadRegistry().personas[personaId];
+      if (!definition) return null;
+      if (promptCache.has(personaId)) return promptCache.get(personaId) ?? null;
+      try {
+        const prompt = interpolate(
+          readFileSync(resolve(promptsDir, definition.prompt), "utf-8"),
+          vars
+        );
+        promptCache.set(personaId, prompt);
+        return prompt;
+      } catch (error) {
+        promptCache.set(personaId, null);
+        warnOnce(
+          `prompt:${personaId}`,
+          `Persona prompt load failed for "${personaId}" (${definition.prompt}); falling back to the default persona.`,
+          error
+        );
+        return null;
+      }
+    } catch {
+      return null;
+    }
+  }
+  function defaultPersonaId() {
+    try {
+      return loadRegistry().defaultPersona ?? null;
+    } catch {
+      return null;
+    }
+  }
+  function resolvePersonaLayer(contactId) {
+    return personaLayerFor(rollPersonaId(contactId)) ?? personaLayerFor(defaultPersonaId());
+  }
+  return {
+    rollPersonaId,
+    resolvePersonaLayer,
+    personaLayerFor,
+    contactFor,
+    defaultPersonaId
+  };
+}
+
+// src/personas/timeContext.ts
+function timeContext(zones, now = Date.now()) {
+  if (zones.length === 0) return "";
+  const at = new Date(now);
+  const parts = zones.flatMap((zone) => {
+    try {
+      const formatted = new Intl.DateTimeFormat("en-GB", {
+        timeZone: zone,
+        weekday: "long",
+        day: "numeric",
+        month: "long",
+        year: "numeric",
+        hour: "2-digit",
+        minute: "2-digit",
+        hour12: false
+      }).format(at);
+      return [`${formatted} (${zone})`];
+    } catch {
+      return [];
+    }
+  });
+  if (parts.length === 0) return "";
+  return `Current date and time: ${parts.join(" / ")}.`;
+}
+export {
+  createGreeter,
+  createPersonaResolver,
+  timeContext
+};

package/dist/personas/resolver.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Persona registry resolver — windowed persona selection driven by a JSON
+ * registry. Framework-free and content-free: it knows how to roll and load a
+ * persona layer, never what a persona says. A registry/prompt failure
+ * degrades to `null` (the caller's default layer) rather than throwing into
+ * a chat request.
+ */
+export interface PersonaDefinition {
+    name: string;
+    /** Path to the persona's prompt file, resolved against `promptsDir`. */
+    prompt: string;
+    language?: string;
+}
+export interface PersonaContact {
+    name?: string;
+    role?: string;
+    /** Persona id rolled for this contact. */
+    persona: string;
+    /** Overrides `personaProbability` for this contact when set. */
+    probability?: number;
+}
+export interface PersonaRegistry {
+    /** Persona id used when a contact is unmapped or its roll doesn't land. */
+    defaultPersona: string;
+    /** 0–1 chance a mapped contact gets their persona on a fresh roll. Default 0.5. */
+    personaProbability?: number;
+    /** Minutes a roll is held before the next message re-rolls it. Default 10. */
+    personaWindowMinutes?: number;
+    contacts?: Record<string, PersonaContact>;
+    personas: Record<string, PersonaDefinition>;
+}
+export interface PersonaResolverOptions {
+    /** Inline registry — takes priority over `registryPath` when both are set. */
+    registry?: PersonaRegistry;
+    /** Path to a JSON registry file, read once and memoized. */
+    registryPath?: string;
+    /** Base directory prompt paths resolve against. Defaults to `registryPath`'s directory, or cwd for an inline registry. */
+    promptsDir?: string;
+    /** Injectable randomness for tests. Default `Math.random`. */
+    random?: () => number;
+    /** Injectable clock for tests. Default `Date.now`. */
+    now?: () => number;
+    /** Template vars (`{{name}}`) interpolated into loaded prompt files. */
+    vars?: Record<string, string>;
+}
+export interface PersonaResolver {
+    /**
+     * The persona id in effect for a contact right now: rolled at
+     * `personaProbability` once per window, held for `personaWindowMinutes`.
+     * `null` means "use the default persona" (unmapped contact or a lost roll).
+     */
+    rollPersonaId(contactId: string): string | null;
+    /**
+     * The interpolated prompt layer for the contact's currently-held persona,
+     * falling back to the default persona's layer. Feeds `prepareChat`'s
+     * `personaLayer` directly.
+     */
+    resolvePersonaLayer(contactId: string): string | null;
+    /** Deterministic layer for an explicit persona id (no dice roll), or null. */
+    personaLayerFor(personaId: string | null): string | null;
+    /** Registry contact record, or undefined. */
+    contactFor(contactId: string): PersonaContact | undefined;
+    /** The registry's configured default persona id, or null on failure. */
+    defaultPersonaId(): string | null;
+}
+export declare function createPersonaResolver(options?: PersonaResolverOptions): PersonaResolver;
+//# sourceMappingURL=resolver.d.ts.map

package/dist/personas/resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../../src/personas/resolver.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,cAAc,EAAE,MAAM,CAAC;IACvB,mFAAmF;IACnF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,8EAA8E;IAC9E,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC1C,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,sBAAsB;IACrC,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,4DAA4D;IAC5D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0HAA0H;IAC1H,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;IACtB,sDAAsD;IACtD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAChD;;;;OAIG;IACH,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACtD,8EAA8E;IAC9E,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAAC;IACzD,6CAA6C;IAC7C,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAAC;IAC1D,wEAAwE;IACxE,gBAAgB,IAAI,MAAM,GAAG,IAAI,CAAC;CACnC;AAYD,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,sBAA2B,GAAG,eAAe,CA+H3F"}

package/dist/personas/resolver.test.d.ts

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

package/dist/personas/resolver.test.d.ts.map

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

package/dist/personas/timeContext.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Live clock line for prompts that answer time-relative questions ("what's
+ * next", "today", "tomorrow") — a chat surface has no other way to know the
+ * current date/time for the zones it cares about.
+ */
+export declare function timeContext(zones: string[], now?: number): string;
+//# sourceMappingURL=timeContext.d.ts.map

package/dist/personas/timeContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeContext.d.ts","sourceRoot":"","sources":["../../src/personas/timeContext.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,CAuB7E"}

package/dist/personas/timeContext.test.d.ts

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

package/dist/personas/timeContext.test.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegoaltoworks/chatter",
-  "version": "0.29.0",
+  "version": "0.31.0",
   "description": "Embeddable AI chatbot framework with RAG, authentication, and customizable widgets",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -35,6 +35,11 @@
       "import": "./dist/usage/index.mjs",
       "require": "./dist/usage/index.js"
     },
+    "./personas": {
+      "types": "./dist/personas/index.d.ts",
+      "import": "./dist/personas/index.mjs",
+      "require": "./dist/personas/index.js"
+    },
     "./channels": {
       "types": "./dist/channels/index.d.ts",
       "import": "./dist/channels/index.mjs",
@@ -53,13 +58,14 @@
   ],
   "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: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: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",
     "build:cjs": "esbuild src/index.ts --bundle --format=cjs --outfile=dist/index.js --external:hono --external:openai --external:@libsql/client --external:jose --platform=node --target=node24",
     "build:mcp": "esbuild src/mcp-server.ts --bundle --format=esm --outfile=dist/mcp-server.mjs --external:@modelcontextprotocol/sdk --external:openai --external:@libsql/client --external:zod --platform=node --target=node24 && esbuild src/mcp-server.ts --bundle --format=cjs --outfile=dist/mcp-server.js --external:@modelcontextprotocol/sdk --external:openai --external:@libsql/client --external:zod --platform=node --target=node24",
     "build:usage": "esbuild src/usage/index.ts --bundle --format=esm --outfile=dist/usage/index.mjs --external:@libsql/client --platform=node --target=node24 && esbuild src/usage/index.ts --bundle --format=cjs --outfile=dist/usage/index.js --external:@libsql/client --platform=node --target=node24",
+    "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: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'",