@diegoaltoworks/chatter 0.34.0 → 0.36.0

package/dist/index.d.ts

@@ -42,5 +42,7 @@ export { privateRoutes } from "./routes/private";
 export { publicRoutes } from "./routes/public";
 export type { ChatterApp } from "./server";
 export { createServer } from "./server";
+export type { Shortener, ShortenerConfig } from "./shortener";
+export { createShortener } from "./shortener";
 export type { BotBranding, BotChatConfig, BotIdentity, ChatterConfig, CustomRoutes, EmbeddingChunk, KnowledgeDocument, ServerDependencies, } from "./types";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAEzE,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAIvC,YAAY,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC1C,YAAY,EACV,aAAa,EACb,gBAAgB,EAChB,UAAU,EACV,WAAW,EACX,QAAQ,EACR,eAAe,GAChB,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACrD,YAAY,EACV,QAAQ,EACR,aAAa,EACb,cAAc,EACd,aAAa,EACb,WAAW,GACZ,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AACzD,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEpE,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC5E,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACzE,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,YAAY,EAAE,eAAe,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEnF,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE3D,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,eAAe,GAChB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEvE,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAG/C,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AACzC,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,YAAY,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAExC,YAAY,EACV,WAAW,EACX,aAAa,EACb,WAAW,EACX,aAAa,EACb,YAAY,EACZ,cAAc,EACd,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAEzE,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAIvC,YAAY,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC1C,YAAY,EACV,aAAa,EACb,gBAAgB,EAChB,UAAU,EACV,WAAW,EACX,QAAQ,EACR,eAAe,GAChB,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACrD,YAAY,EACV,QAAQ,EACR,aAAa,EACb,cAAc,EACd,aAAa,EACb,WAAW,GACZ,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AACzD,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEpE,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC5E,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACzE,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,YAAY,EAAE,eAAe,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEnF,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE3D,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,eAAe,GAChB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEvE,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAG/C,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AACzC,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,YAAY,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,YAAY,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9D,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,YAAY,EACV,WAAW,EACX,aAAa,EACb,WAAW,EACX,aAAa,EACb,YAAY,EACZ,cAAc,EACd,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -7550,6 +7550,7 @@ __export(index_exports, {
   createServer: () => createServer,
   createSession: () => createSession,
   createSessionMiddleware: () => createSessionMiddleware,
+  createShortener: () => createShortener,
   defaultBuckets: () => defaultBuckets,
   demoRoutes: () => demoRoutes,
   detectLeakage: () => detectLeakage,
@@ -33396,6 +33397,40 @@ async function createServer(config2) {
     }
   });
 }
+
+// src/shortener.ts
+var DEFAULT_TIMEOUT_MS = 5e3;
+function createShortener(config2, fetchImpl = fetch) {
+  const apiUrl = config2.apiUrl.replace(/\/+$/, "");
+  return {
+    async shorten(url2) {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), config2.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+      try {
+        const response = await fetchImpl(`${apiUrl}/api/v2/links`, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "X-API-Key": config2.apiKey
+          },
+          body: JSON.stringify({ target: url2, domain: config2.domain }),
+          signal: controller.signal
+        });
+        if (!response.ok) {
+          await response.text().catch(() => "");
+          return url2;
+        }
+        const data = await response.json();
+        if (typeof data.link !== "string") return url2;
+        return data.link.replace(/^http:\/\//, "https://");
+      } catch {
+        return url2;
+      } finally {
+        clearTimeout(timeout);
+      }
+    }
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ApiKeyManager,
@@ -33418,6 +33453,7 @@ async function createServer(config2) {
   createServer,
   createSession,
   createSessionMiddleware,
+  createShortener,
   defaultBuckets,
   demoRoutes,
   detectLeakage,

package/dist/index.mjs

@@ -33358,6 +33358,40 @@ async function createServer(config2) {
     }
   });
 }
+
+// src/shortener.ts
+var DEFAULT_TIMEOUT_MS = 5e3;
+function createShortener(config2, fetchImpl = fetch) {
+  const apiUrl = config2.apiUrl.replace(/\/+$/, "");
+  return {
+    async shorten(url2) {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), config2.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+      try {
+        const response = await fetchImpl(`${apiUrl}/api/v2/links`, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "X-API-Key": config2.apiKey
+          },
+          body: JSON.stringify({ target: url2, domain: config2.domain }),
+          signal: controller.signal
+        });
+        if (!response.ok) {
+          await response.text().catch(() => "");
+          return url2;
+        }
+        const data = await response.json();
+        if (typeof data.link !== "string") return url2;
+        return data.link.replace(/^http:\/\//, "https://");
+      } catch {
+        return url2;
+      } finally {
+        clearTimeout(timeout);
+      }
+    }
+  };
+}
 var export_Chat = import_client3.Chat;
 var export_ChatBot = import_client3.ChatBot;
 var export_ChatButton = import_client3.ChatButton;
