@adriangalilea/utils 2.38.1 → 4.0.0

package/README.md

@@ -2,6 +2,57 @@
 
 TypeScript utilities - logger, currency, offensive programming, file operations, environment management, and more. The sibling of [swift-utils](https://github.com/adriangalilea/swift-utils), [py-utils](https://github.com/adriangalilea/py-utils), and [go-utils](https://github.com/adriangalilea/go-utils). The logging doctrine the three share, and the harness that proves they emit the same record line, live in [utils](https://github.com/adriangalilea/utils).
 
+## Product metrics
+
+```ts
+import { createClient } from "@libsql/client"
+import { defineMetrics } from "@adriangalilea/utils/metrics"
+import { sqliteMetricsWriter } from "@adriangalilea/utils/metrics/sqlite"
+
+const db = createClient({ url: process.env.METRICS_DATABASE_URL!, authToken: process.env.METRICS_AUTH_TOKEN })
+const metrics = defineMetrics({
+  installCopy: { kind: "counter", label: "install command copies", dimensions: { component: ["chat", "glass"] } },
+}, { write: sqliteMetricsWriter(db, "my-project") })
+
+await metrics.installCopy.bump({ dimensions: { component: "chat" } })
+```
+
+Provision the exported `METRICS_SCHEMA` once before collecting. `describe()` returns
+the declarations; the SQL writer stores labels beside daily counters so reports
+discover metrics without another hardcoded list. `readMetrics(db, { from, to,
+project? })` returns daily rows with labels and dimensions, using inclusive UTC dates.
+Readers propagate database errors rather than presenting missing data as zero.
+`summarizeMetrics(rows)` from `metrics/report` produces one generic report shape;
+`renderMetrics(rows, { daily? })` from `metrics/cli` renders it with the existing
+ANSI-aware `cli.table` helpers. Both discover every recorded metric from its
+declaration metadata. No product-specific metric list belongs in a renderer.
+The SQL adapter accepts a libSQL-compatible client; D1 or another store can implement
+the injected `write(measurement)` contract instead. No database client is bundled.
+
+Measurements validate finite nonnegative samples, positive integer counts, and
+declared dimension values. Calls resolve even when validation or storage fails;
+`onError(error, key)` observes failures (the default logs a warning without actor
+data). Await calls or attach them to the runtime's request lifetime (`after` in
+Next.js, `waitUntil` in Workers). Unattached promises are not reliable delivery.
+Counters are best-effort observations, not exactly-once ledgers; retries can count
+twice. Money and successful-install accounting belong elsewhere.
+
+`perUser: true` accepts an optional string or numeric `user` for daily actor rows.
+Enable it only with a deletion and retention policy; no identity is inferred.
+`overlaps: [["a", "b"]]` declares unordered audience overlap, not an ordered funnel.
+Daily totals support counts and averages, not percentile latency or event ordering.
+
+**4.0 migration:** import `DailyMetric` from `metrics/report`, not `metrics/sqlite`.
+Report types and renderers are store-independent; SQLite is one optional adapter.
+This removes the old type export rather than retaining a compatibility alias.
+
+**3.0 migration:** `bot/metrics` and its bot-barrel export are removed. Import
+`@adriangalilea/utils/metrics`; replace `write(key, count, sum, user)` with
+`write({ key, count, sum, user, day, dimensions, spec })`. Rename `funnels` to
+`overlaps` in declarations and schema consumers. Existing stores can adapt the new
+write object without moving historical data. Metric keys and dimensions are storage
+identifiers: introduce a new key when changing meaning rather than relabelling history.
+
 ## Installation
 
 ```bash
@@ -611,7 +662,8 @@ Telegram's [Threaded Mode](https://telegram.org/blog/threaded-conversations) for
 | `@adriangalilea/utils/bot/coalesce` | Joins client-split inbound messages back into one. When a user pastes >4096 chars, Telegram clients fragment it into separate `message` updates with no marker. Middleware detects the burst and emits one combined event. |
 | `@adriangalilea/utils/llm` | Multi-provider LLM caller on the Vercel AI SDK — the policy layer the SDK doesn't ship. `createLlm({ providers, health? })` → `.stream(req)` (typed events: `delta` / `reasoning` / `reset` / `tool-call` / `end`) and `.complete(req)`. **Failover:** priority-ordered across OpenAI-compatible, Anthropic-compatible, and OpenRouter endpoints; multiple keys per provider (health tracked per key fingerprint); per-key circuit breaker with exponential cool-down persisted in any KV-shaped `HealthStore`; an attempt that dies after emitting yields `reset` (discard, next candidate regenerates); empty completions count as failures. **Accounting:** tokens summed across billed attempts; `costUsd` is the ACTUAL charge (OpenRouter usage accounting via `providerMetadata`, or a `cost` field on the raw usage frame) — never a price-table estimate. **Knobs:** per-model temperature, maxTokens caps, `disableThinking` mapped to each dialect. **Tools:** AI SDK `tool()` + `toolChoice` pass through (re-exported). Worker-safe; peers: `ai`, `@ai-sdk/openai-compatible`, `@ai-sdk/anthropic`, `@openrouter/ai-sdk-provider`. |
 | `@adriangalilea/utils/bot/llm` | The Telegram side of an LLM chatbot; the model side is `@adriangalilea/utils/llm`. **Output:** `streamChatReply(ctx, events, opts?)` consumes an `AsyncIterable<LlmStreamEvent>` and paints it with Telegram's native message-draft streaming (`sendMessageDraft` full-frame repaints, throttled ~1/s, keepalive under the ~30s draft TTL), then persists the finished markdown via `ctx.send`, entity-split across 4096 by `@gramio/split`. Reasoning models get a thinking phase — streams into the ephemeral draft and evaporates (`reasoning: 'preview'`, default), persists as an expandable blockquote (`'message'`), or never renders at all (`'hidden'`). Upstream `reset` (provider failover) repaints the draft from scratch. Drafts are private-chat-only (+ BotFather forum-topic mode); elsewhere the preview phase is skipped and only the final send happens. Returns `{ content, reasoning, toolCalls, usage, messages }`. The painter underneath is `@adriangalilea/utils/bot/draft` (`createDraftPreview(ctx, { render, throttleMs? })`): dependency-light (no markdown machinery), for producers that push deltas or own their per-frame rendering (plain or rich-message frames) and persist path, with `streamForensics` (render-regression + reset warnings) built in and exported standalone. **History:** `llmHistory({...})` returns `.plugin` (decorates `ctx.llm` with `.add() / .get() / .clear() / .all() / .clearAll()`, per-(user, thread) OpenAI `ChatMessage` shape, persisted in the shared session record so the menu's 🗑 Forget wipes it automatically) AND `.menuItem` (drop-in "🗑 Delete this thread" for `botMenu` — wipes the LLM history AND calls `deleteForumTopic` so the Telegram thread + all its messages disappear from the chat; falls back to history-only clear when no `threadId` is present). |
-| `@adriangalilea/utils/bot/metrics` | Self-serve product measurement, the flags pattern applied to counting: `defineMetrics(spec, { write, funnels? })` — declare a metric once (counter / timing, `perUser: true` for uniques·repeat·retention·funnels), `bump()`/`record()` at the call site (fire-and-forget, never throws), `describe()` is the schema panels render generically so a new metric reaches every panel with zero panel edits. Storage = one injected atomic day-bucket upsert (aggregate row + per-user row when `user` given); per-user rows are personal data — wipe on forget, prune by age. Money stays in ledgers. |
+| `@adriangalilea/utils/metrics` | Declared counters and timings, bounded dimensions, optional actor IDs, and a schema for generic reporting. Inject a writer; measurement failures are reported without rejecting calls. See Product metrics below. |
+| `@adriangalilea/utils/metrics/sqlite` | Atomic SQLite/libSQL writer, explicit provisioning schema, and inclusive UTC daily reports. Connections and credentials belong to the application. |
 | `@adriangalilea/utils/bot/menu` | `botMenu({ command, description, items, privacy?, personalData?, adminContact })` — `/settings` command + InlineKeyboard router. Root view always renders a `🛡️ Privacy & data` submenu button that wraps the privacy policy link plus (if `personalData: { storage }`) 🗑 Forget + 📥 Export buttons. Items take `keepRow` (render on the same row as the next item — e.g. a two-per-row language picker) and `rootExtra` (render at the bottom of the root menu, below Privacy & data). `label` / `header` / `style` / `visible` resolvers may be **async** (read your db at render time — never cache render strings in the session); `parseMode: 'HTML'` renders the header formatted (you own escaping); `personalData.onForget(ctx, userId)` wipes YOUR tables inside the same try as the session delete, so Forget either forgets everything or reports failure. `toggleMenuItem({ id, read, write, label: { off, on }, toast? })` — convenience factory for boolean-toggle items with dynamic label + optional toast, storage-agnostic via `read`/`write` closures. |
 | `@adriangalilea/utils/bot/payments` | `botPayments({ session, storage, paysupport, paysupportHint?, legal, waiver, vip?, credits?, perks? })` — Telegram Stars monetization in one drop-in plugin. **Three axes, all optional:** `vip` (positional tier ladder — single rung in v1 is just `vip: [{...}]`, ladder is `vip: [{...}, {...}]`; ids are `vip.1`, `vip.2`, …), `credits` (consumable balance + top-up packs `credits.1`, `credits.2`, …), `perks` (orthogonal one-shot unlocks `perks.<key>`). **Surface:** `ctx.payments.atLeast('vip')` / `atLeast('vip.2')` (typed rank check), `ctx.payments.tier()` / `.tier.level()` / `.tier.label()`, `ctx.payments.credits.{balance, consume, tryConsume}` (throws `InsufficientCredits`), `ctx.payments.has(perkId)`, `await ctx.payments.require('vip', { feature? })` (gate that sends a localized upgrade prompt deep-linked to `/settings → 💎 VIP`), `await ctx.payments.invoice(productKey)` (threads Art. 103(m) TRLGDCU consent inline before `sendInvoice`). **Owns:** waiver consent flow (versioned text → forces re-consent on bump, snapshotted on every charge for audit), `/paysupport` slash command (Telegram ToS §6.5; `paysupportHint` overrides the where-to-manage-charges line when your menu isn't `/settings`), idempotent `successful_payment` fulfillment via `pay:idempotency:{chargeId}` sentinel, lazy subscription expiry (no cron needed), tier upgrade auto-cancel of the lower rung's renewal, and admin-DM refund approval (mirror of `accessControl`'s [✅ Aprobar][❌ Denegar] pattern). **Returns:** `{ plugin, menuItem, payouts, onFulfilled }` — `menuItem` is the drop-in `💎 VIP` entry for `botMenu`; `payouts.{record, list, export, exportForUsers}` is the Fragment payout ledger (you receive TON, log the EUR conversion, export time-windowed CSV/JSON for your gestor); `onFulfilled(productKey \| '*', handler)` / `onRefunded(...)` register fire-and-forget hooks (purchase applied / admin-approved refund — a revenue ledger writes on one, reverses on the other). **Stars-only by design** — Telegram ToS §6.2 forbids third-party payment providers for digital goods. Crypto Pay deferred (MiCA risk); Stripe-outside-Telegram is a future v2 channel. Full compliance memo (Spanish-autónomo seller-of-record analysis, Verifactu vs Crea y Crece, MiCA, Art. 103(m) waiver text, GDPR retention) in `src/bot/payments/CLAUDE.md`. |
 | `@adriangalilea/utils/bot/create` | `createBot<S>({ token?, storage?, initial?, admins?, language?, menu?, access?, payments?, handlers?, worker? })` — the composer (see "One bot file, ideation → production" above). Returns `{ build, session, poll, isMain, fetch }`: `poll()` long-polls, `export default app` is a complete Worker, `app.session(ctx)` / the `handlers` callback's `session(ctx)` is the TYPED accessor for your `S` fields. Owns storage+session wiring; resolves storage per environment (D1 binding → `bot/storage-d1`; `BOT_PERSIST` path → sqlite, `redis://` → redis, lazily-imported optional peers; else announced-ephemeral memory) — or pass `storage: (env) => Storage` when the choice is env-dependent (e.g. a D1 binding not named `DB`). Boot NARRATES the composition (`session: memory …`, `features: language(en,es) · menu(/settings)`) so every implicit decision is visible where you're looking. Runnable demo: `pnpm demo:bot`. |
