@diegoaltoworks/chatter 0.25.0 → 0.27.0

package/README.md

@@ -25,6 +25,7 @@
 - 📱 **Mobile Optimized**: Responsive design with iOS/Android-specific fixes
 - ⚡ **High Performance**: Built on Hono with streaming support
 - 🛡️ **Security First**: Rate limiting, CORS, referrer checking, and input guardrails
+- 💸 **Usage Metering**: Per-caller and global daily caps for paid features, multi-instance safe, via `@diegoaltoworks/chatter/usage` ([guide](./docs/usage.md))
 - 📦 **Framework Agnostic**: Works with any JavaScript framework or vanilla JS
 - 🎯 **TypeScript**: Fully typed for excellent developer experience
 
@@ -71,8 +72,9 @@ Complete guides for setup, deployment, and integration:
 - **[Requirements](./docs/requirements.md)** - OpenAI, Turso, Clerk setup and pricing
 - **[Server Setup](./docs/server.md)** - Configuration, knowledge base, prompts, API keys
 - **[Client Integration](./docs/client.md)** - Widgets, React components, theming
+- **[Usage Metering](./docs/usage.md)** - Daily spend caps for paid features
 - **[Deployment](./docs/deployment.md)** - Google Cloud Run, Fly.io, Railway, VPS
-- **[Testing](./docs/testing.md)** - Comprehensive testing guide (254 tests, 98% coverage)
+- **[Testing](./docs/testing.md)** - Comprehensive testing guide
 - **[Code Quality](./docs/CODE_QUALITY.md)** - Security assessment and architecture review
 - **[FAQs](./docs/faqs.md)** - Troubleshooting and common questions
 

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/dist/usage/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Usage metering — daily spend guards for anything that costs money per call.
+ *
+ * Published as the `@diegoaltoworks/chatter/usage` subpath so the core install
+ * stays untouched by it. The limiter itself is pure; the Turso store is the
+ * shipped persistence binding and needs `@libsql/client`, which chatter
+ * already expects for retrieval.
+ *
+ * @packageDocumentation
+ */
+export type { DailyLimitCheck, DailyLimiter, DailyLimiterDeps, DailyLimitReason, DailyLimitsConfig, DailyLimitsStore, } from "./limits";
+export { createDailyLimiter, GLOBAL_LIMIT_KEY, pickDailyLimit, utcDayKey } from "./limits";
+export { createTursoUsageStore } from "./tursoStore";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/usage/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,YAAY,EACV,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAC3F,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC"}

package/dist/usage/index.js

