@mongrov/analytics 0.1.0-alpha.7 → 0.1.0-alpha.9

package/dist/tools/rate-limit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.js","sourceRoot":"","sources":["../../src/tools/rate-limit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,kBAAkB,EAAwB,MAAM,SAAS,CAAA;AAmBlE,MAAM,aAAa,GAAG,KAAM,CAAA;AAC5B,MAAM,WAAW,GAAG,OAAS,CAAA;AAE7B,MAAM,UAAU,iBAAiB,CAC/B,MAA+B,EAAE;IAEjC,MAAM,EAAE,GAAoB,GAAG,CAAC,MAAM,IAAI,kBAAkB,CAAA;IAC5D,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG,CAAA;IAEnC,MAAM,aAAa,GAAG,IAAI,GAAG,EAAuB,CAAA;IACpD,MAAM,WAAW,GAAG,IAAI,GAAG,EAAuB,CAAA;IAClD,MAAM,aAAa,GAAG,IAAI,GAAG,EAAuB,CAAA;IAEpD,SAAS,WAAW,CAClB,GAA6B,EAC7B,GAAW,EACX,QAAgB,EAChB,QAAgB,EAChB,GAAW;QAEX,IAAI,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACpB,IAAI,CAAC,CAAC,EAAE,CAAC;YACP,CAAC,GAAG;gBACF,MAAM,EAAE,QAAQ;gBAChB,YAAY,EAAE,GAAG;gBACjB,QAAQ;gBACR,WAAW,EAAE,QAAQ,GAAG,QAAQ;aACjC,CAAA;YACD,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAA;QACjB,CAAC;QACD,OAAO,CAAC,CAAA;IACV,CAAC;IAED,SAAS,MAAM,CAAC,CAAc,EAAE,GAAW;QACzC,MAAM,OAAO,GAAG,GAAG,GAAG,CAAC,CAAC,YAAY,CAAA;QACpC,IAAI,OAAO,IAAI,CAAC;YAAE,OAAM;QACxB,CAAC,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,MAAM,GAAG,OAAO,GAAG,CAAC,CAAC,WAAW,CAAC,CAAA;QACnE,CAAC,CAAC,YAAY,GAAG,GAAG,CAAA;IACtB,CAAC;IAED,OAAO;QACL,KAAK,CAAC,QAAQ,EAAE,MAAM;YACpB,MAAM,GAAG,GAAG,KAAK,EAAE,CAAA;YACnB,MAAM,OAAO,GAAG,GAAG,QAAQ,IAAI,MAAM,EAAE,CAAA;YACvC,MAAM,OAAO,GAAG,MAAM,CAAA;YAEtB,MAAM,EAAE,GAAG,WAAW,CACpB,aAAa,EACb,OAAO,EACP,EAAE,CAAC,gBAAgB,EACnB,aAAa,EACb,GAAG,CACJ,CAAA;YACD,MAAM,EAAE,GAAG,WAAW,CACpB,WAAW,EACX,OAAO,EACP,EAAE,CAAC,cAAc,EACjB,WAAW,EACX,GAAG,CACJ,CAAA;YACD,MAAM,EAAE,GAAG,WAAW,CACpB,aAAa,EACb,OAAO,EACP,EAAE,CAAC,gBAAgB,EACnB,aAAa,EACb,GAAG,CACJ,CAAA;YAED,MAAM,CAAC,EAAE,EAAE,GAAG,CAAC,CAAA;YACf,MAAM,CAAC,EAAE,EAAE,GAAG,CAAC,CAAA;YACf,MAAM,CAAC,EAAE,EAAE,GAAG,CAAC,CAAA;YAEf,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACpD,OAAO,KAAK,CAAA;YACd,CAAC;YAED,EAAE,CAAC,MAAM,IAAI,CAAC,CAAA;YACd,EAAE,CAAC,MAAM,IAAI,CAAC,CAAA;YACd,EAAE,CAAC,MAAM,IAAI,CAAC,CAAA;YACd,OAAO,IAAI,CAAA;QACb,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/tools/types.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Public type surface for @mongrov/analytics/tools.
+ *
+ * Types shared across tool impls, rate limiter, authorize hooks,
+ * audit writer, wrapper, and the top-level factory.
+ */
+import type { AnalyticsEngine, FamilyMembersProvider } from '../core/types';
+/** Runtime context threaded through every tool impl and authorize hook. */
+export interface ToolContext {
+    readonly requesterUserId: string;
+    readonly brand: string;
+    readonly familyId: string;
+    readonly now?: () => Date;
+}
+/** Bounded text summary returned by every tool impl. */
+export interface ToolResult {
+    readonly text: string;
+    readonly rowCount: number;
+    readonly bytes: number;
+}
+/**
+ * Authorization hook — invoked before every tool execute. `false`
+ * rejects the call before SQL runs. Toolname passes through so hooks
+ * can gate by tool identity in addition to args + ctx.
+ */
+export type AuthorizeFn = (toolName: string, args: Record<string, unknown>, ctx: ToolContext) => Promise<boolean>;
+/**
+ * Token-bucket rate-limit ceilings. Defaults come from
+ * `analytics-ai-tools/spec.md` §Rate limiting.
+ */
+export interface RateLimitConfig {
+    perToolPerMinute: number;
+    perToolPerHour: number;
+    perUserPerMinute: number;
+}
+export declare const DEFAULT_RATE_LIMIT: RateLimitConfig;
+export interface ToolsLogger {
+    debug: (message: string, meta?: Record<string, unknown>) => void;
+    info: (message: string, meta?: Record<string, unknown>) => void;
+    warn: (message: string, meta?: Record<string, unknown>) => void;
+    error: (message: string, meta?: Record<string, unknown>) => void;
+}
+/**
+ * A tool impl. Takes a Zod-parsed input and the runtime context
+ * (augmented with the analytics engine), returns a bounded text
+ * result. `makeTool` (T-10) wraps this with rate → auth → execute →
+ * budget → audit chain to produce an AI SDK `tool()` handle.
+ */
+export type ToolImpl<Input> = (input: Input, ctx: ToolContext & {
+    analytics: AnalyticsEngine;
+}) => Promise<ToolResult>;
+/**
+ * Outcome recorded in `tool_call_audit.outcome`. Enum discipline —
+ * every wrapper code path resolves to exactly one of these.
+ */
+export type ToolOutcome = 'success' | 'rate_limited' | 'authorized_reject' | 'error';
+/**
+ * A single row destined for `tool_call_audit`. Column mapping (see
+ * `core/schemas.ts` line 189):
+ *   ts, brand, family_id, requester_user_id, tool_name, args,
+ *   result_bytes, result_row_count, latency_ms, outcome, error_message
+ */
+export interface AuditEntry {
+    readonly ts: Date;
+    readonly brand: string;
+    readonly familyId: string;
+    readonly requesterUserId: string;
+    readonly toolName: string;
+    readonly args: Record<string, unknown>;
+    readonly resultBytes: number | null;
+    readonly resultRowCount: number | null;
+    readonly latencyMs: number | null;
+    readonly outcome: ToolOutcome;
+    readonly errorMessage: string | null;
+}
+/**
+ * Batched writer for `tool_call_audit`. `record` is non-blocking —
+ * entries flush on batch-size or timer. `flush` and `close` are test
+ * hooks / graceful-shutdown hooks respectively.
+ */
+export interface AuditWriter {
+    record: (entry: AuditEntry) => void;
+    flush: () => Promise<void>;
+    close: () => Promise<void>;
+}
+/**
+ * Per-tool output ceiling enforced by `applyOutputBudget`. Text
+ * exceeding `maxBytes` is UTF-8-safely truncated with a
+ * `\n[truncated]` suffix. `maxRows` is informational — impls limit
+ * row count via SQL.
+ */
+export interface OutputBudget {
+    maxBytes: number;
+    maxRows: number;
+}
+export declare const DEFAULT_OUTPUT_BUDGET: OutputBudget;
+/**
+ * Config for `createAnalyticsTools` factory. All fields except
+ * `analytics` are optional with sane defaults from `spec.md`.
+ *
+ * - `rateLimit: false` disables the limiter entirely (tests only).
+ * - `authorize: undefined` defaults to `familyScopeAuthorize` wired
+ *   with `familyMembersProvider` if supplied.
+ * - `audit.enabled: false` makes `record` a no-op.
+ */
+export interface AnalyticsToolsConfig {
+    analytics: AnalyticsEngine;
+    authorize?: AuthorizeFn;
+    rateLimit?: RateLimitConfig | false;
+    audit?: {
+        enabled?: boolean;
+        batchSize?: number;
+        flushIntervalMs?: number;
+        retentionDays?: number;
+    };
+    outputBudget?: Partial<OutputBudget>;
+    logger?: ToolsLogger;
+    familyMembersProvider?: FamilyMembersProvider;
+    clock?: () => number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/tools/types.d.ts.map

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

package/dist/tools/types.js

@@ -0,0 +1,16 @@
+/**
+ * Public type surface for @mongrov/analytics/tools.
+ *
+ * Types shared across tool impls, rate limiter, authorize hooks,
+ * audit writer, wrapper, and the top-level factory.
+ */
+export const DEFAULT_RATE_LIMIT = {
+    perToolPerMinute: 20,
+    perToolPerHour: 200,
+    perUserPerMinute: 60,
+};
+export const DEFAULT_OUTPUT_BUDGET = {
+    maxBytes: 4096,
+    maxRows: 100,
+};
+//# sourceMappingURL=types.js.map

package/dist/tools/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAwCH,MAAM,CAAC,MAAM,kBAAkB,GAAoB;IACjD,gBAAgB,EAAE,EAAE;IACpB,cAAc,EAAE,GAAG;IACnB,gBAAgB,EAAE,EAAE;CACrB,CAAA;AAwED,MAAM,CAAC,MAAM,qBAAqB,GAAiB;IACjD,QAAQ,EAAE,IAAI;IACd,OAAO,EAAE,GAAG;CACb,CAAA"}

package/dist/tools/wrap.d.ts

@@ -0,0 +1,53 @@
+/**
+ * `makeTool` — compose an AI SDK `tool()` from a raw impl plus the
+ * rate → auth → execute → budget → audit chain.
+ *
+ * The chain order is load-bearing:
+ *   1. Rate limit  → cheap, no I/O; short-circuits abusive callers.
+ *   2. Authorize   → may hit SQL/provider; runs after rate cap.
+ *   3. Execute     → real tool work.
+ *   4. Budget      → truncate oversized text before returning.
+ *   5. Audit       → record every terminal state (success / reject
+ *                    / rate-limited / error).
+ *
+ * Every branch records exactly one audit entry. The wrapper never
+ * throws — errors resolve to a short LLM-friendly string. Because
+ * the AI SDK `execute(input)` signature has no per-call context arg,
+ * the caller supplies a `ctxProvider()` closure that returns the
+ * current `ToolContext` at invocation time (the factory backs this
+ * with a mutable container updated per request).
+ */
+import type { ZodTypeAny } from 'zod';
+import type { AnalyticsEngine } from '../core/types';
+import type { RateLimiter } from './rate-limit';
+import type { AuditWriter, AuthorizeFn, OutputBudget, ToolContext, ToolImpl, ToolsLogger } from './types';
+export interface MakeToolConfig<Input> {
+    name: string;
+    description: string;
+    /**
+     * Accepts any Zod schema whose parsed output is assignable to
+     * `Input`. Widened to `ZodTypeAny` so schemas with `.default()` /
+     * `.optional()` fields (whose input types include `undefined`)
+     * still fit — the AI SDK's own `tool()` uses the same shape.
+     */
+    inputSchema: ZodTypeAny;
+    impl: ToolImpl<Input>;
+    analytics: AnalyticsEngine;
+    authorize?: AuthorizeFn;
+    rateLimiter?: RateLimiter | null;
+    audit: AuditWriter;
+    budget: OutputBudget;
+    logger?: ToolsLogger;
+    /**
+     * Returns the current `ToolContext` at execute-time. The factory
+     * backs this with a mutable container so a single tool handle
+     * threads per-request scope. Returning `null` triggers a clean
+     * error branch (no ctx → audit `error` outcome).
+     */
+    ctxProvider: () => ToolContext | null;
+    clock?: () => number;
+}
+export declare function makeTool<Input>(cfg: MakeToolConfig<Input>): import("ai").Tool<ZodTypeAny, string> & {
+    execute: (args: any, options: import("ai").ToolExecutionOptions) => PromiseLike<string>;
+};
+//# sourceMappingURL=wrap.d.ts.map

package/dist/tools/wrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrap.d.ts","sourceRoot":"","sources":["../../src/tools/wrap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,KAAK,CAAA;AACrC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAEpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC/C,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EACX,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,WAAW,EACZ,MAAM,SAAS,CAAA;AAOhB,MAAM,WAAW,cAAc,CAAC,KAAK;IACnC,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB;;;;;OAKG;IACH,WAAW,EAAE,UAAU,CAAA;IACvB,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAA;IACrB,SAAS,EAAE,eAAe,CAAA;IAC1B,SAAS,CAAC,EAAE,WAAW,CAAA;IACvB,WAAW,CAAC,EAAE,WAAW,GAAG,IAAI,CAAA;IAChC,KAAK,EAAE,WAAW,CAAA;IAClB,MAAM,EAAE,YAAY,CAAA;IACpB,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB;;;;;OAKG;IACH,WAAW,EAAE,MAAM,WAAW,GAAG,IAAI,CAAA;IACrC,KAAK,CAAC,EAAE,MAAM,MAAM,CAAA;CACrB;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,GAAG,EAAE,cAAc,CAAC,KAAK,CAAC;;EAqHzD"}

package/dist/tools/wrap.js

@@ -0,0 +1,135 @@
+/**
+ * `makeTool` — compose an AI SDK `tool()` from a raw impl plus the
+ * rate → auth → execute → budget → audit chain.
+ *
+ * The chain order is load-bearing:
+ *   1. Rate limit  → cheap, no I/O; short-circuits abusive callers.
+ *   2. Authorize   → may hit SQL/provider; runs after rate cap.
+ *   3. Execute     → real tool work.
+ *   4. Budget      → truncate oversized text before returning.
+ *   5. Audit       → record every terminal state (success / reject
+ *                    / rate-limited / error).
+ *
+ * Every branch records exactly one audit entry. The wrapper never
+ * throws — errors resolve to a short LLM-friendly string. Because
+ * the AI SDK `execute(input)` signature has no per-call context arg,
+ * the caller supplies a `ctxProvider()` closure that returns the
+ * current `ToolContext` at invocation time (the factory backs this
+ * with a mutable container updated per request).
+ */
+import { tool } from 'ai';
+import { applyOutputBudget } from './budget';
+const RATE_LIMIT_MESSAGE = 'Rate limit exceeded. Try again shortly.';
+const AUTHZ_MESSAGE = 'Not authorized to access that user\'s data.';
+const ERROR_MESSAGE = 'Tool call failed.';
+const NO_CONTEXT_MESSAGE = 'Tool call failed: request context not set.';
+export function makeTool(cfg) {
+    const clock = cfg.clock ?? Date.now;
+    return tool({
+        description: cfg.description,
+        parameters: cfg.inputSchema,
+        execute: async (input) => {
+            const startMs = clock();
+            const ctx = cfg.ctxProvider();
+            // 0. Ctx guard — audit as error, no rate/auth/execute performed.
+            if (!ctx) {
+                cfg.audit.record({
+                    ts: new Date(clock()),
+                    brand: '',
+                    familyId: '',
+                    requesterUserId: '',
+                    toolName: cfg.name,
+                    args: input,
+                    resultBytes: null,
+                    resultRowCount: null,
+                    latencyMs: clock() - startMs,
+                    outcome: 'error',
+                    errorMessage: 'context not set',
+                });
+                cfg.logger?.warn('tool invoked without context', { toolName: cfg.name });
+                return NO_CONTEXT_MESSAGE;
+            }
+            // 1. Rate limit.
+            if (cfg.rateLimiter && !cfg.rateLimiter.check(cfg.name, ctx.requesterUserId)) {
+                cfg.audit.record({
+                    ts: new Date(clock()),
+                    brand: ctx.brand,
+                    familyId: ctx.familyId,
+                    requesterUserId: ctx.requesterUserId,
+                    toolName: cfg.name,
+                    args: input,
+                    resultBytes: null,
+                    resultRowCount: null,
+                    latencyMs: clock() - startMs,
+                    outcome: 'rate_limited',
+                    errorMessage: null,
+                });
+                return RATE_LIMIT_MESSAGE;
+            }
+            // 2. Authorize.
+            if (cfg.authorize) {
+                const ok = await cfg.authorize(cfg.name, input, ctx);
+                if (!ok) {
+                    cfg.audit.record({
+                        ts: new Date(clock()),
+                        brand: ctx.brand,
+                        familyId: ctx.familyId,
+                        requesterUserId: ctx.requesterUserId,
+                        toolName: cfg.name,
+                        args: input,
+                        resultBytes: null,
+                        resultRowCount: null,
+                        latencyMs: clock() - startMs,
+                        outcome: 'authorized_reject',
+                        errorMessage: null,
+                    });
+                    return AUTHZ_MESSAGE;
+                }
+            }
+            // 3. Execute + 4. Budget + 5. Audit success/error.
+            try {
+                const raw = await cfg.impl(input, {
+                    ...ctx,
+                    analytics: cfg.analytics,
+                });
+                const capped = applyOutputBudget(raw, cfg.budget);
+                cfg.audit.record({
+                    ts: new Date(clock()),
+                    brand: ctx.brand,
+                    familyId: ctx.familyId,
+                    requesterUserId: ctx.requesterUserId,
+                    toolName: cfg.name,
+                    args: input,
+                    resultBytes: capped.bytes,
+                    resultRowCount: capped.rowCount,
+                    latencyMs: clock() - startMs,
+                    outcome: 'success',
+                    errorMessage: null,
+                });
+                return capped.text;
+            }
+            catch (err) {
+                const errorMessage = err instanceof Error ? err.message : String(err);
+                cfg.audit.record({
+                    ts: new Date(clock()),
+                    brand: ctx.brand,
+                    familyId: ctx.familyId,
+                    requesterUserId: ctx.requesterUserId,
+                    toolName: cfg.name,
+                    args: input,
+                    resultBytes: null,
+                    resultRowCount: null,
+                    latencyMs: clock() - startMs,
+                    outcome: 'error',
+                    errorMessage,
+                });
+                cfg.logger?.warn('tool execution failed', {
+                    toolName: cfg.name,
+                    err: errorMessage,
+                });
+                return ERROR_MESSAGE;
+            }
+        },
+    });
+}
+//# sourceMappingURL=wrap.js.map

package/dist/tools/wrap.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mongrov/analytics",
-  "version": "0.1.0-alpha.7",
+  "version": "0.1.0-alpha.9",
   "description": "DuckDB + R2 Iceberg local analytics for @mongrov apps",
   "license": "MIT",
   "repository": {
@@ -64,6 +64,7 @@
   "peerDependencies": {
     "@mongrov/db": "workspace:*",
     "@mongrov/types": "^0.4.0",
+    "ai": ">=4",
     "react": ">=19",
     "react-native": ">=0.81",
     "react-native-duckdb": ">=1.0.0"
@@ -80,6 +81,7 @@
     }
   },
   "dependencies": {
+    "@iarna/toml": "^2.2.5",
     "date-fns-tz": "^3.2.0",
     "p-queue": "^8.0.1",
     "xstate": "^5.30.0"
@@ -90,6 +92,8 @@
     "@testing-library/react": "^14.3.1",
     "@types/react": "^18.3.12",
     "@types/react-dom": "^18.3.1",
+    "ai": "^4.3.0",
+    "fast-check": "^4.9.0",
     "jsdom": "^25.0.1",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",