taximeter 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,404 @@
+import { z } from 'zod';
+import { Server } from 'node:http';
+
+declare const configSchema: z.ZodObject<{
+    budgets: z.ZodPrefault<z.ZodObject<{
+        perTask: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+            amount: z.ZodString;
+            asset: z.ZodString;
+            network: z.ZodOptional<z.ZodString>;
+            window: z.ZodOptional<z.ZodEnum<{
+                "1h": "1h";
+                "24h": "24h";
+                "7d": "7d";
+                "30d": "30d";
+            }>>;
+        }, z.core.$strict>>>;
+        perAgent: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+            amount: z.ZodString;
+            asset: z.ZodString;
+            network: z.ZodOptional<z.ZodString>;
+            window: z.ZodOptional<z.ZodEnum<{
+                "1h": "1h";
+                "24h": "24h";
+                "7d": "7d";
+                "30d": "30d";
+            }>>;
+        }, z.core.$strict>>>;
+        global: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+            amount: z.ZodString;
+            asset: z.ZodString;
+            network: z.ZodOptional<z.ZodString>;
+            window: z.ZodOptional<z.ZodEnum<{
+                "1h": "1h";
+                "24h": "24h";
+                "7d": "7d";
+                "30d": "30d";
+            }>>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
+    policy: z.ZodPrefault<z.ZodObject<{
+        allowHosts: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        denyHosts: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        allowPayTo: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        maxSinglePayment: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        maxSingleAsset: z.ZodDefault<z.ZodString>;
+    }, z.core.$strict>>;
+    ports: z.ZodPrefault<z.ZodObject<{
+        proxy: z.ZodDefault<z.ZodNumber>;
+        dashboard: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+    db: z.ZodDefault<z.ZodString>;
+    upstream: z.ZodOptional<z.ZodURL>;
+}, z.core.$strict>;
+type TaximeterConfig = z.infer<typeof configSchema>;
+/** Merge validated layers from lowest to highest priority without mutating inputs. */
+declare function parseConfig(...layers: unknown[]): TaximeterConfig;
+
+declare function loadConfig(flags?: unknown, options?: {
+    cwd?: string;
+    home?: string;
+    env?: unknown;
+    configFile?: string;
+}): {
+    db: string;
+    budgets: {
+        perTask: {
+            amount: string;
+            asset: string;
+            network?: string | undefined;
+            window?: "1h" | "24h" | "7d" | "30d" | undefined;
+        } | null;
+        perAgent: {
+            amount: string;
+            asset: string;
+            network?: string | undefined;
+            window?: "1h" | "24h" | "7d" | "30d" | undefined;
+        } | null;
+        global: {
+            amount: string;
+            asset: string;
+            network?: string | undefined;
+            window?: "1h" | "24h" | "7d" | "30d" | undefined;
+        } | null;
+    };
+    policy: {
+        allowHosts: string[];
+        denyHosts: string[];
+        allowPayTo: string[];
+        maxSinglePayment: string | null;
+        maxSingleAsset: string;
+    };
+    ports: {
+        proxy: number;
+        dashboard: number;
+    };
+    upstream?: string | undefined;
+};
+
+declare const requestSchema: z.ZodObject<{
+    url: z.ZodURL;
+    method: z.ZodString;
+    headers: z.ZodRecord<z.ZodString, z.ZodString>;
+}, z.core.$strip>;
+declare const responseSchema: z.ZodObject<{
+    status: z.ZodNumber;
+    headers: z.ZodRecord<z.ZodString, z.ZodString>;
+    body: z.ZodOptional<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
+}, z.core.$strip>;
+declare const paymentEventSchema: z.ZodObject<{
+    id: z.ZodUUID;
+    ts: z.ZodISODateTime;
+    rail: z.ZodLiteral<"x402">;
+    attemptedAt: z.ZodOptional<z.ZodISODateTime>;
+    status: z.ZodEnum<{
+        observed: "observed";
+        blocked: "blocked";
+    }>;
+    reason: z.ZodOptional<z.ZodString>;
+    amount: z.ZodString;
+    decimals: z.ZodNumber;
+    decimalsKnown: z.ZodBoolean;
+    asset: z.ZodString;
+    assetSymbol: z.ZodOptional<z.ZodString>;
+    network: z.ZodString;
+    payTo: z.ZodString;
+    payer: z.ZodOptional<z.ZodString>;
+    resource: z.ZodURL;
+    host: z.ZodString;
+    txHash: z.ZodOptional<z.ZodString>;
+    taskId: z.ZodOptional<z.ZodString>;
+    agentId: z.ZodOptional<z.ZodString>;
+    raw: z.ZodString;
+    paymentKey: z.ZodString;
+    settlementStatus: z.ZodDefault<z.ZodEnum<{
+        unknown: "unknown";
+        confirmed: "confirmed";
+        failed: "failed";
+    }>>;
+    settlement_unknown: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+type PaymentEvent = z.infer<typeof paymentEventSchema>;
+declare const outcomeSchema: z.ZodObject<{
+    id: z.ZodUUID;
+    ts: z.ZodISODateTime;
+    paymentId: z.ZodUUID;
+    attemptId: z.ZodOptional<z.ZodUUID>;
+    attemptedAt: z.ZodOptional<z.ZodISODateTime>;
+    status: z.ZodEnum<{
+        unknown: "unknown";
+        confirmed: "confirmed";
+        failed: "failed";
+    }>;
+    txHash: z.ZodOptional<z.ZodString>;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type Outcome = z.infer<typeof outcomeSchema>;
+declare const diagnosticSchema: z.ZodObject<{
+    id: z.ZodUUID;
+    ts: z.ZodISODateTime;
+    code: z.ZodEnum<{
+        settlement_unknown: "settlement_unknown";
+        parse_failed: "parse_failed";
+        tls_unmetered: "tls_unmetered";
+        storage_failed: "storage_failed";
+    }>;
+    resource: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>;
+type Diagnostic = z.infer<typeof diagnosticSchema>;
+declare const blockedBodySchema: z.ZodObject<{
+    error: z.ZodLiteral<"blocked_by_taximeter">;
+    reason: z.ZodString;
+    budget: z.ZodNullable<z.ZodString>;
+    spent: z.ZodString;
+    remaining: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+type BlockedBody = z.infer<typeof blockedBodySchema>;
+
+/** Synchronous storage edge; money derivations remain pure in derive.ts. */
+declare class Ledger {
+    private readonly database;
+    constructor(input: string);
+    transaction<T>(operation: () => T): T;
+    append(input: unknown): boolean;
+    appendOutcome(input: unknown): boolean;
+    events(): {
+        id: string;
+        ts: string;
+        rail: "x402";
+        status: "observed" | "blocked";
+        amount: string;
+        decimals: number;
+        decimalsKnown: boolean;
+        asset: string;
+        network: string;
+        payTo: string;
+        resource: string;
+        host: string;
+        raw: string;
+        paymentKey: string;
+        settlementStatus: "unknown" | "confirmed" | "failed";
+        settlement_unknown: boolean;
+        attemptedAt?: string | undefined;
+        reason?: string | undefined;
+        assetSymbol?: string | undefined;
+        payer?: string | undefined;
+        txHash?: string | undefined;
+        taskId?: string | undefined;
+        agentId?: string | undefined;
+    }[];
+    outcomes(): {
+        id: string;
+        ts: string;
+        paymentId: string;
+        status: "unknown" | "confirmed" | "failed";
+        attemptId?: string | undefined;
+        attemptedAt?: string | undefined;
+        txHash?: string | undefined;
+        reason?: string | undefined;
+    }[];
+    view(): {
+        id: string;
+        ts: string;
+        rail: "x402";
+        status: "observed" | "blocked";
+        amount: string;
+        decimals: number;
+        decimalsKnown: boolean;
+        asset: string;
+        network: string;
+        payTo: string;
+        resource: string;
+        host: string;
+        raw: string;
+        paymentKey: string;
+        settlementStatus: "unknown" | "confirmed" | "failed";
+        settlement_unknown: boolean;
+        attemptedAt?: string | undefined;
+        reason?: string | undefined;
+        assetSymbol?: string | undefined;
+        payer?: string | undefined;
+        txHash?: string | undefined;
+        taskId?: string | undefined;
+        agentId?: string | undefined;
+    }[];
+    diagnose(code: Diagnostic["code"], resource: string, message: string): void;
+    diagnostics(): {
+        id: string;
+        ts: string;
+        code: "settlement_unknown" | "parse_failed" | "tls_unmetered" | "storage_failed";
+        resource: string;
+        message: string;
+    }[];
+    close(): void;
+}
+
+type WireRequest = z.infer<typeof requestSchema>;
+type WireResponse = z.infer<typeof responseSchema>;
+interface Rail {
+    readonly name: string;
+    detect(request: WireRequest, response?: WireResponse): boolean;
+    parse(request: WireRequest, response?: WireResponse): PaymentEvent | null;
+}
+
+type Report = (code: Diagnostic["code"], resource: string, message: string) => void;
+type Settlement = Pick<Outcome, "status" | "txHash" | "reason">;
+/** Stateful challenge cache at the intake edge. Unknown data always returns null. */
+declare class X402Rail implements Rail {
+    readonly name = "x402";
+    private readonly cache;
+    private readonly now;
+    private readonly diagnostic;
+    constructor(options?: {
+        diagnostic?: Report;
+        now?: () => number;
+    });
+    private report;
+    detect(request: WireRequest, response?: WireResponse): boolean;
+    private attribution;
+    parse(input: WireRequest, reply?: WireResponse): PaymentEvent | null;
+    settlement(event: PaymentEvent, input: WireResponse): Settlement;
+}
+
+type Intake = {
+    body?: BlockedBody;
+    payment?: PaymentEvent;
+    attempt?: Outcome;
+};
+/** Shared proxy/SDK intake. Every reservation is committed before returning to I/O. */
+declare class Meter {
+    readonly ledger: Ledger;
+    readonly rail: X402Rail;
+    readonly config: TaximeterConfig;
+    constructor(ledger: Ledger, config: TaximeterConfig);
+    diagnose(code: Diagnostic["code"], resource: string, message: string): void;
+    begin(request: WireRequest): Intake;
+    observe(request: WireRequest, response: WireResponse): void;
+    complete(intake: Intake, response?: WireResponse): void;
+}
+
+/** `amount` is the row's contribution to totals; the original proposal is separate. */
+declare function toCsv(input: PaymentEvent[]): string;
+declare function toJson(input: PaymentEvent[]): string;
+declare function toInvoice(input: PaymentEvent[]): string;
+
+declare const totalSchema: z.ZodObject<{
+    network: z.ZodString;
+    asset: z.ZodString;
+    assetSymbol: z.ZodOptional<z.ZodString>;
+    decimals: z.ZodNumber;
+    decimalsKnown: z.ZodBoolean;
+    amount: z.ZodString;
+    confirmedAmount: z.ZodString;
+    unknownAmount: z.ZodString;
+}, z.core.$strip>;
+type Total = z.infer<typeof totalSchema>;
+/** Stable replay: confirmed evidence wins; otherwise the latest outcome applies. */
+declare function deriveEvents(events: PaymentEvent[], outcomes?: Outcome[]): PaymentEvent[];
+/** Never use a SQLite SUM or floating-point conversion for money. */
+declare function totals(events: PaymentEvent[]): Total[];
+declare function formatAmount(amount: string, decimals: number): string;
+
+type Decision = {
+    allowed: true;
+} | {
+    allowed: false;
+    body: BlockedBody;
+};
+/** Pure, synchronous budget decision. The caller must reserve in the same transaction. */
+declare function evaluate(proposed: PaymentEvent, events: PaymentEvent[], config: TaximeterConfig, now: number): Decision;
+
+declare function createProxy(options: {
+    ledger: Ledger;
+    config: TaximeterConfig;
+}): Server;
+declare function closeProxy(server: Server): Promise<void>;
+
+declare const optionsSchema: z.ZodObject<{
+    ledger: z.ZodOptional<z.ZodCustom<Ledger, Ledger>>;
+    config: z.ZodOptional<z.ZodObject<{
+        budgets: z.ZodOptional<z.ZodObject<{
+            perTask: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                amount: z.ZodOptional<z.ZodString>;
+                asset: z.ZodOptional<z.ZodString>;
+                network: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+                window: z.ZodOptional<z.ZodOptional<z.ZodEnum<{
+                    "1h": "1h";
+                    "24h": "24h";
+                    "7d": "7d";
+                    "30d": "30d";
+                }>>>;
+            }, z.core.$strict>>>;
+            perAgent: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                amount: z.ZodOptional<z.ZodString>;
+                asset: z.ZodOptional<z.ZodString>;
+                network: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+                window: z.ZodOptional<z.ZodOptional<z.ZodEnum<{
+                    "1h": "1h";
+                    "24h": "24h";
+                    "7d": "7d";
+                    "30d": "30d";
+                }>>>;
+            }, z.core.$strict>>>;
+            global: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                amount: z.ZodOptional<z.ZodString>;
+                asset: z.ZodOptional<z.ZodString>;
+                network: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+                window: z.ZodOptional<z.ZodOptional<z.ZodEnum<{
+                    "1h": "1h";
+                    "24h": "24h";
+                    "7d": "7d";
+                    "30d": "30d";
+                }>>>;
+            }, z.core.$strict>>>;
+        }, z.core.$strict>>;
+        policy: z.ZodOptional<z.ZodObject<{
+            allowHosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            denyHosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            allowPayTo: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            maxSinglePayment: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            maxSingleAsset: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        ports: z.ZodOptional<z.ZodObject<{
+            proxy: z.ZodOptional<z.ZodNumber>;
+            dashboard: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+        db: z.ZodOptional<z.ZodString>;
+        upstream: z.ZodOptional<z.ZodURL>;
+    }, z.core.$strict>>;
+    db: z.ZodOptional<z.ZodString>;
+    taskId: z.ZodOptional<z.ZodString>;
+    agentId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+type MeterOptions = z.input<typeof optionsSchema>;
+type MeteredFetch = typeof globalThis.fetch & {
+    close(): void;
+    readonly ledger: Ledger;
+};
+/** Place inside the payment wrapper: wrapFetchWithPayment(withMeter(fetch, opts), client). */
+declare function withMeter(fetchImpl: typeof globalThis.fetch, input?: MeterOptions): MeteredFetch;
+
+declare const version = "0.1.0";
+
+export { Ledger, Meter, type MeterOptions, type MeteredFetch, type PaymentEvent, type Rail, type TaximeterConfig, X402Rail, closeProxy, createProxy, deriveEvents, evaluate, formatAmount, loadConfig, parseConfig, paymentEventSchema, toCsv, toInvoice, toJson, totals, version, withMeter };

package/dist/index.js

@@ -0,0 +1,182 @@
+import {
+  Ledger,
+  Meter,
+  X402Rail,
+  closeProxy,
+  configPatchSchema,
+  createProxy,
+  deriveEvents,
+  evaluate,
+  formatAmount,
+  httpUrlSchema,
+  labelSchema,
+  loadConfig,
+  parseConfig,
+  paymentEventSchema,
+  toCsv,
+  toInvoice,
+  toJson,
+  totals
+} from "./chunk-I7YXGTRZ.js";
+
+// src/sdk/index.ts
+import { z } from "zod";
+var headerInputSchema = z.union([
+  z.instanceof(Headers),
+  z.record(z.string(), z.string()),
+  z.array(z.tuple([z.string(), z.string()]))
+]);
+var initSchema = z.looseObject({
+  method: z.string().optional(),
+  headers: headerInputSchema.optional(),
+  signal: z.instanceof(AbortSignal).nullable().optional()
+});
+var sdkLabel = labelSchema.refine(
+  (value) => !/[\r\n\0]/.test(value),
+  "Attribution must fit an HTTP header"
+);
+var optionsSchema = z.strictObject({
+  ledger: z.instanceof(Ledger).optional(),
+  config: configPatchSchema.optional(),
+  db: z.string().min(1).optional(),
+  taskId: sdkLabel.optional(),
+  agentId: sdkLabel.optional()
+});
+async function challengeBody(response) {
+  const reader = response.clone().body?.getReader();
+  if (!reader) return new Uint8Array();
+  let done = false;
+  let timer;
+  const read = async () => {
+    const parts = [];
+    let length = 0;
+    while (true) {
+      const chunk = await reader.read();
+      if (chunk.done) {
+        done = true;
+        return Buffer.concat(parts);
+      }
+      const bytes = z.instanceof(Uint8Array).parse(chunk.value);
+      length += bytes.byteLength;
+      if (length > 65536) return void 0;
+      parts.push(bytes);
+    }
+  };
+  try {
+    return await Promise.race([
+      read(),
+      new Promise((resolve) => {
+        timer = setTimeout(() => resolve(void 0), 100);
+      })
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+    if (!done) void reader.cancel().catch(() => {
+    });
+  }
+}
+function withMeter(fetchImpl, input = {}) {
+  const transport = z.custom((value) => typeof value === "function").parse(fetchImpl);
+  const options = optionsSchema.parse(input);
+  const overrides = { ...options.config, ...options.db ? { db: options.db } : {} };
+  const config = options.ledger ? parseConfig(overrides) : loadConfig(overrides);
+  const ledger = options.ledger ?? new Ledger(config.db);
+  const meter = new Meter(ledger, config);
+  let closed = false;
+  const wrapped = async (input2, init) => {
+    if (closed) return transport(input2, init);
+    let url;
+    let method;
+    let headers;
+    let forwarded = init;
+    try {
+      const target = z.union([z.string(), z.instanceof(URL), z.instanceof(Request)]).parse(input2);
+      const options2 = initSchema.optional().parse(init);
+      url = httpUrlSchema.parse(target instanceof Request ? target.url : target.toString());
+      method = options2?.method ?? (target instanceof Request ? target.method : "GET");
+      headers = new Headers(
+        options2?.headers ?? (target instanceof Request ? target.headers : void 0)
+      );
+      const signal = options2?.signal ?? (target instanceof Request ? target.signal : void 0);
+      if (signal?.aborted) return transport(input2, init);
+    } catch {
+      meter.diagnose(
+        "parse_failed",
+        "sdk",
+        "Unsupported fetch input; passed directly to the supplied transport."
+      );
+      return transport(input2, init);
+    }
+    if (options.taskId) headers.set("Taximeter-Task", options.taskId);
+    if (options.agentId) headers.set("Taximeter-Agent", options.agentId);
+    if (options.taskId || options.agentId) forwarded = { ...init, headers };
+    const request = { url, method, headers: Object.fromEntries(headers) };
+    const intake = meter.begin(request);
+    if (intake.body)
+      return new Response(JSON.stringify(intake.body), {
+        status: 402,
+        headers: { "Content-Type": "application/json", "Cache-Control": "no-store" }
+      });
+    let response;
+    try {
+      response = await transport(input2, forwarded);
+    } catch (error) {
+      meter.complete(intake);
+      throw error;
+    }
+    const responseHeaders = Object.fromEntries(response.headers);
+    const reply = { status: response.status, headers: responseHeaders };
+    meter.complete(intake, reply);
+    if (response.redirected)
+      meter.diagnose(
+        "parse_failed",
+        url,
+        "The supplied transport followed a redirect internally; intermediate requests were not visible to Taximeter policy. Use redirect: 'error' or expose each hop when host policies must apply to every destination."
+      );
+    if (response.status === 402 && !response.redirected) {
+      try {
+        const body = response.headers.has("payment-required") ? void 0 : await challengeBody(response);
+        const inspectionHeaders = { ...responseHeaders };
+        delete inspectionHeaders["content-encoding"];
+        meter.observe(request, { ...reply, headers: inspectionHeaders, body });
+      } catch {
+        meter.diagnose(
+          "parse_failed",
+          url,
+          "Could not inspect response clone; original response preserved."
+        );
+      }
+    }
+    return response;
+  };
+  return Object.assign(wrapped, {
+    ledger,
+    close() {
+      if (closed) return;
+      closed = true;
+      if (!options.ledger) ledger.close();
+    }
+  });
+}
+
+// src/index.ts
+var version = "0.1.0";
+export {
+  Ledger,
+  Meter,
+  X402Rail,
+  closeProxy,
+  createProxy,
+  deriveEvents,
+  evaluate,
+  formatAmount,
+  loadConfig,
+  parseConfig,
+  paymentEventSchema,
+  toCsv,
+  toInvoice,
+  toJson,
+  totals,
+  version,
+  withMeter
+};