@@ -745,4 +797,4 @@ Bump version in `package.json`, push to `main`. CI handles everything:
 
 ## License
 
-MIT
+MIT

package/dist/bot/index.d.ts

@@ -24,7 +24,6 @@ export * from "./kit.js";
 export * from "./language.js";
 export * from "./llm.js";
 export * from "./menu.js";
-export * from "./metrics.js";
 export * from "./notify.js";
 export * from "./payments/index.js";
 export * from "./storage.js";

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bot/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC;AACrC,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bot/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC;AACrC,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC"}

package/dist/bot/index.js

@@ -24,7 +24,6 @@ export * from "./kit.js";
 export * from "./language.js";
 export * from "./llm.js";
 export * from "./menu.js";
-export * from "./metrics.js";
 export * from "./notify.js";
 export * from "./payments/index.js";
 export * from "./storage.js";

package/dist/bot/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/bot/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC;AACrC,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/bot/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC;AACrC,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC"}

package/dist/metrics/cli.d.ts

@@ -0,0 +1,6 @@
+import { type DailyMetric } from "./report.js";
+/** Render declarations stored beside observations; adding a metric requires no panel edit. */
+export declare function renderMetrics(rows: readonly DailyMetric[], options?: {
+    daily?: boolean;
+}): string;
+//# sourceMappingURL=cli.d.ts.map

