@diegoaltoworks/chatter 0.25.0 → 0.26.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/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.26.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/",