@diegoaltoworks/chatter 0.29.0 → 0.30.0

package/dist/channels/whatsapp/inbound.d.ts

@@ -0,0 +1,131 @@
+/**
+ * WhatsApp inbound: turns a raw Baileys message into a reply through
+ * chatter's own pipeline (`prepareChat` + `answerOnce`), gated by
+ * `./channels`' reply gates and loop guard. `./channel` hands every raw
+ * message to `config.onMessage` uninterpreted — this module is that
+ * interpretation.
+ *
+ * Message-shape parsing (text/caption extraction, contextInfo mentions and
+ * quoted-reply resolution) is genericized from the reference implementation:
+ * text AND contextInfo live in a DIFFERENT place per message shape — plain
+ * text carries both on `extendedTextMessage`, but a photo/video/document
+ * carries its caption on its own message type and its contextInfo there too.
+ * Missing that meant mentions in photo captions were invisible and group
+ * photo requests were silently ignored.
+ *
+ * `createWhatsAppInboundHandler` needs `ServerDependencies`
+ * (`client`/`store`/`prompts`), which only exists once `createServer` builds
+ * it — after `channels` (and therefore `onMessage`) must already be
+ * configured. Wire it up from `ChatterConfig.customRoutes`, which runs
+ * before channels start and receives the same deps:
+ *
+ * ```ts
+ * let handleInbound: ((event: WhatsAppMessageEvent) => Promise<void>) | undefined;
+ * const whatsapp = createWhatsAppChannel({
+ *   sessionSecret: process.env.WA_SESSION_SECRET as string,
+ *   onMessage: (event) => handleInbound?.(event),
+ * });
+ *
+ * await createServer({
+ *   ...,
+ *   channels: [whatsapp],
+ *   customRoutes: async (app, deps) => {
+ *     handleInbound = createWhatsAppInboundHandler({
+ *       client: deps.client,
+ *       store: deps.store,
+ *       prompts: deps.prompts,
+ *       answerFn: deps.config.answerFn,
+ *       bucketsFor: deps.config.bucketsFor,
+ *       registry: new Map(),
+ *     });
+ *   },
+ * });
+ * ```
+ */
+import type { WAMessage, WASocket } from "@whiskeysockets/baileys";
+import type OpenAI from "openai";
+import { type AnswerFn } from "../../core/answer";
+import { type BucketsFor } from "../../core/buckets";
+import type { PromptLoader } from "../../core/prompts";
+import type { VectorStore } from "../../core/retrieval";
+import { type SessionIdentityRegistry } from "../gates";
+import type { WhatsAppMessageEvent } from "./channel";
+export declare function isGroupJid(jid: string): boolean;
+/** "447700900123:17@s.whatsapp.net" (device-suffixed) and "447700900123@s.whatsapp.net" match. */
+export declare function jidsMatch(a: string | undefined, b: string | undefined): boolean;
+export declare function jidToPhoneNumber(jid: string): string;
+/**
+ * Resolve the sender's real phone number. Modern WhatsApp identifies group
+ * senders (and some DM chats) by LID (anonymized `"12345@lid"`), which
+ * carries no relationship to the phone number — treating it as one silently
+ * keys per-person state on garbage. Prefer the `*Pn` fields Baileys attaches
+ * when available, then fall back to the socket's own LID mapping store.
+ *
+ * The returned string is a stable identity key, not guaranteed to be a
+ * dialable phone number: an unresolved LID returns an explicit `"lid:<id>"`
+ * marker rather than a phone-shaped fabrication (`jidToPhoneNumber("12345@lid")`
+ * would otherwise yield `"+12345"`, indistinguishable from a real number) —
+ * callers keying security or spend decisions off `sender` (`bucketsFor`,
+ * usage metering) must not mistake a LID numeral for a phone number.
+ */
+export declare function senderPhoneFor(sock: WASocket, message: WAMessage, chatJid: string): Promise<string>;
+export interface WaMessageContext {
+    mentionedJids: string[];
+    quotedParticipantJid?: string;
+}
+/**
+ * contextInfo (mentions, quoted message) lives in a DIFFERENT place per
+ * message shape: a plain text message carries it on `extendedTextMessage`,
+ * but a photo/video/document message carries it on its own type.
+ */
+export declare function messageContext(message: WAMessage): WaMessageContext;
+/** Text/caption across every shape that can carry one — plain text, a reply, or a photo/video/document caption. */
+export declare function extractText(message: WAMessage): string;
+export interface WhatsAppInboundConfig {
+    client: OpenAI;
+    store: VectorStore;
+    prompts: PromptLoader;
+    answerFn?: AnswerFn;
+    bucketsFor?: BucketsFor;
+    model?: string;
+    /**
+     * Own identities per session — share ONE registry across every session
+     * this process runs so a message from one session's own number never
+     * looks like a stranger to another (the loop-guard case a single
+     * session's `fromMe` flag can't catch). Kept in sync from every message,
+     * not just at connection open, because a session's LID identity can
+     * populate late.
+     */
+    registry: SessionIdentityRegistry;
+    /** Group chats eligible for a reply. Empty (default) = every group. Has no effect on DMs, which always reply regardless. */
+    allowedChats?: string[];
+    muteRegex?: RegExp;
+    unmuteRegex?: RegExp;
+    /** Neutral, overridable acknowledgements — this module ships no bot personality; unset = silent mute/unmute. */
+    muteReply?: string;
+    unmuteReply?: string;
+    dmRateLimit?: {
+        max: number;
+        windowMs: number;
+    };
+    groupRateLimit?: {
+        max: number;
+        windowMs: number;
+    };
+    /** Extra system-prompt section describing the delivery channel; passed through to `prepareChat`. */
+    channelHint?: string;
+    /**
+     * Optional persona layer for a sender/text pair — the resolution
+     * mechanism (registry, windowed rolls, prompt files) lives in its own
+     * module; this only plugs the result into `prepareChat`'s `personaLayer`.
+     * A throw/rejection is treated as "no persona" for that turn.
+     */
+    personaResolver?: (ctx: {
+        senderPhone: string;
+        text: string;
+    }) => string | undefined | Promise<string | undefined>;
+    now?: () => number;
+}
+/** Builds the `onMessage` handler for `createWhatsAppChannel` (see `./channel`) — see the module docstring for how to wire `ServerDependencies` into it. */
+export declare function createWhatsAppInboundHandler(config: WhatsAppInboundConfig): (event: WhatsAppMessageEvent) => Promise<void>;
+//# sourceMappingURL=inbound.d.ts.map