package/dist/metrics/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/metrics/cli.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,WAAW,EAAoB,MAAM,aAAa,CAAC;AAEjE,8FAA8F;AAC9F,wBAAgB,aAAa,CAC5B,IAAI,EAAE,SAAS,WAAW,EAAE,EAC5B,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAC/B,MAAM,CAoDR"}

package/dist/metrics/cli.js

@@ -0,0 +1,50 @@
+import { table, ui } from "../cli/index.js";
+import { summarizeMetrics } from "./report.js";
+/** Render declarations stored beside observations; adding a metric requires no panel edit. */
+export function renderMetrics(rows, options = {}) {
+    if (!rows.length)
+        return "No recorded measurements in this window.";
+    const lines = [];
+    const totals = summarizeMetrics(rows);
+    const groups = new Map();
+    for (const total of totals) {
+        const key = JSON.stringify([total.project, total.key]);
+        const group = groups.get(key) ?? [];
+        group.push(total);
+        groups.set(key, group);
+    }
+    for (const group of groups.values()) {
+        const timing = group[0].kind === "timing";
+        const number = (n) => new Intl.NumberFormat("en-US", { maximumFractionDigits: 2 }).format(n);
+        lines.push(ui.head(`${group[0].project} · ${group[0].label}`));
+        const source = options.daily
+            ? rows
+                .filter((r) => r.project === group[0].project && r.key === group[0].key)
+                .map((r) => ({ ...r, average: r.count ? r.sum / r.count : null }))
+            : group;
+        lines.push(table(source.map((r) => [
+            ...(options.daily ? ["day" in r ? String(r.day) : ""] : []),
+            Object.entries(r.dimensions)
+                .map(([k, v]) => `${k}=${v}`)
+                .join(" · ") || "all",
+            number(r.count),
+            ...(timing ? [`${number(r.average ?? 0)} ${r.unit}`.trim()] : []),
+        ]), {
+            head: [
+                ...(options.daily ? ["day"] : []),
+                "breakdown",
+                timing ? "samples" : "count",
+                ...(timing ? ["average"] : []),
+            ],
+            align: [
+                ...(options.daily ? ["l"] : []),
+                "l",
+                "r",
+                ...(timing ? ["r"] : []),
+            ],
+        }));
+        lines.push("");
+    }
+    return lines.join("\n").trimEnd();
+}
+//# sourceMappingURL=cli.js.map

package/dist/metrics/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/metrics/cli.ts"],"names":[],"mappings":"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"}

package/dist/metrics/index.d.ts

@@ -0,0 +1,54 @@
+/** Product measurement with declared keys and bounded dimensions. No runtime or store dependency. */
+export type MetricSpec = {
+    kind: "counter" | "timing";
+    label: string;
+    help?: string;
+    unit?: string;
+    perUser?: boolean;
+    dimensions?: Record<string, readonly string[]>;
+};
+export interface Measurement {
+    key: string;
+    day: string;
+    count: number;
+    sum: number;
+    user?: string | number;
+    dimensions: Record<string, string>;
+    spec: MetricSpec;
+}
+export interface MetricsOptions<Keys extends string = string> {
+    write: (measurement: Measurement) => Promise<unknown>;
+    /** Unordered user overlap, not an ordered conversion funnel. */
+    overlaps?: ReadonlyArray<readonly [Keys, Keys]>;
+    /** Failures are visible by default, but never reject a measurement call. */
+    onError?: (error: unknown, key: string) => void;
+    now?: () => Date;
+}
+export interface SampleOptions {
+    user?: string | number;
+    dimensions?: Record<string, string>;
+}
+export interface CounterHandle {
+    bump(options?: SampleOptions & {
+        n?: number;
+    }): Promise<void>;
+}
+export interface TimingHandle {
+    record(value: number, options?: SampleOptions): Promise<void>;
+}
+export interface MetricsSchema {
+    metrics: Array<{
+        key: string;
+    } & MetricSpec>;
+    overlaps: Array<{
+        from: string;
+        to: string;
+    }>;
+}
+export type Metrics<Spec extends Record<string, MetricSpec>> = {
+    [K in keyof Spec]: Spec[K]["kind"] extends "counter" ? CounterHandle : TimingHandle;
+} & {
+    describe(): MetricsSchema;
+};
+export declare function defineMetrics<const Spec extends Record<string, MetricSpec>>(input: Spec, opts: MetricsOptions<Extract<keyof Spec, string>>): Metrics<Spec>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/metrics/index.ts"],"names":[],"mappings":"AAAA,qGAAqG;AACrG,MAAM,MAAM,UAAU,GAAG;IACxB,IAAI,EAAE,SAAS,GAAG,QAAQ,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;CAC/C,CAAC;AAEF,MAAM,WAAW,WAAW;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,IAAI,EAAE,UAAU,CAAC;CACjB;AAED,MAAM,WAAW,cAAc,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM;IAC3D,KAAK,EAAE,CAAC,WAAW,EAAE,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACtD,gEAAgE;IAChE,QAAQ,CAAC,EAAE,aAAa,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;IAChD,4EAA4E;IAC5E,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAChD,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC7B,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC;AACD,MAAM,WAAW,aAAa;IAC7B,IAAI,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG;QAAE,CAAC,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9D;AACD,MAAM,WAAW,YAAY;IAC5B,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9D;AACD,MAAM,WAAW,aAAa;IAC7B,OAAO,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,UAAU,CAAC,CAAC;IAC7C,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC9C;AACD,MAAM,MAAM,OAAO,CAAC,IAAI,SAAS,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,IAAI;KAC7D,CAAC,IAAI,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,SAAS,GACjD,aAAa,GACb,YAAY;CACf,GAAG;IAAE,QAAQ,IAAI,aAAa,CAAA;CAAE,CAAC;AAIlC,wBAAgB,aAAa,CAAC,KAAK,CAAC,IAAI,SAAS,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,EAC1E,KAAK,EAAE,IAAI,EACX,IAAI,EAAE,cAAc,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,MAAM,CAAC,CAAC,GAC/C,OAAO,CAAC,IAAI,CAAC,CAqGf"}

