@paybond/kit 0.3.0 → 0.4.0

package/dist/index.js

@@ -47,6 +47,60 @@ export class SignalHttpError extends Error {
         this.bodyText = init.bodyText;
     }
 }
+const agentRecognitionProofHeader = "x-paybond-agent-recognition-proof";
+export class A2AHttpError extends Error {
+    statusCode;
+    url;
+    bodyText;
+    constructor(message, init) {
+        super(message);
+        this.name = "A2AHttpError";
+        this.statusCode = init.statusCode;
+        this.url = init.url;
+        this.bodyText = init.bodyText;
+    }
+}
+export class ProtocolHttpError extends Error {
+    statusCode;
+    url;
+    bodyText;
+    errorCode;
+    errorMessage;
+    constructor(message, init) {
+        super(message);
+        this.name = "ProtocolHttpError";
+        this.statusCode = init.statusCode;
+        this.url = init.url;
+        this.bodyText = init.bodyText;
+        const parsed = parseGatewayErrorEnvelope(init.bodyText);
+        this.errorCode = init.errorCode ?? parsed.errorCode;
+        this.errorMessage = init.errorMessage ?? parsed.errorMessage;
+    }
+}
+function parseGatewayErrorEnvelope(text) {
+    if (!text.trim().startsWith("{")) {
+        return {};
+    }
+    try {
+        const body = JSON.parse(text);
+        if (body === null || Array.isArray(body) || typeof body !== "object") {
+            return {};
+        }
+        const errorCode = typeof body.error === "string" && body.error.trim() ? body.error.trim() : undefined;
+        const errorMessage = typeof body.message === "string" && body.message.trim() ? body.message.trim() : undefined;
+        return { errorCode, errorMessage };
+    }
+    catch {
+        return {};
+    }
+}
+function protocolHTTPErrorMessage(prefix, statusCode, bodyText) {
+    const parsed = parseGatewayErrorEnvelope(bodyText);
+    if (parsed.errorCode) {
+        return `${prefix} HTTP ${statusCode} (${parsed.errorCode}): ${parsed.errorMessage ?? bodyText}`;
+    }
+    return `${prefix} HTTP ${statusCode}: ${bodyText}`;
+}
 function normalizeBase(url) {
     return url.trim().replace(/\/+$/, "");
 }
@@ -770,6 +824,21 @@ export class GatewaySignalClient {
         this.assertTenant(body, url);
         return body;
     }
+    async getSignedPortfolioArtifact(scoreVersion) {
+        const url = `${this.base}signal/v1/portfolio/signed-export${this.scoreQuery(scoreVersion)}`;
+        const res = await this.fetchGetWithRetries(url);
+        const text = await res.text();
+        if (!res.ok) {
+            throw new SignalHttpError(`Signal signed portfolio artifact HTTP ${res.status}: ${text}`, {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+            });
+        }
+        const body = assertJSONObject(JSON.parse(text));
+        this.assertTenant(body, url);
+        return body;
+    }
     async getOperatorExplanation(operatorDid, scoreVersion) {
         const enc = encodeURIComponent(operatorDid);
         const url = `${this.base}signal/v1/operators/${enc}/explanation${this.scoreQuery(scoreVersion)}`;
@@ -815,6 +884,273 @@ export class GatewaySignalClient {
         return body;
     }
 }