@@ -0,0 +1,116 @@
+"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/usage/index.ts
+var index_exports = {};
+__export(index_exports, {
+  GLOBAL_LIMIT_KEY: () => GLOBAL_LIMIT_KEY,
+  createDailyLimiter: () => createDailyLimiter,
+  createTursoUsageStore: () => createTursoUsageStore,
+  pickDailyLimit: () => pickDailyLimit,
+  utcDayKey: () => utcDayKey
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/usage/limits.ts
+var GLOBAL_LIMIT_KEY = "global";
+function utcDayKey(now) {
+  return new Date(now).toISOString().slice(0, 10);
+}
+function createDailyLimiter(config, deps) {
+  const now = deps.now ?? Date.now;
+  return {
+    async checkAndReserve(key) {
+      const day = utcDayKey(now());
+      const perKeyCount = await deps.store.incrementAndGet("key", key, day);
+      if (perKeyCount > config.perKeyDailyLimit) {
+        return { allowed: false, reason: "per-key" };
+      }
+      const globalCount = await deps.store.incrementAndGet("global", GLOBAL_LIMIT_KEY, day);
+      if (globalCount > config.globalDailyLimit) {
+        return { allowed: false, reason: "global" };
+      }
+      return { allowed: true, reason: null };
+    }
+  };
+}
+function pickDailyLimit(value, fallback) {
+  const trimmed = value?.trim();
+  if (trimmed === void 0 || trimmed === "") return fallback;
+  const parsed = Number(trimmed);
+  return Number.isInteger(parsed) && parsed >= 0 ? parsed : fallback;
+}
+
+// src/usage/tursoStore.ts
+var schemaReady = /* @__PURE__ */ new WeakMap();
+function ensureUsageSchema(client, tableName) {
+  let perTable = schemaReady.get(client);
+  if (!perTable) {
+    perTable = /* @__PURE__ */ new Map();
+    schemaReady.set(client, perTable);
+  }
+  const tables = perTable;
+  let ready = tables.get(tableName);
+  if (!ready) {
+    ready = client.execute(
+      `CREATE TABLE IF NOT EXISTS ${tableName} (
+          scope TEXT NOT NULL,
+          key TEXT NOT NULL,
+          day TEXT NOT NULL,
+          count INTEGER NOT NULL DEFAULT 0,
+          PRIMARY KEY (scope, key, day)
+        )`
+    ).catch((error) => {
+      tables.delete(tableName);
+      throw error;
+    });
+    tables.set(tableName, ready);
+  }
+  return ready;
+}
+var VALID_TABLE_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function createTursoUsageStore(client, tableName) {
+  if (!VALID_TABLE_NAME.test(tableName)) {
+    throw new Error(`Invalid usage store table name: ${tableName}`);
+  }
+  return {
+    async incrementAndGet(scope, key, day) {
+      await ensureUsageSchema(client, tableName);
+      const result = await client.execute({
+        sql: `INSERT INTO ${tableName} (scope, key, day, count) VALUES (?, ?, ?, 1)
+              ON CONFLICT(scope, key, day) DO UPDATE SET count = count + 1
+              RETURNING count`,
+        args: [scope, key, day]
+      });
+      const row = result.rows[0];
+      if (!row) {
+        throw new Error(`${tableName} returned no row from upsert`);
+      }
+      return Number(row.count);
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  GLOBAL_LIMIT_KEY,
+  createDailyLimiter,
+  createTursoUsageStore,
+  pickDailyLimit,
+  utcDayKey
+});

package/dist/usage/index.mjs

@@ -0,0 +1,85 @@
+// src/usage/limits.ts
+var GLOBAL_LIMIT_KEY = "global";
+function utcDayKey(now) {
+  return new Date(now).toISOString().slice(0, 10);
+}
+function createDailyLimiter(config, deps) {
+  const now = deps.now ?? Date.now;
+  return {
+    async checkAndReserve(key) {
+      const day = utcDayKey(now());
+      const perKeyCount = await deps.store.incrementAndGet("key", key, day);
+      if (perKeyCount > config.perKeyDailyLimit) {
+        return { allowed: false, reason: "per-key" };
+      }
+      const globalCount = await deps.store.incrementAndGet("global", GLOBAL_LIMIT_KEY, day);
+      if (globalCount > config.globalDailyLimit) {
+        return { allowed: false, reason: "global" };
+      }
+      return { allowed: true, reason: null };
+    }
+  };
+}
+function pickDailyLimit(value, fallback) {
+  const trimmed = value?.trim();
+  if (trimmed === void 0 || trimmed === "") return fallback;
+  const parsed = Number(trimmed);
+  return Number.isInteger(parsed) && parsed >= 0 ? parsed : fallback;
+}
+
+// src/usage/tursoStore.ts
+var schemaReady = /* @__PURE__ */ new WeakMap();
+function ensureUsageSchema(client, tableName) {
+  let perTable = schemaReady.get(client);
+  if (!perTable) {
+    perTable = /* @__PURE__ */ new Map();
+    schemaReady.set(client, perTable);
+  }
+  const tables = perTable;
+  let ready = tables.get(tableName);
+  if (!ready) {
+    ready = client.execute(
+      `CREATE TABLE IF NOT EXISTS ${tableName} (
+          scope TEXT NOT NULL,
+          key TEXT NOT NULL,
+          day TEXT NOT NULL,
+          count INTEGER NOT NULL DEFAULT 0,
+          PRIMARY KEY (scope, key, day)
+        )`
+    ).catch((error) => {
+      tables.delete(tableName);
+      throw error;
+    });
+    tables.set(tableName, ready);
+  }
+  return ready;
+}
+var VALID_TABLE_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function createTursoUsageStore(client, tableName) {
+  if (!VALID_TABLE_NAME.test(tableName)) {
+    throw new Error(`Invalid usage store table name: ${tableName}`);
+  }
+  return {
+    async incrementAndGet(scope, key, day) {
+      await ensureUsageSchema(client, tableName);
+      const result = await client.execute({
+        sql: `INSERT INTO ${tableName} (scope, key, day, count) VALUES (?, ?, ?, 1)
+              ON CONFLICT(scope, key, day) DO UPDATE SET count = count + 1
+              RETURNING count`,
+        args: [scope, key, day]
+      });
+      const row = result.rows[0];
+      if (!row) {
+        throw new Error(`${tableName} returned no row from upsert`);
+      }
+      return Number(row.count);
+    }
+  };
+}
+export {
+  GLOBAL_LIMIT_KEY,
+  createDailyLimiter,
+  createTursoUsageStore,
+  pickDailyLimit,
+  utcDayKey
+};

package/dist/usage/limits.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Daily spend guards — the counting half of "this feature costs money, cap it".
+ *
+ * Framework-free and storage-free: this module knows how to decide, never how
+ * to persist. A host supplies a {@link DailyLimitsStore} (see ./tursoStore for
+ * the shipped one) and instantiates one limiter per metered resource — image
+ * generation, voice minutes, anything with a per-unit price — by giving each
+ * its own store table. Nothing here is chat-specific.
+ */
+/** The two caps every metered resource is subject to. */
+export interface DailyLimitsConfig {
+    /** Units one key may reserve per UTC day. */
+    perKeyDailyLimit: number;
+    /** Units all keys together may reserve per UTC day. */
+    globalDailyLimit: number;
+}
+/** The key the global counter is stored under — that scope has no caller key. */
+export declare const GLOBAL_LIMIT_KEY = "global";
+/** Which cap blocked the request, or null when it was allowed. */
+export type DailyLimitReason = "per-key" | "global" | null;
+export interface DailyLimitCheck {
+    allowed: boolean;
+    reason: DailyLimitReason;
+}
+/**
+ * Structural dependency — a host implements this against its own storage.
+ *
+ * Must increment and read back atomically. Deployments run multiple instances,
+ * so a read-then-write from this process would race with another instance's
+ * and both would see room under a cap that only had space for one.
+ */
+export interface DailyLimitsStore {
+    /** Increments the counter for (scope, key, day) and returns the count after incrementing. */
+    incrementAndGet(scope: "key" | "global", key: string, day: string): Promise<number>;
+}
+/** The UTC calendar day counters roll over on, e.g. "2026-08-01". */
+export declare function utcDayKey(now: number): string;
+export interface DailyLimiterDeps {
+    store: DailyLimitsStore;
+    /** Clock, injectable so day-rollover tests don't depend on real time. */
+    now?: () => number;
+}
+export interface DailyLimiter {
+    /**
+     * Reserves one unit for `key`, subject to both daily caps.
+     *
+     * Call this exactly once per logical request: the increment is permanent and
+     * unconditional (there is no release path), so a duplicate call — or a retry
+     * after a transient failure — permanently burns a second unit of quota for
+     * one request never delivered. Blocked calls still count: a call that trips
+     * the per-key cap still consumes one of that key's daily units, and (by
+     * design — see below) a call that trips the global cap after passing the
+     * per-key check also consumes one of that key's units, for nothing.
+     *
+     * The per-key counter increments before the global one, so a key blocked at
+     * its own cap never touches the shared global budget. The mirror case is
+     * accepted, not fixed: once the global cap is exhausted for the day, every
+     * further caller still burns one of their own per-key units on the way to
+     * being told no. This favours guarding against the more common cost risk
+     * (one key hammering the endpoint) over the rarer one (the global cap
+     * saturating and clipping everyone's personal quota).
+     *
+     * Reserve before spending, not after: the ordering is what makes the cap a
+     * cap. Callers with a cache should check it first, so a cache hit costs
+     * neither money nor quota.
+     */
+    checkAndReserve(key: string): Promise<DailyLimitCheck>;
+}
+export declare function createDailyLimiter(config: DailyLimitsConfig, deps: DailyLimiterDeps): DailyLimiter;
+/**
+ * Reads a cap out of loosely-typed configuration (an env var, a JSON field).
+ *
+ * A configured non-negative integer wins over the default; anything else —
+ * unset, blank, negative, fractional, unparseable — falls back. A malformed
+ * cap must not silently become `NaN`, which compares false against every
+ * count and would disable the guard entirely.
+ *
+ * Blank is trimmed before parsing rather than compared raw: `Number(" ")` is
+ * `0`, so a config value that is whitespace would otherwise be read as a cap
+ * of zero and switch the feature off entirely instead of falling back.
+ *
+ * This is the supported way to build a {@link DailyLimitsConfig}. The limiter
+ * itself does not validate its caps, so a `NaN` reaching it from somewhere
+ * else fails open.
+ */
+export declare function pickDailyLimit(value: string | undefined, fallback: number): number;
+//# sourceMappingURL=limits.d.ts.map

package/dist/usage/limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../../src/usage/limits.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,yDAAyD;AACzD,MAAM,WAAW,iBAAiB;IAChC,6CAA6C;IAC7C,gBAAgB,EAAE,MAAM,CAAC;IACzB,uDAAuD;IACvD,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,iFAAiF;AACjF,eAAO,MAAM,gBAAgB,WAAW,CAAC;AAEzC,kEAAkE;AAClE,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,QAAQ,GAAG,IAAI,CAAC;AAE3D,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,gBAAgB,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6FAA6F;IAC7F,eAAe,CAAC,KAAK,EAAE,KAAK,GAAG,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACrF;AAED,qEAAqE;AACrE,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,gBAAgB,CAAC;IACxB,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CACxD;AAED,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,iBAAiB,EACzB,IAAI,EAAE,gBAAgB,GACrB,YAAY,CAoBd;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKlF"}

package/dist/usage/limits.test.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Daily limiter tests.
+ *
+ * Two properties matter more than the arithmetic and are asserted directly:
+ * the *order* of the two increments (a key blocked at its own cap must not
+ * burn shared budget), and the reserve-once semantics (every call counts,
+ * including blocked ones — there is no release path to lean on).
+ */
+export {};
+//# sourceMappingURL=limits.test.d.ts.map

package/dist/usage/limits.test.d.ts.map

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

package/dist/usage/tursoStore.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Turso/libsql-backed {@link DailyLimitsStore}.
+ *
+ * Schema and upsert only — error typing and wrapping stay with the caller,
+ * because each metered feature wants its own error contract and this layer
+ * should not invent one for them.
+ *
+ * `@libsql/client` is imported for its type alone, so this module adds no
+ * runtime dependency to anyone importing `./usage` for the pure limiter.
+ */
+import type { Client } from "@libsql/client";
+import type { DailyLimitsStore } from "./limits";
+/**
+ * Creates a store that counts into `tableName` on `client`.
+ *
+ * The upsert is a single atomic statement returning the post-increment count,
+ * so concurrent instances each get a distinct number and the cap holds across
+ * a multi-instance deployment. Table creation is idempotent and happens once
+ * per (client, table).
+ *
+ * Give each metered resource its own table — sharing one would make separate
+ * features compete for a single global counter.
+ */
+export declare function createTursoUsageStore(client: Client, tableName: string): DailyLimitsStore;
+//# sourceMappingURL=tursoStore.d.ts.map

package/dist/usage/tursoStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tursoStore.d.ts","sourceRoot":"","sources":["../../src/usage/tursoStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAyCjD;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,gBAAgB,CAuBzF"}

package/dist/usage/tursoStore.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Turso usage store tests.
+ *
+ * Run against a real in-memory libsql client rather than a fake, because the
+ * properties worth proving here are SQL-level: the upsert is atomic, it hands
+ * every concurrent caller a distinct number, and table creation is idempotent.
+ */
+export {};
+//# sourceMappingURL=tursoStore.test.d.ts.map

package/dist/usage/tursoStore.test.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegoaltoworks/chatter",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "description": "Embeddable AI chatbot framework with RAG, authentication, and customizable widgets",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -28,6 +28,11 @@
       "types": "./dist/mcp-server.d.ts",
       "import": "./dist/mcp-server.mjs",
       "require": "./dist/mcp-server.js"
+    },
+    "./usage": {
+      "types": "./dist/usage/index.d.ts",
+      "import": "./dist/usage/index.mjs",
+      "require": "./dist/usage/index.js"
     }
   },
   "files": [
@@ -37,12 +42,13 @@
   ],
   "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: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:bin && bun run build:client && bun run build:copy-client",
     "build:clean": "rm -rf dist",
     "build:types": "tsc --emitDeclarationOnly --outDir dist",
     "build:esm": "esbuild src/index.ts --bundle --format=esm --outfile=dist/index.mjs --external:hono --external:openai --external:@libsql/client --external:jose --platform=node --target=node24",
     "build:cjs": "esbuild src/index.ts --bundle --format=cjs --outfile=dist/index.js --external:hono --external:openai --external:@libsql/client --external:jose --platform=node --target=node24",
     "build:mcp": "esbuild src/mcp-server.ts --bundle --format=esm --outfile=dist/mcp-server.mjs --external:@modelcontextprotocol/sdk --external:openai --external:@libsql/client --external:zod --platform=node --target=node24 && esbuild src/mcp-server.ts --bundle --format=cjs --outfile=dist/mcp-server.js --external:@modelcontextprotocol/sdk --external:openai --external:@libsql/client --external:zod --platform=node --target=node24",
+    "build:usage": "esbuild src/usage/index.ts --bundle --format=esm --outfile=dist/usage/index.mjs --external:@libsql/client --platform=node --target=node24 && esbuild src/usage/index.ts --bundle --format=cjs --outfile=dist/usage/index.js --external:@libsql/client --platform=node --target=node24",
     "build: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'",
     "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/",