package/dist/metrics/index.js

@@ -0,0 +1,86 @@
+const identifier = /^[a-zA-Z][a-zA-Z0-9_]*$/;
+export function defineMetrics(input, opts) {
+    // Snapshot declarations: later caller mutations cannot change validation or labels.
+    const spec = structuredClone(input);
+    for (const [key, s] of Object.entries(spec)) {
+        if (!identifier.test(key) ||
+            key === "describe" ||
+            key === "constructor" ||
+            key === "prototype")
+            throw new Error(`metrics: invalid or reserved key "${key}"`);
+        if (!s.label.trim() || !["counter", "timing"].includes(s.kind))
+            throw new Error(`metrics: invalid declaration "${key}"`);
+        for (const [name, values] of Object.entries(s.dimensions ?? {})) {
+            if (!identifier.test(name) ||
+                !values.length ||
+                new Set(values).size !== values.length ||
+                values.some((v) => typeof v !== "string" || !v.length || v.length > 128))
+                throw new Error(`metrics: invalid dimension "${key}.${name}"`);
+        }
+    }
+    const overlaps = (opts.overlaps ?? []).map(([from, to]) => {
+        if (!spec[from]?.perUser || !spec[to]?.perUser)
+            throw new Error("metrics: overlap requires two declared perUser metrics");
+        return { from, to };
+    });
+    const report = opts.onError ??
+        ((_error, key) => console.warn(`metrics: measurement failed (${key})`));
+    async function write(key, count, sum, options) {
+        try {
+            if (!Number.isSafeInteger(count) ||
+                count <= 0 ||
+                !Number.isFinite(sum) ||
+                sum < 0)
+                throw new Error("metrics: samples must be finite and nonnegative; counts must be positive safe integers");
+            const s = spec[key];
+            const supplied = options?.dimensions ?? {};
+            const dimensions = {};
+            if (Object.keys(supplied).length !== Object.keys(s.dimensions ?? {}).length)
+                throw new Error("metrics: unexpected or missing dimensions");
+            for (const name of Object.keys(s.dimensions ?? {}).sort()) {
+                const value = supplied[name];
+                if (!s.dimensions?.[name].includes(value))
+                    throw new Error(`metrics: invalid dimension ${name}`);
+                dimensions[name] = value;
+            }
+            const user = s.perUser ? options?.user : undefined;
+            if (user !== undefined &&
+                (typeof user === "number"
+                    ? !Number.isSafeInteger(user)
+                    : typeof user !== "string" || !user.length || user.length > 128))
+                throw new Error("metrics: invalid user identifier");
+            await opts.write({
+                key,
+                day: (opts.now?.() ?? new Date()).toISOString().slice(0, 10),
+                count,
+                sum,
+                user,
+                dimensions,
+                spec: structuredClone(s),
+            });
+        }
+        catch (error) {
+            try {
+                report(error, key);
+            }
+            catch {
+                /* Instrumentation must not break its caller. */
+            }
+        }
+    }
+    const out = {};
+    for (const [key, s] of Object.entries(spec)) {
+        out[key] =
+            s.kind === "counter"
+                ? { bump: (o) => write(key, o?.n ?? 1, 0, o) }
+                : { record: (value, o) => write(key, 1, value, o) };
+    }
+    return {
+        ...out,
+        describe: () => structuredClone({
+            metrics: Object.entries(spec).map(([key, s]) => ({ key, ...s })),
+            overlaps,
+        }),
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/metrics/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/metrics/index.ts"],"names":[],"mappings":"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"}

package/dist/metrics/report.d.ts

@@ -0,0 +1,27 @@
+/** Store-independent daily observations, shared by adapters and renderers. */
+export interface DailyMetric {
+    project: string;
+    key: string;
+    label: string;
+    kind: string;
+    help: string;
+    unit: string;
+    dimensions: Record<string, string>;
+    day: string;
+    count: number;
+    sum: number;
+}
+export interface MetricTotal {
+    project: string;
+    key: string;
+    label: string;
+    kind: string;
+    unit: string;
+    dimensions: Record<string, string>;
+    count: number;
+    sum: number;
+    average: number | null;
+}
+/** One report shape for terminal and web. No product names or metric lists. */
+export declare function summarizeMetrics(rows: readonly DailyMetric[]): MetricTotal[];
+//# sourceMappingURL=report.d.ts.map

package/dist/metrics/report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../src/metrics/report.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,MAAM,WAAW,WAAW;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,WAAW;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,GAAG,WAAW,EAAE,CAiC5E"}

package/dist/metrics/report.js

@@ -0,0 +1,31 @@
+/** One report shape for terminal and web. No product names or metric lists. */
+export function summarizeMetrics(rows) {
+    const totals = new Map();
+    for (const row of rows) {
+        const dimensions = Object.fromEntries(Object.entries(row.dimensions).sort(([a], [b]) => a.localeCompare(b)));
+        const key = JSON.stringify([row.project, row.key, dimensions]);
+        const total = totals.get(key) ?? {
+            project: row.project,
+            key: row.key,
+            label: row.label,
+            kind: row.kind,
+            unit: row.unit,
+            dimensions,
+            count: 0,
+            sum: 0,
+            average: null,
+        };
+        total.count += row.count;
+        total.sum += row.sum;
+        total.average =
+            total.kind === "timing" && total.count > 0
+                ? total.sum / total.count
+                : null;
+        totals.set(key, total);
+    }
+    return [...totals.values()].sort((a, b) => a.project.localeCompare(b.project) ||
+        a.key.localeCompare(b.key) ||
+        b.count - a.count ||
+        JSON.stringify(a.dimensions).localeCompare(JSON.stringify(b.dimensions)));
+}
+//# sourceMappingURL=report.js.map

package/dist/metrics/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../src/metrics/report.ts"],"names":[],"mappings":"AA0BA,+EAA+E;AAC/E,MAAM,UAAU,gBAAgB,CAAC,IAA4B;IAC5D,MAAM,MAAM,GAAG,IAAI,GAAG,EAAuB,CAAC;IAC9C,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACxB,MAAM,UAAU,GAAG,MAAM,CAAC,WAAW,CACpC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CACrE,CAAC;QACF,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC;QAC/D,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI;YAChC,OAAO,EAAE,GAAG,CAAC,OAAO;YACpB,GAAG,EAAE,GAAG,CAAC,GAAG;YACZ,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,UAAU;YACV,KAAK,EAAE,CAAC;YACR,GAAG,EAAE,CAAC;YACN,OAAO,EAAE,IAAI;SACb,CAAC;QACF,KAAK,CAAC,KAAK,IAAI,GAAG,CAAC,KAAK,CAAC;QACzB,KAAK,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC;QACrB,KAAK,CAAC,OAAO;YACZ,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,KAAK,GAAG,CAAC;gBACzC,CAAC,CAAC,KAAK,CAAC,GAAG,GAAG,KAAK,CAAC,KAAK;gBACzB,CAAC,CAAC,IAAI,CAAC;QACT,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACxB,CAAC;IACD,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAC/B,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACR,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC;QAClC,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC;QAC1B,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK;QACjB,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CACzE,CAAC;AACH,CAAC"}

package/dist/metrics/sqlite.d.ts

@@ -0,0 +1,25 @@
+import type { Measurement } from "./index.js";
+import type { DailyMetric } from "./report.js";
+/** Structural libSQL interface; callers own connections and credentials. */
+export interface MetricsDatabase {
+    execute(statement: {
+        sql: string;
+        args: Array<string | number>;
+    }): Promise<{
+        rows: Iterable<Record<string, unknown>>;
+    }>;
+    batch(statements: Array<{
+        sql: string;
+        args: Array<string | number>;
+    }>, mode: "write"): Promise<unknown>;
+}
+/** Run explicitly during provisioning, never on a user's request. */
+export declare const METRICS_SCHEMA: readonly ["CREATE TABLE IF NOT EXISTS metric_definition (project TEXT NOT NULL, key TEXT NOT NULL, kind TEXT NOT NULL, label TEXT NOT NULL, help TEXT NOT NULL, unit TEXT NOT NULL, PRIMARY KEY(project, key))", "CREATE TABLE IF NOT EXISTS metric_daily (project TEXT NOT NULL, key TEXT NOT NULL, dimensions TEXT NOT NULL, day TEXT NOT NULL, count INTEGER NOT NULL CHECK(count >= 0), sum REAL NOT NULL CHECK(sum >= 0), PRIMARY KEY(project, key, dimensions, day))", "CREATE TABLE IF NOT EXISTS metric_user_daily (project TEXT NOT NULL, key TEXT NOT NULL, dimensions TEXT NOT NULL, day TEXT NOT NULL, user TEXT NOT NULL, count INTEGER NOT NULL CHECK(count >= 0), sum REAL NOT NULL CHECK(sum >= 0), PRIMARY KEY(project, key, dimensions, day, user))", "CREATE INDEX IF NOT EXISTS metric_user_identity ON metric_user_daily(project, user)"];
+export declare function sqliteMetricsWriter(db: MetricsDatabase, project: string): (m: Measurement) => Promise<void>;
+/** Inclusive UTC dates. Errors propagate: unavailable data must never read as zero. */
+export declare function readMetrics(db: MetricsDatabase, range: {
+    from: string;
+    to: string;
+    project?: string;
+}): Promise<DailyMetric[]>;
+//# sourceMappingURL=sqlite.d.ts.map

package/dist/metrics/sqlite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite.d.ts","sourceRoot":"","sources":["../../src/metrics/sqlite.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,4EAA4E;AAC5E,MAAM,WAAW,eAAe;IAC/B,OAAO,CAAC,SAAS,EAAE;QAClB,GAAG,EAAE,MAAM,CAAC;QACZ,IAAI,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;KAC7B,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;KAAE,CAAC,CAAC;IACzD,KAAK,CACJ,UAAU,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAA;KAAE,CAAC,EAChE,IAAI,EAAE,OAAO,GACX,OAAO,CAAC,OAAO,CAAC,CAAC;CACpB;AAED,qEAAqE;AACrE,eAAO,MAAM,cAAc,g0BAKjB,CAAC;AAEX,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,IAGzD,GAAG,WAAW,mBAkC5B;AAED,uFAAuF;AACvF,wBAAsB,WAAW,CAChC,EAAE,EAAE,eAAe,EACnB,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACnD,OAAO,CAAC,WAAW,EAAE,CAAC,CAyBxB"}

package/dist/metrics/sqlite.js

@@ -0,0 +1,72 @@
+/** Run explicitly during provisioning, never on a user's request. */
+export const METRICS_SCHEMA = [
+    `CREATE TABLE IF NOT EXISTS metric_definition (project TEXT NOT NULL, key TEXT NOT NULL, kind TEXT NOT NULL, label TEXT NOT NULL, help TEXT NOT NULL, unit TEXT NOT NULL, PRIMARY KEY(project, key))`,
+    `CREATE TABLE IF NOT EXISTS metric_daily (project TEXT NOT NULL, key TEXT NOT NULL, dimensions TEXT NOT NULL, day TEXT NOT NULL, count INTEGER NOT NULL CHECK(count >= 0), sum REAL NOT NULL CHECK(sum >= 0), PRIMARY KEY(project, key, dimensions, day))`,
+    `CREATE TABLE IF NOT EXISTS metric_user_daily (project TEXT NOT NULL, key TEXT NOT NULL, dimensions TEXT NOT NULL, day TEXT NOT NULL, user TEXT NOT NULL, count INTEGER NOT NULL CHECK(count >= 0), sum REAL NOT NULL CHECK(sum >= 0), PRIMARY KEY(project, key, dimensions, day, user))`,
+    `CREATE INDEX IF NOT EXISTS metric_user_identity ON metric_user_daily(project, user)`,
+];
+export function sqliteMetricsWriter(db, project) {
+    if (!/^[a-z][a-z0-9-]*$/.test(project))
+        throw new Error("metrics: invalid project");
+    return async (m) => {
+        const dimensions = JSON.stringify(m.dimensions);
+        const statements = [
+            {
+                sql: `INSERT INTO metric_definition VALUES (?, ?, ?, ?, ?, ?) ON CONFLICT(project, key) DO UPDATE SET kind=excluded.kind, label=excluded.label, help=excluded.help, unit=excluded.unit`,
+                args: [
+                    project,
+                    m.key,
+                    m.spec.kind,
+                    m.spec.label,
+                    m.spec.help ?? "",
+                    m.spec.unit ?? "",
+                ],
+            },
+            {
+                sql: `INSERT INTO metric_daily VALUES (?, ?, ?, ?, ?, ?) ON CONFLICT(project, key, dimensions, day) DO UPDATE SET count=count+excluded.count, sum=sum+excluded.sum`,
+                args: [project, m.key, dimensions, m.day, m.count, m.sum],
+            },
+        ];
+        if (m.user !== undefined)
+            statements.push({
+                sql: `INSERT INTO metric_user_daily VALUES (?, ?, ?, ?, ?, ?, ?) ON CONFLICT(project, key, dimensions, day, user) DO UPDATE SET count=count+excluded.count, sum=sum+excluded.sum`,
+                args: [
+                    project,
+                    m.key,
+                    dimensions,
+                    m.day,
+                    String(m.user),
+                    m.count,
+                    m.sum,
+                ],
+            });
+        await db.batch(statements, "write");
+    };
+}
+/** Inclusive UTC dates. Errors propagate: unavailable data must never read as zero. */
+export async function readMetrics(db, range) {
+    for (const day of [range.from, range.to]) {
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(day) ||
+            new Date(day).toISOString().slice(0, 10) !== day)
+            throw new Error("metrics: invalid UTC date");
+    }
+    if (range.from > range.to)
+        throw new Error("metrics: reversed date range");
+    const result = await db.execute({
+        sql: `SELECT d.*, s.label, s.kind, s.help, s.unit FROM metric_daily d JOIN metric_definition s USING(project, key) WHERE day >= ? AND day <= ? ${range.project ? "AND project = ?" : ""} ORDER BY project, key, dimensions, day`,
+        args: [range.from, range.to, ...(range.project ? [range.project] : [])],
+    });
+    return Array.from(result.rows, (r) => ({
+        project: String(r.project),
+        key: String(r.key),
+        label: String(r.label),
+        kind: String(r.kind),
+        help: String(r.help),
+        unit: String(r.unit),
+        dimensions: JSON.parse(String(r.dimensions)),
+        day: String(r.day),
+        count: Number(r.count),
+        sum: Number(r.sum),
+    }));
+}
+//# sourceMappingURL=sqlite.js.map

package/dist/metrics/sqlite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite.js","sourceRoot":"","sources":["../../src/metrics/sqlite.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@adriangalilea/utils",
-	"version": "2.38.1",
+	"version": "4.0.0",
 	"description": "TypeScript utilities - logger, currency, formatter, GramIO bot plugins, and more",
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",
@@ -184,9 +184,21 @@
 			"types": "./dist/bot/inline-feedback.d.ts",
 			"default": "./dist/bot/inline-feedback.js"
 		},
