@belticlabs/agent-risk-sdk 0.6.0 → 0.8.0

package/dist/client-DFZL4Pt3.d.ts

@@ -0,0 +1,298 @@
+import { J as JsonValue, e as CatalogQuery, d as CatalogOutput, N as JsonObject, W as PaymentSummary, o as DeclaredIntent } from './index-CBUSXzgG.js';
+import { A as ApiClient, S as Session, b as SessionOptions, a as Decision } from './session-DTIzd1EQ.js';
+import { z } from 'zod';
+
+/**
+ * One way to pay, as the seller wrote it: the fields a wallet needs are
+ * checked, everything else (`extra`, the scheme's own parts) is kept so the
+ * chosen entry can be echoed back as `accepted`.
+ */
+declare const Requirement: z.ZodObject<{
+    scheme: z.ZodString;
+    network: z.ZodString;
+    asset: z.ZodString;
+    amount: z.ZodString;
+    payTo: z.ZodString;
+    maxTimeoutSeconds: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>;
+type X402Requirement = z.infer<typeof Requirement>;
+/** The whole challenge a quote answers: payment options, the resource, and the request the seller expects (`bazaar` extension). */
+declare const Challenge: z.ZodPipe<z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<unknown, string>>, z.ZodObject<{
+    x402Version: z.ZodLiteral<2>;
+    accepts: z.ZodArray<z.ZodUnknown>;
+    resource: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        url: z.ZodString;
+        description: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    }, z.core.$loose>>>;
+    extensions: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        bazaar: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+            info: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+                input: z.ZodCatch<z.ZodOptional<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>>;
+            }, z.core.$loose>>>;
+            schema: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+                properties: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+                    input: z.ZodCatch<z.ZodOptional<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>>;
+                }, z.core.$loose>>>;
+            }, z.core.$loose>>>;
+        }, z.core.$loose>>>;
+    }, z.core.$loose>>>;
+}, z.core.$loose>>, z.ZodTransform<{
+    resource: {
+        url: string;
+        description: string | undefined;
+    } | null;
+    accepts: {
+        [x: string]: unknown;
+        scheme: string;
+        network: string;
+        asset: string;
+        amount: string;
+        payTo: string;
+        maxTimeoutSeconds?: number | undefined;
+    }[];
+    input: string | number | boolean | JsonValue[] | {
+        [key: string]: JsonValue;
+    } | null;
+    inputSchema: string | number | boolean | JsonValue[] | {
+        [key: string]: JsonValue;
+    } | null;
+}, {
+    [x: string]: unknown;
+    x402Version: 2;
+    accepts: unknown[];
+    resource?: {
+        [x: string]: unknown;
+        url: string;
+        description?: string | undefined;
+    } | undefined;
+    extensions?: {
+        [x: string]: unknown;
+        bazaar?: {
+            [x: string]: unknown;
+            info?: {
+                [x: string]: unknown;
+                input?: JsonValue | undefined;
+            } | undefined;
+            schema?: {
+                [x: string]: unknown;
+                properties?: {
+                    [x: string]: unknown;
+                    input?: JsonValue | undefined;
+                } | undefined;
+            } | undefined;
+        } | undefined;
+    } | undefined;
+}>>;
+type X402Challenge = z.output<typeof Challenge>;
+/** The seller's settlement of a paid request (`PAYMENT-RESPONSE`). */
+declare const Settlement: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<unknown, string>>, z.ZodObject<{
+    success: z.ZodBoolean;
+    transaction: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    network: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    payer: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    errorReason: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    errorMessage: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+}, z.core.$loose>>;
+type X402Settlement = z.output<typeof Settlement>;
+
+/**
+ * x402 artifacts → protocol moments (Fraud SDK RFC › Protocol Adapter —
+ * x402). The moment is normalized (payee, amount, payer) so both sides of
+ * a purchase compare; the artifact travels whole in `raw`. For x402 the
+ * currency is `<network>/<asset>` (GAP-49) and the value is the atomic
+ * amount as the protocol carries it — `beltic.x402.summary` gives a buyer
+ * the same normalization for the payment it is about to evaluate, so what
+ * it asks about and what the fetch records are one and the same.
+ */
+
+/**
+ * The minimum an `accepts` entry needs to become a moment; unknown parts
+ * are named, never dropped.
+ */
+interface AcceptsLike {
+    payTo?: string | undefined;
+    amount?: string | undefined;
+    network?: string | undefined;
+    asset?: string | undefined;
+}
+
+/**
+ * x402 on the buyer half, as `beltic.x402` (Fraud SDK RFC › Protocol
+ * Adapter — x402):
+ *
+ *   catalog  where to buy: the platform's live search of public x402
+ *            catalogs (GAP-90)
+ *   fetch    the paying fetch, observed. It sits *inside* the agent's
+ *            paying fetch, so it sees the 402 → `payment.requested` and the
+ *            retry carrying the payment → `payment.presented`, into which
+ *            it injects the session binding (GAP-30). Before a request that
+ *            presents payment leaves, the session's evidence is flushed: the
+ *            seller evaluates as soon as it sees the payment (GAP-66). It
+ *            never pays and never decides.
+ *   quote    the price of a request before paying it: the same request
+ *            through `fetch` (so the 402 is on record), its challenge read —
+ *            payment options, resource, the request the seller expects
+ *   pay      the same request again, carrying the payment the wallet
+ *            signed for the chosen option, and the settlement it answered.
+ *            Signing is the wallet's: the SDK never holds a key
+ *   summary  an `accepts` entry as the payment `session.decide` takes
+ *   intent   a mandate for x402 spend, its cap in the rail's currency
+ *
+ * Only x402 v2 is read (GAP-72), and nothing here loads `@x402/*`: a buyer
+ * is observed without installing it. The seller half is `attachX402` in
+ * `/x402` and the middleware in `/hono`.
+ */
+
+/** What `catalog` searches for: `q` is required, `limit` defaults to 8 on the platform (1..20). */
+type CatalogSearch = Omit<CatalogQuery, 'limit'> & {
+    limit?: number | undefined;
+};
+/** The request a paid resource is called with; `quote` and the payment send the same one. */
+interface X402Request {
+    /** `GET` without a body, `POST` with one, unless given. */
+    method?: string | undefined;
+    /** Sent as JSON. */
+    body?: JsonValue | undefined;
+}
+interface X402Quote {
+    /** The status the resource answered the unpaid request with. */
+    status: number;
+    /** Its v2 challenge when it answered 402 with one; null when it asked for nothing or in a form this does not read. */
+    challenge: X402Challenge | null;
+}
+/** A payment the wallet signed: the option it accepted, as the challenge listed it, and the scheme's payload. */
+interface X402Signed {
+    accepted: X402Requirement;
+    /** Scheme-specific, e.g. `exact` on EVM: `{ authorization, signature }` (EIP-3009). */
+    payload: JsonObject;
+}
+interface X402Payment {
+    /** The resource's answer to the paid request; its body is unread. */
+    response: Response;
+    /** The seller's `PAYMENT-RESPONSE`, when it sent one. */
+    settlement: X402Settlement | null;
+}
+interface X402IntentInput {
+    mandate: string;
+    network: string;
+    asset: string;
+    /** Atomic units of `asset`, as x402 carries amounts — a decimal string or a bigint, never a float. */
+    maxAmount: string | bigint;
+    validUntil: string | Date;
+    merchantAllowlist?: string[] | undefined;
+}
+declare class X402 {
+    private readonly api;
+    constructor(api: ApiClient);
+    /**
+     * x402-payable APIs matching `q`, grouped by vendor, as the platform finds
+     * them live in public catalogs (GAP-90); with `network`, only what can be
+     * paid there. `sources` says which catalogs answered. Null when the
+     * platform could not be reached (GAP-70); a rejected query throws.
+     */
+    catalog(search: CatalogSearch): Promise<CatalogOutput | null>;
+    /**
+     * A fetch bound to `session` that records what x402 crosses it. A request
+     * made while the session has no stream (the platform could not open one,
+     * GAP-70) goes through unrecorded.
+     */
+    fetch(session: Session): typeof globalThis.fetch;
+    /** The unpaid request, sent as it will be paid, and the challenge it answered. */
+    quote(session: Session, url: string, request?: X402Request): Promise<X402Quote>;
+    /**
+     * The request, sent as it was quoted, carrying `signed` as an x402 v2
+     * `PAYMENT-SIGNATURE` through `fetch` — so the presentation is recorded,
+     * bound to the session and flushed before it leaves (GAP-66). What the
+     * seller settled is read, not recorded (GAP-77).
+     */
+    pay(session: Session, url: string, signed: X402Signed, request?: X402Request): Promise<X402Payment>;
+    /** An `accepts` entry as the payment `session.decide` takes — the normalization the recorded moments use. */
+    summary(accepts: AcceptsLike | undefined, opts?: {
+        payer?: string | undefined;
+    }): PaymentSummary;
+    /**
+     * The declared intent for an x402 mandate (Fraud SDK RFC › Session ›
+     * `intent.declared`). The cap must be in the currency the rail's moments
+     * carry — `<network>/<asset>`, atomic units (GAP-49) — or the platform's
+     * spend detectors compare two currencies and never meet.
+     */
+    intent(input: X402IntentInput): DeclaredIntent;
+    /** The request as `quote` and `pay` send it: `GET` bare, `POST` with a JSON body, unless told otherwise. */
+    private static init;
+    /** An x402 header value: base64 of the JSON. */
+    private static encode;
+}
+
+/**
+ * One SDK, two halves (Fraud SDK RFC › Summary). `Beltic` is the single
+ * client: `session` for the buyer half, `evaluate` for whichever half is
+ * about to let a payment through, and `x402` for what the buyer does on
+ * that rail — find an API (`catalog`, GAP-90), observe the paying fetch
+ * (`fetch`), read a price and pay it (`quote`, `pay`), shape what it asks
+ * about (`summary`, `intent`). Integrations that pull an optional peer are plain functions
+ * behind subpath exports:
+ *
+ *   @belticlabs/agent-risk-sdk/ai    → middleware(session), wrapTools(session, …)
+ *   @belticlabs/agent-risk-sdk/x402  → attachX402(beltic, …)              (seller)
+ *   @belticlabs/agent-risk-sdk/hono  → belticPaymentMiddleware(beltic, …) (seller)
+ *
+ * Neither half decides risk locally: verdicts are platform-side.
+ *
+ * A client is configured or it is not constructed — `Beltic.fromEnv()`
+ * reads `BELTIC_*`, and there is no disabled client (GAP-78). Evidence is
+ * a side channel of the work it observes, so a platform outage never
+ * throws into that work (GAP-70): the transport waits it out, `session`
+ * runs without a stream, `evaluate` answers `Decision.absent()` — never an
+ * invented verdict — and `x402.catalog` answers `null`. What the platform
+ * *rejects* (a 4xx, a forked chain) is the client's fault and throws.
+ */
+
+declare const SDK_VERSION = "0.8.0";
+interface BelticOptions {
+    apiKey: string;
+    baseUrl: string;
+    /** The agent's 32-byte Ed25519 seed as 64 hex — the buyer half. Without it, `session` is unavailable; the seller half works. */
+    agentSeed?: string | undefined;
+}
+declare class Beltic {
+    /** x402 for the buyer: `catalog`, `fetch`, `quote`, `pay`, `summary`, `intent`. */
+    readonly x402: X402;
+    private readonly api;
+    private readonly transport;
+    /** Open handles by conversation id (GAP-84). */
+    private readonly sessions;
+    /**
+     * The client the environment describes: `BELTIC_API_KEY` and
+     * `BELTIC_BASE_URL`, both required, and `BELTIC_AGENT_SEED` (64 hex) for
+     * the buyer half. A missing required variable is a configuration error,
+     * thrown (GAP-78).
+     */
+    static fromEnv(env?: Record<string, string | undefined>): Beltic;
+    constructor(opts: BelticOptions);
+    /**
+     * A conversation: new without an id, resumed with one — the id `session.id()`
+     * answered in this or any earlier process (GAP-84). One handle per
+     * conversation in-process until it closes; the options count when a
+     * session is opened. See `Session`.
+     */
+    session(id?: string, opts?: SessionOptions): Session;
+    /**
+     * The platform's verdict on a payment — the seller's before it verifies,
+     * the buyer's before it presents (Fraud SDK RFC › Evaluation Client).
+     * Read-your-writes: the session's buffered evidence is flushed first so
+     * the platform judges what the caller already saw (GAP-16/88). With a `callId`
+     * the platform answers the decision already taken for that call anywhere
+     * in the conversation (GAP-84). Absent when the platform could not be
+     * reached (GAP-70).
+     */
+    evaluate(sessionId: string, payment: PaymentSummary, opts?: {
+        callId?: string | undefined;
+    }): Promise<Decision>;
+    /** Send everything buffered now — every session's — and wait for that attempt. */
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+    /** `process.env` where there is a `process` (Node); `{}` on workerd, where the shell passes its `env`. */
+    private static processEnv;
+}
+
+export { type AcceptsLike as A, Beltic as B, type CatalogSearch as C, SDK_VERSION as S, X402 as X, type BelticOptions as a, type X402Challenge as b, type X402IntentInput as c, type X402Payment as d, type X402Quote as e, type X402Request as f, type X402Requirement as g, type X402Settlement as h, type X402Signed as i };