package/dist/channels/whatsapp/inbound.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbound.d.ts","sourceRoot":"","sources":["../../../src/channels/whatsapp/inbound.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AACjC,OAAO,EAAE,KAAK,QAAQ,EAAc,MAAM,mBAAmB,CAAC;AAC9D,OAAO,EAAE,KAAK,UAAU,EAAkB,MAAM,oBAAoB,CAAC;AAErE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAKL,KAAK,uBAAuB,EAE7B,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAItD,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE/C;AAED,kGAAkG;AAClG,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAI/E;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGpD;AAeD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,SAAS,EAClB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,CA+BjB;AAID,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,SAAS,GAAG,gBAAgB,CAWnE;AAED,mHAAmH;AACnH,wBAAgB,WAAW,CAAC,OAAO,EAAE,SAAS,GAAG,MAAM,CAWtD;AAID,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,WAAW,CAAC;IACnB,OAAO,EAAE,YAAY,CAAC;IACtB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;OAOG;IACH,QAAQ,EAAE,uBAAuB,CAAC;IAClC,4HAA4H;IAC5H,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gHAAgH;IAChH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAChD,cAAc,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IACnD,oGAAoG;IACpG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE;QACtB,WAAW,EAAE,MAAM,CAAC;QACpB,IAAI,EAAE,MAAM,CAAC;KACd,KAAK,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACvD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAqBD,4JAA4J;AAC5J,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,qBAAqB,GAC5B,CAAC,KAAK,EAAE,oBAAoB,KAAK,OAAO,CAAC,IAAI,CAAC,CA0GhD"}

package/dist/channels/whatsapp/inbound.test.d.ts

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

