@paybond/kit 0.9.7 → 0.9.8

package/dist/index.d.ts

@@ -4,6 +4,10 @@
  */
 import { type BuildSignedCreateIntentParams, type SettlementRail } from "./principal-intent.js";
 import { type SignPayeeEvidenceParams } from "./payee-evidence.js";
+export type SpendScope = {
+    scope_type: string;
+    scope_key: string;
+};
 export type VerifyCapabilityResult = {
     allow: boolean;
     auditId: string;
@@ -11,6 +15,28 @@ export type VerifyCapabilityResult = {
     intentId: string;
     code?: string;
     message?: string;
+    decisionId?: string;
+    approvalRequestId?: string;
+    policyVersion?: number;
+    reasonCodes?: string[];
+    spendScope?: SpendScope;
+    remainingCents?: number;
+    retryAfter?: number;
+    /** True when gateway policy requires operator approval before execution may proceed. */
+    approvalRequired?: boolean;
+};
+export type PaybondSpendAuthorizationInput = {
+    operation: string;
+    requestedSpendCents?: number;
+    vendorId?: string;
+    taskId?: string;
+    workflowId?: string;
+    toolCallId?: string;
+    toolName?: string;
+    currency?: string;
+    agentSubject?: string;
+    approvalToken?: string;
+    idempotencyKey?: string;
 };
 export type SubmitEvidenceResult = {
     intentId: string;
@@ -715,14 +741,19 @@ export declare class PaybondCapabilityBinding {
     authorizeSpend(input: PaybondSpendAuthorizationInput): Promise<VerifyCapabilityResult>;
 }
 export type PaybondSpendGuardInit = {
-    harbor: Pick<HarborClient | GatewayHarborClient, "tenantId" | "verifyCapability">;
+    harbor: Pick<HarborClient | GatewayHarborClient, "tenantId" | "verifyCapability"> & {
+        completeSpendDecision?: (input: {
+            decisionId: string;
+            outcome: "consumed" | "released";
+        }) => Promise<void>;
+    };
     intentId: string;
     capabilityToken: string;
 };
-export type PaybondSpendAuthorizationInput = {
-    operation: string;
-    requestedSpendCents?: number;
-};
+export declare class PaybondSpendApprovalRequiredError extends Error {
+    readonly result: VerifyCapabilityResult;
+    constructor(result: VerifyCapabilityResult);
+}
 export declare class PaybondSpendDeniedError extends Error {
     readonly result: VerifyCapabilityResult;
     constructor(result: VerifyCapabilityResult);
@@ -730,13 +761,15 @@ export declare class PaybondSpendDeniedError extends Error {
 export type PaybondToolHandler<TArgs extends unknown[], TResult> = (...args: TArgs) => TResult | Promise<TResult>;
 export type PaybondGuardedToolHandler<TArgs extends unknown[], TResult> = (...args: TArgs) => Promise<Awaited<TResult>>;
 export declare class PaybondSpendGuard {
-    readonly harbor: Pick<HarborClient | GatewayHarborClient, "tenantId" | "verifyCapability">;
+    readonly harbor: PaybondSpendGuardInit["harbor"];
     readonly intentId: string;
     readonly capabilityToken: string;
     constructor(init: PaybondSpendGuardInit | PaybondCapabilityBinding);
     verifySpendCapability(input: PaybondSpendAuthorizationInput): Promise<VerifyCapabilityResult>;
     authorizeSpend(input: PaybondSpendAuthorizationInput): Promise<VerifyCapabilityResult>;
     assertSpendAuthorized(input: PaybondSpendAuthorizationInput): Promise<VerifyCapabilityResult>;
+    /** Finalizes scope reservations tied to an authorization decision after tool execution. */
+    completeSpendAuthorization(decisionId: string, outcome: "consumed" | "released"): Promise<void>;
     guardTool<TArgs extends unknown[], TResult>(input: PaybondSpendAuthorizationInput, handler: PaybondToolHandler<TArgs, TResult>): PaybondGuardedToolHandler<TArgs, TResult>;
 }
 export declare function authorizeSpend(source: PaybondSpendGuardInit | PaybondCapabilityBinding, input: PaybondSpendAuthorizationInput): Promise<VerifyCapabilityResult>;
@@ -799,11 +832,9 @@ export declare class HarborClient {
      * @throws HarborHttpError when HTTP fails
      * @throws Error when Harbor echoes a different tenant / intent than requested
      */
-    verifyCapability(input: {
+    verifyCapability(input: PaybondSpendAuthorizationInput & {
         intentId: string;
         token: string;
-        operation: string;
-        requestedSpendCents?: number;
     }): Promise<VerifyCapabilityResult>;
     verifySpendCapability(input: {
         intentId: string;
@@ -897,11 +928,9 @@ export declare class GatewayHarborClient {
     private fetchWithRetries;
     private postJSON;
     private mutationHeaders;
-    verifyCapability(input: {
+    verifyCapability(input: PaybondSpendAuthorizationInput & {
         intentId: string;
         token: string;
-        operation: string;
-        requestedSpendCents?: number;
     }): Promise<VerifyCapabilityResult>;
     verifySpendCapability(input: {
         intentId: string;
@@ -915,6 +944,11 @@ export declare class GatewayHarborClient {
         operation: string;
         requestedSpendCents?: number;
     }): Promise<VerifyCapabilityResult>;
+    /** Finalizes active spend reservations after tool execution completes or is aborted. */
+    completeSpendDecision(input: {
+        decisionId: string;
+        outcome: "consumed" | "released";
+    }): Promise<void>;
     createIntent(body: Record<string, unknown>, options: GatewayHarborMutationOptions): Promise<Record<string, unknown>>;
     fundIntent(intentId: string, options: GatewayHarborMutationOptions & {
         paymentSignature?: string;

package/dist/index.js

@@ -4,6 +4,77 @@
  */
 import { buildSignedCreateIntentBody, } from "./principal-intent.js";
 import { signPayeeEvidenceBinding } from "./payee-evidence.js";
+function parseVerifyCapabilityBody(body, expectedTenant, expectedIntentId) {
+    const tenant = String(body.tenant ?? "");
+    const intentId = String(body.intent_id ?? "");
+    if (tenant !== expectedTenant) {
+        throw new Error(`verify tenant mismatch: client=${expectedTenant} remote=${tenant}`);
+    }
+    if (intentId !== expectedIntentId) {
+        throw new Error(`verify intent mismatch: requested=${expectedIntentId} remote=${intentId}`);
+    }
+    const reasonCodes = Array.isArray(body.reason_codes)
+        ? body.reason_codes.map((value) => String(value))
+        : undefined;
+    const spendScope = body.spend_scope && typeof body.spend_scope === "object" && !Array.isArray(body.spend_scope)
+        ? {
+            scope_type: String(body.spend_scope.scope_type ?? ""),
+            scope_key: String(body.spend_scope.scope_key ?? ""),
+        }
+        : undefined;
+    const code = body.code != null ? String(body.code) : undefined;
+    const approvalRequired = code === "approval_required" ||
+        reasonCodes?.includes("approval_threshold_exceeded") ||
+        reasonCodes?.includes("approval_required_pending") ||
+        reasonCodes?.includes("anomaly_new_vendor") ||
+        reasonCodes?.includes("anomaly_amount_spike") ||
+        reasonCodes?.includes("anomaly_rapid_auth") ||
+        reasonCodes?.includes("anomaly_cap_proximity") ||
+        false;
+    return {
+        allow: Boolean(body.allow),
+        auditId: String(body.audit_id ?? ""),
+        tenant,
+        intentId,
+        code,
+        message: body.message != null ? String(body.message) : undefined,
+        decisionId: body.decision_id != null ? String(body.decision_id) : undefined,
+        approvalRequestId: body.approval_request_id != null ? String(body.approval_request_id) : undefined,
+        policyVersion: typeof body.policy_version === "number" ? body.policy_version : undefined,
+        reasonCodes,
+        spendScope,
+        remainingCents: typeof body.remaining_cents === "number" ? body.remaining_cents : undefined,
+        retryAfter: typeof body.retry_after === "number" ? body.retry_after : undefined,
+        approvalRequired,
+    };
+}
+function verifyCapabilityPayload(input) {
+    const payload = {
+        intent_id: input.intentId,
+        token: input.token,
+        operation: input.operation,
+        requested_spend_cents: input.requestedSpendCents ?? 0,
+    };
+    if (input.vendorId?.trim())
+        payload.vendor_id = input.vendorId.trim();
+    if (input.taskId?.trim())
+        payload.task_id = input.taskId.trim();
+    if (input.workflowId?.trim())
+        payload.workflow_id = input.workflowId.trim();
+    if (input.toolCallId?.trim())
+        payload.tool_call_id = input.toolCallId.trim();
+    if (input.toolName?.trim())
+        payload.tool_name = input.toolName.trim();
+    if (input.currency?.trim())
+        payload.currency = input.currency.trim();
+    if (input.agentSubject?.trim())
+        payload.agent_subject = input.agentSubject.trim();
+    if (input.approvalToken?.trim())
+        payload.approval_token = input.approvalToken.trim();
+    if (input.idempotencyKey?.trim())
+        payload.idempotency_key = input.idempotencyKey.trim();
+    return payload;
+}
 export const DEFAULT_PAYBOND_GATEWAY_BASE_URL = "https://api.paybond.ai";
 function defaultGatewayBaseUrl(value) {
     const trimmed = value?.trim();
@@ -158,16 +229,24 @@ export class PaybondCapabilityBinding {
     }
     async verifySpendCapability(input) {
         return this.harbor.verifyCapability({
+            ...input,
             intentId: this.intentId,
             token: this.capabilityToken,
-            operation: input.operation,
-            requestedSpendCents: input.requestedSpendCents,
         });
     }
     async authorizeSpend(input) {
         return this.verifySpendCapability(input);
     }
 }
+export class PaybondSpendApprovalRequiredError extends Error {
+    result;
+    constructor(result) {
+        const reason = result.message ?? result.code ?? "approval_required";
+        super(`Paybond spend authorization requires approval: ${reason}`);
+        this.name = "PaybondSpendApprovalRequiredError";
+        this.result = result;
+    }
+}
 export class PaybondSpendDeniedError extends Error {
     result;
     constructor(result) {
@@ -188,10 +267,9 @@ export class PaybondSpendGuard {
     }
     async verifySpendCapability(input) {
         return this.harbor.verifyCapability({
+            ...input,
             intentId: this.intentId,
             token: this.capabilityToken,
-            operation: input.operation,
-            requestedSpendCents: input.requestedSpendCents,
         });
     }
     async authorizeSpend(input) {
@@ -200,14 +278,42 @@ export class PaybondSpendGuard {
     async assertSpendAuthorized(input) {
         const result = await this.authorizeSpend(input);
         if (!result.allow) {
+            if (result.approvalRequired) {
+                throw new PaybondSpendApprovalRequiredError(result);
+            }
             throw new PaybondSpendDeniedError(result);
         }
         return result;
     }
+    /** Finalizes scope reservations tied to an authorization decision after tool execution. */
+    async completeSpendAuthorization(decisionId, outcome) {
+        const complete = this.harbor.completeSpendDecision;
+        if (!complete) {
+            return;
+        }
+        await complete.call(this.harbor, { decisionId, outcome });
+    }
     guardTool(input, handler) {
         return async (...args) => {
-            await this.assertSpendAuthorized(input);
-            return await handler(...args);
+            const auth = await this.assertSpendAuthorized(input);
+            try {
+                const result = await handler(...args);
+                if (auth.decisionId) {
+                    await this.completeSpendAuthorization(auth.decisionId, "consumed");
+                }
+                return result;
+            }
+            catch (err) {
+                if (auth.decisionId) {
+                    try {
+                        await this.completeSpendAuthorization(auth.decisionId, "released");
+                    }
+                    catch {
+                        // Best-effort release when the guarded handler fails.
+                    }
+                }
+                throw err;
+            }
         };
     }
 }
@@ -245,6 +351,9 @@ export function paybondRuntimeToolCallAdapter(init) {
             if (init.onDeny) {
                 return await init.onDeny(result, call);
             }
+            if (result.approvalRequired) {
+                throw new PaybondSpendApprovalRequiredError(result);
+            }
             throw new PaybondSpendDeniedError(result);
         }
         return await init.execute(call);
@@ -384,17 +493,13 @@ export class HarborClient {
      */
     async verifyCapability(input) {
         const url = `${this.base}verify`;
-        const payload = {
-            intent_id: input.intentId,
-            token: input.token,
-            operation: input.operation,
-            requested_spend_cents: input.requestedSpendCents ?? 0,
-        };
+        const payload = verifyCapabilityPayload(input);
         const res = await this.fetchWithRetries(url, {
             method: "POST",
             headers: {
                 "content-type": "application/json",
                 "x-tenant-id": this.tenantId,
+                ...(input.idempotencyKey?.trim() ? { "idempotency-key": input.idempotencyKey.trim() } : {}),
             },
             body: JSON.stringify(payload),
         }, { retryBody: payload });
@@ -407,20 +512,7 @@ export class HarborClient {
             });
         }
         const body = JSON.parse(text);
-        if (body.tenant !== this.tenantId) {
-            throw new Error(`verify tenant mismatch: client=${this.tenantId} harbor=${body.tenant}`);
-        }
-        if (body.intent_id !== input.intentId) {
-            throw new Error(`verify intent mismatch: requested=${input.intentId} harbor=${body.intent_id}`);
-        }
-        return {
-            allow: body.allow,
-            auditId: body.audit_id,
-            tenant: body.tenant,
-            intentId: body.intent_id,
-            code: body.code,
-            message: body.message,
-        };
+        return parseVerifyCapabilityBody(body, this.tenantId, input.intentId);
     }
     async verifySpendCapability(input) {
         return this.verifyCapability(input);
@@ -722,13 +814,12 @@ export class GatewayHarborClient {
         });
     }
     async verifyCapability(input) {
-        const payload = {
-            intent_id: input.intentId,
-            token: input.token,
-            operation: input.operation,
-            requested_spend_cents: input.requestedSpendCents ?? 0,
-        };
-        const { res, text, url } = await this.postJSON("/verify", payload);
+        const payload = verifyCapabilityPayload(input);
+        const headers = {};
+        if (input.idempotencyKey?.trim()) {
+            headers["idempotency-key"] = input.idempotencyKey.trim();
+        }
+        const { res, text, url } = await this.postJSON("/verify", payload, headers);
         if (!res.ok) {
             throw new HarborHttpError(`Gateway verify HTTP ${res.status}: ${text}`, {
                 statusCode: res.status,
@@ -737,20 +828,7 @@ export class GatewayHarborClient {
             });
         }
         const body = JSON.parse(text);
-        if (body.tenant !== this.tenantId) {
-            throw new Error(`verify tenant mismatch: client=${this.tenantId} gateway=${body.tenant}`);
-        }
-        if (body.intent_id !== input.intentId) {
-            throw new Error(`verify intent mismatch: requested=${input.intentId} gateway=${body.intent_id}`);
-        }
-        return {
-            allow: body.allow,
-            auditId: body.audit_id,
-            tenant: body.tenant,
-            intentId: body.intent_id,
-            code: body.code,
-            message: body.message,
-        };
+        return parseVerifyCapabilityBody(body, this.tenantId, input.intentId);
     }
     async verifySpendCapability(input) {
         return this.verifyCapability(input);
@@ -758,6 +836,17 @@ export class GatewayHarborClient {
     async authorizeSpend(input) {
         return this.verifyCapability(input);
     }
+    /** Finalizes active spend reservations after tool execution completes or is aborted. */
+    async completeSpendDecision(input) {
+        const { res, text, url } = await this.postJSON(`/v1/spend/decisions/${encodeURIComponent(input.decisionId)}/complete`, { outcome: input.outcome });
+        if (!res.ok) {
+            throw new HarborHttpError(`Gateway spend complete HTTP ${res.status}: ${text}`, {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+            });
+        }
+    }
     async createIntent(body, options) {
         const { res, text, url } = await this.postJSON("/harbor/intents", body, this.mutationHeaders("createIntent", options));
         if (!res.ok) {

package/dist/mcp-server.js

@@ -3,7 +3,7 @@
 import { readFileSync } from "node:fs";
 import { GatewayAuthError, GatewayFraudClient, GatewaySignalClient, SignalHttpError, DEFAULT_PAYBOND_GATEWAY_BASE_URL, } from "./index.js";
 const SERVER_NAME = "Paybond MCP";
-const SERVER_VERSION = "0.9.7";
+const SERVER_VERSION = "0.9.8";
 const MCP_PROTOCOL_VERSION = "2025-11-25";
 const DEFAULT_PRINCIPAL_PATH = "/v1/auth/principal";
 const DEFAULT_RECOGNITION_VERIFIER_ID = "paybond-gateway";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paybond/kit",
-  "version": "0.9.7",
+  "version": "0.9.8",
   "mcpName": "io.github.nonameuserd/paybond",
   "description": "Paybond Kit for TypeScript: agent spend governance for paid tool calls with spend authorization, evidence receipts, refunds, disputes, hosted Gateway sessions, and settlement.",
   "license": "Apache-2.0",