@paybond/kit 0.2.1 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # `@paybond/kit`
 
-Paybond Kit for TypeScript provides a tenant-bound Harbor client, gateway-backed service-account sessions, capability verification, canonical signing helpers for intent creation and evidence submission, tenant-scoped ledger provenance reads, and tenant-scoped Signal analytics and reputation reads.
+Paybond Kit for TypeScript provides a tenant-bound Harbor client, gateway-backed service-account sessions, capability verification, canonical signing helpers for intent creation and evidence submission, x402 / USDC-on-Base intent funding helpers, tenant-scoped ledger provenance reads, and tenant-scoped Signal analytics and reputation reads.
 
 Install the public package with:
 
@@ -56,14 +56,16 @@ try {
 ## What the package includes
 
 - `Paybond.open(...)` for gateway-authenticated, tenant-derived Harbor sessions
-- `HarborClient` for capability verification, intent creation, evidence submission, and ledger reads
+- `HarborClient` for capability verification, intent creation, x402 funding, evidence submission, and ledger reads
 - `GatewaySignalClient` and `ServiceAccountSignalSession` for tenant-scoped Signal reads
 - `paybond.signal` on `Paybond` sessions opened from one service-account API key
-- `PaybondIntents` helpers for principal-signed intent creation and payee-signed evidence submission
+- `PaybondIntents` helpers for principal-signed intent creation, x402 funding, and payee-signed evidence submission
 - Low-level signing helpers exported for advanced callers
 
 `allowedTools` values are your own tool or operation names, not a Paybond-owned catalog. Harbor enforces string matching against whatever names you chose when creating the intent.
 
+`settlementRail` on intent creation is only a rail request. Stripe destinations and x402 receive addresses stay tenant-owned server-side config and are never supplied by the SDK caller.
+
 ## What it does not include
 
 - No operator-tier settlement or console workflows

package/dist/index.d.ts

@@ -2,7 +2,7 @@
  * Paybond Kit — TypeScript Harbor client with tenant binding, retries, optional upstream JWT,
  * and gateway service-account token exchange (`POST /v1/auth/harbor-access`).
  */
-import { type BuildSignedCreateIntentParams } from "./principal-intent.js";
+import { type BuildSignedCreateIntentParams, type SettlementRail } from "./principal-intent.js";
 import { type SignPayeeEvidenceParams } from "./payee-evidence.js";
 export type VerifyCapabilityResult = {
     allow: boolean;
@@ -18,6 +18,44 @@ export type SubmitEvidenceResult = {
     state: string;
     predicatePassed?: boolean;
 };
+export type IntentFundingResult = {
+    settlementRail: SettlementRail;
+    harborFundEndpoint?: string;
+    status?: string;
+    paymentSessionId?: string;
+    paymentUrl?: string;
+    asset?: string;
+    network?: string;
+    authorizationId?: string;
+    captureId?: string;
+    voidId?: string;
+    refundId?: string;
+    sourceAddress?: string;
+    targetAddress?: string;
+    authorizationExpiresAt?: string;
+    captureExpiresAt?: string;
+    refundExpiresAt?: string;
+    onchainTransactionHashes?: {
+        authorizations?: string[];
+        captures?: string[];
+        voids?: string[];
+        refunds?: string[];
+    };
+};
+export type FundIntentResult = {
+    statusCode: 200 | 202 | 402;
+    paymentRequired?: string;
+    paymentResponse?: string;
+    intentId: string;
+    tenant: string;
+    state: string;
+    settlementRail: SettlementRail;
+    currency: string;
+    amountCents: number;
+    funded: boolean;
+    capabilityToken?: string;
+    funding?: IntentFundingResult;
+};
 /** Async supplier for short-lived Harbor JWTs minted by the Paybond gateway. */
 export type HarborBearerSupplier = () => Promise<string | null | undefined>;
 /**
@@ -172,6 +210,21 @@ export declare class HarborClient {
     createIntent(body: Record<string, unknown>, options?: {
         idempotencyKey?: string;
     }): Promise<Record<string, unknown>>;
+    /**
+     * POST `/intents/{intentId}/fund` for x402 / USDC-on-Base funding.
+     *
+     * Harbor returns:
+     * - `402` with `paymentRequired` details when a facilitator or wallet must sign
+     * - `202` while authorization is pending
+     * - `200` once the intent is funded and any capability token is available
+     *
+     * @throws HarborHttpError for non-funding HTTP errors
+     * @throws Error when Harbor echoes a different tenant or intent than requested
+     */
+    fundIntent(intentId: string, options?: {
+        paymentSignature?: string;
+        idempotencyKey?: string;
+    }): Promise<FundIntentResult>;
     /**
      * POST `/intents/{intentId}/evidence` with a signed evidence JSON body.
      *
@@ -240,24 +293,37 @@ export declare class ServiceAccountSignalSession {
     static open(init: ServiceAccountSignalSessionInit): Promise<ServiceAccountSignalSession>;
     aclose(): Promise<void>;
 }
-/** Parameters for {@link PaybondIntents.create} (tenant is taken from the bound Harbor client). */
+/**
+ * Parameters for {@link PaybondIntents.create} (tenant is taken from the bound Harbor client).
+ * `settlementRail`, when set, requests one allowed rail; Harbor still resolves the destination
+ * from tenant-owned settlement config.
+ */
 export type PaybondCreateIntentParams = Omit<BuildSignedCreateIntentParams, "tenantId" | "intentId"> & {
     intentId?: string;
 };
 /** Parameters for {@link PaybondIntents.submitEvidence} (tenant is taken from the bound Harbor client). */
 export type PaybondSubmitEvidenceParams = Omit<SignPayeeEvidenceParams, "tenantId">;
 /**
- * Ergonomic intent helpers: principal-signed intent create and payee-signed evidence.
+ * Ergonomic intent helpers: principal-signed intent create, x402 funding, and payee-signed evidence.
  */
 export declare class PaybondIntents {
     private readonly harbor;
     constructor(harbor: HarborClient);
     /**
-     * Build a principal-signed `POST /intents` body and submit it. `principalSigningSeed` must be 32 bytes.
+     * Build a principal-signed `POST /intents` body and submit it. `principalSigningSeed` must be
+     * 32 bytes. `settlementRail` only requests an allowed rail; destinations stay server-owned.
      */
     create(params: PaybondCreateIntentParams & {
         idempotencyKey?: string;
     }): Promise<Record<string, unknown>>;
+    /**
+     * Advance Harbor `/intents/{id}/fund` for x402 / USDC-on-Base intents.
+     */
+    fund(params: {
+        intentId: string;
+        paymentSignature?: string;
+        idempotencyKey?: string;
+    }): Promise<FundIntentResult>;
     /**
      * Sign payee evidence and POST it. `payeeSigningSeed` must be 32 bytes.
      */
@@ -281,5 +347,5 @@ export declare class Paybond {
     aclose(): Promise<void>;
 }
 export { normalizeJson, jsonValueDigest } from "./json-digest.js";
-export { buildSignedCreateIntentBody, intentCreationSignBytesRaw, type BuildSignedCreateIntentParams, } from "./principal-intent.js";
+export { buildSignedCreateIntentBody, intentCreationSignBytesRaw, type BuildSignedCreateIntentParams, type SettlementRail, } from "./principal-intent.js";
 export { artifactsDigest, signPayeeEvidenceBinding, type SignPayeeEvidenceParams } from "./payee-evidence.js";

package/dist/index.js

@@ -2,7 +2,7 @@
  * Paybond Kit — TypeScript Harbor client with tenant binding, retries, optional upstream JWT,
  * and gateway service-account token exchange (`POST /v1/auth/harbor-access`).
  */
-import { buildSignedCreateIntentBody } from "./principal-intent.js";
+import { buildSignedCreateIntentBody, } from "./principal-intent.js";
 import { signPayeeEvidenceBinding } from "./payee-evidence.js";
 /**
  * Structured HTTP failure from Harbor with operator-facing diagnostics.
@@ -292,7 +292,7 @@ export class HarborClient {
         }
         throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
     }
-    async fetchWithRetries(url, init, { retryBody }) {
+    async fetchWithRetries(url, init, { retryBody, retryBodyText, }) {
         let lastErr;
         for (let attempt = 0; attempt < this.maxRetries; attempt++) {
             let res;
@@ -318,10 +318,18 @@ export class HarborClient {
                 const raSec = parseRetryAfterSeconds(res.headers.get("retry-after"));
                 const delayMs = raSec != null ? raSec * 1000 : backoffMs(attempt);
                 await new Promise((r) => setTimeout(r, delayMs));
-                init = {
-                    ...init,
-                    body: JSON.stringify(retryBody),
-                };
+                if (retryBodyText !== undefined) {
+                    init = {
+                        ...init,
+                        body: retryBodyText,
+                    };
+                }
+                else if (retryBody !== undefined) {
+                    init = {
+                        ...init,
+                        body: JSON.stringify(retryBody),
+                    };
+                }
                 continue;
             }
             return res;
@@ -403,6 +411,79 @@ export class HarborClient {
         }
         return JSON.parse(text);
     }
+    /**
+     * POST `/intents/{intentId}/fund` for x402 / USDC-on-Base funding.
+     *
+     * Harbor returns:
+     * - `402` with `paymentRequired` details when a facilitator or wallet must sign
+     * - `202` while authorization is pending
+     * - `200` once the intent is funded and any capability token is available
+     *
+     * @throws HarborHttpError for non-funding HTTP errors
+     * @throws Error when Harbor echoes a different tenant or intent than requested
+     */
+    async fundIntent(intentId, options) {
+        const url = `${this.base}intents/${intentId}/fund`;
+        const headers = {
+            "x-tenant-id": this.tenantId,
+        };
+        if (options?.idempotencyKey?.trim()) {
+            headers["idempotency-key"] = options.idempotencyKey.trim();
+        }
+        if (options?.paymentSignature?.trim()) {
+            headers["payment-signature"] = options.paymentSignature.trim();
+        }
+        const res = await this.fetchWithRetries(url, {
+            method: "POST",
+            headers,
+            body: "",
+        }, { retryBodyText: "" });
+        const text = await res.text();
+        if (![200, 202, 402].includes(res.status)) {
+            throw new HarborHttpError(`Harbor fund intent HTTP ${res.status}: ${text}`, {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+            });
+        }
+        const body = assertJSONObject(JSON.parse(text));
+        const tenant = String(body.tenant ?? "");
+        if (tenant !== this.tenantId) {
+            throw new Error(`fund tenant mismatch: client=${this.tenantId} harbor=${tenant}`);
+        }
+        const echoedIntentId = String(body.intent_id ?? "");
+        if (echoedIntentId !== intentId) {
+            throw new Error(`fund intent mismatch: requested=${intentId} harbor=${echoedIntentId}`);
+        }
+        if (typeof body.state !== "string" || !body.state.trim()) {
+            throw new Error("fund response missing state");
+        }
+        if (typeof body.currency !== "string" || !body.currency.trim()) {
+            throw new Error("fund response missing currency");
+        }
+        const amountCents = Number(body.amount_cents);
+        if (!Number.isFinite(amountCents)) {
+            throw new Error("fund response missing amount_cents");
+        }
+        return {
+            statusCode: res.status,
+            paymentRequired: res.headers.get("payment-required") ?? undefined,
+            paymentResponse: res.headers.get("payment-response") ?? undefined,
+            intentId: echoedIntentId,
+            tenant,
+            state: body.state,
+            settlementRail: readSettlementRailValue(body.settlement_rail, "fund settlement_rail"),
+            currency: body.currency,
+            amountCents,
+            funded: Boolean(body.funded),
+            capabilityToken: typeof body.capability_token === "string" && body.capability_token.trim()
+                ? body.capability_token
+                : undefined,
+            funding: body.funding === undefined || body.funding === null
+                ? undefined
+                : parseIntentFundingResult(body.funding),
+        };
+    }
     /**
      * POST `/intents/{intentId}/evidence` with a signed evidence JSON body.
      *
@@ -523,12 +604,71 @@ export class HarborClient {
     }
 }
 const DEFAULT_PRINCIPAL_PATH = "/v1/auth/principal";
+const SETTLEMENT_RAIL_VALUES = new Set(["stripe_connect", "x402_usdc_base"]);
 function assertJSONObject(value) {
     if (value === null || typeof value !== "object" || Array.isArray(value)) {
         throw new Error("expected JSON object");
     }
     return value;
 }
+function readSettlementRailValue(value, field) {
+    if (typeof value !== "string" || !SETTLEMENT_RAIL_VALUES.has(value)) {
+        throw new Error(`invalid ${field}`);
+    }
+    return value;
+}
+function readStringArrayValue(value, field) {
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+        throw new Error(`invalid ${field}`);
+    }
+    return [...value];
+}
+function parseIntentFundingResult(value) {
+    const body = assertJSONObject(value);
+    const onchainRaw = body.onchain_transaction_hashes;
+    const onchain = onchainRaw === undefined || onchainRaw === null
+        ? undefined
+        : (() => {
+            const parsed = assertJSONObject(onchainRaw);
+            return {
+                authorizations: parsed.authorizations === undefined
+                    ? undefined
+                    : readStringArrayValue(parsed.authorizations, "funding.onchain_transaction_hashes.authorizations"),
+                captures: parsed.captures === undefined
+                    ? undefined
+                    : readStringArrayValue(parsed.captures, "funding.onchain_transaction_hashes.captures"),
+                voids: parsed.voids === undefined
+                    ? undefined
+                    : readStringArrayValue(parsed.voids, "funding.onchain_transaction_hashes.voids"),
+                refunds: parsed.refunds === undefined
+                    ? undefined
+                    : readStringArrayValue(parsed.refunds, "funding.onchain_transaction_hashes.refunds"),
+            };
+        })();
+    const readOptionalString = (field) => {
+        const raw = body[field];
+        return typeof raw === "string" && raw.trim() ? raw : undefined;
+    };
+    return {
+        settlementRail: readSettlementRailValue(body.settlement_rail, "funding.settlement_rail"),
+        harborFundEndpoint: readOptionalString("harbor_fund_endpoint"),
+        status: readOptionalString("status"),
+        paymentSessionId: readOptionalString("payment_session_id"),
+        paymentUrl: readOptionalString("payment_url"),
+        asset: readOptionalString("asset"),
+        network: readOptionalString("network"),
+        authorizationId: readOptionalString("authorization_id"),
+        captureId: readOptionalString("capture_id"),
+        voidId: readOptionalString("void_id"),
+        refundId: readOptionalString("refund_id"),
+        sourceAddress: readOptionalString("source_address"),
+        targetAddress: readOptionalString("target_address"),
+        authorizationExpiresAt: readOptionalString("authorization_expires_at"),
+        captureExpiresAt: readOptionalString("capture_expires_at"),
+        refundExpiresAt: readOptionalString("refund_expires_at"),
+        onchainTransactionHashes: onchain,
+    };
+}
 /**
  * Tenant-bound reader for gateway Signal routes.
  */
@@ -743,7 +883,7 @@ export class ServiceAccountSignalSession {
     }
 }
 /**
- * Ergonomic intent helpers: principal-signed intent create and payee-signed evidence.
+ * Ergonomic intent helpers: principal-signed intent create, x402 funding, and payee-signed evidence.
  */
 export class PaybondIntents {
     harbor;
@@ -751,7 +891,8 @@ export class PaybondIntents {
         this.harbor = harbor;
     }
     /**
-     * Build a principal-signed `POST /intents` body and submit it. `principalSigningSeed` must be 32 bytes.
+     * Build a principal-signed `POST /intents` body and submit it. `principalSigningSeed` must be
+     * 32 bytes. `settlementRail` only requests an allowed rail; destinations stay server-owned.
      */
     async create(params) {
         const { idempotencyKey, intentId: maybeIntentId, ...fields } = params;
@@ -763,6 +904,15 @@ export class PaybondIntents {
         });
         return this.harbor.createIntent(body, { idempotencyKey });
     }
+    /**
+     * Advance Harbor `/intents/{id}/fund` for x402 / USDC-on-Base intents.
+     */
+    async fund(params) {
+        return this.harbor.fundIntent(params.intentId, {
+            paymentSignature: params.paymentSignature,
+            idempotencyKey: params.idempotencyKey,
+        });
+    }
     /**
      * Sign payee evidence and POST it. `payeeSigningSeed` must be 32 bytes.
      */

package/dist/principal-intent.d.ts

@@ -2,6 +2,8 @@
  * Principal intent creation signing for raw `predicate_dsl` (no managed-policy binding).
  * Matches `crates/harbor-intent-escrow/src/signing.rs` (`intent_creation_sign_bytes_raw`).
  */
+/** Tenant-configured settlement rail names. Clients may request a rail, not a destination. */
+export type SettlementRail = "stripe_connect" | "x402_usdc_base";
 export declare function intentCreationSignBytesRaw(input: {
     tenantId: string;
     intentId: string;
@@ -30,8 +32,11 @@ export type BuildSignedCreateIntentParams = {
     deadlineRfc3339: string;
     allowedTools: string[];
     predicateRef?: string;
+    /** Optional rail request for the new intent. Harbor resolves the destination server-side. */
+    settlementRail?: SettlementRail;
 };
 /**
  * Build a Harbor `POST /intents` JSON body with principal Ed25519 detached signature.
+ * `settlementRail` only requests an allowed rail; destinations remain tenant-owned server-side.
  */
 export declare function buildSignedCreateIntentBody(params: BuildSignedCreateIntentParams): Record<string, unknown>;

package/dist/principal-intent.js

@@ -5,6 +5,13 @@
 import { sign, getPublicKey } from "@noble/ed25519";
 import { parse as parseUuid } from "uuid";
 import { jsonValueDigest } from "./json-digest.js";
+const SETTLEMENT_RAIL_VALUES = new Set(["stripe_connect", "x402_usdc_base"]);
+function validateSettlementRail(value) {
+    if (!SETTLEMENT_RAIL_VALUES.has(value)) {
+        throw new Error(`settlementRail must be one of ${[...SETTLEMENT_RAIL_VALUES].join(", ")}`);
+    }
+    return value;
+}
 function concatBytes(...parts) {
     const n = parts.reduce((a, p) => a + p.length, 0);
     const out = new Uint8Array(n);
@@ -80,6 +87,7 @@ function bytesToBase64(bytes) {
 }
 /**
  * Build a Harbor `POST /intents` JSON body with principal Ed25519 detached signature.
+ * `settlementRail` only requests an allowed rail; destinations remain tenant-owned server-side.
  */
 export function buildSignedCreateIntentBody(params) {
     if (params.principalSigningSeed.length !== 32) {
@@ -88,6 +96,9 @@ export function buildSignedCreateIntentBody(params) {
     if (params.allowedTools.length === 0) {
         throw new Error("allowedTools must be non-empty");
     }
+    const settlementRail = params.settlementRail
+        ? validateSettlementRail(params.settlementRail)
+        : undefined;
     const predicateRef = params.predicateRef ?? "";
     const msg = intentCreationSignBytesRaw({
         tenantId: params.tenantId,
@@ -124,5 +135,8 @@ export function buildSignedCreateIntentBody(params) {
     if (predicateRef.trim() !== "") {
         body.predicate_ref = predicateRef;
     }
+    if (settlementRail) {
+        body.settlement_rail = settlementRail;
+    }
     return body;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paybond/kit",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Paybond Kit for TypeScript: tenant-bound Harbor sessions, capability verification, and signed intent/evidence flows.",
   "license": "Apache-2.0",
   "type": "module",