package/dist/channels/whatsapp/inbound.test.d.ts.map

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

package/dist/channels/whatsapp/index.d.ts

@@ -29,5 +29,6 @@ export type { Baileys } from "./baileys";
 export { loadBaileys } from "./baileys";
 export { acquireSessionLease, createWhatsAppChannel, type LeaseGatedConnectDeps, reconnectDelayMs, senderNameFor, shutdownWaSessions, type WaSessionHandle, type WhatsAppChannelConfig, type WhatsAppMessageEvent, } from "./channel";
 export { decrypt, encrypt } from "./crypto";
+export { createWhatsAppInboundHandler, extractText, isGroupJid, jidsMatch, jidToPhoneNumber, messageContext, senderPhoneFor, type WaMessageContext, type WhatsAppInboundConfig, } from "./inbound";
 export { canAcquireLease, createTursoWaLeaseStore, LEASE_HEARTBEAT_MS, LEASE_STALE_MS, LEASE_WAIT_MS, type WaLeaseRow, type WaLeaseStore, } from "./lease";
 //# sourceMappingURL=index.d.ts.map

package/dist/channels/whatsapp/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/channels/whatsapp/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,YAAY,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,KAAK,qBAAqB,EAC1B,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,GAC1B,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,kBAAkB,EAClB,cAAc,EACd,aAAa,EACb,KAAK,UAAU,EACf,KAAK,YAAY,GAClB,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/channels/whatsapp/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,YAAY,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,KAAK,qBAAqB,EAC1B,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,GAC1B,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,EACL,4BAA4B,EAC5B,WAAW,EACX,UAAU,EACV,SAAS,EACT,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,GAC3B,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,kBAAkB,EAClB,cAAc,EACd,aAAa,EACb,KAAK,UAAU,EACf,KAAK,YAAY,GAClB,MAAM,SAAS,CAAC"}

package/dist/channels/whatsapp/index.js

@@ -37,11 +37,18 @@ __export(index_exports, {
   canAcquireLease: () => canAcquireLease,
   createTursoWaLeaseStore: () => createTursoWaLeaseStore,
   createWhatsAppChannel: () => createWhatsAppChannel,
+  createWhatsAppInboundHandler: () => createWhatsAppInboundHandler,
   decrypt: () => decrypt,
   encrypt: () => encrypt,
+  extractText: () => extractText,
+  isGroupJid: () => isGroupJid,
+  jidToPhoneNumber: () => jidToPhoneNumber,
+  jidsMatch: () => jidsMatch,
   loadBaileys: () => loadBaileys,
+  messageContext: () => messageContext,
   reconnectDelayMs: () => reconnectDelayMs,
   senderNameFor: () => senderNameFor,
+  senderPhoneFor: () => senderPhoneFor,
   shutdownWaSessions: () => shutdownWaSessions,
   useTursoAuthState: () => useTursoAuthState
 });
@@ -459,6 +466,324 @@ function createWhatsAppChannel(config) {
     }
   };
 }
