@402flow/sdk 0.1.0-alpha.1

package/dist/contracts.js

@@ -0,0 +1,244 @@
+import { z } from 'zod';
+export const receiptAuthorizationOutcomeSchema = z.enum(['allowed']);
+export const settlementEvidenceClassSchema = z.enum([
+    'none',
+    'inconclusive',
+    'merchant_verifiable_success',
+    'settled',
+]);
+export const fulfillmentStatusSchema = z.enum([
+    'succeeded',
+    'failed',
+    'inconclusive',
+]);
+export const paymentProofSourceSchema = z.enum(['merchant', 'local_simulation']);
+export const paidRequestProtocolSchema = z.enum(['x402', 'l402']);
+export const paidRequestHttpMethodSchema = z.enum([
+    'GET',
+    'POST',
+    'PUT',
+    'PATCH',
+    'DELETE',
+    'HEAD',
+    'OPTIONS',
+]);
+export const paidRequestReasonCodeSchema = z.enum([
+    'policy_allow',
+    'policy_denied',
+    'policy_review_required',
+    'payment_execution_in_progress',
+    'preflight_incompatible',
+    'merchant_rejected',
+    'settlement_proof_conflict',
+    'merchant_transport_lost',
+    'payment_rail_missing',
+    'payment_rail_wrong_organization',
+    'payment_rail_disabled',
+    'payment_rail_incompatible',
+]);
+const externalIdPattern = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const decimalAmountPattern = /^\d+(?:\.\d+)?$/;
+const minorUnitAmountPattern = /^\d+$/;
+const currencyCodePattern = /^(?:[A-Z0-9_-]{3,10}|0x[a-fA-F0-9]{40})$/;
+export const defaultMoneyPrecision = 6;
+export const externalIdSchema = z
+    .string()
+    .trim()
+    .min(3)
+    .max(64)
+    .regex(externalIdPattern);
+export const monetaryAmountSchema = z.string().regex(decimalAmountPattern);
+export const currencyCodeSchema = z.string().regex(currencyCodePattern);
+export const moneyUnitSchema = z.literal('minor');
+function formatMonetaryAmount(amount, precision) {
+    if (!decimalAmountPattern.test(amount)) {
+        throw new Error('Invalid monetary amount format.');
+    }
+    const parts = amount.split('.');
+    const wholePart = parts[0] ?? '0';
+    const fractionalPart = parts[1] ?? '';
+    if (fractionalPart.length > precision) {
+        throw new Error('Monetary amount exceeds the declared precision.');
+    }
+    if (precision === 0) {
+        return wholePart;
+    }
+    return `${wholePart}.${fractionalPart.padEnd(precision, '0')}`;
+}
+export function monetaryAmountToMinorUnits(amount, precision) {
+    const normalizedAmount = formatMonetaryAmount(amount, precision);
+    if (precision === 0) {
+        return normalizedAmount;
+    }
+    const parts = normalizedAmount.split('.');
+    const wholePart = parts[0] ?? '0';
+    const fractionalPart = parts[1] ?? '';
+    const minorUnits = `${wholePart}${fractionalPart}`.replace(/^0+(?=\d)/, '');
+    return minorUnits || '0';
+}
+export const normalizedMoneySchema = z
+    .object({
+    asset: currencyCodeSchema,
+    amount: monetaryAmountSchema,
+    amountMinor: z.string().regex(minorUnitAmountPattern),
+    precision: z.number().int().min(0).max(defaultMoneyPrecision),
+    unit: moneyUnitSchema,
+})
+    .superRefine((value, context) => {
+    try {
+        const normalizedAmount = formatMonetaryAmount(value.amount, value.precision);
+        if (normalizedAmount !== value.amount) {
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['amount'],
+                message: 'Money amount must match the declared precision.',
+            });
+        }
+        if (monetaryAmountToMinorUnits(value.amount, value.precision) !==
+            value.amountMinor) {
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['amountMinor'],
+                message: 'Money minor-unit amount must match the declared amount and precision.',
+            });
+        }
+    }
+    catch (error) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['amount'],
+            message: error instanceof Error
+                ? error.message
+                : 'Invalid monetary amount provided.',
+        });
+    }
+});
+export const paidRequestContextSchema = z.object({
+    organization: externalIdSchema,
+    agent: externalIdSchema,
+    purpose: z.string().min(1).max(200).optional(),
+    metadata: z.record(z.unknown()).optional(),
+});
+export const paidRequestTargetSchema = z.object({
+    merchant: externalIdSchema,
+    paymentRail: externalIdSchema,
+});
+export const paidRequestHttpRequestSchema = z.object({
+    url: z.string().url(),
+    method: paidRequestHttpMethodSchema,
+    headers: z.record(z.string()).optional(),
+    body: z.string().optional(),
+    bodyHash: z.string().min(1).max(128).optional(),
+});
+export const paidRequestChallengeSchema = z.object({
+    protocol: paidRequestProtocolSchema,
+    money: normalizedMoneySchema,
+    payee: z.string().min(1).max(255).optional(),
+    memo: z.string().min(1).max(500).optional(),
+    raw: z.record(z.unknown()).default({}),
+});
+export const sdkPaymentDecisionRequestSchema = z.object({
+    context: paidRequestContextSchema,
+    target: paidRequestTargetSchema,
+    request: paidRequestHttpRequestSchema,
+    challenge: paidRequestChallengeSchema,
+    idempotencyKey: z.string().min(1).max(128).optional(),
+});
+export const sdkReceiptSchema = z.object({
+    receiptId: z.string().uuid(),
+    paidRequestId: z.string().uuid(),
+    paymentAttemptId: z.string().uuid(),
+    organizationId: z.string().uuid(),
+    agentId: z.string().uuid(),
+    merchantId: z.string().uuid(),
+    protocol: paidRequestProtocolSchema,
+    money: normalizedMoneySchema,
+    authorizationOutcome: receiptAuthorizationOutcomeSchema,
+    requestUrl: z.string().url(),
+    requestMethod: paidRequestHttpMethodSchema,
+    paymentReference: z.string().min(1).max(128).optional(),
+    evidenceSource: paymentProofSourceSchema.optional(),
+    settlementEvidenceClass: settlementEvidenceClassSchema.optional(),
+    settlementIdentifier: z.string().min(1).max(255).optional(),
+    fulfillmentStatus: fulfillmentStatusSchema.optional(),
+    createdAt: z.string().datetime(),
+    completedAt: z.string().datetime().optional(),
+});
+export const sdkMerchantResponseSchema = z.object({
+    status: z.number().int().min(100).max(599),
+    headers: z.record(z.string()).default({}),
+    body: z.string().default(''),
+});
+export const sdkPaymentDecisionAllowResponseSchema = z.object({
+    outcome: z.literal('allow'),
+    paidRequestId: z.string().uuid(),
+    paymentAttemptId: z.string().uuid(),
+    reasonCode: paidRequestReasonCodeSchema,
+    reason: z.string().min(1),
+    merchantResponse: sdkMerchantResponseSchema,
+    receipt: sdkReceiptSchema,
+});
+export const sdkPaymentDecisionPaidFulfillmentFailedResponseSchema = z.object({
+    outcome: z.literal('paid_fulfillment_failed'),
+    paidRequestId: z.string().uuid(),
+    paymentAttemptId: z.string().uuid(),
+    reasonCode: z.literal('merchant_rejected'),
+    reason: z.string().min(1),
+    merchantResponse: sdkMerchantResponseSchema,
+    settlementEvidenceClass: settlementEvidenceClassSchema,
+    fulfillmentStatus: z.literal('failed'),
+    receipt: sdkReceiptSchema,
+    evidence: z.record(z.unknown()).optional(),
+});
+export const sdkPaymentDecisionExecutionFailedResponseSchema = z.object({
+    outcome: z.literal('execution_failed'),
+    paidRequestId: z.string().uuid(),
+    paymentAttemptId: z.string().uuid(),
+    reasonCode: z.enum(['merchant_rejected', 'settlement_proof_conflict']),
+    reason: z.string().min(1),
+    merchantResponse: sdkMerchantResponseSchema,
+    evidence: z.record(z.unknown()).optional(),
+});
+export const sdkPaymentDecisionPreflightFailedResponseSchema = z.object({
+    outcome: z.literal('preflight_failed'),
+    paidRequestId: z.string().uuid(),
+    paymentAttemptId: z.string().uuid(),
+    reasonCode: z.literal('preflight_incompatible'),
+    reason: z.string().min(1),
+    evidence: z.record(z.unknown()).optional(),
+});
+export const sdkPaymentDecisionExecutingResponseSchema = z.object({
+    outcome: z.literal('executing'),
+    paidRequestId: z.string().uuid(),
+    paymentAttemptId: z.string().uuid(),
+    reasonCode: z.literal('payment_execution_in_progress'),
+    reason: z.string().min(1),
+});
+export const sdkPaymentDecisionInconclusiveResponseSchema = z.object({
+    outcome: z.literal('inconclusive'),
+    paidRequestId: z.string().uuid(),
+    paymentAttemptId: z.string().uuid(),
+    reasonCode: z.literal('merchant_transport_lost'),
+    reason: z.string().min(1),
+    evidence: z.record(z.unknown()).optional(),
+});
+export const sdkPaymentDecisionDenyResponseSchema = z.object({
+    outcome: z.literal('deny'),
+    paidRequestId: z.string().uuid().optional(),
+    reasonCode: paidRequestReasonCodeSchema,
+    reason: z.string().min(1),
+    policyReviewEventId: z.string().uuid().optional(),
+});
+export const sdkPaymentDecisionResponseSchema = z.discriminatedUnion('outcome', [
+    sdkPaymentDecisionAllowResponseSchema,
+    sdkPaymentDecisionPaidFulfillmentFailedResponseSchema,
+    sdkPaymentDecisionExecutingResponseSchema,
+    sdkPaymentDecisionPreflightFailedResponseSchema,
+    sdkPaymentDecisionExecutionFailedResponseSchema,
+    sdkPaymentDecisionInconclusiveResponseSchema,
+    sdkPaymentDecisionDenyResponseSchema,
+]);
+export const sdkReceiptResponseSchema = z.object({
+    receipt: sdkReceiptSchema,
+});
+//# sourceMappingURL=contracts.js.map

