@paybond/kit 0.3.0 → 0.5.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(/\/+$/, "");
 }
@@ -605,6 +659,16 @@ export class HarborClient {
 }
 const DEFAULT_PRINCIPAL_PATH = "/v1/auth/principal";
 const SETTLEMENT_RAIL_VALUES = new Set(["stripe_connect", "x402_usdc_base"]);
+const FRAUD_REVIEW_EVENT_TYPES = new Set([
+    "review_open_requested",
+    "appeal_requested",
+    "replay_requested",
+    "review_outcome_recorded",
+    "confirmed_risk",
+    "false_positive",
+    "needs_more_evidence",
+]);
+const FRAUD_REVIEW_OUTCOMES = new Set(["confirmed_risk", "false_positive", "needs_more_evidence"]);
 function assertJSONObject(value) {
     if (value === null || typeof value !== "object" || Array.isArray(value)) {
         throw new Error("expected JSON object");
@@ -770,6 +834,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 +894,553 @@ export class GatewaySignalClient {
         return body;
     }
 }
+/**
+ * Tenant-bound client for gateway fraud review and metrics routes.
+ */
+export class GatewayFraudClient {
+    base;
+    tenantId;
+    bearerToken;
+    maxRetries;
+    constructor(gatewayBaseUrl, tenantId, options) {
+        this.base = normalizeBase(gatewayBaseUrl) + "/";
+        this.tenantId = tenantId.trim();
+        this.bearerToken = options.staticGatewayBearerToken.trim();
+        this.maxRetries = Math.max(1, options.maxRetries ?? 3);
+    }
+    async fetchGetWithRetries(url) {
+        let lastErr;
+        for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+            let res;
+            try {
+                res = await fetch(url, {
+                    method: "GET",
+                    headers: {
+                        accept: "application/json",
+                        authorization: `Bearer ${this.bearerToken}`,
+                    },
+                });
+            }
+            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 fetchPostJSON(url, payload) {
+        return fetch(url, {
+            method: "POST",
+            headers: {
+                accept: "application/json",
+                authorization: `Bearer ${this.bearerToken}`,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify(payload),
+        });
+    }
+    async fetchPutJSON(url, payload) {
+        return fetch(url, {
+            method: "PUT",
+            headers: {
+                accept: "application/json",
+                authorization: `Bearer ${this.bearerToken}`,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify(payload),
+        });
+    }
+    assertTenant(body, url) {
+        const tid = String(body.tenant_id ?? "");
+        if (tid !== this.tenantId) {
+            throw new Error(`fraud tenant mismatch: client=${this.tenantId} gateway=${tid} url=${url}`);
+        }
+    }
+    assertOperator(body, operatorDid, label) {
+        const echoedOperator = String(body.operator_did ?? "");
+        if (echoedOperator !== operatorDid) {
+            throw new Error(`fraud ${label} operator mismatch: requested=${operatorDid} gateway=${echoedOperator}`);
+        }
+    }
+    query(params) {
+        const qs = new URLSearchParams();
+        for (const [key, value] of Object.entries(params)) {
+            if (typeof value === "number") {
+                qs.set(key, String(value));
+                continue;
+            }
+            if (typeof value === "string" && value.trim()) {
+                qs.set(key, value.trim());
+            }
+        }
+        const raw = qs.toString();
+        return raw ? `?${raw}` : "";
+    }
+    normalizedSeverity(severity) {
+        const normalized = severity?.trim();
+        if (!normalized) {
+            return undefined;
+        }
+        if (!["elevated", "high", "critical"].includes(normalized)) {
+            throw new Error("fraud severity must be one of elevated, high, or critical");
+        }
+        return normalized;
+    }
+    normalizedWindow(window) {
+        const normalized = window?.trim();
+        if (!normalized) {
+            return undefined;
+        }
+        if (!["24h", "7d", "30d"].includes(normalized)) {
+            throw new Error("fraud metrics window must be one of 24h, 7d, or 30d");
+        }
+        return normalized;
+    }
+    normalizedReleaseGateMode(mode) {
+        const normalized = mode.trim();
+        if (!["review_only", "critical_hold"].includes(normalized)) {
+            throw new Error("fraud release gate mode must be one of review_only or critical_hold");
+        }
+        return normalized;
+    }
+    normalizedReviewEventType(eventType) {
+        const normalized = eventType.trim();
+        if (!FRAUD_REVIEW_EVENT_TYPES.has(normalized)) {
+            throw new Error("fraud review eventType must be one of review_open_requested, appeal_requested, replay_requested, review_outcome_recorded, confirmed_risk, false_positive, or needs_more_evidence");
+        }
+        return normalized;
+    }
+    normalizedReviewOutcome(outcome) {
+        const normalized = outcome.trim();
+        if (!FRAUD_REVIEW_OUTCOMES.has(normalized)) {
+            throw new Error("fraud review outcome must be one of confirmed_risk, false_positive, or needs_more_evidence");
+        }
+        return normalized;
+    }
+    optionalReviewContext(value) {
+        const normalized = value?.trim();
+        return normalized || undefined;
+    }
+    async getFraudAssessment(operatorDid, scoreVersion) {
+        const enc = encodeURIComponent(operatorDid);
+        const url = `${this.base}signal/v1/operators/${enc}/review-status${this.query({
+            score_version: scoreVersion,
+        })}`;
+        const res = await this.fetchGetWithRetries(url);
+        const text = await res.text();
+        if (res.status === 404) {
+            return null;
+        }
+        if (!res.ok) {
+            throw new SignalHttpError(`Fraud assessment HTTP ${res.status}: ${text}`, {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+            });
+        }
+        const body = assertJSONObject(JSON.parse(text));
+        this.assertTenant(body, url);
+        this.assertOperator(body, operatorDid, "assessment");
+        return body;
+    }
+    async listFraudReviewQueue(options = {}) {
+        let rawLimit;
+        if (options.limit !== undefined) {
+            if (!Number.isFinite(options.limit)) {
+                throw new Error("fraud review queue limit must be a finite number");
+            }
+            rawLimit = Math.max(1, Math.min(Math.floor(options.limit), 500));
+        }
+        const url = `${this.base}signal/v1/review-queue${this.query({
+            state: options.state,
+            fraud_severity: this.normalizedSeverity(options.severity),
+            limit: rawLimit,
+            score_version: options.scoreVersion,
+        })}`;
+        const res = await this.fetchGetWithRetries(url);
+        const text = await res.text();
+        if (!res.ok) {
+            throw new SignalHttpError(`Fraud review queue HTTP ${res.status}: ${text}`, {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+            });
+        }
+        const body = assertJSONObject(JSON.parse(text));
+        this.assertTenant(body, url);
+        return body;
+    }
+    async getFraudMetrics(options = {}) {
+        const url = `${this.base}signal/v1/fraud/metrics${this.query({
+            window: this.normalizedWindow(options.window),
+            score_version: options.scoreVersion,
+        })}`;
+        const res = await this.fetchGetWithRetries(url);
+        const text = await res.text();
+        if (!res.ok) {
+            throw new SignalHttpError(`Fraud metrics HTTP ${res.status}: ${text}`, {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+            });
+        }
+        const body = assertJSONObject(JSON.parse(text));
+        this.assertTenant(body, url);
+        return body;
+    }
+    async getFraudReleaseGateConfig(scoreVersion) {
+        const url = `${this.base}signal/v1/fraud/release-gate${this.query({
+            score_version: scoreVersion,
+        })}`;
+        const res = await this.fetchGetWithRetries(url);
+        const text = await res.text();
+        if (!res.ok) {
+            throw new SignalHttpError(`Fraud release gate HTTP ${res.status}: ${text}`, {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+            });
+        }
+        const body = assertJSONObject(JSON.parse(text));
+        this.assertTenant(body, url);
+        return body;
+    }
+    async setFraudReleaseGateMode(mode) {
+        const normalized = this.normalizedReleaseGateMode(mode);
+        const url = `${this.base}signal/v1/fraud/release-gate`;
+        const res = await this.fetchPutJSON(url, { mode: normalized });
+        const text = await res.text();
+        if (!res.ok) {
+            throw new SignalHttpError(`Fraud release gate update HTTP ${res.status}: ${text}`, {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+            });
+        }
+        const body = assertJSONObject(JSON.parse(text));
+        this.assertTenant(body, url);
+        return body;
+    }
+    async recordFraudReviewEvent(operatorDid, event, scoreVersion) {
+        let eventType = this.normalizedReviewEventType(event.eventType);
+        let reviewOutcome = event.reviewOutcome ?? event.review_outcome;
+        if (FRAUD_REVIEW_OUTCOMES.has(eventType)) {
+            reviewOutcome = eventType;
+            eventType = "review_outcome_recorded";
+        }
+        const normalizedOutcome = reviewOutcome === undefined ? undefined : this.normalizedReviewOutcome(reviewOutcome);
+        if (eventType === "review_outcome_recorded" && normalizedOutcome === undefined) {
+            throw new Error("fraud review outcome must be one of confirmed_risk, false_positive, or needs_more_evidence");
+        }
+        const signalCode = this.optionalReviewContext(event.signalCode ?? event.signal_code);
+        const intentId = this.optionalReviewContext(event.intentId ?? event.intent_id);
+        const providerEventId = this.optionalReviewContext(event.providerEventId ?? event.provider_event_id);
+        const enc = encodeURIComponent(operatorDid);
+        const url = `${this.base}signal/v1/operators/${enc}/review-events${this.query({
+            score_version: scoreVersion,
+        })}`;
+        const res = await this.fetchPostJSON(url, {
+            event_type: eventType,
+            ...(normalizedOutcome ? { review_outcome: normalizedOutcome } : {}),
+            ...(signalCode ? { signal_code: signalCode } : {}),
+            ...(intentId ? { intent_id: intentId } : {}),
+            ...(providerEventId ? { provider_event_id: providerEventId } : {}),
+            summary: event.summary,
+        });
+        const text = await res.text();
+        if (!res.ok && res.status !== 429) {
+            throw new SignalHttpError(`Fraud review event HTTP ${res.status}: ${text}`, {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+            });
+        }
+        const body = assertJSONObject(JSON.parse(text));
+        this.assertTenant(body, url);
+        this.assertOperator(body, operatorDid, "review event");
+        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}`;
@@ -882,6 +1508,25 @@ export class ServiceAccountSignalSession {
         await Promise.resolve();
     }
 }
+/**
+ * Tenant-bound fraud review and metrics session for one service-account API key.
+ */
+export class ServiceAccountFraudSession {
+    fraud;
+    constructor(fraud) {
+        this.fraud = fraud;
+    }
+    static async open(init) {
+        const tenantId = await resolveGatewayTenantId(init.gatewayBaseUrl, init.apiKey, init.principalPath ?? DEFAULT_PRINCIPAL_PATH, Math.max(1, init.maxRetries ?? 3));
+        return new ServiceAccountFraudSession(new GatewayFraudClient(init.gatewayBaseUrl, tenantId, {
+            staticGatewayBearerToken: init.apiKey,
+            maxRetries: init.maxRetries ?? 3,
+        }));
+    }
+    async aclose() {
+        await Promise.resolve();
+    }
+}
 /**
  * Ergonomic intent helpers: principal-signed intent create, x402 funding, and payee-signed evidence.
  */
@@ -931,12 +1576,18 @@ export class PaybondIntents {
 export class Paybond {
     harbor;
     signal;
+    fraud;
+    a2a;
+    protocol;
     intents;
     session;
-    constructor(session, signal) {
+    constructor(session, signal, fraud, a2a, protocol) {
         this.session = session;
         this.harbor = session.harbor;
         this.signal = signal;
+        this.fraud = fraud;
+        this.a2a = a2a;
+        this.protocol = protocol;
         this.intents = new PaybondIntents(session.harbor);
     }
     /** Open a tenant-bound session via gateway `harbor-access` exchange. */
@@ -946,7 +1597,19 @@ export class Paybond {
             staticGatewayBearerToken: init.apiKey,
             maxRetries: init.maxRetries ?? 3,
         });
-        return new Paybond(session, signal);
+        const fraud = new GatewayFraudClient(init.gatewayBaseUrl, session.harbor.tenantId, {
+            staticGatewayBearerToken: init.apiKey,
+            maxRetries: init.maxRetries ?? 3,
+        });
+        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, fraud, a2a, protocol);
     }
     async rotateHarborToken() {
         await this.session.rotateHarborToken();