+
+// 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/core/buckets.ts
+function defaultBuckets(mode) {
+  return ["base", mode];
+}
+function isIdentified(sender) {
+  return typeof sender === "string" && sender.trim().length > 0;
+}
+function normalize(buckets) {
+  const out = [];
+  for (const raw of buckets) {
+    if (typeof raw !== "string") continue;
+    const bucket = raw.trim();
+    if (bucket && !out.includes(bucket)) out.push(bucket);
+  }
+  return out;
+}
+async function resolveBuckets({
+  mode,
+  sender,
+  bucketsFor
+}) {
+  if (!bucketsFor) return void 0;
+  const identified = isIdentified(sender);
+  const requested = await bucketsFor(identified ? { mode, sender } : { mode });
+  if (!Array.isArray(requested)) return void 0;
+  const cleaned = normalize(requested);
+  if (identified) return cleaned;
+  const ceiling = new Set(defaultBuckets(mode));
+  return cleaned.filter((bucket) => ceiling.has(bucket));
+}
+
+// src/core/pipeline.ts
+var MODE_SETTINGS = {
+  public: { topK: 6, label: "Context" },
+  private: { topK: 8, label: "Internal Context" }
+};
+async function prepareChat({
+  store,
+  prompts,
+  mode,
+  messages,
+  personaLayer,
+  channelHint,
+  buckets
+}) {
+  const lastUserMsg = [...messages].reverse().find((m) => m.role === "user");
+  if (!lastUserMsg) {
+    throw new Error("no user message found in conversation");
+  }
+  const { topK, label } = MODE_SETTINGS[mode];
+  const ctx = await store.query(lastUserMsg.content, topK, buckets ?? defaultBuckets(mode));
+  const persona = personaLayer?.trim() || (mode === "private" ? prompts.privatePersona : prompts.publicPersona);
+  const hint = channelHint?.trim();
+  const system = [
+    prompts.baseSystemRules,
+    persona,
+    ...hint ? [hint] : [],
+    `${label}:
+${ctx.join("\n\n")}`
+  ].join("\n\n");
+  return { system, messages };
+}
+
+// src/channels/gates.ts
+function matches(re, text) {
+  return new RegExp(re.source, re.flags.replace(/[gy]/g, "")).test(text);
+}
+function decideChannelAction(msg, config) {
+  if (msg.fromBot || !msg.text.trim()) return "ignore";
+  if (!msg.isDirectMessage) {
+    if (config.allowedChats.length > 0 && !config.allowedChats.includes(msg.chatId)) {
+      return "ignore";
+    }
+    if (config.muteRegex && matches(config.muteRegex, msg.text)) return "mute";
+    if (config.unmuteRegex && matches(config.unmuteRegex, msg.text)) return "unmute";
+    if (config.mutedChats.has(msg.chatId)) return "ignore";
+    return msg.mentionsBot || msg.isReplyToBot ? "reply" : "ignore";
+  }
+  return "reply";
+}
+function createSlidingWindowRateLimiter(maxPerWindow, windowMs, now = Date.now) {
+  const log = /* @__PURE__ */ new Map();
+  return function allow(key) {
+    const cutoff = now() - windowMs;
+    const entries = (log.get(key) ?? []).filter((t) => t > cutoff);
+    if (entries.length >= maxPerWindow) {
+      if (entries.length > 0) log.set(key, entries);
+      else log.delete(key);
+      return false;
+    }
+    entries.push(now());
+    log.set(key, entries);
+    return true;
+  };
+}
+function underReplyRateLimit(msg, limiters) {
+  return msg.isDirectMessage ? limiters.dm(msg.chatId) : limiters.group(msg.chatId);
+}
+function isFromAnySession(id, registry) {
+  if (!id) return false;
+  for (const ids of registry.values()) {
+    if (ids.includes(id)) return true;
+  }
+  return false;
+}
+function isEffectivelyFromSelf(msg, registry) {
+  return msg.fromBot || isFromAnySession(msg.senderId, registry);
+}
+
+// src/channels/whatsapp/inbound.ts
+function isGroupJid(jid) {
+  return jid.endsWith("@g.us");
+}
+function jidsMatch(a, b) {
+  if (!a || !b) return false;
+  const bare = (jid) => jid.split("@")[0]?.split(":")[0] ?? jid;
+  return bare(a) === bare(b);
+}
+function jidToPhoneNumber(jid) {
+  const bare = jid.split("@")[0]?.split(":")[0] ?? "";
+  return bare.startsWith("+") ? bare : `+${bare}`;
+}
+function normalizeJid(jid) {
+  const [user = "", domain] = jid.split("@");
+  const bareUser = user.split(":")[0] ?? user;
+  return domain ? `${bareUser}@${domain}` : bareUser;
+}
+async function senderPhoneFor(sock, message, chatJid) {
+  const key = message.key;
+  let jid = [key.participantPn, key.senderPn, key.participant, key.remoteJidAlt, chatJid].find(
+    (candidate) => typeof candidate === "string" && candidate.length > 0
+  ) ?? chatJid;
+  if (jid.endsWith("@lid")) {
+    try {
+      const mapped = await sock.signalRepository?.lidMapping?.getPNForLID?.(jid);
+      if (mapped) jid = mapped;
+    } catch {
+    }
+  }
+  return jid.endsWith("@lid") ? `lid:${jid.split("@")[0]?.split(":")[0] ?? jid}` : jidToPhoneNumber(jid);
+}
+function messageContext(message) {
+  const content = message.message;
+  const contextInfo = content?.extendedTextMessage?.contextInfo ?? content?.imageMessage?.contextInfo ?? content?.videoMessage?.contextInfo ?? content?.documentMessage?.contextInfo;
+  return {
+    mentionedJids: contextInfo?.mentionedJid ?? [],
+    quotedParticipantJid: contextInfo?.participant ?? void 0
+  };
+}
+function extractText(message) {
+  const content = message.message;
+  if (!content) return "";
+  return content.conversation ?? content.extendedTextMessage?.text ?? content.imageMessage?.caption ?? content.videoMessage?.caption ?? content.documentMessage?.caption ?? "";
+}
+var DEFAULT_GROUP_RATE_LIMIT = { max: 30, windowMs: 60 * 60 * 1e3 };
+var DEFAULT_DM_RATE_LIMIT = { max: 20, windowMs: 60 * 60 * 1e3 };
+async function resolvePersonaLayer(config, ctx) {
+  if (!config.personaResolver) return void 0;
+  try {
+    return await config.personaResolver(ctx);
+  } catch {
+    return void 0;
+  }
+}
+function createWhatsAppInboundHandler(config) {
+  const mutedChats = /* @__PURE__ */ new Set();
+  const now = config.now ?? Date.now;
+  const group = config.groupRateLimit ?? DEFAULT_GROUP_RATE_LIMIT;
+  const dm = config.dmRateLimit ?? DEFAULT_DM_RATE_LIMIT;
+  const underGroupRateLimit = createSlidingWindowRateLimiter(group.max, group.windowMs, now);
+  const underDmRateLimit = createSlidingWindowRateLimiter(dm.max, dm.windowMs, now);
+  return async function handleWhatsAppMessage(event) {
+    const { sessionId, sock, message } = event;
+    try {
+      const chatId = message.key.remoteJid ?? "";
+      if (!chatId || chatId === "status@broadcast") return;
+      const text = extractText(message);
+      const context = messageContext(message);
+      const senderId = message.key.participant ?? chatId;
+      const ownIds = [sock.user?.id, sock.user?.lid].filter((id) => Boolean(id)).map(normalizeJid);
+      config.registry.set(sessionId, ownIds);
+      const fromBot = isEffectivelyFromSelf(
+        { fromBot: message.key.fromMe ?? false, senderId: normalizeJid(senderId) },
+        config.registry
+      );
+      const msg = {
+        chatId,
+        senderId,
+        text,
+        isDirectMessage: !isGroupJid(chatId),
+        mentionsBot: context.mentionedJids.some((jid) => ownIds.some((own) => jidsMatch(jid, own))),
+        isReplyToBot: ownIds.some((own) => jidsMatch(context.quotedParticipantJid, own)),
+        fromBot
+      };
+      const action = decideChannelAction(msg, {
+        allowedChats: config.allowedChats ?? [],
+        mutedChats,
+        muteRegex: config.muteRegex,
+        unmuteRegex: config.unmuteRegex
+      });
+      if (action === "mute") {
+        mutedChats.add(chatId);
+        if (config.muteReply) await sock.sendMessage(chatId, { text: config.muteReply });
+        return;
+      }
+      if (action === "unmute") {
+        mutedChats.delete(chatId);
+        if (config.unmuteReply) await sock.sendMessage(chatId, { text: config.unmuteReply });
+        return;
+      }
+      if (action !== "reply") return;
+      if (!underReplyRateLimit(msg, { dm: underDmRateLimit, group: underGroupRateLimit })) {
+        return;
+      }
+      const senderPhone = await senderPhoneFor(sock, message, chatId);
+      const personaLayer = await resolvePersonaLayer(config, { senderPhone, text });
+      const buckets = await resolveBuckets({
+        mode: "public",
+        sender: senderPhone,
+        bucketsFor: config.bucketsFor
+      });
+      const messages = [{ role: "user", content: text }];
+      const { system } = await prepareChat({
+        store: config.store,
+        prompts: config.prompts,
+        mode: "public",
+        messages,
+        personaLayer,
+        channelHint: config.channelHint,
+        buckets
+      });
+      const { content } = await answerOnce({
+        answerFn: config.answerFn,
+        client: config.client,
+        system,
+        messages,
+        mode: "public",
+        sender: senderPhone,
+        model: config.model
+      });
+      if (content) {
+        await sock.sendMessage(chatId, { text: content }, { quoted: message });
+      }
+    } catch (error) {
+      console.warn(`WhatsApp[${sessionId}]: inbound message handling failed:`, error);
+    }
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   LEASE_HEARTBEAT_MS,
@@ -468,11 +793,18 @@ function createWhatsAppChannel(config) {
   canAcquireLease,
   createTursoWaLeaseStore,
   createWhatsAppChannel,
+  createWhatsAppInboundHandler,
   decrypt,
   encrypt,
+  extractText,
+  isGroupJid,
+  jidToPhoneNumber,
+  jidsMatch,
   loadBaileys,
+  messageContext,
   reconnectDelayMs,
   senderNameFor,
+  senderPhoneFor,
   shutdownWaSessions,
   useTursoAuthState
 });

package/dist/channels/whatsapp/index.mjs

@@ -410,6 +410,324 @@ function createWhatsAppChannel(config) {
     }
   };
 }