package/dist/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,126 @@
+import { type ParsedChallenge } from './challenge-detection.js';
+import { type PaidRequestContext, type PaidRequestTarget, type SdkPaymentDecisionResponse, type SdkReceipt, type SdkReceiptResponse } from './contracts.js';
+export type AgentPayAuth = {
+    type: 'bootstrapKey';
+    bootstrapKey: string;
+} | {
+    type: 'runtimeToken';
+    runtimeToken: string;
+};
+export type AgentPayClientOptions = {
+    controlPlaneBaseUrl: string;
+    auth: AgentPayAuth;
+    fetch?: typeof fetch;
+    headers?: Record<string, string>;
+};
+export type FetchPaidOptions = {
+    target: PaidRequestTarget;
+    challenge?: ParsedChallenge;
+    idempotencyKey?: string;
+};
+type PaidProtocol = ParsedChallenge['protocol'];
+type DenyDecision = Extract<SdkPaymentDecisionResponse, {
+    outcome: 'deny';
+}>;
+type ExecutingDecision = Extract<SdkPaymentDecisionResponse, {
+    outcome: 'executing';
+}>;
+type InconclusiveDecision = Extract<SdkPaymentDecisionResponse, {
+    outcome: 'inconclusive';
+}>;
+type ExecutionFailedDecision = Extract<SdkPaymentDecisionResponse, {
+    outcome: 'execution_failed';
+}>;
+type PreflightFailedDecision = Extract<SdkPaymentDecisionResponse, {
+    outcome: 'preflight_failed';
+}>;
+type PaidFulfillmentFailedDecision = Extract<SdkPaymentDecisionResponse, {
+    outcome: 'paid_fulfillment_failed';
+}>;
+type PaidResponseBase = {
+    protocol: PaidProtocol | 'none';
+    response: Response;
+};
+export type PassthroughPaidResponse = PaidResponseBase & {
+    kind: 'passthrough';
+    protocol: 'none';
+};
+export type SuccessPaidResponse = PaidResponseBase & {
+    kind: 'success';
+    protocol: PaidProtocol;
+    paidRequestId: string;
+    paymentAttemptId: string;
+    receiptId: string;
+    receipt: SdkReceipt;
+};
+export type PaidFulfillmentFailedResponse = PaidResponseBase & {
+    kind: 'paid_fulfillment_failed';
+    protocol: PaidProtocol;
+    paidRequestId: string;
+    paymentAttemptId: string;
+    receiptId: string;
+    receipt: SdkReceipt;
+    reason: string;
+    decision: PaidFulfillmentFailedDecision;
+};
+export type DeniedPaidResponse = PaidResponseBase & {
+    kind: 'denied';
+    protocol: PaidProtocol;
+    paidRequestId?: string;
+    reason: string;
+    decision: DenyDecision;
+    policyReviewEventId?: string;
+};
+export type ExecutionPendingPaidResponse = PaidResponseBase & {
+    kind: 'execution_pending';
+    protocol: PaidProtocol;
+    paidRequestId: string;
+    paymentAttemptId: string;
+    reason: string;
+    decision: ExecutingDecision;
+};
+export type ExecutionInconclusivePaidResponse = PaidResponseBase & {
+    kind: 'execution_inconclusive';
+    protocol: PaidProtocol;
+    paidRequestId: string;
+    paymentAttemptId: string;
+    reason: string;
+    decision: InconclusiveDecision;
+};
+export type ExecutionFailedPaidResponse = PaidResponseBase & {
+    kind: 'execution_failed';
+    protocol: PaidProtocol;
+    paidRequestId: string;
+    paymentAttemptId: string;
+    reason: string;
+    decision: ExecutionFailedDecision;
+};
+export type PreflightFailedPaidResponse = PaidResponseBase & {
+    kind: 'preflight_failed';
+    protocol: PaidProtocol;
+    paidRequestId: string;
+    paymentAttemptId: string;
+    reason: string;
+    decision: PreflightFailedDecision;
+};
+export type PaidResponse = PassthroughPaidResponse | SuccessPaidResponse | PaidFulfillmentFailedResponse | DeniedPaidResponse | ExecutionPendingPaidResponse | ExecutionInconclusivePaidResponse | ExecutionFailedPaidResponse | PreflightFailedPaidResponse;
+export declare class AgentPayClient {
+    private readonly controlPlaneBaseUrl;
+    private readonly auth;
+    private readonly fetchImpl;
+    private readonly headers;
+    private cachedRuntimeToken;
+    private pendingRuntimeToken;
+    constructor(options: AgentPayClientOptions);
+    fetchPaid(input: string, init: RequestInit | undefined, context: PaidRequestContext, options: FetchPaidOptions): Promise<PaidResponse>;
+    lookupReceipt(receiptId: string): Promise<SdkReceiptResponse>;
+    private createDecisionRequest;
+    private requestPaymentDecision;
+    private mapDecisionToPaidResponse;
+    private getRuntimeAuthorizationHeader;
+    private resolveRuntimeToken;
+    private requestRuntimeToken;
+    private controlPlaneFetch;
+}
+export declare function createAgentPayClient(options: AgentPayClientOptions): AgentPayClient;
+export {};

