@diegoaltoworks/chatter 0.26.0 → 0.27.0

package/dist/channels/gates.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Channel-agnostic reply gates — pure and testable, zero imports from the
+ * rest of chatter. A transport (WhatsApp, or any future channel) resolves
+ * its own wire format into a {@link ChannelMessage} and calls
+ * {@link decideChannelAction} to learn whether to answer, stay quiet, or
+ * flip a mute switch. Nothing here knows about jids, Baileys, or any
+ * specific bot's name — mention/reply-to detection is the transport's job;
+ * this module only combines the already-resolved booleans with allowlist,
+ * mute, and rate-limit policy.
+ */
+/** The slice of an inbound message every channel can resolve into this shape. */
+export interface ChannelMessage {
+    /** The conversation this message belongs to — a DM thread or a group. */
+    chatId: string;
+    senderId: string;
+    text: string;
+    /** True for a 1:1 conversation; false for a group/channel with other members. */
+    isDirectMessage: boolean;
+    /** Resolved by the caller: does this message @-mention the bot? */
+    mentionsBot: boolean;
+    /** Resolved by the caller: is this message a reply to one of the bot's own messages? */
+    isReplyToBot: boolean;
+    /** True when the bot itself sent this message (including via another session — see {@link isEffectivelyFromSelf}). */
+    fromBot: boolean;
+}
+export type ChannelAction = "reply" | "ignore" | "mute" | "unmute";
+export interface ChannelGateConfig {
+    /** Chats eligible for a reply. Empty = every chat is eligible (the master allowlist switch). */
+    allowedChats: string[];
+    /** Group chats currently muted — addressed messages there are ignored until unmuted. Has no effect on DMs, which always reply. */
+    mutedChats: Set<string>;
+    /**
+     * Caller-supplied trigger for "go quiet in this group chat". No default:
+     * this module ships no bot name or in-character phrasing, so mute/unmute
+     * are inert unless a host configures a pattern. Never applied to DMs.
+     */
+    muteRegex?: RegExp;
+    unmuteRegex?: RegExp;
+}
+/**
+ * DMs always reply. In groups, only an allowlisted, unmuted chat gets a
+ * reply, and only when addressed (mentioned or replying to the bot) —
+ * merely mentioning the bot's name in third person is not an invitation.
+ * The unmute check runs before the muted-chat gate so an unmute phrase can
+ * un-silence the bot in the same message, and both run after the allowlist
+ * so a chat the bot isn't eligible for can't toggle its mute state.
+ */
+export declare function decideChannelAction(msg: ChannelMessage, config: ChannelGateConfig): ChannelAction;
+/**
+ * Sliding-window rate limiter (pure, injectable clock): true = allowed and
+ * counted. One instance guards one budget — callers wanting separate DM and
+ * group budgets create two (see {@link underReplyRateLimit}).
+ */
+export declare function createSlidingWindowRateLimiter(maxPerWindow: number, windowMs: number, now?: () => number): (key: string) => boolean;
+/**
+ * Routes a chat to its DM or group rate limiter so a flood in one can't
+ * spend the other's budget — a DM flood used to be entirely unthrottled
+ * before this split existed. Each limiter is expected to be its own
+ * {@link createSlidingWindowRateLimiter} instance.
+ */
+export declare function underReplyRateLimit(msg: Pick<ChannelMessage, "chatId" | "isDirectMessage">, limiters: {
+    dm: (chatId: string) => boolean;
+    group: (chatId: string) => boolean;
+}): boolean;
+/**
+ * Every session's own identities ever seen, keyed by session id. A
+ * multi-session deployment (e.g. two linked numbers in one process) gives
+ * each session only its own identity from its transport — a message that
+ * actually came from a *different* session's identity looks like a
+ * stranger, not "us", and the two sessions can ping-pong replies at each
+ * other indefinitely. Callers populate this directly (`registry.set(sessionId, ids)`)
+ * as each session's identities become known, typically on connect and kept
+ * in sync as they change.
+ *
+ * Entries are NOT expected to be removed when a session disconnects: a
+ * session's own identity is still "us" while it reconnects, and losing that
+ * during exactly the disconnect/reconnect window this guard exists for
+ * would defeat it.
+ */
+export type SessionIdentityRegistry = Map<string, string[]>;
+/** True when `id` matches an identity of ANY session ever registered, not just the one that received the message. */
+export declare function isFromAnySession(id: string | undefined, registry: SessionIdentityRegistry): boolean;
+/**
+ * The one predicate transports need before deciding fromBot: a message is
+ * effectively from the bot itself if the transport already flagged it so,
+ * or if its sender id matches an identity registered by any session (the
+ * loop-guard case a single session's own flag can't catch).
+ */
+export declare function isEffectivelyFromSelf(msg: Pick<ChannelMessage, "fromBot" | "senderId">, registry: SessionIdentityRegistry): boolean;
+//# sourceMappingURL=gates.d.ts.map

package/dist/channels/gates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gates.d.ts","sourceRoot":"","sources":["../../src/channels/gates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,iFAAiF;AACjF,MAAM,WAAW,cAAc;IAC7B,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,eAAe,EAAE,OAAO,CAAC;IACzB,mEAAmE;IACnE,WAAW,EAAE,OAAO,CAAC;IACrB,wFAAwF;IACxF,YAAY,EAAE,OAAO,CAAC;IACtB,sHAAsH;IACtH,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEnE,MAAM,WAAW,iBAAiB;IAChC,gGAAgG;IAChG,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,kIAAkI;IAClI,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACxB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAOD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,cAAc,EAAE,MAAM,EAAE,iBAAiB,GAAG,aAAa,CAYjG;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAC5C,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,GAAG,GAAE,MAAM,MAAiB,SAGD,MAAM,KAAG,OAAO,CAY5C;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,IAAI,CAAC,cAAc,EAAE,QAAQ,GAAG,iBAAiB,CAAC,EACvD,QAAQ,EAAE;IAAE,EAAE,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;IAAC,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAA;CAAE,GAChF,OAAO,CAET;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,uBAAuB,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;AAE5D,qHAAqH;AACrH,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,MAAM,GAAG,SAAS,EACtB,QAAQ,EAAE,uBAAuB,GAChC,OAAO,CAMT;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,IAAI,CAAC,cAAc,EAAE,SAAS,GAAG,UAAU,CAAC,EACjD,QAAQ,EAAE,uBAAuB,GAChC,OAAO,CAET"}

package/dist/channels/gates.test.d.ts

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

package/dist/channels/gates.test.d.ts.map

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

package/package.json

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