+
+// 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/core/buckets.ts
+function defaultBuckets(mode) {
+  return ["base", mode];
+}
+function isIdentified(sender) {
+  return typeof sender === "string" && sender.trim().length > 0;
+}
+function normalize(buckets) {
+  const out = [];
+  for (const raw of buckets) {
+    if (typeof raw !== "string") continue;
+    const bucket = raw.trim();
+    if (bucket && !out.includes(bucket)) out.push(bucket);
+  }
+  return out;
+}
+async function resolveBuckets({
+  mode,
+  sender,
+  bucketsFor
+}) {
+  if (!bucketsFor) return void 0;
+  const identified = isIdentified(sender);
+  const requested = await bucketsFor(identified ? { mode, sender } : { mode });
+  if (!Array.isArray(requested)) return void 0;
+  const cleaned = normalize(requested);
+  if (identified) return cleaned;
+  const ceiling = new Set(defaultBuckets(mode));
+  return cleaned.filter((bucket) => ceiling.has(bucket));
+}
+
+// src/core/pipeline.ts
+var MODE_SETTINGS = {
+  public: { topK: 6, label: "Context" },
+  private: { topK: 8, label: "Internal Context" }
+};
+async function prepareChat({
+  store,
+  prompts,
+  mode,
+  messages,
+  personaLayer,
+  channelHint,
+  buckets
+}) {
+  const lastUserMsg = [...messages].reverse().find((m) => m.role === "user");
+  if (!lastUserMsg) {
+    throw new Error("no user message found in conversation");
+  }
+  const { topK, label } = MODE_SETTINGS[mode];
+  const ctx = await store.query(lastUserMsg.content, topK, buckets ?? defaultBuckets(mode));
+  const persona = personaLayer?.trim() || (mode === "private" ? prompts.privatePersona : prompts.publicPersona);
+  const hint = channelHint?.trim();
+  const system = [
+    prompts.baseSystemRules,
+    persona,
+    ...hint ? [hint] : [],
+    `${label}:
+${ctx.join("\n\n")}`
+  ].join("\n\n");
+  return { system, messages };
+}
+
+// src/channels/gates.ts
+function matches(re, text) {
+  return new RegExp(re.source, re.flags.replace(/[gy]/g, "")).test(text);
+}
+function decideChannelAction(msg, config) {
+  if (msg.fromBot || !msg.text.trim()) return "ignore";
+  if (!msg.isDirectMessage) {
+    if (config.allowedChats.length > 0 && !config.allowedChats.includes(msg.chatId)) {
+      return "ignore";
+    }
+    if (config.muteRegex && matches(config.muteRegex, msg.text)) return "mute";
+    if (config.unmuteRegex && matches(config.unmuteRegex, msg.text)) return "unmute";
+    if (config.mutedChats.has(msg.chatId)) return "ignore";
+    return msg.mentionsBot || msg.isReplyToBot ? "reply" : "ignore";
+  }
+  return "reply";
+}
+function createSlidingWindowRateLimiter(maxPerWindow, windowMs, now = Date.now) {
+  const log = /* @__PURE__ */ new Map();
+  return function allow(key) {
+    const cutoff = now() - windowMs;
+    const entries = (log.get(key) ?? []).filter((t) => t > cutoff);
+    if (entries.length >= maxPerWindow) {
+      if (entries.length > 0) log.set(key, entries);
+      else log.delete(key);
+      return false;
+    }
+    entries.push(now());
+    log.set(key, entries);
+    return true;
+  };
+}
+function underReplyRateLimit(msg, limiters) {
+  return msg.isDirectMessage ? limiters.dm(msg.chatId) : limiters.group(msg.chatId);
+}
+function isFromAnySession(id, registry) {
+  if (!id) return false;
+  for (const ids of registry.values()) {
+    if (ids.includes(id)) return true;
+  }
+  return false;
+}
+function isEffectivelyFromSelf(msg, registry) {
+  return msg.fromBot || isFromAnySession(msg.senderId, registry);
+}
+
+// src/channels/whatsapp/inbound.ts
+function isGroupJid(jid) {
+  return jid.endsWith("@g.us");
+}
+function jidsMatch(a, b) {
+  if (!a || !b) return false;
+  const bare = (jid) => jid.split("@")[0]?.split(":")[0] ?? jid;
+  return bare(a) === bare(b);
+}
+function jidToPhoneNumber(jid) {
+  const bare = jid.split("@")[0]?.split(":")[0] ?? "";
+  return bare.startsWith("+") ? bare : `+${bare}`;
+}
+function normalizeJid(jid) {
+  const [user = "", domain] = jid.split("@");
+  const bareUser = user.split(":")[0] ?? user;
+  return domain ? `${bareUser}@${domain}` : bareUser;
+}
+async function senderPhoneFor(sock, message, chatJid) {
+  const key = message.key;
+  let jid = [key.participantPn, key.senderPn, key.participant, key.remoteJidAlt, chatJid].find(
+    (candidate) => typeof candidate === "string" && candidate.length > 0
+  ) ?? chatJid;
+  if (jid.endsWith("@lid")) {
+    try {
+      const mapped = await sock.signalRepository?.lidMapping?.getPNForLID?.(jid);
+      if (mapped) jid = mapped;
+    } catch {
+    }
+  }
+  return jid.endsWith("@lid") ? `lid:${jid.split("@")[0]?.split(":")[0] ?? jid}` : jidToPhoneNumber(jid);
+}
+function messageContext(message) {
+  const content = message.message;
+  const contextInfo = content?.extendedTextMessage?.contextInfo ?? content?.imageMessage?.contextInfo ?? content?.videoMessage?.contextInfo ?? content?.documentMessage?.contextInfo;
+  return {
+    mentionedJids: contextInfo?.mentionedJid ?? [],
+    quotedParticipantJid: contextInfo?.participant ?? void 0
+  };
+}
+function extractText(message) {
+  const content = message.message;
+  if (!content) return "";
+  return content.conversation ?? content.extendedTextMessage?.text ?? content.imageMessage?.caption ?? content.videoMessage?.caption ?? content.documentMessage?.caption ?? "";
+}
+var DEFAULT_GROUP_RATE_LIMIT = { max: 30, windowMs: 60 * 60 * 1e3 };
+var DEFAULT_DM_RATE_LIMIT = { max: 20, windowMs: 60 * 60 * 1e3 };
+async function resolvePersonaLayer(config, ctx) {
+  if (!config.personaResolver) return void 0;
+  try {
+    return await config.personaResolver(ctx);
+  } catch {
+    return void 0;
+  }
+}
+function createWhatsAppInboundHandler(config) {
+  const mutedChats = /* @__PURE__ */ new Set();
+  const now = config.now ?? Date.now;
+  const group = config.groupRateLimit ?? DEFAULT_GROUP_RATE_LIMIT;
+  const dm = config.dmRateLimit ?? DEFAULT_DM_RATE_LIMIT;
+  const underGroupRateLimit = createSlidingWindowRateLimiter(group.max, group.windowMs, now);
+  const underDmRateLimit = createSlidingWindowRateLimiter(dm.max, dm.windowMs, now);
+  return async function handleWhatsAppMessage(event) {
+    const { sessionId, sock, message } = event;
+    try {
+      const chatId = message.key.remoteJid ?? "";
+      if (!chatId || chatId === "status@broadcast") return;
+      const text = extractText(message);
+      const context = messageContext(message);
+      const senderId = message.key.participant ?? chatId;
+      const ownIds = [sock.user?.id, sock.user?.lid].filter((id) => Boolean(id)).map(normalizeJid);
+      config.registry.set(sessionId, ownIds);
+      const fromBot = isEffectivelyFromSelf(
+        { fromBot: message.key.fromMe ?? false, senderId: normalizeJid(senderId) },
+        config.registry
+      );
+      const msg = {
+        chatId,
+        senderId,
+        text,
+        isDirectMessage: !isGroupJid(chatId),
+        mentionsBot: context.mentionedJids.some((jid) => ownIds.some((own) => jidsMatch(jid, own))),
+        isReplyToBot: ownIds.some((own) => jidsMatch(context.quotedParticipantJid, own)),
+        fromBot
+      };
+      const action = decideChannelAction(msg, {
+        allowedChats: config.allowedChats ?? [],
+        mutedChats,
+        muteRegex: config.muteRegex,
+        unmuteRegex: config.unmuteRegex
+      });
+      if (action === "mute") {
+        mutedChats.add(chatId);
+        if (config.muteReply) await sock.sendMessage(chatId, { text: config.muteReply });
+        return;
+      }
+      if (action === "unmute") {
+        mutedChats.delete(chatId);
+        if (config.unmuteReply) await sock.sendMessage(chatId, { text: config.unmuteReply });
+        return;
+      }
+      if (action !== "reply") return;
+      if (!underReplyRateLimit(msg, { dm: underDmRateLimit, group: underGroupRateLimit })) {
+        return;
+      }
+      const senderPhone = await senderPhoneFor(sock, message, chatId);
+      const personaLayer = await resolvePersonaLayer(config, { senderPhone, text });
+      const buckets = await resolveBuckets({
+        mode: "public",
+        sender: senderPhone,
+        bucketsFor: config.bucketsFor
+      });
+      const messages = [{ role: "user", content: text }];
+      const { system } = await prepareChat({
+        store: config.store,
+        prompts: config.prompts,
+        mode: "public",
+        messages,
+        personaLayer,
+        channelHint: config.channelHint,
+        buckets
+      });
+      const { content } = await answerOnce({
+        answerFn: config.answerFn,
+        client: config.client,
+        system,
+        messages,
+        mode: "public",
+        sender: senderPhone,
+        model: config.model
+      });
+      if (content) {
+        await sock.sendMessage(chatId, { text: content }, { quoted: message });
+      }
+    } catch (error) {
+      console.warn(`WhatsApp[${sessionId}]: inbound message handling failed:`, error);
+    }
+  };
+}
 export {
   LEASE_HEARTBEAT_MS,
   LEASE_STALE_MS,
@@ -418,11 +736,18 @@ export {
   canAcquireLease,
   createTursoWaLeaseStore,
   createWhatsAppChannel,
+  createWhatsAppInboundHandler,
   decrypt,
   encrypt,
+  extractText,
+  isGroupJid,
+  jidToPhoneNumber,
+  jidsMatch,
   loadBaileys,
+  messageContext,
   reconnectDelayMs,
   senderNameFor,
+  senderPhoneFor,
   shutdownWaSessions,
   useTursoAuthState
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegoaltoworks/chatter",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "description": "Embeddable AI chatbot framework with RAG, authentication, and customizable widgets",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",