@x402sentinel/x402 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Valeo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,388 @@
+# Valeo Sentinel
+
+**Enterprise audit & compliance for x402 payments. One line to add. Zero config to start.**
+
+---
+
+## The Problem
+
+AI agents are spending real money autonomously. The [x402 protocol](https://github.com/coinbase/x402) enables internet-native payments, but provides no built-in audit trail, budget controls, or compliance tooling.
+
+- 75% of enterprise leaders say compliance is a blocker for autonomous agent payments (KPMG 2025)
+- 61% report fragmented payment logs across agent fleets
+- Zero visibility into *which agent* spent *how much* on *what endpoint* and *who approved it*
+
+Sentinel fixes this with a single line of code.
+
+---
+
+## Quick Start
+
+### Before (plain x402)
+
+```ts
+import { x402Client, wrapFetchWithPayment } from "@x402/fetch";
+import { registerExactEvmScheme } from "@x402/evm/exact/client";
+
+const client = new x402Client();
+registerExactEvmScheme(client, { signer });
+const fetchWithPayment = wrapFetchWithPayment(fetch, client);
+
+const response = await fetchWithPayment("https://api.example.com/paid");
+```
+
+### After (with Sentinel)
+
+```ts
+import { x402Client, wrapFetchWithPayment } from "@x402/fetch";
+import { registerExactEvmScheme } from "@x402/evm/exact/client";
+import { wrapWithSentinel, standardPolicy } from "@x402sentinel/x402"; // <-- add
+
+const client = new x402Client();
+registerExactEvmScheme(client, { signer });
+const fetchWithPayment = wrapFetchWithPayment(fetch, client);
+
+const secureFetch = wrapWithSentinel(fetchWithPayment, {   // <-- wrap
+  agentId: "agent-weather-001",
+  budget: standardPolicy(),
+});
+
+const response = await secureFetch("https://api.example.com/paid"); // same API
+```
+
+That's it. Same `fetch` interface. Budget enforcement + audit trail included.
+
+### Install
+
+```bash
+npm install @x402sentinel/x402
+# or
+pnpm add @x402sentinel/x402
+```
+
+---
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| **Budget Enforcement** | Per-call, hourly, daily, and lifetime spend limits. Blocks before payment. |
+| **Spike Detection** | Flags payments that exceed N× the rolling average |
+| **Audit Trails** | Every payment logged with agent ID, team, endpoint, tx hash, timing |
+| **Endpoint Filtering** | Allowlist/blocklist URL patterns |
+| **Approval Workflows** | Require human approval above a threshold |
+| **Storage Backends** | In-memory (default), JSONL file, or remote API |
+| **Dashboard Queries** | Query spend by agent, team, endpoint, time range |
+| **CSV/JSON Export** | Export audit data for compliance reviews |
+| **Zero Dependencies** | No runtime deps beyond x402 peer deps |
+| **Drop-in Wrapper** | One line change. Remove Sentinel, code works identically. |
+
+---
+
+## Configuration
+
+```ts
+const secureFetch = wrapWithSentinel(fetchWithPayment, {
+  // Required
+  agentId: "agent-weather-001",
+
+  // Optional identity
+  team: "data-ops",
+  humanSponsor: "alice@company.com",
+
+  // Budget policy
+  budget: {
+    maxPerCall: "1.00",      // max USDC per single payment
+    maxPerHour: "25.00",     // hourly rolling cap
+    maxPerDay: "200.00",     // daily rolling cap
+    maxTotal: "10000.00",    // lifetime cap
+    spikeThreshold: 3.0,     // flag if > 3× rolling average
+    allowedEndpoints: ["https://api.trusted.com/*"],
+    blockedEndpoints: ["https://api.sketchy.com/*"],
+    requireApproval: {
+      above: "50.00",
+      handler: async (ctx) => await askSlackForApproval(ctx),
+    },
+  },
+
+  // Audit settings
+  audit: {
+    enabled: true,
+    storage: new MemoryStorage(),  // or FileStorage, ApiStorage
+    redactFields: ["secret_key"],
+    enrichment: {
+      staticTags: ["production"],
+      tagRules: [
+        { pattern: ".*openai.*", tags: ["llm", "openai"] },
+      ],
+    },
+  },
+
+  // Lifecycle hooks
+  hooks: {
+    afterPayment: async (record) => { /* log to DataDog */ },
+    onBudgetExceeded: async (violation) => { /* page on-call */ },
+    onAnomaly: async (anomaly) => { /* alert Slack */ },
+  },
+
+  // Custom metadata on every record
+  metadata: { environment: "production", cost_center: "ENG-2024" },
+});
+```
+
+---
+
+## Budget Policies
+
+### Presets
+
+```ts
+import {
+  conservativePolicy,  // $0.10/call, $5/hr, $50/day
+  standardPolicy,      // $1.00/call, $25/hr, $200/day
+  liberalPolicy,       // $10/call, $100/hr, $1000/day
+  unlimitedPolicy,     // no limits (audit only)
+  customPolicy,        // override any defaults
+} from "@x402sentinel/x402";
+```
+
+| Preset | Per Call | Per Hour | Per Day |
+|--------|---------|---------|---------|
+| `conservativePolicy()` | $0.10 | $5.00 | $50.00 |
+| `standardPolicy()` | $1.00 | $25.00 | $200.00 |
+| `liberalPolicy()` | $10.00 | $100.00 | $1,000.00 |
+| `unlimitedPolicy()` | -- | -- | -- |
+
+### Custom Policy
+
+```ts
+const policy = customPolicy({
+  maxPerCall: "5.00",
+  maxPerHour: "50.00",
+  spikeThreshold: 5.0,
+  blockedEndpoints: ["https://*.competitors.com/*"],
+});
+```
+
+### Error Handling
+
+```ts
+import { SentinelBudgetError } from "@x402sentinel/x402";
+
+try {
+  await secureFetch("https://api.example.com/expensive");
+} catch (err) {
+  if (err instanceof SentinelBudgetError) {
+    console.log(err.message);
+    // "Budget exceeded: $2.50 spent of $5.00 hourly limit on agent-weather-001"
+    console.log(err.violation.type);   // "hourly"
+    console.log(err.violation.limit);  // "5.00"
+  }
+}
+```
+
+---
+
+## Audit Records
+
+Every payment produces an `AuditRecord` with:
+
+```ts
+{
+  id: "a1b2c3d4e5f6g7h8",    // deterministic hash
+  agent_id: "agent-weather-001",
+  team: "data-ops",
+  human_sponsor: "alice@company.com",
+  amount: "0.50",              // human-readable USDC
+  amount_raw: "500000",        // base units
+  asset: "USDC",
+  network: "eip155:8453",
+  tx_hash: "0xabc...",
+  endpoint: "https://api.weather.com/v1/current",
+  method: "GET",
+  status_code: 200,
+  response_time_ms: 150,
+  policy_evaluation: "allowed",
+  budget_remaining: "24.50",
+  created_at: 1700000000000,
+  tags: ["production", "weather"],
+  metadata: { cost_center: "ENG-2024" },
+}
+```
+
+### Storage Backends
+
+```ts
+import { MemoryStorage, FileStorage, ApiStorage } from "@x402sentinel/x402";
+
+// In-memory (default) — 10k records, FIFO eviction
+const memory = new MemoryStorage(10_000);
+
+// JSONL file — persistent, append-only
+const file = new FileStorage(".valeo/audit.jsonl");
+
+// Remote API — batched writes to api.valeo.money
+const api = new ApiStorage({ apiKey: "val_..." });
+```
+
+### Querying
+
+```ts
+import { AuditLogger } from "@x402sentinel/x402";
+
+const logger = new AuditLogger({ storage: memory });
+
+const records = await logger.query({
+  agentId: "agent-weather-001",
+  startTime: Date.now() - 86400000,
+  status: ["allowed", "flagged"],
+  limit: 100,
+});
+
+const summary = await logger.summarize({ team: "data-ops" });
+console.log(summary.total_spend);  // "$1,234.56"
+
+const csv = await logger.exportCSV();
+```
+
+---
+
+## Dashboard
+
+```ts
+import { SentinelDashboard } from "@x402sentinel/x402/dashboard";
+
+const dashboard = new SentinelDashboard({ storage: myStorage });
+
+// Spend reports
+const report = await dashboard.getSpend({
+  agentId: "bot-1",
+  range: "last_day",
+});
+console.log(report.totalSpend, report.count);
+
+// Agent summaries
+const agents = await dashboard.getAgents();
+
+// Alerts (violations + anomalies)
+const alerts = await dashboard.getAlerts();
+```
+
+Dashboard queries run locally against your storage backend. No remote API required.
+
+---
+
+## Integration Guide
+
+Sentinel wraps **any** x402-compatible fetch. It works with:
+
+- `@x402/fetch` + `x402Client` (current)
+- `x402-fetch` + viem wallet (legacy)
+- Any function with the `fetch` signature that handles x402 internally
+
+The wrapper never touches the response body. It reads only headers (`PAYMENT-RESPONSE`, `PAYMENT-REQUIRED`) for audit data.
+
+---
+
+## API Reference
+
+### `wrapWithSentinel(fetch, config): typeof fetch`
+
+Wraps an x402 fetch function with Sentinel instrumentation. Returns a drop-in replacement.
+
+### `BudgetManager`
+
+```ts
+class BudgetManager {
+  constructor(policy: BudgetPolicy);
+  evaluate(context: PaymentContext): BudgetEvaluation;
+  record(amount: string, endpoint: string): void;
+  getState(): BudgetState;
+  reset(scope: 'hourly' | 'daily' | 'total'): void;
+  serialize(): string;
+  static deserialize(data: string, policy: BudgetPolicy): BudgetManager;
+}
+```
+
+### `AuditLogger`
+
+```ts
+class AuditLogger {
+  constructor(config?: AuditConfig);
+  log(record): Promise<AuditRecord>;
+  logBlocked(context, violation): Promise<AuditRecord>;
+  query(query: AuditQuery): Promise<AuditRecord[]>;
+  summarize(query?): Promise<AuditSummary>;
+  exportCSV(query?): Promise<string>;
+  exportJSON(query?): Promise<string>;
+  flush(): Promise<void>;
+}
+```
+
+### Error Classes
+
+| Class | When | Fatal? |
+|-------|------|--------|
+| `SentinelBudgetError` | Budget limit exceeded | Yes (blocks payment) |
+| `SentinelAuditError` | Audit write failed | No (never blocks) |
+| `SentinelConfigError` | Invalid configuration | Yes (at init) |
+
+---
+
+## Full Stack Product
+
+Sentinel is an SDK + Dashboard + API + Docs in a single monorepo:
+
+```
+├── /                      SDK (@x402sentinel/x402)
+├── app/                   Next.js 15 application
+│   ├── /login             API key authentication
+│   ├── /dashboard         Real-time analytics dashboard
+│   ├── /docs              Full documentation site
+│   └── /api/v1/*          REST API (18 endpoints)
+├── Dockerfile             Production Docker image
+└── docker-compose.yml     One-command deployment
+```
+
+### Quick Deploy
+
+```bash
+docker compose up --build -d
+```
+
+### Development
+
+```bash
+pnpm install
+make seed    # Populate demo data (500 payments)
+make dev     # Start dashboard at localhost:3000
+```
+
+Login with demo API key: `sk_sentinel_demo_000`
+
+### Available Make Commands
+
+| Command | Description |
+|---------|-------------|
+| `make dev` | Start Next.js dev server |
+| `make build` | Build SDK + app |
+| `make test` | Run SDK tests |
+| `make seed` | Seed demo data |
+| `make docker-up` | Build & start Docker |
+| `make docker-down` | Stop Docker |
+
+---
+
+## Roadmap
+
+- Multi-agent budget coordination (shared team budgets)
+- Escrow and pre-commitment flows
+- Treasury management integration
+- On-chain agent identity verification
+- Real-time dashboard at [app.valeo.money](https://app.valeo.money)
+
+---
+
+## License
+
+MIT

package/dist/chunk-25PZCEL2.js

@@ -0,0 +1,93 @@
+// src/utils/money.ts
+var USDC_DECIMALS = 6;
+var USDC_SCALE = 10n ** BigInt(USDC_DECIMALS);
+function parseUSDC(human) {
+  const trimmed = human.trim();
+  if (trimmed === "") {
+    throw new Error("Cannot parse empty string as USDC amount");
+  }
+  const negative = trimmed.startsWith("-");
+  if (negative) {
+    throw new Error(
+      `Negative USDC amounts are not allowed: "${human}"`
+    );
+  }
+  const dotIndex = trimmed.indexOf(".");
+  if (dotIndex === -1) {
+    return BigInt(trimmed) * USDC_SCALE;
+  }
+  const wholePart = trimmed.slice(0, dotIndex) || "0";
+  let fracPart = trimmed.slice(dotIndex + 1);
+  if (fracPart.length > USDC_DECIMALS) {
+    throw new Error(
+      `USDC amount "${human}" exceeds ${USDC_DECIMALS} decimal places`
+    );
+  }
+  fracPart = fracPart.padEnd(USDC_DECIMALS, "0");
+  return BigInt(wholePart) * USDC_SCALE + BigInt(fracPart);
+}
+function formatUSDC(raw) {
+  const isNeg = raw < 0n;
+  const abs = isNeg ? -raw : raw;
+  const whole = abs / USDC_SCALE;
+  const frac = abs % USDC_SCALE;
+  const fracStr = frac.toString().padStart(USDC_DECIMALS, "0");
+  return `${isNeg ? "-" : ""}${whole}.${fracStr}`;
+}
+function formatUSDCHuman(raw) {
+  const full = formatUSDC(raw);
+  const dotIndex = full.indexOf(".");
+  if (dotIndex === -1) return full;
+  let end = full.length;
+  while (end > dotIndex + 3 && full[end - 1] === "0") {
+    end--;
+  }
+  return full.slice(0, end);
+}
+function addUSDC(a, b) {
+  return formatUSDC(parseUSDC(a) + parseUSDC(b));
+}
+function compareUSDC(a, b) {
+  const diff = parseUSDC(a) - parseUSDC(b);
+  if (diff < 0n) return -1;
+  if (diff > 0n) return 1;
+  return 0;
+}
+function calculateAverage(amounts) {
+  if (amounts.length === 0) return formatUSDC(0n);
+  let sum = 0n;
+  for (const a of amounts) {
+    sum += parseUSDC(a);
+  }
+  return formatUSDC(sum / BigInt(amounts.length));
+}
+
+// src/utils/time.ts
+var HOUR_MS = 60 * 60 * 1e3;
+var DAY_MS = 24 * HOUR_MS;
+function getHourStart(now) {
+  const ref = now ?? Date.now();
+  return ref - ref % HOUR_MS;
+}
+function getDayStart(now) {
+  const ref = now ?? Date.now();
+  return ref - ref % DAY_MS;
+}
+function resolveTimeRange(range, now) {
+  const ref = now ?? Date.now();
+  if (typeof range === "object") return range;
+  switch (range) {
+    case "last_hour":
+      return { start: ref - HOUR_MS, end: ref };
+    case "last_day":
+      return { start: ref - DAY_MS, end: ref };
+    case "last_week":
+      return { start: ref - 7 * DAY_MS, end: ref };
+    case "last_month":
+      return { start: ref - 30 * DAY_MS, end: ref };
+  }
+}
+
+export { addUSDC, calculateAverage, compareUSDC, formatUSDC, formatUSDCHuman, getDayStart, getHourStart, parseUSDC, resolveTimeRange };
+//# sourceMappingURL=chunk-25PZCEL2.js.map
+//# sourceMappingURL=chunk-25PZCEL2.js.map

package/dist/chunk-25PZCEL2.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/utils/money.ts","../src/utils/time.ts"],"names":[],"mappings":"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","file":"chunk-25PZCEL2.js","sourcesContent":["/** USDC has 6 decimal places: 1 USDC = 1_000_000 base units */\nexport const USDC_DECIMALS = 6;\nconst USDC_SCALE = 10n ** BigInt(USDC_DECIMALS);\n\n/**\n * Parse a human-readable USDC string (e.g., \"1.50\") into base units as bigint.\n * Handles integers, decimals with up to 6 places, and leading/trailing zeros.\n */\nexport function parseUSDC(human: string): bigint {\n  const trimmed = human.trim();\n  if (trimmed === \"\") {\n    throw new Error(\"Cannot parse empty string as USDC amount\");\n  }\n\n  const negative = trimmed.startsWith(\"-\");\n  if (negative) {\n    throw new Error(\n      `Negative USDC amounts are not allowed: \"${human}\"`\n    );\n  }\n\n  const dotIndex = trimmed.indexOf(\".\");\n  if (dotIndex === -1) {\n    return BigInt(trimmed) * USDC_SCALE;\n  }\n\n  const wholePart = trimmed.slice(0, dotIndex) || \"0\";\n  let fracPart = trimmed.slice(dotIndex + 1);\n\n  if (fracPart.length > USDC_DECIMALS) {\n    throw new Error(\n      `USDC amount \"${human}\" exceeds ${USDC_DECIMALS} decimal places`\n    );\n  }\n\n  fracPart = fracPart.padEnd(USDC_DECIMALS, \"0\");\n  return BigInt(wholePart) * USDC_SCALE + BigInt(fracPart);\n}\n\n/** Format base units to a full 6-decimal USDC string (e.g., 1500000n -> \"1.500000\") */\nexport function formatUSDC(raw: bigint): string {\n  const isNeg = raw < 0n;\n  const abs = isNeg ? -raw : raw;\n  const whole = abs / USDC_SCALE;\n  const frac = abs % USDC_SCALE;\n  const fracStr = frac.toString().padStart(USDC_DECIMALS, \"0\");\n  return `${isNeg ? \"-\" : \"\"}${whole}.${fracStr}`;\n}\n\n/** Format base units to a trimmed human-readable string (e.g., 1500000n -> \"1.50\") */\nexport function formatUSDCHuman(raw: bigint): string {\n  const full = formatUSDC(raw);\n  const dotIndex = full.indexOf(\".\");\n  if (dotIndex === -1) return full;\n\n  let end = full.length;\n  while (end > dotIndex + 3 && full[end - 1] === \"0\") {\n    end--;\n  }\n  return full.slice(0, end);\n}\n\n/** Add two human-readable USDC amounts, return human-readable result */\nexport function addUSDC(a: string, b: string): string {\n  return formatUSDC(parseUSDC(a) + parseUSDC(b));\n}\n\n/** Subtract b from a (both human-readable USDC), return human-readable result */\nexport function subtractUSDC(a: string, b: string): string {\n  return formatUSDC(parseUSDC(a) - parseUSDC(b));\n}\n\n/** Compare two human-readable USDC amounts. Returns -1, 0, or 1. */\nexport function compareUSDC(a: string, b: string): -1 | 0 | 1 {\n  const diff = parseUSDC(a) - parseUSDC(b);\n  if (diff < 0n) return -1;\n  if (diff > 0n) return 1;\n  return 0;\n}\n\n/** Check if spent exceeds limit (both human-readable USDC strings) */\nexport function isOverBudget(spent: string, limit: string): boolean {\n  return parseUSDC(spent) > parseUSDC(limit);\n}\n\n/** Calculate the average of human-readable USDC amounts. Returns \"0.000000\" for empty array. */\nexport function calculateAverage(amounts: string[]): string {\n  if (amounts.length === 0) return formatUSDC(0n);\n  let sum = 0n;\n  for (const a of amounts) {\n    sum += parseUSDC(a);\n  }\n  return formatUSDC(sum / BigInt(amounts.length));\n}\n","const HOUR_MS = 60 * 60 * 1000;\nconst DAY_MS = 24 * HOUR_MS;\n\n/** Check if a timestamp falls within `windowMs` milliseconds of now */\nexport function isWithinWindow(timestamp: number, windowMs: number, now?: number): boolean {\n  const ref = now ?? Date.now();\n  return ref - timestamp < windowMs;\n}\n\n/** Get the start of the current hour as a unix ms timestamp */\nexport function getHourStart(now?: number): number {\n  const ref = now ?? Date.now();\n  return ref - (ref % HOUR_MS);\n}\n\n/** Get the start of the current day (UTC) as a unix ms timestamp */\nexport function getDayStart(now?: number): number {\n  const ref = now ?? Date.now();\n  return ref - (ref % DAY_MS);\n}\n\n/** Format a unix ms timestamp as an ISO 8601 string */\nexport function formatTimestamp(ts: number): string {\n  return new Date(ts).toISOString();\n}\n\n/** Resolve a named time range to epoch ms boundaries */\nexport function resolveTimeRange(\n  range: \"last_hour\" | \"last_day\" | \"last_week\" | \"last_month\" | { start: number; end: number },\n  now?: number,\n): { start: number; end: number } {\n  const ref = now ?? Date.now();\n  if (typeof range === \"object\") return range;\n  switch (range) {\n    case \"last_hour\":\n      return { start: ref - HOUR_MS, end: ref };\n    case \"last_day\":\n      return { start: ref - DAY_MS, end: ref };\n    case \"last_week\":\n      return { start: ref - 7 * DAY_MS, end: ref };\n    case \"last_month\":\n      return { start: ref - 30 * DAY_MS, end: ref };\n  }\n}\n"]}

package/dist/chunk-7H4FRU7K.cjs

@@ -0,0 +1,103 @@
+'use strict';
+
+// src/utils/money.ts
+var USDC_DECIMALS = 6;
+var USDC_SCALE = 10n ** BigInt(USDC_DECIMALS);
+function parseUSDC(human) {
+  const trimmed = human.trim();
+  if (trimmed === "") {
+    throw new Error("Cannot parse empty string as USDC amount");
+  }
+  const negative = trimmed.startsWith("-");
+  if (negative) {
+    throw new Error(
+      `Negative USDC amounts are not allowed: "${human}"`
+    );
+  }
+  const dotIndex = trimmed.indexOf(".");
+  if (dotIndex === -1) {
+    return BigInt(trimmed) * USDC_SCALE;
+  }
+  const wholePart = trimmed.slice(0, dotIndex) || "0";
+  let fracPart = trimmed.slice(dotIndex + 1);
+  if (fracPart.length > USDC_DECIMALS) {
+    throw new Error(
+      `USDC amount "${human}" exceeds ${USDC_DECIMALS} decimal places`
+    );
+  }
+  fracPart = fracPart.padEnd(USDC_DECIMALS, "0");
+  return BigInt(wholePart) * USDC_SCALE + BigInt(fracPart);
+}
+function formatUSDC(raw) {
+  const isNeg = raw < 0n;
+  const abs = isNeg ? -raw : raw;
+  const whole = abs / USDC_SCALE;
+  const frac = abs % USDC_SCALE;
+  const fracStr = frac.toString().padStart(USDC_DECIMALS, "0");
+  return `${isNeg ? "-" : ""}${whole}.${fracStr}`;
+}
+function formatUSDCHuman(raw) {
+  const full = formatUSDC(raw);
+  const dotIndex = full.indexOf(".");
+  if (dotIndex === -1) return full;
+  let end = full.length;
+  while (end > dotIndex + 3 && full[end - 1] === "0") {
+    end--;
+  }
+  return full.slice(0, end);
+}
+function addUSDC(a, b) {
+  return formatUSDC(parseUSDC(a) + parseUSDC(b));
+}
+function compareUSDC(a, b) {
+  const diff = parseUSDC(a) - parseUSDC(b);
+  if (diff < 0n) return -1;
+  if (diff > 0n) return 1;
+  return 0;
+}
+function calculateAverage(amounts) {
+  if (amounts.length === 0) return formatUSDC(0n);
+  let sum = 0n;
+  for (const a of amounts) {
+    sum += parseUSDC(a);
+  }
+  return formatUSDC(sum / BigInt(amounts.length));
+}
+
+// src/utils/time.ts
+var HOUR_MS = 60 * 60 * 1e3;
+var DAY_MS = 24 * HOUR_MS;
+function getHourStart(now) {
+  const ref = now ?? Date.now();
+  return ref - ref % HOUR_MS;
+}
+function getDayStart(now) {
+  const ref = now ?? Date.now();
+  return ref - ref % DAY_MS;
+}
+function resolveTimeRange(range, now) {
+  const ref = now ?? Date.now();
+  if (typeof range === "object") return range;
+  switch (range) {
+    case "last_hour":
+      return { start: ref - HOUR_MS, end: ref };
+    case "last_day":
+      return { start: ref - DAY_MS, end: ref };
+    case "last_week":
+      return { start: ref - 7 * DAY_MS, end: ref };
+    case "last_month":
+      return { start: ref - 30 * DAY_MS, end: ref };
+  }
+}
+
+exports.addUSDC = addUSDC;
+exports.calculateAverage = calculateAverage;
+exports.compareUSDC = compareUSDC;
+exports.formatUSDC = formatUSDC;
+exports.formatUSDCHuman = formatUSDCHuman;
+exports.getDayStart = getDayStart;
+exports.getHourStart = getHourStart;
+exports.parseUSDC = parseUSDC;
+exports.resolveTimeRange = resolveTimeRange;
+//# sourceMappingURL=chunk-7H4FRU7K.cjs.map
+//# sourceMappingURL=chunk-7H4FRU7K.cjs.map

package/dist/chunk-7H4FRU7K.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/utils/money.ts","../src/utils/time.ts"],"names":[],"mappings":"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","file":"chunk-7H4FRU7K.cjs","sourcesContent":["/** USDC has 6 decimal places: 1 USDC = 1_000_000 base units */\nexport const USDC_DECIMALS = 6;\nconst USDC_SCALE = 10n ** BigInt(USDC_DECIMALS);\n\n/**\n * Parse a human-readable USDC string (e.g., \"1.50\") into base units as bigint.\n * Handles integers, decimals with up to 6 places, and leading/trailing zeros.\n */\nexport function parseUSDC(human: string): bigint {\n  const trimmed = human.trim();\n  if (trimmed === \"\") {\n    throw new Error(\"Cannot parse empty string as USDC amount\");\n  }\n\n  const negative = trimmed.startsWith(\"-\");\n  if (negative) {\n    throw new Error(\n      `Negative USDC amounts are not allowed: \"${human}\"`\n    );\n  }\n\n  const dotIndex = trimmed.indexOf(\".\");\n  if (dotIndex === -1) {\n    return BigInt(trimmed) * USDC_SCALE;\n  }\n\n  const wholePart = trimmed.slice(0, dotIndex) || \"0\";\n  let fracPart = trimmed.slice(dotIndex + 1);\n\n  if (fracPart.length > USDC_DECIMALS) {\n    throw new Error(\n      `USDC amount \"${human}\" exceeds ${USDC_DECIMALS} decimal places`\n    );\n  }\n\n  fracPart = fracPart.padEnd(USDC_DECIMALS, \"0\");\n  return BigInt(wholePart) * USDC_SCALE + BigInt(fracPart);\n}\n\n/** Format base units to a full 6-decimal USDC string (e.g., 1500000n -> \"1.500000\") */\nexport function formatUSDC(raw: bigint): string {\n  const isNeg = raw < 0n;\n  const abs = isNeg ? -raw : raw;\n  const whole = abs / USDC_SCALE;\n  const frac = abs % USDC_SCALE;\n  const fracStr = frac.toString().padStart(USDC_DECIMALS, \"0\");\n  return `${isNeg ? \"-\" : \"\"}${whole}.${fracStr}`;\n}\n\n/** Format base units to a trimmed human-readable string (e.g., 1500000n -> \"1.50\") */\nexport function formatUSDCHuman(raw: bigint): string {\n  const full = formatUSDC(raw);\n  const dotIndex = full.indexOf(\".\");\n  if (dotIndex === -1) return full;\n\n  let end = full.length;\n  while (end > dotIndex + 3 && full[end - 1] === \"0\") {\n    end--;\n  }\n  return full.slice(0, end);\n}\n\n/** Add two human-readable USDC amounts, return human-readable result */\nexport function addUSDC(a: string, b: string): string {\n  return formatUSDC(parseUSDC(a) + parseUSDC(b));\n}\n\n/** Subtract b from a (both human-readable USDC), return human-readable result */\nexport function subtractUSDC(a: string, b: string): string {\n  return formatUSDC(parseUSDC(a) - parseUSDC(b));\n}\n\n/** Compare two human-readable USDC amounts. Returns -1, 0, or 1. */\nexport function compareUSDC(a: string, b: string): -1 | 0 | 1 {\n  const diff = parseUSDC(a) - parseUSDC(b);\n  if (diff < 0n) return -1;\n  if (diff > 0n) return 1;\n  return 0;\n}\n\n/** Check if spent exceeds limit (both human-readable USDC strings) */\nexport function isOverBudget(spent: string, limit: string): boolean {\n  return parseUSDC(spent) > parseUSDC(limit);\n}\n\n/** Calculate the average of human-readable USDC amounts. Returns \"0.000000\" for empty array. */\nexport function calculateAverage(amounts: string[]): string {\n  if (amounts.length === 0) return formatUSDC(0n);\n  let sum = 0n;\n  for (const a of amounts) {\n    sum += parseUSDC(a);\n  }\n  return formatUSDC(sum / BigInt(amounts.length));\n}\n","const HOUR_MS = 60 * 60 * 1000;\nconst DAY_MS = 24 * HOUR_MS;\n\n/** Check if a timestamp falls within `windowMs` milliseconds of now */\nexport function isWithinWindow(timestamp: number, windowMs: number, now?: number): boolean {\n  const ref = now ?? Date.now();\n  return ref - timestamp < windowMs;\n}\n\n/** Get the start of the current hour as a unix ms timestamp */\nexport function getHourStart(now?: number): number {\n  const ref = now ?? Date.now();\n  return ref - (ref % HOUR_MS);\n}\n\n/** Get the start of the current day (UTC) as a unix ms timestamp */\nexport function getDayStart(now?: number): number {\n  const ref = now ?? Date.now();\n  return ref - (ref % DAY_MS);\n}\n\n/** Format a unix ms timestamp as an ISO 8601 string */\nexport function formatTimestamp(ts: number): string {\n  return new Date(ts).toISOString();\n}\n\n/** Resolve a named time range to epoch ms boundaries */\nexport function resolveTimeRange(\n  range: \"last_hour\" | \"last_day\" | \"last_week\" | \"last_month\" | { start: number; end: number },\n  now?: number,\n): { start: number; end: number } {\n  const ref = now ?? Date.now();\n  if (typeof range === \"object\") return range;\n  switch (range) {\n    case \"last_hour\":\n      return { start: ref - HOUR_MS, end: ref };\n    case \"last_day\":\n      return { start: ref - DAY_MS, end: ref };\n    case \"last_week\":\n      return { start: ref - 7 * DAY_MS, end: ref };\n    case \"last_month\":\n      return { start: ref - 30 * DAY_MS, end: ref };\n  }\n}\n"]}