@tollbase/core 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tollbase contributors
+
+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,14 @@
+# @tollbase/core
+
+Shared protocol types for Tollbase: the agent-facing service manifest, the
+machine-readable HTTP 402 challenge, usage-event shapes, plus configuration and
+logging utilities used by Tollbase services.
+
+You normally do not install this directly; it comes with
+[`@tollbase/middleware`](https://www.npmjs.com/package/@tollbase/middleware).
+
+```ts
+import { err402, ManifestSchema, type Plan } from "@tollbase/core/types";
+```
+
+MIT.

package/dist/config.d.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+/**
+ * All runtime configuration comes from the environment and is validated once
+ * at boot. Anything invalid fails fast with a readable error instead of
+ * surfacing later as a mysterious runtime bug.
+ */
+declare const ConfigSchema: z.ZodObject<{
+    NODE_ENV: z.ZodDefault<z.ZodEnum<["development", "test", "production"]>>;
+    PORT: z.ZodDefault<z.ZodNumber>;
+    TOLLBASE_DB: z.ZodDefault<z.ZodString>;
+    LOG_LEVEL: z.ZodDefault<z.ZodEnum<["debug", "info", "warn", "error"]>>;
+    STRIPE_SECRET_KEY: z.ZodOptional<z.ZodString>;
+    TOLLBASE_TAKE_BPS: z.ZodDefault<z.ZodNumber>;
+    RESEND_API_KEY: z.ZodOptional<z.ZodString>;
+    EMAIL_FROM: z.ZodDefault<z.ZodString>;
+    TOLLBASE_SESSION_SECRET: z.ZodOptional<z.ZodString>;
+    TOLLBASE_DEMO_MODE: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    NODE_ENV: "development" | "test" | "production";
+    PORT: number;
+    TOLLBASE_DB: string;
+    LOG_LEVEL: "debug" | "info" | "warn" | "error";
+    TOLLBASE_TAKE_BPS: number;
+    EMAIL_FROM: string;
+    TOLLBASE_DEMO_MODE: boolean;
+    STRIPE_SECRET_KEY?: string | undefined;
+    RESEND_API_KEY?: string | undefined;
+    TOLLBASE_SESSION_SECRET?: string | undefined;
+}, {
+    NODE_ENV?: "development" | "test" | "production" | undefined;
+    PORT?: number | undefined;
+    TOLLBASE_DB?: string | undefined;
+    LOG_LEVEL?: "debug" | "info" | "warn" | "error" | undefined;
+    STRIPE_SECRET_KEY?: string | undefined;
+    TOLLBASE_TAKE_BPS?: number | undefined;
+    RESEND_API_KEY?: string | undefined;
+    EMAIL_FROM?: string | undefined;
+    TOLLBASE_SESSION_SECRET?: string | undefined;
+    TOLLBASE_DEMO_MODE?: boolean | undefined;
+}>;
+export type Config = z.infer<typeof ConfigSchema>;
+export declare function loadConfig(env?: NodeJS.ProcessEnv): Config;
+export {};

package/dist/config.js

@@ -0,0 +1,38 @@
+import { z } from "zod";
+/**
+ * All runtime configuration comes from the environment and is validated once
+ * at boot. Anything invalid fails fast with a readable error instead of
+ * surfacing later as a mysterious runtime bug.
+ */
+const ConfigSchema = z.object({
+    NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
+    PORT: z.coerce.number().int().positive().default(4600),
+    TOLLBASE_DB: z.string().default("tollbase.db"),
+    LOG_LEVEL: z.enum(["debug", "info", "warn", "error"]).default("info"),
+    // Payments. When STRIPE_SECRET_KEY is unset the mock adapter is used, which
+    // keeps local development and CI runnable with zero external accounts.
+    STRIPE_SECRET_KEY: z.string().optional(),
+    // Optional Stripe Connect account of the vendor for direct charges. The
+    // platform take rate is expressed in basis points of each charge.
+    TOLLBASE_TAKE_BPS: z.coerce.number().int().min(0).max(2000).default(150),
+    // Notifications. When RESEND_API_KEY is unset, approval links are printed
+    // to the server log (development behaviour).
+    RESEND_API_KEY: z.string().optional(),
+    EMAIL_FROM: z.string().default("Tollbase <approvals@tollbase.local>"),
+    // Signs dashboard session cookies. When unset, a random per-boot secret is
+    // used (dev behaviour: restarting the control plane logs everyone out).
+    TOLLBASE_SESSION_SECRET: z.string().min(16).optional(),
+    // Never enable in production: exposes raw approval tokens for the demo.
+    TOLLBASE_DEMO_MODE: z.coerce.boolean().default(false),
+});
+export function loadConfig(env = process.env) {
+    const parsed = ConfigSchema.safeParse(env);
+    if (!parsed.success) {
+        const issues = parsed.error.issues.map((i) => `  ${i.path.join(".")}: ${i.message}`).join("\n");
+        throw new Error(`Invalid configuration:\n${issues}`);
+    }
+    if (parsed.data.NODE_ENV === "production" && parsed.data.TOLLBASE_DEMO_MODE) {
+        throw new Error("TOLLBASE_DEMO_MODE must not be enabled in production");
+    }
+    return parsed.data;
+}

package/dist/log.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Minimal structured logger. JSON lines in production (machine-parseable by
+ * any log pipeline), human-readable key=value in development. Deliberately
+ * dependency-free: a logging library is not worth a supply-chain edge here.
+ */
+type Level = "debug" | "info" | "warn" | "error";
+export interface Logger {
+    debug(msg: string, fields?: Record<string, unknown>): void;
+    info(msg: string, fields?: Record<string, unknown>): void;
+    warn(msg: string, fields?: Record<string, unknown>): void;
+    error(msg: string, fields?: Record<string, unknown>): void;
+    child(bound: Record<string, unknown>): Logger;
+}
+export declare function createLogger(opts?: {
+    level?: Level;
+    json?: boolean;
+    bound?: Record<string, unknown>;
+}): Logger;
+export {};

package/dist/log.js

@@ -0,0 +1,25 @@
+const LEVELS = { debug: 10, info: 20, warn: 30, error: 40 };
+export function createLogger(opts = {}) {
+    const threshold = LEVELS[opts.level ?? "info"];
+    const emit = (level, msg, fields) => {
+        if (LEVELS[level] < threshold)
+            return;
+        const record = { ts: new Date().toISOString(), level, msg, ...opts.bound, ...fields };
+        if (opts.json) {
+            console.log(JSON.stringify(record));
+        }
+        else {
+            const kv = Object.entries({ ...opts.bound, ...fields })
+                .map(([k, v]) => `${k}=${typeof v === "string" ? v : JSON.stringify(v)}`)
+                .join(" ");
+            console.log(`${record.ts} ${level.toUpperCase().padEnd(5)} ${msg}${kv ? "  " + kv : ""}`);
+        }
+    };
+    return {
+        debug: (m, f) => emit("debug", m, f),
+        info: (m, f) => emit("info", m, f),
+        warn: (m, f) => emit("warn", m, f),
+        error: (m, f) => emit("error", m, f),
+        child: (bound) => createLogger({ ...opts, bound: { ...opts.bound, ...bound } }),
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,176 @@
+import { z } from "zod";
+/** Pricing: MVP supports per-call pricing. Tiered/per-unit models follow the same shape. */
+export declare const PlanSchema: z.ZodObject<{
+    name: z.ZodString;
+    model: z.ZodLiteral<"per_call">;
+    unit_cents: z.ZodNumber;
+    currency: z.ZodDefault<z.ZodString>;
+    scopes: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    model: "per_call";
+    unit_cents: number;
+    currency: string;
+    scopes: string[];
+}, {
+    name: string;
+    model: "per_call";
+    unit_cents: number;
+    scopes: string[];
+    currency?: string | undefined;
+}>;
+export type Plan = z.infer<typeof PlanSchema>;
+/** /.well-known/agent.json — the discovery manifest agents parse. Keep stable: it is a public protocol. */
+export declare const ManifestSchema: z.ZodObject<{
+    tollbase_version: z.ZodLiteral<"1">;
+    service: z.ZodObject<{
+        name: z.ZodString;
+        slug: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        slug: string;
+    }, {
+        name: string;
+        slug: string;
+    }>;
+    auth: z.ZodObject<{
+        register_url: z.ZodString;
+        methods: z.ZodArray<z.ZodEnum<["web_bot_auth", "email_claim"]>, "many">;
+        key_url: z.ZodString;
+        claim_required: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        register_url: string;
+        methods: ("web_bot_auth" | "email_claim")[];
+        key_url: string;
+        claim_required: boolean;
+    }, {
+        register_url: string;
+        methods: ("web_bot_auth" | "email_claim")[];
+        key_url: string;
+        claim_required: boolean;
+    }>;
+    plans: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        model: z.ZodLiteral<"per_call">;
+        unit_cents: z.ZodNumber;
+        currency: z.ZodDefault<z.ZodString>;
+        scopes: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        model: "per_call";
+        unit_cents: number;
+        currency: string;
+        scopes: string[];
+    }, {
+        name: string;
+        model: "per_call";
+        unit_cents: number;
+        scopes: string[];
+        currency?: string | undefined;
+    }>, "many">;
+    docs: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    tollbase_version: "1";
+    service: {
+        name: string;
+        slug: string;
+    };
+    auth: {
+        register_url: string;
+        methods: ("web_bot_auth" | "email_claim")[];
+        key_url: string;
+        claim_required: boolean;
+    };
+    plans: {
+        name: string;
+        model: "per_call";
+        unit_cents: number;
+        currency: string;
+        scopes: string[];
+    }[];
+    docs?: string | undefined;
+}, {
+    tollbase_version: "1";
+    service: {
+        name: string;
+        slug: string;
+    };
+    auth: {
+        register_url: string;
+        methods: ("web_bot_auth" | "email_claim")[];
+        key_url: string;
+        claim_required: boolean;
+    };
+    plans: {
+        name: string;
+        model: "per_call";
+        unit_cents: number;
+        scopes: string[];
+        currency?: string | undefined;
+    }[];
+    docs?: string | undefined;
+}>;
+export type Manifest = z.infer<typeof ManifestSchema>;
+/** Structured HTTP 402 challenge — the machine-readable paywall loop. `reason` enum is the contract. */
+export declare const Err402Reason: z.ZodEnum<["cap_exceeded", "no_plan", "payment_failed", "not_claimed"]>;
+export type Err402ReasonT = z.infer<typeof Err402Reason>;
+export interface Err402Body {
+    error: "payment_required";
+    reason: Err402ReasonT;
+    account_id: string | null;
+    topup_url: string | null;
+    claim_url: string | null;
+    plan_options: Plan[];
+    message: string;
+}
+export declare function err402(reason: Err402ReasonT, opts: {
+    accountId?: string;
+    topupUrl?: string;
+    claimUrl?: string;
+    plans?: Plan[];
+}): Err402Body;
+export declare const RegisterRequestSchema: z.ZodObject<{
+    requested_scopes: z.ZodArray<z.ZodString, "many">;
+    operator_email: z.ZodString;
+    agent_label: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    requested_scopes: string[];
+    operator_email: string;
+    agent_label?: string | undefined;
+}, {
+    requested_scopes: string[];
+    operator_email: string;
+    agent_label?: string | undefined;
+}>;
+export type RegisterRequest = z.infer<typeof RegisterRequestSchema>;
+export declare const UsageEventSchema: z.ZodObject<{
+    idempotency_key: z.ZodString;
+    account_id: z.ZodString;
+    tool: z.ZodString;
+    units: z.ZodNumber;
+    cost_cents: z.ZodNumber;
+    occurred_at: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    idempotency_key: string;
+    account_id: string;
+    tool: string;
+    units: number;
+    cost_cents: number;
+    occurred_at: string;
+}, {
+    idempotency_key: string;
+    account_id: string;
+    tool: string;
+    units: number;
+    cost_cents: number;
+    occurred_at: string;
+}>;
+export type UsageEvent = z.infer<typeof UsageEventSchema>;
+/** JWT claims carried by agent access tokens. Cap is embedded so the vendor enforces locally (P1). */
+export interface AgentTokenClaims {
+    sub: string;
+    svc: string;
+    scope: string;
+    cap: number;
+    [k: string]: unknown;
+}

package/dist/types.js

@@ -0,0 +1,54 @@
+import { z } from "zod";
+/** Pricing: MVP supports per-call pricing. Tiered/per-unit models follow the same shape. */
+export const PlanSchema = z.object({
+    name: z.string(),
+    model: z.literal("per_call"),
+    unit_cents: z.number().int().positive(),
+    currency: z.string().default("usd"),
+    scopes: z.array(z.string()).min(1),
+});
+/** /.well-known/agent.json — the discovery manifest agents parse. Keep stable: it is a public protocol. */
+export const ManifestSchema = z.object({
+    tollbase_version: z.literal("1"),
+    service: z.object({ name: z.string(), slug: z.string() }),
+    auth: z.object({
+        register_url: z.string().url(),
+        methods: z.array(z.enum(["web_bot_auth", "email_claim"])),
+        key_url: z.string().url(),
+        claim_required: z.boolean(),
+    }),
+    plans: z.array(PlanSchema),
+    docs: z.string().url().optional(),
+});
+/** Structured HTTP 402 challenge — the machine-readable paywall loop. `reason` enum is the contract. */
+export const Err402Reason = z.enum(["cap_exceeded", "no_plan", "payment_failed", "not_claimed"]);
+export function err402(reason, opts) {
+    const messages = {
+        cap_exceeded: "Spend cap reached. Request a top-up to continue.",
+        no_plan: "No plan selected for this account. Register first.",
+        payment_failed: "Payment method failed. Ask your operator to update it.",
+        not_claimed: "Account pending operator approval. Poll status or ask your operator to claim.",
+    };
+    return {
+        error: "payment_required",
+        reason,
+        account_id: opts.accountId ?? null,
+        topup_url: opts.topupUrl ?? null,
+        claim_url: opts.claimUrl ?? null,
+        plan_options: opts.plans ?? [],
+        message: messages[reason],
+    };
+}
+export const RegisterRequestSchema = z.object({
+    requested_scopes: z.array(z.string()).min(1),
+    operator_email: z.string().email(),
+    agent_label: z.string().max(120).optional(),
+});
+export const UsageEventSchema = z.object({
+    idempotency_key: z.string().min(8),
+    account_id: z.string(),
+    tool: z.string(),
+    units: z.number().positive(),
+    cost_cents: z.number().int().nonnegative(),
+    occurred_at: z.string(),
+});

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@tollbase/core",
+  "version": "0.3.0",
+  "description": "Tollbase shared protocol types (manifest, 402 challenge) plus config and logging utilities.",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    "./types": {
+      "source": "./src/types.ts",
+      "types": "./dist/types.d.ts",
+      "default": "./dist/types.js"
+    },
+    "./config": {
+      "source": "./src/config.ts",
+      "types": "./dist/config.d.ts",
+      "default": "./dist/config.js"
+    },
+    "./log": {
+      "source": "./src/log.ts",
+      "types": "./dist/log.d.ts",
+      "default": "./dist/log.js"
+    }
+  },
+  "dependencies": {
+    "zod": "^3.23.8"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tollbase/tollbase.git"
+  },
+  "homepage": "https://tollbase.dev",
+  "keywords": [
+    "ai-agents",
+    "agents",
+    "billing",
+    "metering",
+    "mcp",
+    "payments",
+    "402",
+    "usage-based"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build"
+  }
+}