package/dist/index.js

@@ -0,0 +1,290 @@
+import { createHash } from 'node:crypto';
+import { detectChallengeFromResponse, } from './challenge-detection.js';
+import { sdkPaymentDecisionRequestSchema, sdkPaymentDecisionResponseSchema, sdkReceiptResponseSchema, } from './contracts.js';
+const defaultRuntimeTokenRefreshWindowMs = 30_000;
+function trimTrailingSlash(value) {
+    return value.endsWith('/') ? value.slice(0, -1) : value;
+}
+function normalizeHeaders(headers) {
+    if (!headers) {
+        return undefined;
+    }
+    const normalizedHeaders = {};
+    const headerMap = new Headers(headers);
+    headerMap.forEach((value, key) => {
+        normalizedHeaders[key] = value;
+    });
+    return normalizedHeaders;
+}
+function createJsonResponse(status, payload) {
+    return new Response(JSON.stringify(payload), {
+        status,
+        headers: {
+            'content-type': 'application/json',
+        },
+    });
+}
+function createMerchantResponse(merchantResponse) {
+    return new Response(merchantResponse.body, {
+        status: merchantResponse.status,
+        headers: merchantResponse.headers,
+    });
+}
+function getReplayableRequestBody(body) {
+    if (body === undefined || body === null) {
+        return undefined;
+    }
+    if (typeof body === 'string') {
+        return body;
+    }
+    if (body instanceof URLSearchParams) {
+        return body.toString();
+    }
+    throw new Error('Paid requests currently support replayable string and URLSearchParams bodies when routed through the control plane.');
+}
+function hashRequestBody(body) {
+    if (!body) {
+        return undefined;
+    }
+    return createHash('sha256').update(body).digest('hex');
+}
+function parseRuntimeTokenResponse(payload) {
+    if (!payload || typeof payload !== 'object') {
+        throw new Error('Runtime token exchange returned an invalid payload.');
+    }
+    const token = payload.token;
+    const expiresAt = payload.expiresAt;
+    if (typeof token !== 'string' || token.length === 0) {
+        throw new Error('Runtime token exchange response is missing token.');
+    }
+    if (typeof expiresAt !== 'string' || Number.isNaN(Date.parse(expiresAt))) {
+        throw new Error('Runtime token exchange response is missing expiresAt.');
+    }
+    return {
+        token,
+        expiresAt,
+    };
+}
+export class AgentPayClient {
+    controlPlaneBaseUrl;
+    auth;
+    fetchImpl;
+    headers;
+    cachedRuntimeToken;
+    pendingRuntimeToken;
+    constructor(options) {
+        this.controlPlaneBaseUrl = trimTrailingSlash(options.controlPlaneBaseUrl);
+        this.auth = options.auth;
+        this.fetchImpl = options.fetch ?? fetch;
+        this.headers = options.headers;
+    }
+    async fetchPaid(input, init = {}, context, options) {
+        let challenge = options.challenge;
+        if (!challenge) {
+            const initialResponse = await this.fetchImpl(input, init);
+            challenge = await detectChallengeFromResponse(initialResponse);
+            if (!challenge) {
+                return {
+                    kind: 'passthrough',
+                    protocol: 'none',
+                    response: initialResponse,
+                };
+            }
+        }
+        const decisionRequest = await this.createDecisionRequest(input, init, context, options, challenge);
+        const decision = await this.requestPaymentDecision(decisionRequest);
+        return this.mapDecisionToPaidResponse(decision, challenge.protocol);
+    }
+    async lookupReceipt(receiptId) {
+        const response = await this.controlPlaneFetch(`/api/sdk/receipts/${receiptId}`, {
+            method: 'GET',
+        }, await this.getRuntimeAuthorizationHeader());
+        if (!response.ok) {
+            throw new Error(`Receipt lookup failed with status ${response.status}.`);
+        }
+        return sdkReceiptResponseSchema.parse(await response.json());
+    }
+    async createDecisionRequest(input, init, context, options, challenge) {
+        const requestBody = getReplayableRequestBody(init.body);
+        return sdkPaymentDecisionRequestSchema.parse({
+            context,
+            target: options.target,
+            request: {
+                url: input,
+                method: (init.method ?? 'GET').toUpperCase(),
+                headers: normalizeHeaders(init.headers),
+                body: requestBody,
+                bodyHash: hashRequestBody(requestBody),
+            },
+            challenge: {
+                protocol: challenge.protocol,
+                money: challenge.money,
+                raw: challenge.raw,
+                ...(challenge.payee ? { payee: challenge.payee } : {}),
+            },
+            idempotencyKey: options.idempotencyKey,
+        });
+    }
+    async requestPaymentDecision(decisionRequest) {
+        const decisionResponse = await this.controlPlaneFetch('/api/sdk/payment-decisions', {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+            },
+            body: JSON.stringify(decisionRequest),
+        }, await this.getRuntimeAuthorizationHeader());
+        if (!decisionResponse.ok) {
+            throw new Error(`Payment decision failed with status ${decisionResponse.status}.`);
+        }
+        return sdkPaymentDecisionResponseSchema.parse(await decisionResponse.json());
+    }
+    mapDecisionToPaidResponse(decision, protocol) {
+        switch (decision.outcome) {
+            case 'allow': {
+                const response = {
+                    kind: 'success',
+                    protocol,
+                    response: createMerchantResponse(decision.merchantResponse),
+                    paidRequestId: decision.paidRequestId,
+                    paymentAttemptId: decision.paymentAttemptId,
+                    receiptId: decision.receipt.receiptId,
+                    receipt: decision.receipt,
+                };
+                return response;
+            }
+            case 'paid_fulfillment_failed': {
+                const response = {
+                    kind: 'paid_fulfillment_failed',
+                    protocol,
+                    response: createMerchantResponse(decision.merchantResponse),
+                    paidRequestId: decision.paidRequestId,
+                    paymentAttemptId: decision.paymentAttemptId,
+                    receiptId: decision.receipt.receiptId,
+                    receipt: decision.receipt,
+                    reason: decision.reason,
+                    decision,
+                };
+                return response;
+            }
+            case 'deny': {
+                const response = {
+                    kind: 'denied',
+                    protocol,
+                    response: createJsonResponse(403, decision),
+                    reason: decision.reason,
+                    decision,
+                    ...(decision.paidRequestId
+                        ? { paidRequestId: decision.paidRequestId }
+                        : {}),
+                    ...(decision.policyReviewEventId
+                        ? { policyReviewEventId: decision.policyReviewEventId }
+                        : {}),
+                };
+                return response;
+            }
+            case 'executing': {
+                const response = {
+                    kind: 'execution_pending',
+                    protocol,
+                    response: createJsonResponse(202, decision),
+                    paidRequestId: decision.paidRequestId,
+                    paymentAttemptId: decision.paymentAttemptId,
+                    reason: decision.reason,
+                    decision,
+                };
+                return response;
+            }
+            case 'inconclusive': {
+                const response = {
+                    kind: 'execution_inconclusive',
+                    protocol,
+                    response: createJsonResponse(202, decision),
+                    paidRequestId: decision.paidRequestId,
+                    paymentAttemptId: decision.paymentAttemptId,
+                    reason: decision.reason,
+                    decision,
+                };
+                return response;
+            }
+            case 'execution_failed': {
+                const response = {
+                    kind: 'execution_failed',
+                    protocol,
+                    response: createMerchantResponse(decision.merchantResponse),
+                    paidRequestId: decision.paidRequestId,
+                    paymentAttemptId: decision.paymentAttemptId,
+                    reason: decision.reason,
+                    decision,
+                };
+                return response;
+            }
+            case 'preflight_failed': {
+                const response = {
+                    kind: 'preflight_failed',
+                    protocol,
+                    response: createJsonResponse(502, decision),
+                    paidRequestId: decision.paidRequestId,
+                    paymentAttemptId: decision.paymentAttemptId,
+                    reason: decision.reason,
+                    decision,
+                };
+                return response;
+            }
+        }
+    }
+    async getRuntimeAuthorizationHeader() {
+        const runtimeToken = await this.resolveRuntimeToken();
+        return `Bearer ${runtimeToken}`;
+    }
+    async resolveRuntimeToken() {
+        if (this.auth.type === 'runtimeToken') {
+            return this.auth.runtimeToken;
+        }
+        if (this.cachedRuntimeToken) {
+            const expiresInMs = this.cachedRuntimeToken.expiresAtMs - Date.now();
+            if (expiresInMs > defaultRuntimeTokenRefreshWindowMs) {
+                return this.cachedRuntimeToken.token;
+            }
+        }
+        if (!this.pendingRuntimeToken) {
+            this.pendingRuntimeToken = this.requestRuntimeToken();
+        }
+        try {
+            return await this.pendingRuntimeToken;
+        }
+        finally {
+            this.pendingRuntimeToken = undefined;
+        }
+    }
+    async requestRuntimeToken() {
+        if (this.auth.type !== 'bootstrapKey') {
+            throw new Error('Runtime token exchange requires bootstrapKey auth.');
+        }
+        const response = await this.controlPlaneFetch('/api/sdk/runtime-tokens', {
+            method: 'POST',
+        }, `Bearer ${this.auth.bootstrapKey}`);
+        if (!response.ok) {
+            throw new Error(`Runtime token exchange failed with status ${response.status}.`);
+        }
+        const runtimeToken = parseRuntimeTokenResponse(await response.json());
+        this.cachedRuntimeToken = {
+            token: runtimeToken.token,
+            expiresAtMs: Date.parse(runtimeToken.expiresAt),
+        };
+        return runtimeToken.token;
+    }
+    async controlPlaneFetch(path, init, authorizationHeader) {
+        return this.fetchImpl(`${this.controlPlaneBaseUrl}${path}`, {
+            ...init,
+            headers: {
+                ...(this.headers ?? {}),
+                ...(normalizeHeaders(init.headers) ?? {}),
+                Authorization: authorizationHeader,
+            },
+        });
+    }
+}
+export function createAgentPayClient(options) {
+    return new AgentPayClient(options);
+}
+//# sourceMappingURL=index.js.map