-		"./bot/metrics": {
-			"types": "./dist/bot/metrics.d.ts",
-			"default": "./dist/bot/metrics.js"
+		"./metrics": {
+			"types": "./dist/metrics/index.d.ts",
+			"default": "./dist/metrics/index.js"
+		},
+		"./metrics/sqlite": {
+			"types": "./dist/metrics/sqlite.d.ts",
+			"default": "./dist/metrics/sqlite.js"
+		},
+		"./metrics/report": {
+			"types": "./dist/metrics/report.d.ts",
+			"default": "./dist/metrics/report.js"
+		},
+		"./metrics/cli": {
+			"types": "./dist/metrics/cli.d.ts",
+			"default": "./dist/metrics/cli.js"
 		},
 		"./bot/text": {
 			"types": "./dist/bot/text.d.ts",
@@ -203,7 +215,7 @@
 	"scripts": {
 		"build": "tsc",
 		"dev": "tsx src/index.ts",
-		"test": "echo 'Tests not configured yet'",
+		"test": "tsx tests/metrics-test.ts",
 		"test:log": "tsx tests/log-test.ts",
 		"test:runtime": "tsx tests/runtime-test.ts",
 		"test:text": "tsx tests/text-test.ts",

package/dist/bot/metrics.d.ts

@@ -1,106 +0,0 @@
-/**
- * Metric registry — self-serve product measurement, the `bot/flags` pattern
- * applied to counting. Declare a metric ONCE in code and it exists
- * everywhere: `metrics.<key>.bump()` / `.record(value)` at the call site,
- * generic day-bucketed storage underneath (no migration per metric), and
- * `metrics.describe()` as the schema admin panels render generically — a new
- * metric reaches every panel with zero panel edits.
- *
- * Built to answer PRODUCT questions, not just count:
- *   volume     how many times           → counter
- *   averages   how long / how big       → timing (count + sum → avg)
- *   uniques    how many distinct users  → perUser: true
- *   repeat     used it again same day?  → per-user day rows with count > 1
- *   retention  came back another day?   → same user on ≥ 2 distinct days
- *   funnels    of those who did A, who did B → declared pairs over the
- *              shared user space; panels render conversion % generically
- *   depth      how far do they go       → per-user daily counts distribute
- *
- * Storage is ONE injected write op; the atomic upserts live with the
- * consumer's database. Contract: always add (count, sum) to the day bucket
- * for `key`; when `user` is present, ALSO to the per-user day bucket, e.g.:
- *
- *   INSERT INTO metric (key, day, count, sum) VALUES (?1, date('now'), ?2, ?3)
- *     ON CONFLICT (key, day) DO UPDATE SET count = count + ?2, sum = sum + ?3;
- *   -- and when user is present:
- *   INSERT INTO metric_user (key, user, day, count, sum) VALUES (?1, ?4, date('now'), ?2, ?3)
- *     ON CONFLICT (key, user, day) DO UPDATE SET count = count + ?2, sum = sum + ?3;
- *
- * Per-user rows are personal data: wipe them in your forget-user path, and
- * prune by age (growth is users × metrics × days). Writes are FIRE-AND-FORGET
- * and never throw — measurement must never break the product. The registry
- * IS the cardinality cap: keys are declared identifiers, never free-form
- * strings. Money stays in ledgers; this is operational/product counting.
- *
- * @example
- * const metrics = defineMetrics({
- *   chapterOpens: { kind: "counter", label: "chapter opens", perUser: true },
- *   chapterPages: { kind: "counter", label: "chapter pages", perUser: true, help: "Back/Next taps" },
- *   chapterLatency: { kind: "timing", label: "chapter latency", unit: "ms" },
- * }, {
- *   write: (key, addCount, addSum, user) => store.metricBump(key, addCount, addSum, user),
- *   funnels: [["chapterOpens", "chapterPages"]],
- * })
- *
- * void metrics.chapterOpens.bump({ user: ctx.from.id })
- * void metrics.chapterLatency.record(Date.now() - startedAt)
- * metrics.describe() // → { metrics: [...], funnels: [...] } — panels iterate this
- */
-/** One metric declaration. `perUser: true` unlocks uniques/repeat/retention/funnels for it. */
-export type MetricSpec = {
-    kind: "counter";
-    label: string;
-    help?: string;
-    perUser?: boolean;
-} | {
-    kind: "timing";
-    label: string;
-    help?: string;
-    unit?: string;
-    perUser?: boolean;
-};
-export interface MetricsOptions<Keys extends string = string> {
-    /**
-     * The atomic day-bucket upsert(s): add `addCount`/`addSum` to today's row
-     * for `key`, and — when `user` is present — to the per-user day row too
-     * (one batch). Failures are swallowed by the registry; make the op itself
-     * atomic.
-     */
-    write: (key: string, addCount: number, addSum: number, user?: number) => Promise<unknown>;
-    /**
-     * Declared conversion pairs over perUser metrics ("of users who did FROM,
-     * how many did TO"). Panels render these generically; they are queries
-     * over the shared user space, not extra storage.
-     */
-    funnels?: ReadonlyArray<readonly [Keys, Keys]>;
-}
-export interface CounterHandle {
-    /** Count `n` events (default 1); pass `user` on perUser metrics. Fire-and-forget, never throws. */
-    bump(opts?: {
-        user?: number;
-        n?: number;
-    }): Promise<void>;
-}
-export interface TimingHandle {
-    /** Record one sample; pass `user` on perUser metrics. Fire-and-forget, never throws. */
-    record(value: number, opts?: {
-        user?: number;
-    }): Promise<void>;
-}
-export interface MetricsSchema {
-    metrics: Array<{
-        key: string;
-    } & MetricSpec>;
-    funnels: Array<{
-        from: string;
-        to: string;
-    }>;
-}
-export type Metrics<Spec extends Record<string, MetricSpec>> = {
-    [K in keyof Spec]: Spec[K]["kind"] extends "counter" ? CounterHandle : TimingHandle;
-} & {
-    /** The registry schema, for panels to render generically. */
-    describe(): MetricsSchema;
-};
-export declare function defineMetrics<const Spec extends Record<string, MetricSpec>>(spec: Spec, opts: MetricsOptions<Extract<keyof Spec, string>>): Metrics<Spec>;
-//# sourceMappingURL=metrics.d.ts.map

package/dist/bot/metrics.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/bot/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,+FAA+F;AAC/F,MAAM,MAAM,UAAU,GACnB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GACpE;IACA,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEL,MAAM,WAAW,cAAc,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM;IAC3D;;;;;OAKG;IACH,KAAK,EAAE,CACN,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,MAAM,KACT,OAAO,CAAC,OAAO,CAAC,CAAC;IACtB;;;;OAIG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;CAC/C;AAED,MAAM,WAAW,aAAa;IAC7B,mGAAmG;IACnG,IAAI,CAAC,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1D;AACD,MAAM,WAAW,YAAY;IAC5B,wFAAwF;IACxF,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/D;AAED,MAAM,WAAW,aAAa;IAC7B,OAAO,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,UAAU,CAAC,CAAC;IAC7C,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC7C;AAED,MAAM,MAAM,OAAO,CAAC,IAAI,SAAS,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,IAAI;KAC7D,CAAC,IAAI,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,SAAS,GACjD,aAAa,GACb,YAAY;CACf,GAAG;IACH,6DAA6D;IAC7D,QAAQ,IAAI,aAAa,CAAC;CAC1B,CAAC;AAEF,wBAAgB,aAAa,CAAC,KAAK,CAAC,IAAI,SAAS,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,EAC1E,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,cAAc,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,MAAM,CAAC,CAAC,GAC/C,OAAO,CAAC,IAAI,CAAC,CA2Cf"}

package/dist/bot/metrics.js

@@ -1,91 +0,0 @@
-/**
- * Metric registry — self-serve product measurement, the `bot/flags` pattern
- * applied to counting. Declare a metric ONCE in code and it exists
- * everywhere: `metrics.<key>.bump()` / `.record(value)` at the call site,
- * generic day-bucketed storage underneath (no migration per metric), and
- * `metrics.describe()` as the schema admin panels render generically — a new
- * metric reaches every panel with zero panel edits.
- *
- * Built to answer PRODUCT questions, not just count:
- *   volume     how many times           → counter
- *   averages   how long / how big       → timing (count + sum → avg)
- *   uniques    how many distinct users  → perUser: true
- *   repeat     used it again same day?  → per-user day rows with count > 1
- *   retention  came back another day?   → same user on ≥ 2 distinct days
- *   funnels    of those who did A, who did B → declared pairs over the
- *              shared user space; panels render conversion % generically
- *   depth      how far do they go       → per-user daily counts distribute
- *
- * Storage is ONE injected write op; the atomic upserts live with the
- * consumer's database. Contract: always add (count, sum) to the day bucket
- * for `key`; when `user` is present, ALSO to the per-user day bucket, e.g.:
- *
- *   INSERT INTO metric (key, day, count, sum) VALUES (?1, date('now'), ?2, ?3)
- *     ON CONFLICT (key, day) DO UPDATE SET count = count + ?2, sum = sum + ?3;
- *   -- and when user is present:
- *   INSERT INTO metric_user (key, user, day, count, sum) VALUES (?1, ?4, date('now'), ?2, ?3)
- *     ON CONFLICT (key, user, day) DO UPDATE SET count = count + ?2, sum = sum + ?3;
- *
- * Per-user rows are personal data: wipe them in your forget-user path, and
- * prune by age (growth is users × metrics × days). Writes are FIRE-AND-FORGET
- * and never throw — measurement must never break the product. The registry
- * IS the cardinality cap: keys are declared identifiers, never free-form
- * strings. Money stays in ledgers; this is operational/product counting.
- *
- * @example
- * const metrics = defineMetrics({
- *   chapterOpens: { kind: "counter", label: "chapter opens", perUser: true },
- *   chapterPages: { kind: "counter", label: "chapter pages", perUser: true, help: "Back/Next taps" },
- *   chapterLatency: { kind: "timing", label: "chapter latency", unit: "ms" },
- * }, {
- *   write: (key, addCount, addSum, user) => store.metricBump(key, addCount, addSum, user),
- *   funnels: [["chapterOpens", "chapterPages"]],
- * })
- *
- * void metrics.chapterOpens.bump({ user: ctx.from.id })
- * void metrics.chapterLatency.record(Date.now() - startedAt)
- * metrics.describe() // → { metrics: [...], funnels: [...] } — panels iterate this
- */
-export function defineMetrics(spec, opts) {
-    for (const [key, s] of Object.entries(spec)) {
-        if (!/^[a-zA-Z][a-zA-Z0-9_]*$/.test(key))
-            throw new Error(`metrics: invalid key "${key}"`);
-        if (!s.label)
-            throw new Error(`metrics: "${key}" needs a label`);
-    }
-    for (const [from, to] of opts.funnels ?? []) {
-        for (const k of [from, to]) {
-            if (!spec[k])
-                throw new Error(`metrics: funnel references unknown metric "${k}"`);
-            if (!spec[k].perUser)
-                throw new Error(`metrics: funnel metric "${k}" must be perUser (funnels join on user)`);
-        }
-    }
-    const out = {};
-    for (const [key, s] of Object.entries(spec)) {
-        out[key] =
-            s.kind === "counter"
-                ? {
-                    async bump(o) {
-                        await opts
-                            .write(key, o?.n ?? 1, 0, s.perUser ? o?.user : undefined)
-                            .catch(() => { });
-                    },
-                }
-                : {
-                    async record(value, o) {
-                        await opts
-                            .write(key, 1, value, s.perUser ? o?.user : undefined)
-                            .catch(() => { });
-                    },
-                };
-    }
-    return {
-        ...out,
-        describe: () => ({
-            metrics: Object.entries(spec).map(([key, s]) => ({ key, ...s })),
-            funnels: (opts.funnels ?? []).map(([from, to]) => ({ from, to })),
-        }),
-    };
-}
-//# sourceMappingURL=metrics.js.map

package/dist/bot/metrics.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../src/bot/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAyDH,MAAM,UAAU,aAAa,CAC5B,IAAU,EACV,IAAiD;IAEjD,KAAK,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7C,IAAI,CAAC,yBAAyB,CAAC,IAAI,CAAC,GAAG,CAAC;YACvC,MAAM,IAAI,KAAK,CAAC,yBAAyB,GAAG,GAAG,CAAC,CAAC;QAClD,IAAI,CAAC,CAAC,CAAC,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,aAAa,GAAG,iBAAiB,CAAC,CAAC;IAClE,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC;QAC7C,KAAK,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC;YAC5B,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;gBACX,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,GAAG,CAAC,CAAC;YACrE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO;gBACnB,MAAM,IAAI,KAAK,CACd,2BAA2B,CAAC,0CAA0C,CACtE,CAAC;QACJ,CAAC;IACF,CAAC;IAED,MAAM,GAAG,GAAiD,EAAE,CAAC;IAC7D,KAAK,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7C,GAAG,CAAC,GAAG,CAAC;YACP,CAAC,CAAC,IAAI,KAAK,SAAS;gBACnB,CAAC,CAAC;oBACA,KAAK,CAAC,IAAI,CAAC,CAAiC;wBAC3C,MAAM,IAAI;6BACR,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;6BACzD,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;oBACnB,CAAC;iBACD;gBACF,CAAC,CAAC;oBACA,KAAK,CAAC,MAAM,CAAC,KAAa,EAAE,CAAqB;wBAChD,MAAM,IAAI;6BACR,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;6BACrD,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;oBACnB,CAAC;iBACD,CAAC;IACN,CAAC;IACD,OAAO;QACN,GAAG,GAAG;QACN,QAAQ,EAAE,GAAkB,EAAE,CAAC,CAAC;YAC/B,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;YAChE,OAAO,EAAE,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;SACjE,CAAC;KACe,CAAC;AACpB,CAAC"}