@@ -33382,6 +33416,7 @@ export {
   createServer,
   createSession,
   createSessionMiddleware,
+  createShortener,
   defaultBuckets,
   demoRoutes,
   detectLeakage,

package/dist/scheduler/claimStore.d.ts

@@ -0,0 +1,27 @@
+/**
+ * A Turso-backed exactly-once claim: an atomic upsert means two instances
+ * racing the same entry can never both believe they claimed it — see
+ * `canClaim`, which mirrors `canAcquireLease` in
+ * `../channels/whatsapp/lease.ts`. A failed send calls `release` to delete
+ * the claim row, letting the entry be claimed again by whichever instance
+ * ticks next within the grace window. An instance that dies mid-delivery
+ * without releasing leaves its claim to go stale instead: after
+ * `claimTimeoutMs` with no renewal, another instance may take it over.
+ */
+import type { Client } from "@libsql/client";
+import type { ScheduleClaimStore } from "./types";
+export declare const DEFAULT_CLAIM_TABLE = "chatter_schedule_claims";
+/** How long an unreleased claim blocks reclaiming — short relative to a typical grace window, so a crashed claimant frees up in time for a retry to still land within grace. */
+export declare const DEFAULT_CLAIM_TIMEOUT_MS: number;
+export interface ScheduleClaimRow {
+    instanceId: string;
+    claimedAt: number;
+}
+/**
+ * Pure: may `instanceId` take (or keep) the claim on an entry right now,
+ * given the current row (null = unclaimed)? Mirrors the SQL WHERE clause in
+ * `createTursoScheduleClaimStore` — keep the two in sync.
+ */
+export declare function canClaim(existing: ScheduleClaimRow | null, instanceId: string, now: number, claimTimeoutMs: number): boolean;
+export declare function createTursoScheduleClaimStore(client: Client, instanceId: string, tableName?: string, claimTimeoutMs?: number): ScheduleClaimStore;
+//# sourceMappingURL=claimStore.d.ts.map

package/dist/scheduler/claimStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claimStore.d.ts","sourceRoot":"","sources":["../../src/scheduler/claimStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAElD,eAAO,MAAM,mBAAmB,4BAA4B,CAAC;AAC7D,gLAAgL;AAChL,eAAO,MAAM,wBAAwB,QAAa,CAAC;AAKnD,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CACtB,QAAQ,EAAE,gBAAgB,GAAG,IAAI,EACjC,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,EACX,cAAc,EAAE,MAAM,GACrB,OAAO,CAIT;AA8BD,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,SAAS,GAAE,MAA4B,EACvC,cAAc,GAAE,MAAiC,GAChD,kBAAkB,CA4BpB"}

package/dist/scheduler/claimStore.test.d.ts

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

package/dist/scheduler/claimStore.test.d.ts.map

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

package/dist/scheduler/compose.d.ts

@@ -0,0 +1,23 @@
+import type OpenAI from "openai";
+import type { AnswerFn } from "../core/answer";
+import type { PipelineMessage, PipelineMode } from "../core/pipeline";
+import type { ComposeFn, ScheduleEntry } from "./types";
+/**
+ * Runs the pluggable compose step and guarantees a message comes back: a
+ * missing compose function, a blank result, or a throwing/rejecting compose
+ * all fall back to `fallbackMessage` rather than blocking delivery.
+ */
+export declare function composeMessage(entry: ScheduleEntry, compose: ComposeFn | undefined, fallbackMessage: string): Promise<string>;
+export interface AnswerComposeOptions {
+    client: OpenAI;
+    system: string;
+    /** Turns a schedule entry's opaque payload into the messages sent to the brain. */
+    buildMessages: (entry: ScheduleEntry) => PipelineMessage[];
+    answerFn?: AnswerFn;
+    mode?: PipelineMode;
+    temperature?: number;
+    model?: string;
+}
+/** Builds a `ComposeFn` that composes via `answerFn`/`completeOnce`, for callers who want an LLM-written message instead of static text. */
+export declare function createAnswerCompose(options: AnswerComposeOptions): ComposeFn;
+//# sourceMappingURL=compose.d.ts.map

package/dist/scheduler/compose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../../src/scheduler/compose.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AACjC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAExD;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE,SAAS,GAAG,SAAS,EAC9B,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,MAAM,CAAC,CASjB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,mFAAmF;IACnF,aAAa,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,eAAe,EAAE,CAAC;IAC3D,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,4IAA4I;AAC5I,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,SAAS,CAa5E"}

package/dist/scheduler/compose.test.d.ts

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

package/dist/scheduler/compose.test.d.ts.map

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

package/dist/scheduler/deliver.d.ts

@@ -0,0 +1,10 @@
+import type { ChannelSenderRegistry } from "../channels/senders";
+import type { ScheduleEntry } from "./types";
+export interface DeliverOptions {
+    senders: ChannelSenderRegistry;
+    /** Try voice first when the channel supports it; text is always the guaranteed fallback. */
+    voiceAttempted?: boolean;
+}
+/** Delivers a composed message. Text is guaranteed; voice is only ever a best-effort first attempt. */
+export declare function deliver(entry: ScheduleEntry, message: string, options: DeliverOptions): Promise<boolean>;
+//# sourceMappingURL=deliver.d.ts.map

package/dist/scheduler/deliver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deliver.d.ts","sourceRoot":"","sources":["../../src/scheduler/deliver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,qBAAqB,CAAC;IAC/B,4FAA4F;IAC5F,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,uGAAuG;AACvG,wBAAsB,OAAO,CAC3B,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,OAAO,CAAC,CAMlB"}

package/dist/scheduler/deliver.test.d.ts

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

package/dist/scheduler/deliver.test.d.ts.map

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

package/dist/scheduler/dueDrops.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Pure fire-time filtering. A schedule fires once its time has passed, but
+ * only within a grace window — a stale entry (the process was down, or the
+ * tick was delayed) past grace is skipped rather than delivered late.
+ */
+import type { ScheduleEntry } from "./types";
+export declare function isDue(entry: ScheduleEntry, now: number): boolean;
+export declare function isWithinGrace(entry: ScheduleEntry, now: number, graceMs: number): boolean;
+/** Due entries still inside their grace window, in caller-supplied order. */
+export declare function dueDrops(entries: ScheduleEntry[], now: number, graceMs: number): ScheduleEntry[];
+/** Due entries whose grace window has already passed — reported so callers can log them, never delivered. */
+export declare function staleDrops(entries: ScheduleEntry[], now: number, graceMs: number): ScheduleEntry[];
+//# sourceMappingURL=dueDrops.d.ts.map

package/dist/scheduler/dueDrops.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dueDrops.d.ts","sourceRoot":"","sources":["../../src/scheduler/dueDrops.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,wBAAgB,KAAK,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAEhE;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAEzF;AAED,6EAA6E;AAC7E,wBAAgB,QAAQ,CAAC,OAAO,EAAE,aAAa,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,aAAa,EAAE,CAEhG;AAED,6GAA6G;AAC7G,wBAAgB,UAAU,CACxB,OAAO,EAAE,aAAa,EAAE,EACxB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,GACd,aAAa,EAAE,CAEjB"}

package/dist/scheduler/dueDrops.test.d.ts

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

package/dist/scheduler/dueDrops.test.d.ts.map

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

package/dist/scheduler/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Scheduler — exactly-once outbound delivery on a caller-supplied fire time.
+ * Published as the `@diegoaltoworks/chatter/scheduler` subpath so the core
+ * install stays untouched by it.
+ *
+ * Content-free: chatter stores no schedule data of its own. A caller
+ * supplies candidate {@link ScheduleEntry} objects each tick (its own store,
+ * cron, queue, anything); this module adds the parts that are easy to get
+ * wrong in a multi-instance deployment — an exactly-once claim in Turso so
+ * two instances never both deliver the same entry, a fire-time grace window
+ * so a delayed tick doesn't send stale messages, a pluggable compose step
+ * (static text or an LLM call via `answerFn`/`completeOnce`) that always
+ * falls back rather than blocking delivery, and delivery through the
+ * channel sender registry with an optional voice-attempted/text-guaranteed
+ * mode.
+ *
+ * @packageDocumentation
+ */
+export type { ScheduleClaimRow } from "./claimStore";
+export { canClaim, createTursoScheduleClaimStore, DEFAULT_CLAIM_TABLE, DEFAULT_CLAIM_TIMEOUT_MS, } from "./claimStore";
+export type { AnswerComposeOptions } from "./compose";
+export { composeMessage, createAnswerCompose } from "./compose";
+export type { DeliverOptions } from "./deliver";
+export { deliver } from "./deliver";
+export { dueDrops, isDue, isWithinGrace, staleDrops } from "./dueDrops";
+export type { Scheduler, SchedulerConfig } from "./scheduler";
+export { createScheduler, DEFAULT_FALLBACK_MESSAGE, DEFAULT_GRACE_MS, DEFAULT_INTERVAL_MS, } from "./scheduler";
+export type { TickOptions } from "./tick";
+export { runTick } from "./tick";
+export type { ComposeFn, ScheduleClaimStore, ScheduleEntry, TickResult } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/scheduler/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scheduler/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EACL,QAAQ,EACR,6BAA6B,EAC7B,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAChE,YAAY,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxE,YAAY,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EACL,eAAe,EACf,wBAAwB,EACxB,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACjC,YAAY,EAAE,SAAS,EAAE,kBAAkB,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC"}

package/dist/scheduler/index.js

@@ -0,0 +1,332 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/scheduler/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DEFAULT_CLAIM_TABLE: () => DEFAULT_CLAIM_TABLE,
+  DEFAULT_CLAIM_TIMEOUT_MS: () => DEFAULT_CLAIM_TIMEOUT_MS,
+  DEFAULT_FALLBACK_MESSAGE: () => DEFAULT_FALLBACK_MESSAGE,
+  DEFAULT_GRACE_MS: () => DEFAULT_GRACE_MS,
+  DEFAULT_INTERVAL_MS: () => DEFAULT_INTERVAL_MS,
+  canClaim: () => canClaim,
+  composeMessage: () => composeMessage,
+  createAnswerCompose: () => createAnswerCompose,
+  createScheduler: () => createScheduler,
+  createTursoScheduleClaimStore: () => createTursoScheduleClaimStore,
+  deliver: () => deliver,
+  dueDrops: () => dueDrops,
+  isDue: () => isDue,
+  isWithinGrace: () => isWithinGrace,
+  runTick: () => runTick,
+  staleDrops: () => staleDrops
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/scheduler/claimStore.ts
+var DEFAULT_CLAIM_TABLE = "chatter_schedule_claims";
+var DEFAULT_CLAIM_TIMEOUT_MS = 2 * 6e4;
+var VALID_TABLE_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function canClaim(existing, instanceId, now, claimTimeoutMs) {
+  if (!existing) return true;
+  if (existing.instanceId === instanceId) return true;
+  return now - existing.claimedAt >= claimTimeoutMs;
+}
+var schemaReady = /* @__PURE__ */ new WeakMap();
+function ensureSchema(client, tableName) {
+  let perTable = schemaReady.get(client);
+  if (!perTable) {
+    perTable = /* @__PURE__ */ new Map();
+    schemaReady.set(client, perTable);
+  }
+  let ready = perTable.get(tableName);
+  if (!ready) {
+    const table = perTable;
+    ready = client.execute(
+      `CREATE TABLE IF NOT EXISTS ${tableName} (
+          schedule_id TEXT PRIMARY KEY,
+          instance_id TEXT NOT NULL,
+          claimed_at INTEGER NOT NULL
+        )`
+    ).catch((error) => {
+      table.delete(tableName);
+      throw error;
+    });
+    perTable.set(tableName, ready);
+  }
+  return ready;
+}
+function createTursoScheduleClaimStore(client, instanceId, tableName = DEFAULT_CLAIM_TABLE, claimTimeoutMs = DEFAULT_CLAIM_TIMEOUT_MS) {
+  if (!VALID_TABLE_NAME.test(tableName)) {
+    throw new Error(`Invalid schedule claim table name: ${tableName}`);
+  }
+  return {
+    async claim(id, now) {
+      await ensureSchema(client, tableName);
+      const result = await client.execute({
+        sql: `INSERT INTO ${tableName} (schedule_id, instance_id, claimed_at) VALUES (?, ?, ?)
+              ON CONFLICT(schedule_id) DO UPDATE SET
+                instance_id = excluded.instance_id,
+                claimed_at = excluded.claimed_at
+              WHERE ${tableName}.instance_id = excluded.instance_id
+                 OR ${tableName}.claimed_at <= excluded.claimed_at - ?
+              RETURNING instance_id`,
+        args: [id, instanceId, now, claimTimeoutMs]
+      });
+      const row = result.rows[0];
+      return Boolean(row) && row.instance_id === instanceId;
+    },
+    async release(id) {
+      await ensureSchema(client, tableName);
+      await client.execute({
+        sql: `DELETE FROM ${tableName} WHERE schedule_id = ? AND instance_id = ?`,
+        args: [id, instanceId]
+      });
+    }
+  };
+}
+
+// src/core/guardrails.ts
+function detectLeakage(text) {
+  const flags = [
+    /system prompt/i,
+    /hidden instruction/i,
+    /here (are|is) (my|the) rules/i,
+    /BEGIN SYSTEM PROMPT/i,
+    /tool instructions/i
+  ];
+  return flags.some((rx) => rx.test(text));
+}
+function scrubOutput(text) {
+  return text.replace(/sk-[A-Za-z0-9]{15,}/g, "[REDACTED]").replace(/AIza[0-9A-Za-z_-]{30,}/g, "[REDACTED]");
+}
+function guardOutput(text) {
+  if (detectLeakage(text)) {
+    return "Sorry, I can't share internal instructions. How else can I help?";
+  }
+  return scrubOutput(text);
+}
+
+// src/core/llm.ts
+var DEFAULT_MODEL = "gpt-4o";
+async function completeOnce({
+  client,
+  system,
+  messages,
+  temperature = 0.2,
+  model = DEFAULT_MODEL
+}) {
+  const res = await client.chat.completions.create({
+    model,
+    temperature,
+    messages: [{ role: "system", content: system }, ...messages]
+  });
+  const text = res.choices[0]?.message?.content ?? "";
+  return {
+    content: guardOutput(text),
+    usage: res.usage || { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 }
+  };
+}
+
+// src/core/answer.ts
+var noUsage = () => ({ prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 });
+async function runAnswerFn(answerFn, { system, messages, mode, sender }) {
+  const result = await answerFn({ system, messages, mode, sender });
+  const raw = typeof result === "string" ? result : result?.content;
+  const usage = typeof result === "string" ? void 0 : result?.usage;
+  return {
+    content: guardOutput(typeof raw === "string" ? raw : ""),
+    usage: usage ?? noUsage()
+  };
+}
+async function answerOnce({
+  answerFn,
+  client,
+  system,
+  messages,
+  mode,
+  sender,
+  temperature,
+  model
+}) {
+  if (answerFn) {
+    return runAnswerFn(answerFn, { system, messages, mode, sender });
+  }
+  return completeOnce({ client, system, messages, temperature, model });
+}
+
+// src/scheduler/compose.ts
+async function composeMessage(entry, compose, fallbackMessage) {
+  if (!compose) return fallbackMessage;
+  try {
+    const result = await compose(entry);
+    return result.trim().length > 0 ? result : fallbackMessage;
+  } catch (error) {
+    console.warn(`Scheduler compose failed for entry "${entry.id}":`, error);
+    return fallbackMessage;
+  }
+}
+function createAnswerCompose(options) {
+  return async (entry) => {
+    const { content } = await answerOnce({
+      client: options.client,
+      system: options.system,
+      messages: options.buildMessages(entry),
+      mode: options.mode ?? "private",
+      answerFn: options.answerFn,
+      temperature: options.temperature,
+      model: options.model
+    });
+    return content;
+  };
+}
+
+// src/scheduler/deliver.ts
+async function deliver(entry, message, options) {
+  if (options.voiceAttempted) {
+    const voiceSent = await options.senders.sendVoice(entry.channel, entry.chatId, message);
+    if (voiceSent) return true;
+  }
+  return options.senders.sendText(entry.channel, entry.chatId, message);
+}
+
+// src/scheduler/dueDrops.ts
+function isDue(entry, now) {
+  return entry.fireAt <= now;
+}
+function isWithinGrace(entry, now, graceMs) {
+  return now - entry.fireAt <= graceMs;
+}
+function dueDrops(entries, now, graceMs) {
+  return entries.filter((entry) => isDue(entry, now) && isWithinGrace(entry, now, graceMs));
+}
+function staleDrops(entries, now, graceMs) {
+  return entries.filter((entry) => isDue(entry, now) && !isWithinGrace(entry, now, graceMs));
+}
+
+// src/scheduler/tick.ts
+async function runTick(entries, options) {
+  const result = { sent: [], notClaimed: [], stale: [], failed: [] };
+  for (const entry of staleDrops(entries, options.now, options.graceMs)) {
+    result.stale.push(entry.id);
+  }
+  for (const entry of dueDrops(entries, options.now, options.graceMs)) {
+    const claimed = await options.claims.claim(entry.id, options.now);
+    if (!claimed) {
+      result.notClaimed.push(entry.id);
+      continue;
+    }
+    try {
+      const message = await composeMessage(entry, options.compose, options.fallbackMessage);
+      const delivered = await deliver(entry, message, {
+        senders: options.senders,
+        voiceAttempted: options.voiceAttempted
+      });
+      if (delivered) {
+        result.sent.push(entry.id);
+      } else {
+        await options.claims.release(entry.id);
+        result.failed.push(entry.id);
+      }
+    } catch (error) {
+      console.warn(`Scheduler delivery failed for entry "${entry.id}":`, error);
+      await options.claims.release(entry.id);
+      result.failed.push(entry.id);
+    }
+  }
+  return result;
+}
+
+// src/scheduler/scheduler.ts
+var DEFAULT_GRACE_MS = 5 * 6e4;
+var DEFAULT_INTERVAL_MS = 6e4;
+var DEFAULT_FALLBACK_MESSAGE = "You have a scheduled message.";
+var defaultSchedule = (fn, ms) => {
+  const timer = setInterval(fn, ms);
+  if (typeof timer === "object" && "unref" in timer) timer.unref();
+  return { stop: () => clearInterval(timer) };
+};
+function createScheduler(config) {
+  const claims = createTursoScheduleClaimStore(
+    config.db,
+    config.instanceId ?? crypto.randomUUID(),
+    config.tableName ?? DEFAULT_CLAIM_TABLE,
+    config.claimTimeoutMs ?? DEFAULT_CLAIM_TIMEOUT_MS
+  );
+  const graceMs = config.graceMs ?? DEFAULT_GRACE_MS;
+  const fallbackMessage = config.fallbackMessage ?? DEFAULT_FALLBACK_MESSAGE;
+  const now = config.now ?? Date.now;
+  const schedule = config.schedule ?? defaultSchedule;
+  let running;
+  let ticking = false;
+  async function tickOnce() {
+    const entries = await config.fetchPending();
+    const result = await runTick(entries, {
+      claims,
+      senders: config.senders,
+      now: now(),
+      graceMs,
+      fallbackMessage,
+      compose: config.compose,
+      voiceAttempted: config.voiceAttempted
+    });
+    config.onTick?.(result);
+    return result;
+  }
+  return {
+    start() {
+      if (running) return;
+      running = schedule(() => {
+        if (ticking) return;
+        ticking = true;
+        tickOnce().catch((error) => {
+          if (config.onError) config.onError(error);
+          else console.warn("Scheduler tick failed:", error);
+        }).finally(() => {
+          ticking = false;
+        });
+      }, config.intervalMs ?? DEFAULT_INTERVAL_MS);
+    },
+    stop() {
+      if (!running) return;
+      running.stop();
+      running = void 0;
+    },
+    tickOnce
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_CLAIM_TABLE,
+  DEFAULT_CLAIM_TIMEOUT_MS,
+  DEFAULT_FALLBACK_MESSAGE,
+  DEFAULT_GRACE_MS,
+  DEFAULT_INTERVAL_MS,
+  canClaim,
+  composeMessage,
+  createAnswerCompose,
+  createScheduler,
+  createTursoScheduleClaimStore,
+  deliver,
+  dueDrops,
+  isDue,
+  isWithinGrace,
+  runTick,
+  staleDrops
+});

package/dist/scheduler/index.mjs

@@ -0,0 +1,290 @@
+// src/scheduler/claimStore.ts
+var DEFAULT_CLAIM_TABLE = "chatter_schedule_claims";
+var DEFAULT_CLAIM_TIMEOUT_MS = 2 * 6e4;
+var VALID_TABLE_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function canClaim(existing, instanceId, now, claimTimeoutMs) {
+  if (!existing) return true;
+  if (existing.instanceId === instanceId) return true;
+  return now - existing.claimedAt >= claimTimeoutMs;
+}
+var schemaReady = /* @__PURE__ */ new WeakMap();
+function ensureSchema(client, tableName) {
+  let perTable = schemaReady.get(client);
+  if (!perTable) {
+    perTable = /* @__PURE__ */ new Map();
+    schemaReady.set(client, perTable);
+  }
+  let ready = perTable.get(tableName);
+  if (!ready) {
+    const table = perTable;
+    ready = client.execute(
+      `CREATE TABLE IF NOT EXISTS ${tableName} (
+          schedule_id TEXT PRIMARY KEY,
+          instance_id TEXT NOT NULL,
+          claimed_at INTEGER NOT NULL
+        )`
+    ).catch((error) => {
+      table.delete(tableName);
+      throw error;
+    });
+    perTable.set(tableName, ready);
+  }
+  return ready;
+}
+function createTursoScheduleClaimStore(client, instanceId, tableName = DEFAULT_CLAIM_TABLE, claimTimeoutMs = DEFAULT_CLAIM_TIMEOUT_MS) {
+  if (!VALID_TABLE_NAME.test(tableName)) {
+    throw new Error(`Invalid schedule claim table name: ${tableName}`);
+  }
+  return {
+    async claim(id, now) {
+      await ensureSchema(client, tableName);
+      const result = await client.execute({
+        sql: `INSERT INTO ${tableName} (schedule_id, instance_id, claimed_at) VALUES (?, ?, ?)
+              ON CONFLICT(schedule_id) DO UPDATE SET
+                instance_id = excluded.instance_id,
+                claimed_at = excluded.claimed_at
+              WHERE ${tableName}.instance_id = excluded.instance_id
+                 OR ${tableName}.claimed_at <= excluded.claimed_at - ?
+              RETURNING instance_id`,
+        args: [id, instanceId, now, claimTimeoutMs]
+      });
+      const row = result.rows[0];
+      return Boolean(row) && row.instance_id === instanceId;
+    },
+    async release(id) {
+      await ensureSchema(client, tableName);
+      await client.execute({
+        sql: `DELETE FROM ${tableName} WHERE schedule_id = ? AND instance_id = ?`,
+        args: [id, instanceId]
+      });
+    }
+  };
+}
+
+// src/core/guardrails.ts
+function detectLeakage(text) {
+  const flags = [
+    /system prompt/i,
+    /hidden instruction/i,
+    /here (are|is) (my|the) rules/i,
+    /BEGIN SYSTEM PROMPT/i,
+    /tool instructions/i
+  ];
+  return flags.some((rx) => rx.test(text));
+}
+function scrubOutput(text) {
+  return text.replace(/sk-[A-Za-z0-9]{15,}/g, "[REDACTED]").replace(/AIza[0-9A-Za-z_-]{30,}/g, "[REDACTED]");
+}
+function guardOutput(text) {
+  if (detectLeakage(text)) {
+    return "Sorry, I can't share internal instructions. How else can I help?";
+  }
+  return scrubOutput(text);
+}
+
+// src/core/llm.ts
+var DEFAULT_MODEL = "gpt-4o";
+async function completeOnce({
+  client,
+  system,
+  messages,
+  temperature = 0.2,
+  model = DEFAULT_MODEL
+}) {
+  const res = await client.chat.completions.create({
+    model,
+    temperature,
+    messages: [{ role: "system", content: system }, ...messages]
+  });
+  const text = res.choices[0]?.message?.content ?? "";
+  return {
+    content: guardOutput(text),
+    usage: res.usage || { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 }
+  };
+}
+
+// src/core/answer.ts
+var noUsage = () => ({ prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 });
+async function runAnswerFn(answerFn, { system, messages, mode, sender }) {
+  const result = await answerFn({ system, messages, mode, sender });
+  const raw = typeof result === "string" ? result : result?.content;
+  const usage = typeof result === "string" ? void 0 : result?.usage;
+  return {
+    content: guardOutput(typeof raw === "string" ? raw : ""),
+    usage: usage ?? noUsage()
+  };
+}
+async function answerOnce({
+  answerFn,
+  client,
+  system,
+  messages,
+  mode,
+  sender,
+  temperature,
+  model
+}) {
+  if (answerFn) {
+    return runAnswerFn(answerFn, { system, messages, mode, sender });
+  }
+  return completeOnce({ client, system, messages, temperature, model });
+}
+
+// src/scheduler/compose.ts
+async function composeMessage(entry, compose, fallbackMessage) {
+  if (!compose) return fallbackMessage;
+  try {
+    const result = await compose(entry);
+    return result.trim().length > 0 ? result : fallbackMessage;
+  } catch (error) {
+    console.warn(`Scheduler compose failed for entry "${entry.id}":`, error);
+    return fallbackMessage;
+  }
+}
+function createAnswerCompose(options) {
+  return async (entry) => {
+    const { content } = await answerOnce({
+      client: options.client,
+      system: options.system,
+      messages: options.buildMessages(entry),
+      mode: options.mode ?? "private",
+      answerFn: options.answerFn,
+      temperature: options.temperature,
+      model: options.model
+    });
+    return content;
+  };
+}
+
+// src/scheduler/deliver.ts
+async function deliver(entry, message, options) {
+  if (options.voiceAttempted) {
+    const voiceSent = await options.senders.sendVoice(entry.channel, entry.chatId, message);
+    if (voiceSent) return true;
+  }
+  return options.senders.sendText(entry.channel, entry.chatId, message);
+}
+
+// src/scheduler/dueDrops.ts
+function isDue(entry, now) {
+  return entry.fireAt <= now;
+}
+function isWithinGrace(entry, now, graceMs) {
+  return now - entry.fireAt <= graceMs;
+}
+function dueDrops(entries, now, graceMs) {
+  return entries.filter((entry) => isDue(entry, now) && isWithinGrace(entry, now, graceMs));
+}
+function staleDrops(entries, now, graceMs) {
+  return entries.filter((entry) => isDue(entry, now) && !isWithinGrace(entry, now, graceMs));
+}
+
+// src/scheduler/tick.ts
+async function runTick(entries, options) {
+  const result = { sent: [], notClaimed: [], stale: [], failed: [] };
+  for (const entry of staleDrops(entries, options.now, options.graceMs)) {
+    result.stale.push(entry.id);
+  }
+  for (const entry of dueDrops(entries, options.now, options.graceMs)) {
+    const claimed = await options.claims.claim(entry.id, options.now);
+    if (!claimed) {
+      result.notClaimed.push(entry.id);
+      continue;
+    }
+    try {
+      const message = await composeMessage(entry, options.compose, options.fallbackMessage);
+      const delivered = await deliver(entry, message, {
+        senders: options.senders,
+        voiceAttempted: options.voiceAttempted
+      });
+      if (delivered) {
+        result.sent.push(entry.id);
+      } else {
+        await options.claims.release(entry.id);
+        result.failed.push(entry.id);
+      }
+    } catch (error) {
+      console.warn(`Scheduler delivery failed for entry "${entry.id}":`, error);
+      await options.claims.release(entry.id);
+      result.failed.push(entry.id);
+    }
+  }
+  return result;
+}
+
+// src/scheduler/scheduler.ts
+var DEFAULT_GRACE_MS = 5 * 6e4;
+var DEFAULT_INTERVAL_MS = 6e4;
+var DEFAULT_FALLBACK_MESSAGE = "You have a scheduled message.";
+var defaultSchedule = (fn, ms) => {
+  const timer = setInterval(fn, ms);
+  if (typeof timer === "object" && "unref" in timer) timer.unref();
+  return { stop: () => clearInterval(timer) };
+};
+function createScheduler(config) {
+  const claims = createTursoScheduleClaimStore(
+    config.db,
+    config.instanceId ?? crypto.randomUUID(),
+    config.tableName ?? DEFAULT_CLAIM_TABLE,
+    config.claimTimeoutMs ?? DEFAULT_CLAIM_TIMEOUT_MS
+  );
+  const graceMs = config.graceMs ?? DEFAULT_GRACE_MS;
+  const fallbackMessage = config.fallbackMessage ?? DEFAULT_FALLBACK_MESSAGE;
+  const now = config.now ?? Date.now;
+  const schedule = config.schedule ?? defaultSchedule;
+  let running;
+  let ticking = false;
+  async function tickOnce() {
+    const entries = await config.fetchPending();
+    const result = await runTick(entries, {
+      claims,
+      senders: config.senders,
+      now: now(),
+      graceMs,
+      fallbackMessage,
+      compose: config.compose,
+      voiceAttempted: config.voiceAttempted
+    });
+    config.onTick?.(result);
+    return result;
+  }
+  return {
+    start() {
+      if (running) return;
+      running = schedule(() => {
+        if (ticking) return;
+        ticking = true;
+        tickOnce().catch((error) => {
+          if (config.onError) config.onError(error);
+          else console.warn("Scheduler tick failed:", error);
+        }).finally(() => {
+          ticking = false;
+        });
+      }, config.intervalMs ?? DEFAULT_INTERVAL_MS);
+    },
+    stop() {
+      if (!running) return;
+      running.stop();
+      running = void 0;
+    },
+    tickOnce
+  };
+}
+export {
+  DEFAULT_CLAIM_TABLE,
+  DEFAULT_CLAIM_TIMEOUT_MS,
+  DEFAULT_FALLBACK_MESSAGE,
+  DEFAULT_GRACE_MS,
+  DEFAULT_INTERVAL_MS,
+  canClaim,
+  composeMessage,
+  createAnswerCompose,
+  createScheduler,
+  createTursoScheduleClaimStore,
+  deliver,
+  dueDrops,
+  isDue,
+  isWithinGrace,
+  runTick,
+  staleDrops
+};

package/dist/scheduler/scheduler.d.ts

@@ -0,0 +1,44 @@
+import type { Client } from "@libsql/client";
+import type { ChannelSenderRegistry } from "../channels/senders";
+import type { ComposeFn, ScheduleEntry, TickResult } from "./types";
+export declare const DEFAULT_GRACE_MS: number;
+export declare const DEFAULT_INTERVAL_MS = 60000;
+export declare const DEFAULT_FALLBACK_MESSAGE = "You have a scheduled message.";
+export interface SchedulerConfig {
+    db: Client;
+    senders: ChannelSenderRegistry;
+    /** Returns the caller's own pending candidates for this tick — chatter stores no schedule content. */
+    fetchPending: () => Promise<ScheduleEntry[]> | ScheduleEntry[];
+    tableName?: string;
+    graceMs?: number;
+    intervalMs?: number;
+    claimTimeoutMs?: number;
+    instanceId?: string;
+    compose?: ComposeFn;
+    fallbackMessage?: string;
+    voiceAttempted?: boolean;
+    onTick?: (result: TickResult) => void;
+    onError?: (error: unknown) => void;
+    /** Injectable for tests; defaults to `setInterval`/`clearInterval`. */
+    schedule?: (fn: () => void, ms: number) => {
+        stop: () => void;
+    };
+    /** Injectable for tests; defaults to `Date.now`. */
+    now?: () => number;
+}
+export interface Scheduler {
+    /** Starts ticking on `intervalMs`. No-op if already started. */
+    start(): void;
+    /** Stops ticking. No-op if not started. */
+    stop(): void;
+    /** Runs one tick immediately, outside the interval — useful for tests and manual triggers. */
+    tickOnce(): Promise<TickResult>;
+}
+/**
+ * The ticker: on each interval, pulls pending candidates from the caller,
+ * claims each due one exactly once across every running instance, composes
+ * and delivers it, and releases the claim on a failed send so it retries
+ * within the grace window instead of being lost.
+ */
+export declare function createScheduler(config: SchedulerConfig): Scheduler;
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/scheduler/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../src/scheduler/scheduler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAOjE,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAEpE,eAAO,MAAM,gBAAgB,QAAa,CAAC;AAC3C,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAC1C,eAAO,MAAM,wBAAwB,kCAAkC,CAAC;AAExE,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,qBAAqB,CAAC;IAC/B,sGAAsG;IACtG,YAAY,EAAE,MAAM,OAAO,CAAC,aAAa,EAAE,CAAC,GAAG,aAAa,EAAE,CAAC;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC;IACtC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACnC,uEAAuE;IACvE,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK;QAAE,IAAI,EAAE,MAAM,IAAI,CAAA;KAAE,CAAC;IAChE,oDAAoD;IACpD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,SAAS;IACxB,gEAAgE;IAChE,KAAK,IAAI,IAAI,CAAC;IACd,2CAA2C;IAC3C,IAAI,IAAI,IAAI,CAAC;IACb,8FAA8F;IAC9F,QAAQ,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;CACjC;AAQD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CAsDlE"}

package/dist/scheduler/scheduler.test.d.ts

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

package/dist/scheduler/scheduler.test.d.ts.map

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

package/dist/scheduler/tick.d.ts

@@ -0,0 +1,19 @@
+import type { ChannelSenderRegistry } from "../channels/senders";
+import type { ComposeFn, ScheduleClaimStore, ScheduleEntry, TickResult } from "./types";
+export interface TickOptions {
+    claims: ScheduleClaimStore;
+    senders: ChannelSenderRegistry;
+    now: number;
+    graceMs: number;
+    fallbackMessage: string;
+    compose?: ComposeFn;
+    voiceAttempted?: boolean;
+}
+/**
+ * One scheduler tick over caller-supplied candidate entries. Chatter stores
+ * no schedule content of its own — `entries` is whatever the caller's own
+ * store considers pending; this adds the exactly-once claim, the grace
+ * window, and delivery on top.
+ */
+export declare function runTick(entries: ScheduleEntry[], options: TickOptions): Promise<TickResult>;
+//# sourceMappingURL=tick.d.ts.map

package/dist/scheduler/tick.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tick.d.ts","sourceRoot":"","sources":["../../src/scheduler/tick.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAIjE,OAAO,KAAK,EAAE,SAAS,EAAE,kBAAkB,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAExF,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,kBAAkB,CAAC;IAC3B,OAAO,EAAE,qBAAqB,CAAC;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAsB,OAAO,CAAC,OAAO,EAAE,aAAa,EAAE,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAsCjG"}

package/dist/scheduler/tick.test.d.ts

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

package/dist/scheduler/tick.test.d.ts.map

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

package/dist/scheduler/types.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Content-free by design: chatter stores no schedule data of its own.
+ * `id`/`fireAt`/`channel`/`chatId` are the minimum the claim/grace/delivery
+ * machinery needs; `payload` is opaque caller data for the compose step.
+ */
+export interface ScheduleEntry {
+    /** Stable, caller-assigned id — the claim table's primary key. */
+    id: string;
+    /** Epoch ms the entry is due to fire. */
+    fireAt: number;
+    /** Sender-registry channel name to deliver through. */
+    channel: string;
+    /** Channel-specific recipient id. */
+    chatId: string;
+    /** Opaque caller data passed to the compose step; chatter never reads it. */
+    payload?: unknown;
+}
+/** Turns an entry into outbound text. Chatter never inspects the result beyond checking it is non-blank. */
+export type ComposeFn = (entry: ScheduleEntry) => Promise<string> | string;
+export interface ScheduleClaimStore {
+    /** Atomically claims `id` for this instance; resolves false if another instance already holds it. */
+    claim(id: string, now: number): Promise<boolean>;
+    /** Releases this instance's claim on `id`, e.g. after a failed send, so it can be retried within grace. */
+    release(id: string): Promise<void>;
+}
+export interface TickResult {
+    /** Ids delivered this tick. */
+    sent: string[];
+    /** Ids due within grace but already claimed by another instance. */
+    notClaimed: string[];
+    /** Ids due but past their grace window — skipped, never claimed or delivered. */
+    stale: string[];
+    /** Ids claimed this tick whose delivery failed; the claim was released so a later tick can retry. */
+    failed: string[];
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/scheduler/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,kEAAkE;IAClE,EAAE,EAAE,MAAM,CAAC;IACX,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,4GAA4G;AAC5G,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,aAAa,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;AAE3E,MAAM,WAAW,kBAAkB;IACjC,qGAAqG;IACrG,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjD,2GAA2G;IAC3G,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,UAAU;IACzB,+BAA+B;IAC/B,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,oEAAoE;IACpE,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,iFAAiF;IACjF,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,qGAAqG;IACrG,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB"}

package/dist/shortener.d.ts

@@ -0,0 +1,24 @@
+/**
+ * URL shortening against a Kutt-compatible API, config-injected (no
+ * `process.env` reads) so hosts can wire credentials however they like.
+ *
+ * The hard invariant: {@link Shortener.shorten} never throws. Any failure —
+ * network error, an aborted request past `timeoutMs`, or a non-2xx/malformed
+ * response — resolves to the original URL, since a shortener outage must
+ * never break something user-facing that only wanted a shorter link.
+ */
+export interface ShortenerConfig {
+    /** Base URL of the Kutt (or Kutt-compatible) instance, e.g. "https://kutt.it". */
+    apiUrl: string;
+    apiKey: string;
+    /** Custom short domain configured on the Kutt instance, if any. */
+    domain?: string;
+    /** Abort the request after this many milliseconds. Defaults to 5000. */
+    timeoutMs?: number;
+}
+export interface Shortener {
+    /** Resolves to the shortened URL, or the input `url` unchanged on any failure. */
+    shorten(url: string): Promise<string>;
+}
+export declare function createShortener(config: ShortenerConfig, fetchImpl?: typeof fetch): Shortener;
+//# sourceMappingURL=shortener.d.ts.map

package/dist/shortener.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shortener.d.ts","sourceRoot":"","sources":["../src/shortener.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,eAAe;IAC9B,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,SAAS;IACxB,kFAAkF;IAClF,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACvC;AAQD,wBAAgB,eAAe,CAC7B,MAAM,EAAE,eAAe,EACvB,SAAS,GAAE,OAAO,KAAa,GAC9B,SAAS,CAqCX"}

package/dist/shortener.test.d.ts

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

package/dist/shortener.test.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegoaltoworks/chatter",
-  "version": "0.34.0",
+  "version": "0.36.0",
   "description": "Embeddable AI chatbot framework with RAG, authentication, and customizable widgets",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -59,6 +59,11 @@
       "types": "./dist/images/index.d.ts",
       "import": "./dist/images/index.mjs",
       "require": "./dist/images/index.js"
+    },
+    "./scheduler": {
+      "types": "./dist/scheduler/index.d.ts",
+      "import": "./dist/scheduler/index.mjs",
+      "require": "./dist/scheduler/index.js"
     }
   },
   "files": [
@@ -68,7 +73,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:flows && bun run build:images && 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:images && bun run build:scheduler && 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",
@@ -80,6 +85,7 @@
     "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:images": "esbuild src/images/index.ts --bundle --format=esm --outfile=dist/images/index.mjs --external:@libsql/client --external:openai --platform=node --target=node24 && esbuild src/images/index.ts --bundle --format=cjs --outfile=dist/images/index.js --external:@libsql/client --external:openai --platform=node --target=node24",
+    "build:scheduler": "esbuild src/scheduler/index.ts --bundle --format=esm --outfile=dist/scheduler/index.mjs --external:@libsql/client --external:openai --platform=node --target=node24 && esbuild src/scheduler/index.ts --bundle --format=cjs --outfile=dist/scheduler/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/",