@reinconsole/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,502 @@
+import { Vendor, Asset, Chain, TaskContext, Agent, Policy, Decision, PaymentIntent, Receipt } from '@reinconsole/core';
+export { Decision, PaymentIntent, Receipt, ReceiptSettlement, TaskContext } from '@reinconsole/core';
+import { z } from 'zod';
+
+/**
+ * x402 wire shapes (spec v1), mock-first: these schemas are what Rein's mock
+ * facilitator and tests speak today, and they track the published x402 spec so
+ * real vendors parse identically when the live integration lands.
+ */
+/** One way to pay, as offered inside a 402 response body. */
+declare const PaymentRequirement: z.ZodObject<{
+    scheme: z.ZodString;
+    network: z.ZodString;
+    /** Amount in the asset's atomic units (e.g. "10000" = 0.01 USDC at 6 decimals). */
+    maxAmountRequired: z.ZodString;
+    resource: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    mimeType: z.ZodOptional<z.ZodString>;
+    payTo: z.ZodString;
+    maxTimeoutSeconds: z.ZodOptional<z.ZodNumber>;
+    /** Token contract address — or, mock-first, a plain symbol like "USDC". */
+    asset: z.ZodString;
+    extra: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    scheme: string;
+    network: string;
+    maxAmountRequired: string;
+    payTo: string;
+    asset: string;
+    resource?: string | undefined;
+    description?: string | undefined;
+    mimeType?: string | undefined;
+    maxTimeoutSeconds?: number | undefined;
+    extra?: Record<string, unknown> | undefined;
+}, {
+    scheme: string;
+    network: string;
+    maxAmountRequired: string;
+    payTo: string;
+    asset: string;
+    resource?: string | undefined;
+    description?: string | undefined;
+    mimeType?: string | undefined;
+    maxTimeoutSeconds?: number | undefined;
+    extra?: Record<string, unknown> | undefined;
+}>;
+type PaymentRequirement = z.infer<typeof PaymentRequirement>;
+/** The full 402 body a paywalled vendor returns. */
+declare const PaymentRequired: z.ZodObject<{
+    x402Version: z.ZodNumber;
+    accepts: z.ZodArray<z.ZodObject<{
+        scheme: z.ZodString;
+        network: z.ZodString;
+        /** Amount in the asset's atomic units (e.g. "10000" = 0.01 USDC at 6 decimals). */
+        maxAmountRequired: z.ZodString;
+        resource: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        mimeType: z.ZodOptional<z.ZodString>;
+        payTo: z.ZodString;
+        maxTimeoutSeconds: z.ZodOptional<z.ZodNumber>;
+        /** Token contract address — or, mock-first, a plain symbol like "USDC". */
+        asset: z.ZodString;
+        extra: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        scheme: string;
+        network: string;
+        maxAmountRequired: string;
+        payTo: string;
+        asset: string;
+        resource?: string | undefined;
+        description?: string | undefined;
+        mimeType?: string | undefined;
+        maxTimeoutSeconds?: number | undefined;
+        extra?: Record<string, unknown> | undefined;
+    }, {
+        scheme: string;
+        network: string;
+        maxAmountRequired: string;
+        payTo: string;
+        asset: string;
+        resource?: string | undefined;
+        description?: string | undefined;
+        mimeType?: string | undefined;
+        maxTimeoutSeconds?: number | undefined;
+        extra?: Record<string, unknown> | undefined;
+    }>, "many">;
+    error: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    x402Version: number;
+    accepts: {
+        scheme: string;
+        network: string;
+        maxAmountRequired: string;
+        payTo: string;
+        asset: string;
+        resource?: string | undefined;
+        description?: string | undefined;
+        mimeType?: string | undefined;
+        maxTimeoutSeconds?: number | undefined;
+        extra?: Record<string, unknown> | undefined;
+    }[];
+    error?: string | undefined;
+}, {
+    x402Version: number;
+    accepts: {
+        scheme: string;
+        network: string;
+        maxAmountRequired: string;
+        payTo: string;
+        asset: string;
+        resource?: string | undefined;
+        description?: string | undefined;
+        mimeType?: string | undefined;
+        maxTimeoutSeconds?: number | undefined;
+        extra?: Record<string, unknown> | undefined;
+    }[];
+    error?: string | undefined;
+}>;
+type PaymentRequired = z.infer<typeof PaymentRequired>;
+declare function networkToChain(network: string): Chain | undefined;
+/**
+ * Resolve a requirement's asset to a symbol Rein knows. Tries, in order: the
+ * asset field as a literal symbol (mock-first), `extra.symbol`, then known
+ * contract addresses (exact case for Solana, lowercased for EVM), then any
+ * caller-supplied address map.
+ */
+declare function resolveAsset(requirement: PaymentRequirement, extraAddresses?: Record<string, Asset>): Asset | undefined;
+/**
+ * Convert an atomic-unit amount to a normalized decimal string without floats,
+ * e.g. ("10000", 6) -> "0.01". Stablecoins Rein supports all use 6 decimals;
+ * a requirement can override via `extra.decimals`.
+ */
+declare function atomicToDecimal(atomic: string, decimals: number): string;
+/**
+ * The inverse of {@link atomicToDecimal}: a human-unit decimal string to atomic
+ * units without floats, e.g. ("0.05", 6) -> "50000". Throws if the value has
+ * more fraction digits than the asset carries (sub-atomic precision is a
+ * pricing bug, not something to round silently).
+ */
+declare function decimalToAtomic(decimal: string, decimals: number): string;
+declare function requirementDecimals(requirement: PaymentRequirement): number;
+/** A requirement the guard fully understood, mapped into Rein's domain. */
+interface ResolvedRequirement {
+    requirement: PaymentRequirement;
+    chain: Chain;
+    asset: Asset;
+    /** Human-unit decimal amount, e.g. "0.01". */
+    amount: string;
+}
+/**
+ * Pick the first offer the guard can govern: scheme `exact`, a network that
+ * maps to a supported chain, and a resolvable asset. Returns undefined when
+ * no offer qualifies — callers must treat that as fail-closed.
+ */
+declare function selectRequirement(accepts: readonly PaymentRequirement[], extraAddresses?: Record<string, Asset>): ResolvedRequirement | undefined;
+/** What the guard submits to the policy engine (the `/v1/evaluate` shape). */
+interface IntentSubmission {
+    agentId: string;
+    vendor: Vendor;
+    resource: string;
+    amount: string;
+    asset: Asset;
+    chain: Chain;
+    taskContext?: TaskContext;
+}
+/** Build the evaluate payload for a resolved offer on a given request URL. */
+declare function toIntentSubmission(resolved: ResolvedRequirement, url: string, agentId: string, taskContext: TaskContext | undefined): IntentSubmission;
+
+/** Any fetch-compatible function (global fetch, undici, or a test double). */
+type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+declare const Health: z.ZodObject<{
+    status: z.ZodString;
+    publicKey: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    status: string;
+    publicKey: string;
+}, {
+    status: string;
+    publicKey: string;
+}>;
+declare const EvaluateResponse: z.ZodObject<{
+    intent: z.ZodObject<{
+        id: z.ZodString;
+        agentId: z.ZodString;
+        vendor: z.ZodObject<{
+            host: z.ZodString;
+            address: z.ZodString;
+            erc8004Id: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            address: string;
+            host: string;
+            erc8004Id?: string | undefined;
+        }, {
+            address: string;
+            host: string;
+            erc8004Id?: string | undefined;
+        }>;
+        resource: z.ZodString;
+        amount: z.ZodString;
+        asset: z.ZodEnum<["USDC", "USDT", "EURC"]>;
+        chain: z.ZodEnum<["base", "solana", "polygon", "bnb"]>;
+        taskContext: z.ZodDefault<z.ZodObject<{
+            taskId: z.ZodOptional<z.ZodString>;
+            parentRunId: z.ZodOptional<z.ZodString>;
+            purpose: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            taskId?: string | undefined;
+            parentRunId?: string | undefined;
+            purpose?: string | undefined;
+        }, {
+            taskId?: string | undefined;
+            parentRunId?: string | undefined;
+            purpose?: string | undefined;
+        }>>;
+        nonce: z.ZodString;
+        createdAt: z.ZodDate;
+    }, "strip", z.ZodTypeAny, {
+        chain: "base" | "solana" | "polygon" | "bnb";
+        id: string;
+        createdAt: Date;
+        agentId: string;
+        vendor: {
+            address: string;
+            host: string;
+            erc8004Id?: string | undefined;
+        };
+        resource: string;
+        amount: string;
+        asset: "USDC" | "USDT" | "EURC";
+        taskContext: {
+            taskId?: string | undefined;
+            parentRunId?: string | undefined;
+            purpose?: string | undefined;
+        };
+        nonce: string;
+    }, {
+        chain: "base" | "solana" | "polygon" | "bnb";
+        id: string;
+        createdAt: Date;
+        agentId: string;
+        vendor: {
+            address: string;
+            host: string;
+            erc8004Id?: string | undefined;
+        };
+        resource: string;
+        amount: string;
+        asset: "USDC" | "USDT" | "EURC";
+        nonce: string;
+        taskContext?: {
+            taskId?: string | undefined;
+            parentRunId?: string | undefined;
+            purpose?: string | undefined;
+        } | undefined;
+    }>;
+    decision: z.ZodObject<{
+        id: z.ZodString;
+        intentId: z.ZodString;
+        intentHash: z.ZodString;
+        outcome: z.ZodEnum<["allow", "deny", "escalate"]>;
+        matchedRules: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        reason: z.ZodOptional<z.ZodString>;
+        policyId: z.ZodString;
+        policyVersion: z.ZodString;
+        prevHash: z.ZodString;
+        hash: z.ZodString;
+        signature: z.ZodString;
+        latencyMs: z.ZodNumber;
+        decidedAt: z.ZodDate;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        intentId: string;
+        intentHash: string;
+        outcome: "allow" | "deny" | "escalate";
+        matchedRules: string[];
+        policyId: string;
+        policyVersion: string;
+        prevHash: string;
+        hash: string;
+        signature: string;
+        latencyMs: number;
+        decidedAt: Date;
+        reason?: string | undefined;
+    }, {
+        id: string;
+        intentId: string;
+        intentHash: string;
+        outcome: "allow" | "deny" | "escalate";
+        policyId: string;
+        policyVersion: string;
+        prevHash: string;
+        hash: string;
+        signature: string;
+        latencyMs: number;
+        decidedAt: Date;
+        matchedRules?: string[] | undefined;
+        reason?: string | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    intent: {
+        chain: "base" | "solana" | "polygon" | "bnb";
+        id: string;
+        createdAt: Date;
+        agentId: string;
+        vendor: {
+            address: string;
+            host: string;
+            erc8004Id?: string | undefined;
+        };
+        resource: string;
+        amount: string;
+        asset: "USDC" | "USDT" | "EURC";
+        taskContext: {
+            taskId?: string | undefined;
+            parentRunId?: string | undefined;
+            purpose?: string | undefined;
+        };
+        nonce: string;
+    };
+    decision: {
+        id: string;
+        intentId: string;
+        intentHash: string;
+        outcome: "allow" | "deny" | "escalate";
+        matchedRules: string[];
+        policyId: string;
+        policyVersion: string;
+        prevHash: string;
+        hash: string;
+        signature: string;
+        latencyMs: number;
+        decidedAt: Date;
+        reason?: string | undefined;
+    };
+}, {
+    intent: {
+        chain: "base" | "solana" | "polygon" | "bnb";
+        id: string;
+        createdAt: Date;
+        agentId: string;
+        vendor: {
+            address: string;
+            host: string;
+            erc8004Id?: string | undefined;
+        };
+        resource: string;
+        amount: string;
+        asset: "USDC" | "USDT" | "EURC";
+        nonce: string;
+        taskContext?: {
+            taskId?: string | undefined;
+            parentRunId?: string | undefined;
+            purpose?: string | undefined;
+        } | undefined;
+    };
+    decision: {
+        id: string;
+        intentId: string;
+        intentHash: string;
+        outcome: "allow" | "deny" | "escalate";
+        policyId: string;
+        policyVersion: string;
+        prevHash: string;
+        hash: string;
+        signature: string;
+        latencyMs: number;
+        decidedAt: Date;
+        matchedRules?: string[] | undefined;
+        reason?: string | undefined;
+    };
+}>;
+type EvaluateResponse = z.infer<typeof EvaluateResponse>;
+interface EngineClientOptions {
+    /** Base URL of the policy engine, e.g. "http://localhost:8787". */
+    baseUrl: string;
+    /** Override the transport (tests, custom agents). Defaults to global fetch. */
+    fetch?: FetchLike;
+}
+/**
+ * Thin typed client for the policy-engine HTTP API. Every response is parsed
+ * through the @reinconsole/core schemas, so wire drift fails loudly at the boundary.
+ */
+declare class EngineClient {
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(options: EngineClientOptions);
+    private request;
+    health(): Promise<z.infer<typeof Health>>;
+    registerAgent(input: {
+        orgId: string;
+        name: string;
+        erc8004Id?: string;
+        wallets?: Agent['wallets'];
+    }): Promise<Agent>;
+    listAgents(): Promise<Agent[]>;
+    freeze(agentId: string): Promise<void>;
+    unfreeze(agentId: string): Promise<void>;
+    addPolicy(policy: z.input<typeof Policy>): Promise<Policy>;
+    listPolicies(): Promise<Policy[]>;
+    /** The hot path: submit an intent, get the normalized intent + signed decision. */
+    evaluate(submission: IntentSubmission): Promise<EvaluateResponse>;
+    decisions(): Promise<Decision[]>;
+}
+
+/**
+ * Builds the `X-PAYMENT` header for an allowed intent. Mock payers and the
+ * local EIP-3009 payer ignore the decision; the session-key signer tier
+ * requires it — the {intent, decision} pair is the engine-signed voucher the
+ * signer verifies before any key is put to work.
+ */
+type Payer = (requirement: PaymentRequirement, intent: PaymentIntent, decision: Decision) => string | Promise<string>;
+interface GuardOptions {
+    /** Policy engine base URL, e.g. "http://localhost:8787". */
+    engineUrl: string;
+    /** The agent this guard speaks for (must be registered with the engine). */
+    agentId: string;
+    /** Base fetch the guard wraps by default (vendor-facing). Defaults to global fetch. */
+    fetch?: FetchLike;
+    /** Transport for talking to the policy engine. Defaults to global fetch. */
+    engineFetch?: FetchLike;
+    /** Task context attached to every intent unless overridden via withTask(). */
+    taskContext?: TaskContext;
+    /**
+     * What a blocked payment looks like to the caller: 'throw' (default) raises
+     * PaymentBlockedError; 'respond' returns a synthetic 402 JSON response, for
+     * agent loops that prefer inspecting responses over catching.
+     */
+    onBlocked?: 'throw' | 'respond';
+    /** If set, the guard settles allowed payments itself (pay + retry). */
+    payer?: Payer;
+    /** Extra token-address -> symbol mappings for asset resolution. */
+    assetAddresses?: Record<string, Asset>;
+    /** Called once per receipt, as it is recorded. */
+    onReceipt?: (receipt: Receipt) => void;
+}
+/**
+ * The Rein guard: wrap an agent's fetch once, and every x402 paywall it hits
+ * is policy-checked before any payment exists, with a receipt either way.
+ *
+ * Layering: the guard wraps the BASE fetch, underneath any x402 payment
+ * library. The first (unpaid) request surfaces the 402; the guard evaluates
+ * it and either blocks — so the payment layer never sees the paywall — or
+ * releases the 402 upward. The payment layer's `X-PAYMENT` retry then flows
+ * back through the guard, which attaches the settlement to the receipt.
+ * Alternatively, pass a `payer` and the guard completes the payment itself.
+ */
+declare class Guard {
+    readonly client: EngineClient;
+    private readonly options;
+    private readonly baseFetch;
+    private readonly task;
+    private readonly log;
+    /** Allowed-but-unsettled receipts awaiting the payment layer's retry, by URL. */
+    private readonly pendingByUrl;
+    constructor(options: GuardOptions);
+    /** Every receipt this guard has recorded, oldest first. */
+    receipts(): readonly Receipt[];
+    /** Run `fn` with a task context attached to every intent submitted inside it. */
+    withTask<T>(context: TaskContext, fn: () => T): T;
+    /**
+     * The one-liner: returns a fetch-compatible function that enforces policy on
+     * every x402 paywall. Wraps the guard's base fetch unless one is passed.
+     */
+    wrap(fetchImpl?: FetchLike): FetchLike;
+    private record;
+    private settlePending;
+}
+/** Convenience factory mirroring the docs: `const guard = createGuard({...})`. */
+declare function createGuard(options: GuardOptions): Guard;
+
+/** Base class for everything the SDK throws, so callers can catch broadly. */
+declare class ReinError extends Error {
+    constructor(message: string);
+}
+/** The policy engine answered with a non-2xx status. */
+declare class EngineError extends ReinError {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, body: unknown, message?: string);
+}
+/**
+ * The engine evaluated the intent and did NOT allow it (deny or escalate —
+ * v0.1 blocks both; escalation approval flows land later). The payment was
+ * never constructed, so no funds moved. Carries the full evidence trail.
+ */
+declare class PaymentBlockedError extends ReinError {
+    readonly intent: PaymentIntent;
+    readonly decision: Decision;
+    readonly receipt: Receipt;
+    constructor(intent: PaymentIntent, decision: Decision, receipt: Receipt);
+}
+/**
+ * The vendor's 402 was x402-shaped but offered no requirement the guard can
+ * govern (unknown scheme/network/asset). The guard fails closed rather than
+ * letting an ungoverned payment through.
+ */
+declare class UnsupportedRequirementError extends ReinError {
+    readonly url: string;
+    constructor(url: string);
+}
+
+export { EngineClient, type EngineClientOptions, EngineError, EvaluateResponse, type FetchLike, Guard, type GuardOptions, type IntentSubmission, type Payer, PaymentBlockedError, PaymentRequired, PaymentRequirement, ReinError, type ResolvedRequirement, UnsupportedRequirementError, atomicToDecimal, createGuard, decimalToAtomic, networkToChain, requirementDecimals, resolveAsset, selectRequirement, toIntentSubmission };