+/**
+ * Public or optionally authenticated reader for the gateway's A2A discovery surface.
+ */
+export class GatewayA2AClient {
+    base;
+    bearerToken;
+    maxRetries;
+    constructor(gatewayBaseUrl, options) {
+        this.base = normalizeBase(gatewayBaseUrl) + "/";
+        this.bearerToken = options?.staticGatewayBearerToken?.trim() || undefined;
+        this.maxRetries = Math.max(1, options?.maxRetries ?? 3);
+    }
+    async fetchGetWithRetries(url) {
+        let lastErr;
+        for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+            let res;
+            try {
+                const headers = new Headers({
+                    accept: "application/json",
+                });
+                if (this.bearerToken) {
+                    headers.set("authorization", `Bearer ${this.bearerToken}`);
+                }
+                res = await fetch(url, {
+                    method: "GET",
+                    headers,
+                });
+            }
+            catch (e) {
+                lastErr = e;
+                if (attempt + 1 >= this.maxRetries)
+                    throw e;
+                await new Promise((r) => setTimeout(r, backoffMs(attempt)));
+                continue;
+            }
+            if ([429, 500, 502, 503, 504].includes(res.status)) {
+                if (attempt + 1 >= this.maxRetries) {
+                    return res;
+                }
+                const raSec = parseRetryAfterSeconds(res.headers.get("retry-after"));
+                const delayMs = raSec != null ? raSec * 1000 : backoffMs(attempt);
+                await new Promise((r) => setTimeout(r, delayMs));
+                continue;
+            }
+            return res;
+        }
+        throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
+    }
+    async getAgentCard() {
+        const url = `${this.base}.well-known/agent-card.json`;
+        const res = await this.fetchGetWithRetries(url);
+        const text = await res.text();
+        if (!res.ok) {
+            throw new A2AHttpError(`A2A agent card HTTP ${res.status}: ${text}`, {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+            });
+        }
+        return assertJSONObject(JSON.parse(text));
+    }
+    async getTaskContracts() {
+        const url = `${this.base}protocol/v2/a2a/task-contracts`;
+        const res = await this.fetchGetWithRetries(url);
+        const text = await res.text();
+        if (!res.ok) {
+            throw new A2AHttpError(`A2A task contracts HTTP ${res.status}: ${text}`, {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+            });
+        }
+        return assertJSONObject(JSON.parse(text));
+    }
+    async getTaskContract(contractId) {
+        const enc = encodeURIComponent(contractId);
+        const url = `${this.base}protocol/v2/a2a/task-contracts/${enc}`;
+        const res = await this.fetchGetWithRetries(url);
+        const text = await res.text();
+        if (!res.ok) {
+            throw new A2AHttpError(`A2A task contract HTTP ${res.status}: ${text}`, {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+            });
+        }
+        return assertJSONObject(JSON.parse(text));
+    }
+}
+export class GatewayProtocolClient {
+    tenantId;
+    base;
+    staticGatewayBearerToken;
+    maxRetries;
+    constructor(gatewayBaseUrl, tenantId, init) {
+        this.base = `${normalizeBase(gatewayBaseUrl)}/`;
+        this.tenantId = tenantId.trim();
+        this.staticGatewayBearerToken = init?.staticGatewayBearerToken?.trim() || null;
+        this.maxRetries = Math.max(1, init?.maxRetries ?? 3);
+    }
+    async fetchWithRetries(url, init) {
+        let lastErr;
+        for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+            let res;
+            try {
+                res = await fetch(url, init);
+            }
+            catch (e) {
+                lastErr = e;
+                if (attempt + 1 >= this.maxRetries) {
+                    throw e;
+                }
+                await new Promise((r) => setTimeout(r, backoffMs(attempt)));
+                continue;
+            }
+            if ([429, 500, 502, 503, 504].includes(res.status) && attempt + 1 < this.maxRetries) {
+                const raSec = parseRetryAfterSeconds(res.headers.get("retry-after"));
+                const delayMs = raSec != null ? raSec * 1000 : backoffMs(attempt);
+                await new Promise((r) => setTimeout(r, delayMs));
+                continue;
+            }
+            return res;
+        }
+        throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
+    }
+    headers(extra) {
+        const headers = new Headers(extra);
+        headers.set("accept", "application/json");
+        headers.set("x-tenant-id", this.tenantId);
+        if (this.staticGatewayBearerToken) {
+            headers.set("authorization", `Bearer ${this.staticGatewayBearerToken}`);
+        }
+        return headers;
+    }
+    async postJSON(path, payload, extraHeaders) {
+        const url = `${this.base}${path.replace(/^\/+/, "")}`;
+        const res = await this.fetchWithRetries(url, {
+            method: "POST",
+            headers: this.headers({
+                "content-type": "application/json",
+                ...(extraHeaders ?? {}),
+            }),
+            body: JSON.stringify(payload),
+        });
+        const text = await res.text();
+        if (!res.ok) {
+            const parsed = parseGatewayErrorEnvelope(text);
+            throw new ProtocolHttpError(protocolHTTPErrorMessage(`gateway POST ${path}`, res.status, text), {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+                errorCode: parsed.errorCode,
+                errorMessage: parsed.errorMessage,
+            });
+        }
+        return assertJSONObject(JSON.parse(text));
+    }
+    async importAgentMandateV1(init) {
+        const url = `${this.base}protocol/v2/mandates`;
+        const res = await this.fetchWithRetries(url, {
+            method: "POST",
+            headers: this.headers({ "content-type": "application/json" }),
+            body: JSON.stringify({
+                signed_mandate: init.signedMandate,
+                intent_id: init.intentId,
+                transport_binding: init.transportBinding ?? {},
+                recognition_proof: init.recognitionProof,
+            }),
+        });
+        const text = await res.text();
+        if (!res.ok) {
+            const parsed = parseGatewayErrorEnvelope(text);
+            throw new ProtocolHttpError(protocolHTTPErrorMessage("protocol mandate import", res.status, text), {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+                errorCode: parsed.errorCode,
+                errorMessage: parsed.errorMessage,
+            });
+        }
+        const body = assertJSONObject(JSON.parse(text));
+        if (String(body.intent_id ?? "").trim() !== init.intentId) {
+            throw new Error(`protocol intent mismatch: requested=${init.intentId} gateway=${String(body.intent_id ?? "")}`);
+        }
+        if (String(body.mandate?.authorization?.tenant_id ?? "").trim() !== this.tenantId) {
+            throw new Error(`protocol mandate tenant mismatch: client=${this.tenantId} gateway=${String(body.mandate?.authorization?.tenant_id ?? "")}`);
+        }
+        return body;
+    }
+    async getSettlementReceiptV1(receiptId) {
+        const enc = encodeURIComponent(receiptId);
+        const url = `${this.base}protocol/v2/receipts/${enc}`;
+        const res = await this.fetchWithRetries(url, {
+            method: "GET",
+            headers: this.headers(),
+        });
+        const text = await res.text();
+        if (!res.ok) {
+            const parsed = parseGatewayErrorEnvelope(text);
+            throw new ProtocolHttpError(protocolHTTPErrorMessage("protocol settlement receipt", res.status, text), {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+                errorCode: parsed.errorCode,
+                errorMessage: parsed.errorMessage,
+            });
+        }
+        const body = assertJSONObject(JSON.parse(text));
+        if (String(body.receipt_id ?? "").trim() !== receiptId) {
+            throw new Error(`protocol receipt mismatch: requested=${receiptId} gateway=${String(body.receipt_id ?? "")}`);
+        }
+        if (String(body.tenant_id ?? "").trim() !== this.tenantId) {
+            throw new Error(`protocol receipt tenant mismatch: client=${this.tenantId} gateway=${String(body.tenant_id ?? "")}`);
+        }
+        return body;
+    }
+    async verifyProtocolReceiptV1(receipt) {
+        const url = `${this.base}protocol/v2/receipts/verify`;
+        const res = await this.fetchWithRetries(url, {
+            method: "POST",
+            headers: this.headers({ "content-type": "application/json" }),
+            body: JSON.stringify(receipt),
+        });
+        const text = await res.text();
+        if (!res.ok) {
+            const parsed = parseGatewayErrorEnvelope(text);
+            throw new ProtocolHttpError(protocolHTTPErrorMessage("protocol receipt verify", res.status, text), {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+                errorCode: parsed.errorCode,
+                errorMessage: parsed.errorMessage,
+            });
+        }
+        return assertJSONObject(JSON.parse(text));
+    }
+    async createHarborIntent(init) {
+        return this.postJSON("/harbor/intents", init.body, gatewayMutationHeaders(init.recognitionProof, {
+            ...(init.idempotencyKey?.trim() ? { "idempotency-key": init.idempotencyKey.trim() } : {}),
+        }));
+    }
+    async fundHarborIntent(init) {
+        return this.postJSON(`/harbor/intents/${encodeURIComponent(init.intentId)}/fund`, {}, gatewayMutationHeaders(init.recognitionProof, {
+            ...(init.paymentSignature?.trim() ? { "payment-signature": init.paymentSignature.trim() } : {}),
+            ...(init.idempotencyKey?.trim() ? { "idempotency-key": init.idempotencyKey.trim() } : {}),
+        }));
+    }
+    async submitHarborEvidence(init) {
+        return this.postJSON(`/harbor/intents/${encodeURIComponent(init.intentId)}/evidence`, init.body, gatewayMutationHeaders(init.recognitionProof, {
+            ...(init.idempotencyKey?.trim() ? { "idempotency-key": init.idempotencyKey.trim() } : {}),
+        }));
+    }
+    async confirmHarborSettlement(init) {
+        return this.postJSON(`/harbor/intents/${encodeURIComponent(init.intentId)}/settlement/confirm`, init.body, gatewayMutationHeaders(init.recognitionProof, {
+            ...(init.idempotencyKey?.trim() ? { "idempotency-key": init.idempotencyKey.trim() } : {}),
+        }));
+    }
+}
+function gatewayMutationHeaders(recognitionProof, headers) {
+    return {
+        ...(headers ?? {}),
+        [agentRecognitionProofHeader]: encodeRecognitionProofHeader(recognitionProof),
+    };
+}
+function encodeRecognitionProofHeader(proof) {
+    return Buffer.from(JSON.stringify(proof), "utf8").toString("base64url");
+}
 async function resolveGatewayTenantId(gatewayBaseUrl, apiKey, principalPath, maxRetries) {
     const base = normalizeBase(gatewayBaseUrl);
     const path = principalPath.startsWith("/") ? principalPath : `/${principalPath}`;
@@ -931,12 +1267,16 @@ export class PaybondIntents {
 export class Paybond {
     harbor;
     signal;
+    a2a;
+    protocol;
     intents;
     session;
-    constructor(session, signal) {
+    constructor(session, signal, a2a, protocol) {
         this.session = session;
         this.harbor = session.harbor;
         this.signal = signal;
+        this.a2a = a2a;
+        this.protocol = protocol;
         this.intents = new PaybondIntents(session.harbor);
     }
     /** Open a tenant-bound session via gateway `harbor-access` exchange. */
@@ -946,7 +1286,15 @@ export class Paybond {
             staticGatewayBearerToken: init.apiKey,
             maxRetries: init.maxRetries ?? 3,
         });
-        return new Paybond(session, signal);
+        const a2a = new GatewayA2AClient(init.gatewayBaseUrl, {
+            staticGatewayBearerToken: init.apiKey,
+            maxRetries: init.maxRetries ?? 3,
+        });
+        const protocol = new GatewayProtocolClient(init.gatewayBaseUrl, session.harbor.tenantId, {
+            staticGatewayBearerToken: init.apiKey,
+            maxRetries: init.maxRetries ?? 3,
+        });
+        return new Paybond(session, signal, a2a, protocol);
     }
     async rotateHarborToken() {
         await this.session.rotateHarborToken();

package/dist/mcp-server.d.ts

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+type JSONRPCID = string | number | null;
+type JSONRPCRequest = {
+    jsonrpc?: unknown;
+    id?: JSONRPCID;
+    method?: unknown;
+    params?: unknown;
+};
+type JSONRPCResponse = {
+    jsonrpc: "2.0";
+    id: JSONRPCID;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+    };
+};
+type MCPCallToolResult = {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+};
+export type PaybondMCPSettings = {
+    gatewayBaseUrl: string;
+    apiKey: string;
+    harborBaseUrl?: string;
+    harborAccessPath?: string;
+    principalPath?: string;
+    maxRetries?: number;
+    clockSkewSeconds?: number;
+};
+export declare class PaybondMCPServer {
+    private readonly runtime;
+    private readonly tools;
+    private initialized;
+    constructor(settings: PaybondMCPSettings);
+    listTools(): Array<Record<string, unknown>>;
+    callTool(name: string, args?: Record<string, unknown>): Promise<MCPCallToolResult>;
+    handleMessage(message: JSONRPCRequest): Promise<JSONRPCResponse | null>;
+    runStdio(): void;
+    private handleLine;
+    private writeResponse;
+    private buildTools;
+}
+export declare function settingsFromEnv(env?: Record<string, string | undefined>): PaybondMCPSettings;
+export declare function main(argv?: string[]): number;
+export {};