@stellar-agent-services/payment-client 0.0.0-stage → 0.1.1

package/dist/client.d.ts

@@ -0,0 +1,138 @@
+import { type JobView, type JsonObject, type Problem, type ProviderManifest, type ServiceDescriptor } from "@stellar-agent-services/protocol";
+import type { PaymentRequired, PaymentRequirements } from "@x402/core/types";
+import type { Journal, SecretStore } from "./journal.js";
+import { type PolicyViolation, type SpendingPolicy } from "./policy.js";
+import type { PaymentMethod, Signer } from "./strategies.js";
+import { type VerificationSource } from "./verification.js";
+export interface PaymentClientOptions {
+    /** Who pays: localKeySigner(), or a wallet adapter. */
+    signer: Signer;
+    /** How to pay. The first method that matches the challenge is used. Default: x402ExactStellar(). */
+    methods?: PaymentMethod[];
+    policy: SpendingPolicy;
+    /** Trusted by the application. Required only when the policy sets verification minimums [V1]. */
+    verificationSource?: VerificationSource;
+    journal: Journal;
+    secrets: SecretStore;
+    fetch?: typeof fetch;
+    /** Soroban RPC for the default payment method. Defaults to the public testnet RPC. */
+    rpcUrl?: string;
+    /** Accept http://localhost providers, for local development. */
+    allowLocalhost?: boolean;
+    /** How long pay() and recover() follow a running job before returning it. Default 120 s. */
+    followSeconds?: number;
+    /** Also follow payment_uncertain within followSeconds. Default false: return uncertainty to the caller [J13]. */
+    followPaymentUncertain?: boolean;
+    /** Time between polls while following a job. Default: the provider's Retry-After, or 2000 ms. */
+    pollMs?: number;
+    /** How long quote() and pay() wait out a busy provider (429 or 503) before giving up. Default 30 s. */
+    busyWaitSeconds?: number;
+}
+export interface Quote {
+    manifestUrl: string;
+    manifest: ProviderManifest;
+    service: ServiceDescriptor;
+    input: JsonObject;
+    jobId: string;
+    bindingHash: string;
+    challenge: PaymentRequired;
+    requirements: PaymentRequirements;
+    /** The 402 does not match the manifest [P7], or no installed method can pay it. Any entry blocks the payment. */
+    challengeViolations: string[];
+    /** The installed payment method that pays this challenge. */
+    methodId: string | undefined;
+    /** What a policy wallet can still pay on chain, when the signer reports a budget. */
+    walletBudget: string | undefined;
+    /** The spending policy's violations, and the wallet budget's (`wallet.budget`). */
+    policyViolations: PolicyViolation[];
+    /** No violations, but above the auto-approve amount: a human must approve. */
+    needsApproval: boolean;
+}
+export interface PaymentResult {
+    job: JobView;
+    /** The approved transfer was confirmed on chain. Only then may a UI show "paid" [J16]. */
+    confirmed: boolean;
+    /** Why a charged job is not confirmed. */
+    unconfirmedReason?: string;
+}
+/** The payment may or may not have gone through. Run recover(jobId); never pay again. */
+export declare class PaymentUncertainError extends Error {
+    readonly jobId: string;
+    /** What happened, without the advice the message adds. */
+    readonly reason: string;
+    name: string;
+    constructor(jobId: string, 
+    /** What happened, without the advice the message adds. */
+    reason: string);
+}
+export declare class PaymentRefusedError extends Error {
+    name: string;
+}
+export declare class ProviderError extends Error {
+    readonly status: number;
+    readonly problem: Partial<Problem<string>> | undefined;
+    name: string;
+    constructor(status: number, problem: Partial<Problem<string>> | undefined);
+}
+/** The provider is busy (429 or 503) and answered before taking the payment: nothing was charged. */
+export declare class ProviderBusyError extends ProviderError {
+    /** When the provider suggested trying again. */
+    readonly retryAfterSeconds: number | undefined;
+    name: string;
+    constructor(status: number, problem: Partial<Problem<string>> | undefined, 
+    /** When the provider suggested trying again. */
+    retryAfterSeconds: number | undefined);
+}
+export declare class PaymentClient {
+    private readonly options;
+    private readonly fetch;
+    private readonly methods;
+    /** Jobs inside pay() right now. A slow signer, such as a wallet popup, must not let a job be signed twice. */
+    private readonly paying;
+    constructor(options: PaymentClientOptions);
+    get address(): string;
+    /** Everything needed to show the approval screen. Nothing is signed or paid. */
+    quote(manifestUrl: string, serviceName: string, input: JsonObject): Promise<Quote>;
+    /** Whether quote() found nothing that blocks the payment (approval aside). */
+    payable(quote: Quote): boolean;
+    /**
+     * Signs once and pays. `approved` is the human's answer to the approval screen; it is ignored for
+     * payments the policy auto-approves. A refusal is journaled and thrown.
+     */
+    pay(quote: Quote, { approved }: {
+        approved: boolean;
+    }): Promise<PaymentResult>;
+    /**
+     * The human said no on the approval screen. Journaled, and nothing is signed. Too late once the job is
+     * being paid or was sent; recover() it instead.
+     */
+    decline(quote: Quote): Promise<void>;
+    private payOnce;
+    /** Resumes a job from the journal with check-status and get-result. Never pays. */
+    recover(jobId: string): Promise<PaymentResult>;
+    /**
+     * Polls get-result while the provider answers 409 request_in_progress, at its Retry-After pace, for at
+     * most followSeconds. Resolves with the first job view, or undefined if settlement outlasted the wait.
+     */
+    private whileSettling;
+    private finish;
+    /** Checks the transaction against what this job journaled in `sending`, never against the receipt. */
+    private confirm;
+    /** The first installed method that pays the entry. A method that throws does not match (fail closed). */
+    private methodFor;
+    /** Spending policy, trusted verification [V1], and the wallet's on-chain budget must all pass. */
+    private checkLimits;
+    /**
+     * Polls get-result until the job finishes or followSeconds pass, at the provider's Retry-After pace.
+     * A busy or in-progress answer while polling only means "ask again later" [Q9], [J7].
+     */
+    private follow;
+    /** get-result. Answers other than a job view, a busy provider or a job still settling throw. */
+    private getResult;
+    /** Sends create-job, and sends it again while the provider is busy and `until` allows [Q8]. */
+    private createJob;
+    private get busyWaitMs();
+    private jobHeaders;
+    private reasons;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

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

package/dist/client.js

@@ -0,0 +1,522 @@
+// The payment flow (docs/payment-client.md, "One payment, step by step"):
+//
+//   quote():   manifest -> job id, token, binding hash -> unpaid create-job -> 402 -> checkChallenge
+//              -> pick a payment method -> policy and wallet budget. Nothing is signed.
+//   pay():     approval -> sign once -> journal `sending` -> paid create-job -> follow the job ->
+//              confirm on chain.
+//   recover(): check-status / get-result from the journal. Never signs or pays again.
+//
+// A busy provider answers create-job with 429 or 503 before it claims or settles anything. The client
+// waits out Retry-After and sends the same request again, the paid one with the same signed payment,
+// which still buys at most one job (docs/provider-standard.md §5.8) [Q8]. It gives up after
+// busyWaitSeconds, or once the signed payment is about to expire.
+//
+// 409 request_in_progress means the opposite: the provider has claimed the payment and is still
+// settling it [J7]. The client never pays again; it follows the job with get-result until it has a job
+// view, for followSeconds, and otherwise hands it back for recover().
+//
+// The signer and the payment methods are strategies (strategies.ts). Every safety step stays here, so
+// it holds whichever ones are plugged in.
+import { bindingHash, canonicalSha256, checkChallenge, createJobUrl, IDEMPOTENCY_KEY, JOB_TOKEN, jobResultUrl, parseRetryAfter, } from "@stellar-agent-services/protocol";
+import { decodePaymentRequiredHeader, encodePaymentSignatureHeader } from "@x402/core/http";
+import { loadManifest } from "./manifest.js";
+import { checkPolicy, PAY_ACTION, policyHash } from "./policy.js";
+import { X402_EXACT_STELLAR, x402ExactStellar } from "./x402-exact-stellar.js";
+import { matchesVerification } from "./verification.js";
+/** The payment may or may not have gone through. Run recover(jobId); never pay again. */
+export class PaymentUncertainError extends Error {
+    jobId;
+    reason;
+    name = "PaymentUncertainError";
+    constructor(jobId, 
+    /** What happened, without the advice the message adds. */
+    reason) {
+        super(`${reason}. The payment may have gone through: recover job ${jobId}, do not pay again.`);
+        this.jobId = jobId;
+        this.reason = reason;
+    }
+}
+export class PaymentRefusedError extends Error {
+    name = "PaymentRefusedError";
+}
+export class ProviderError extends Error {
+    status;
+    problem;
+    name = "ProviderError";
+    constructor(status, problem) {
+        super(`the provider answered ${status}${problem?.code ? ` ${problem.code}` : ""}${problem?.detail ? `: ${problem.detail}` : ""}`);
+        this.status = status;
+        this.problem = problem;
+    }
+}
+/** The provider is busy (429 or 503) and answered before taking the payment: nothing was charged. */
+export class ProviderBusyError extends ProviderError {
+    retryAfterSeconds;
+    name = "ProviderBusyError";
+    constructor(status, problem, 
+    /** When the provider suggested trying again. */
+    retryAfterSeconds) {
+        super(status, problem);
+        this.retryAfterSeconds = retryAfterSeconds;
+        const again = retryAfterSeconds === undefined ? "later" : `in ${retryAfterSeconds} s`;
+        this.message = `the provider is busy${problem?.code ? ` (${problem.code})` : ""}; try again ${again}`;
+    }
+}
+/** Seconds to wait when a busy answer has no usable Retry-After. */
+const BUSY_RETRY_SECONDS = 2;
+/** Room left, before the signed payment expires, for the provider to settle it. */
+const PAYMENT_EXPIRY_MARGIN_SECONDS = 10;
+export class PaymentClient {
+    options;
+    fetch;
+    methods;
+    /** Jobs inside pay() right now. A slow signer, such as a wallet popup, must not let a job be signed twice. */
+    paying = new Set();
+    constructor(options) {
+        this.options = options;
+        this.fetch = options.fetch ?? fetch;
+        this.methods = options.methods ?? [x402ExactStellar(options.rpcUrl === undefined ? {} : { rpcUrl: options.rpcUrl })];
+        if (this.methods.length === 0)
+            throw new TypeError("PaymentClient needs at least one payment method");
+        const ids = this.methods.map((method) => method.id);
+        // Recovery finds the method that paid by its id.
+        if (new Set(ids).size !== ids.length)
+            throw new TypeError(`payment method ids must be unique: ${ids.join(", ")}`);
+    }
+    get address() {
+        return this.options.signer.address;
+    }
+    /** Everything needed to show the approval screen. Nothing is signed or paid. */
+    async quote(manifestUrl, serviceName, input) {
+        const { journal, secrets, policy } = this.options;
+        const loadOptions = { fetch: this.fetch };
+        if (this.options.allowLocalhost !== undefined)
+            loadOptions.allowLocalhost = this.options.allowLocalhost;
+        const manifest = await loadManifest(manifestUrl, loadOptions);
+        const service = manifest.services.find((candidate) => candidate.name === serviceName);
+        if (service === undefined)
+            throw new PaymentRefusedError(`the provider has no service "${serviceName}"`);
+        // The job identity is fixed, and saved, before the first request [J1].
+        const jobId = crypto.randomUUID();
+        const token = base64url(crypto.getRandomValues(new Uint8Array(32)));
+        const binding = await bindingHash(service.name, input);
+        await secrets.set(jobId, token);
+        const hash = await policyHash(policy);
+        await journal.append("intent", jobId, hash, {
+            manifestUrl,
+            baseUrl: manifest.baseUrl,
+            service: service.name,
+            bindingHash: binding,
+            input,
+        });
+        const response = await this.createJob(createJobUrl(manifest.baseUrl, service.name), { method: "POST", headers: this.jobHeaders(jobId, token), body: JSON.stringify(input), redirect: "manual" }, Date.now() + this.busyWaitMs);
+        if (isBusy(response))
+            throw await busyError(response);
+        if (response.status !== 402)
+            throw new ProviderError(response.status, await readProblem(response));
+        const header = response.headers.get("PAYMENT-REQUIRED");
+        const challenge = header !== null ? decodePaymentRequiredHeader(header) : (await response.json());
+        const challengeViolations = checkChallenge(manifest, service.name, challenge).map((v) => `[${v.rule}] ${v.pointer}: ${v.message}`);
+        const requirements = challenge.accepts?.[0] ?? {};
+        const method = this.methodFor(requirements);
+        if (method === undefined)
+            challengeViolations.push(noMethod(requirements));
+        const limits = await this.checkLimits(requirements, manifest, manifestUrl);
+        const quote = {
+            manifestUrl,
+            manifest,
+            service,
+            input,
+            jobId,
+            bindingHash: binding,
+            challenge,
+            requirements,
+            challengeViolations,
+            methodId: method?.id,
+            walletBudget: limits.walletBudget,
+            policyViolations: limits.violations,
+            needsApproval: limits.needsApproval,
+        };
+        if (!this.payable(quote))
+            await journal.append("refused", jobId, hash, { reasons: this.reasons(quote) });
+        return quote;
+    }
+    /** Whether quote() found nothing that blocks the payment (approval aside). */
+    payable(quote) {
+        return quote.challengeViolations.length === 0 && quote.policyViolations.length === 0;
+    }
+    /**
+     * Signs once and pays. `approved` is the human's answer to the approval screen; it is ignored for
+     * payments the policy auto-approves. A refusal is journaled and thrown.
+     */
+    async pay(quote, { approved }) {
+        if (!this.payable(quote))
+            throw new PaymentRefusedError(this.reasons(quote).join("; "));
+        if (this.options.journal.forJob(quote.jobId).some((entry) => entry.event === "sending")) {
+            throw new PaymentRefusedError(`job ${quote.jobId} was already paid for; use recover()`);
+        }
+        // Checked and marked before the first await, so a second pay() for this job can't sign it again.
+        if (this.paying.has(quote.jobId))
+            throw new PaymentRefusedError(`job ${quote.jobId} is already being paid`);
+        this.paying.add(quote.jobId);
+        try {
+            return await this.payOnce(quote, approved);
+        }
+        finally {
+            this.paying.delete(quote.jobId);
+        }
+    }
+    /**
+     * The human said no on the approval screen. Journaled, and nothing is signed. Too late once the job is
+     * being paid or was sent; recover() it instead.
+     */
+    async decline(quote) {
+        const { journal, policy } = this.options;
+        if (this.paying.has(quote.jobId))
+            return;
+        if (journal.forJob(quote.jobId).some((entry) => entry.event === "refused" || entry.event === "sending"))
+            return;
+        await journal.append("refused", quote.jobId, await policyHash(policy), { reasons: ["the user declined"] });
+    }
+    async payOnce(quote, approved) {
+        const { journal, policy, signer } = this.options;
+        const hash = await policyHash(policy);
+        const method = this.methodFor(quote.requirements);
+        if (method === undefined)
+            throw new PaymentRefusedError(noMethod(quote.requirements));
+        // Limits are checked again: another payment may have run since the quote.
+        const decision = await this.checkLimits(quote.requirements, quote.manifest, quote.manifestUrl);
+        if (!decision.allowed) {
+            await journal.append("refused", quote.jobId, hash, { reasons: decision.violations.map((v) => `${v.field}: ${v.message}`) });
+            throw new PaymentRefusedError(decision.violations.map((v) => v.message).join("; "));
+        }
+        if (decision.needsApproval && !approved) {
+            await journal.append("refused", quote.jobId, hash, { reasons: ["the user declined"] });
+            throw new PaymentRefusedError("the user declined the payment");
+        }
+        await journal.append("approved", quote.jobId, hash, { by: decision.needsApproval ? "user" : "policy" });
+        let signed;
+        // Taken before signing, which may wait on a wallet popup: the payment's validity starts when it is built.
+        const signedAt = Date.now();
+        try {
+            signed = await method.createPayload(quote.requirements, signer);
+        }
+        catch (error) {
+            // Nothing was sent, so nothing was charged, and the user may try again.
+            const reason = `the payment was not signed: ${error.message}`;
+            await journal.append("refused", quote.jobId, hash, { reasons: [reason] });
+            throw new PaymentRefusedError(reason);
+        }
+        const payload = { ...signed, x402Version: 2, resource: quote.challenge.resource, accepted: quote.requirements };
+        // Written and flushed before the request goes out: from here on, this job is never signed again.
+        await journal.append("sending", quote.jobId, hash, { ...pick(quote.requirements), payer: signer.address, method: method.id });
+        const token = (await this.options.secrets.get(quote.jobId));
+        // A busy provider is waited out with the same signed payment [Q8], but only while it can still settle it.
+        const expiresAt = signedAt + (quote.requirements.maxTimeoutSeconds - PAYMENT_EXPIRY_MARGIN_SECONDS) * 1000;
+        let response;
+        try {
+            response = await this.createJob(createJobUrl(quote.manifest.baseUrl, quote.service.name), {
+                method: "POST",
+                headers: { ...this.jobHeaders(quote.jobId, token), "PAYMENT-SIGNATURE": encodePaymentSignatureHeader(payload) },
+                body: JSON.stringify(quote.input),
+                redirect: "manual",
+            }, Math.min(Date.now() + this.busyWaitMs, expiresAt));
+        }
+        catch (error) {
+            await journal.append("uncertain", quote.jobId, hash, { reason: "the paid request failed in transit" });
+            throw new PaymentUncertainError(quote.jobId, `the paid request failed (${error.message})`);
+        }
+        if (response.status === 402) {
+            const reason = (await readChallengeError(response)) ?? "payment_rejected";
+            // The provider refused before settling: nothing was charged.
+            await journal.append("failed", quote.jobId, hash, { charged: false, reason });
+            throw new PaymentRefusedError(`the provider rejected the payment: ${reason}`);
+        }
+        if (isBusy(response)) {
+            // Answered at step 5 of §5.4, before the payment was verified or claimed: nothing was charged.
+            const error = await busyError(response);
+            await journal.append("failed", quote.jobId, hash, { charged: false, reason: error.problem?.code ?? `provider_busy_${response.status}` });
+            throw error;
+        }
+        if (isInProgress(response)) {
+            // The provider holds the payment and is still settling it: follow the job, never pay again.
+            const settled = await this.whileSettling(quote.manifest.baseUrl, quote.jobId, token, response);
+            if (settled === undefined) {
+                await journal.append("uncertain", quote.jobId, hash, { reason: "the provider was still settling the payment" });
+                throw new PaymentUncertainError(quote.jobId, "the provider is still settling the payment");
+            }
+            return this.finish(quote.manifest.baseUrl, quote.jobId, token, settled.job, hash, settled.retryAfter);
+        }
+        if (response.status !== 200 && response.status !== 202) {
+            await journal.append("uncertain", quote.jobId, hash, { reason: `the provider answered ${response.status}` });
+            throw new PaymentUncertainError(quote.jobId, `the provider answered ${response.status}`);
+        }
+        const job = (await response.json());
+        return this.finish(quote.manifest.baseUrl, quote.jobId, token, job, hash, retryAfterMs(response));
+    }
+    /** Resumes a job from the journal with check-status and get-result. Never pays. */
+    async recover(jobId) {
+        const { journal, secrets, policy } = this.options;
+        const entries = journal.forJob(jobId);
+        const intent = entries.find((entry) => entry.event === "intent");
+        const token = await secrets.get(jobId);
+        if (intent === undefined || token === undefined)
+            throw new Error(`job ${jobId} is not in this journal`);
+        if (!entries.some((entry) => entry.event === "sending")) {
+            throw new Error(`job ${jobId} was never paid for, so there is nothing to recover`);
+        }
+        const hash = await policyHash(policy);
+        const baseUrl = String(intent.details["baseUrl"]);
+        await journal.append("recovered", jobId, hash, {});
+        const response = await this.getResult(baseUrl, jobId, token);
+        if (isBusy(response))
+            throw await busyError(response);
+        if (isInProgress(response)) {
+            const settled = await this.whileSettling(baseUrl, jobId, token, response);
+            if (settled === undefined)
+                throw new PaymentUncertainError(jobId, "the provider is still settling the payment");
+            return this.finish(baseUrl, jobId, token, settled.job, hash, settled.retryAfter);
+        }
+        const job = await readJob(response);
+        return this.finish(baseUrl, jobId, token, job, hash, retryAfterMs(response));
+    }
+    /**
+     * Polls get-result while the provider answers 409 request_in_progress, at its Retry-After pace, for at
+     * most followSeconds. Resolves with the first job view, or undefined if settlement outlasted the wait.
+     */
+    async whileSettling(baseUrl, jobId, token, response) {
+        const deadline = Date.now() + (this.options.followSeconds ?? 120) * 1000;
+        for (;;) {
+            const wait = this.options.pollMs ?? retryAfterMs(response) ?? 2000;
+            await response.body?.cancel();
+            if (Date.now() + wait > deadline)
+                return undefined;
+            await sleep(wait);
+            response = await this.getResult(baseUrl, jobId, token);
+            // Busy is "ask again later" too [Q9].
+            if (!isInProgress(response) && !isBusy(response))
+                return { job: await readJob(response), retryAfter: retryAfterMs(response) };
+        }
+    }
+    async finish(baseUrl, jobId, token, first, hash, retryAfter) {
+        const { journal } = this.options;
+        const job = await this.follow(baseUrl, jobId, token, first, retryAfter);
+        let confirmation = { confirmed: false };
+        if (job.charged === true) {
+            confirmation = job.payment === undefined ? { confirmed: false, reason: "the provider sent no payment receipt" } : await this.confirm(jobId, job.payment.transaction);
+            const settled = journal.forJob(jobId).filter((entry) => entry.event === "settled");
+            // Journaled once, and again only when a later check confirms what an earlier one could not.
+            if (settled.length === 0 || (confirmation.confirmed && !settled.some((entry) => entry.details["confirmed"] === true))) {
+                await journal.append("settled", jobId, hash, {
+                    transaction: job.payment?.transaction ?? "",
+                    network: job.payment?.network ?? "",
+                    amount: job.payment?.amount ?? "",
+                    confirmed: confirmation.confirmed,
+                    ...(confirmation.reason === undefined ? {} : { reason: confirmation.reason }),
+                });
+            }
+        }
+        if (job.status === "failed")
+            await journal.append("failed", jobId, hash, { charged: job.charged, code: job.error?.code ?? "" });
+        else if (job.status === "succeeded")
+            await journal.append("result", jobId, hash, { status: job.status });
+        const result = { job, confirmed: confirmation.confirmed };
+        if (job.charged === true && confirmation.reason !== undefined)
+            result.unconfirmedReason = confirmation.reason;
+        return result;
+    }
+    /** Checks the transaction against what this job journaled in `sending`, never against the receipt. */
+    async confirm(jobId, transaction) {
+        const { journal } = this.options;
+        const sending = journal.forJob(jobId).find((entry) => entry.event === "sending").details;
+        // One transaction proves one job: a provider must not reuse an earlier payment as a receipt.
+        const other = journal
+            .entries()
+            .find((entry) => entry.event === "settled" && entry.jobId !== jobId && entry.details["confirmed"] === true && entry.details["transaction"] === transaction);
+        if (other !== undefined)
+            return { confirmed: false, reason: `transaction ${transaction} already confirmed job ${other.jobId}` };
+        // Journals from before `method` was recorded were paid with the only method there was.
+        const methodId = typeof sending["method"] === "string" ? sending["method"] : X402_EXACT_STELLAR;
+        const method = this.methods.find((candidate) => candidate.id === methodId);
+        if (method === undefined)
+            return { confirmed: false, reason: `payment method "${methodId}" is not installed, so the payment can't be checked` };
+        try {
+            return await method.confirm(transaction, {
+                network: String(sending["network"]),
+                asset: String(sending["asset"]),
+                amount: String(sending["amount"]),
+                payTo: String(sending["payTo"]),
+                // Journals from before `payer` was recorded were signed by this client's key.
+                payer: typeof sending["payer"] === "string" ? sending["payer"] : this.address,
+            });
+        }
+        catch (error) {
+            return { confirmed: false, reason: `the payment could not be checked: ${error.message}` };
+        }
+    }
+    /** The first installed method that pays the entry. A method that throws does not match (fail closed). */
+    methodFor(requirements) {
+        return this.methods.find((method) => {
+            try {
+                return method.matches(requirements);
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    /** Spending policy, trusted verification [V1], and the wallet's on-chain budget must all pass. */
+    async checkLimits(requirements, manifest, manifestUrl) {
+        const { policy, journal, signer } = this.options;
+        const terms = pick(requirements);
+        let verification;
+        if (policy.minVerificationScore !== undefined || policy.stellar.minProviderLevel !== undefined) {
+            const subject = {
+                network: terms.network,
+                payTo: terms.payTo,
+                manifestUrl,
+                manifestSha256: await canonicalSha256(manifest),
+                ...(manifest.provider.agentId === undefined ? {} : { agentId: manifest.provider.agentId }),
+            };
+            try {
+                const evidence = await this.options.verificationSource?.read({ ...subject });
+                if (matchesVerification(evidence, subject))
+                    verification = evidence;
+            }
+            catch {
+                // An unavailable source is missing evidence, never permission to sign [V1].
+            }
+        }
+        const decision = checkPolicy(policy, {
+            action: PAY_ACTION,
+            ...terms,
+            amount: terms.amount ?? "0",
+            spentLast24h: journal.spentSince(new Date(Date.now() - 86400_000)),
+            ...(verification === undefined ? {} : { verification }),
+        });
+        if (signer.budget === undefined || terms.amount === undefined)
+            return { ...decision, walletBudget: undefined };
+        let walletBudget;
+        let problem;
+        try {
+            const reported = await signer.budget(terms.network, terms.asset);
+            if (reported !== undefined && !/^\d+$/.test(reported))
+                problem = `the wallet reported an invalid budget "${reported}"`;
+            else
+                walletBudget = reported;
+        }
+        catch (error) {
+            problem = `the wallet's budget could not be read: ${error.message}`;
+        }
+        if (walletBudget !== undefined && BigInt(terms.amount) > BigInt(walletBudget))
+            problem = "the amount is above what the wallet's on-chain budget has left";
+        if (problem === undefined)
+            return { ...decision, walletBudget };
+        return { allowed: false, violations: [...decision.violations, { field: "wallet.budget", message: problem }], needsApproval: false, walletBudget };
+    }
+    /**
+     * Polls get-result until the job finishes or followSeconds pass, at the provider's Retry-After pace.
+     * A busy or in-progress answer while polling only means "ask again later" [Q9], [J7].
+     */
+    async follow(baseUrl, jobId, token, job, retryAfter) {
+        const deadline = Date.now() + (this.options.followSeconds ?? 120) * 1000;
+        while ((job.status !== "succeeded" && job.status !== "failed") || (job.status === "succeeded" && job.output === undefined)) {
+            // Only provider reconciliation resolves uncertainty [J13]. Opt-in polling reads that same job [J11].
+            if ((job.status === "payment_uncertain" && this.options.followPaymentUncertain !== true) || Date.now() >= deadline)
+                return job;
+            const wait = this.options.pollMs ?? retryAfter ?? 2000;
+            await sleep(Math.min(wait, deadline - Date.now()));
+            const response = await this.getResult(baseUrl, jobId, token);
+            retryAfter = retryAfterMs(response);
+            if (isBusy(response) || isInProgress(response))
+                await response.body?.cancel();
+            else
+                job = await readJob(response);
+        }
+        return job;
+    }
+    /** get-result. Answers other than a job view, a busy provider or a job still settling throw. */
+    async getResult(baseUrl, jobId, token) {
+        const response = await this.fetch(jobResultUrl(baseUrl, jobId), { headers: { [JOB_TOKEN]: token }, redirect: "manual" });
+        if (response.status !== 200 && response.status !== 202 && !isBusy(response) && !isInProgress(response)) {
+            throw new ProviderError(response.status, await readProblem(response));
+        }
+        return response;
+    }
+    /** Sends create-job, and sends it again while the provider is busy and `until` allows [Q8]. */
+    async createJob(url, init, until) {
+        for (;;) {
+            const response = await this.fetch(url, init);
+            if (!isBusy(response))
+                return response;
+            // A little jitter, so clients turned away together don't all come back together.
+            const wait = (retryAfterMs(response) ?? BUSY_RETRY_SECONDS * 1000) * (1 + Math.random() * 0.2);
+            if (Date.now() + wait > until)
+                return response;
+            await response.body?.cancel();
+            await sleep(wait);
+        }
+    }
+    get busyWaitMs() {
+        return (this.options.busyWaitSeconds ?? 30) * 1000;
+    }
+    jobHeaders(jobId, token) {
+        return { "Content-Type": "application/json", [IDEMPOTENCY_KEY]: jobId, [JOB_TOKEN]: token };
+    }
+    reasons(quote) {
+        return [...quote.challengeViolations, ...quote.policyViolations.map((v) => `${v.field}: ${v.message}`)];
+    }
+}
+function noMethod(requirements) {
+    return `no installed payment method pays scheme "${String(requirements.scheme)}" on ${String(requirements.network)}`;
+}
+/** Without Node's Buffer, so the core runs in the browser too. */
+function base64url(bytes) {
+    return btoa(String.fromCharCode(...bytes)).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+function pick(requirements) {
+    return {
+        network: requirements.network,
+        asset: requirements.asset,
+        amount: requirements.amount,
+        payTo: requirements.payTo,
+    };
+}
+function isBusy(response) {
+    return response.status === 429 || response.status === 503;
+}
+/** 409 request_in_progress: the job exists and its payment is still being claimed or settled [J7]. */
+function isInProgress(response) {
+    return response.status === 409;
+}
+function retryAfterMs(response) {
+    const seconds = parseRetryAfter(response.headers.get("Retry-After"));
+    return seconds === undefined ? undefined : seconds * 1000;
+}
+async function busyError(response) {
+    return new ProviderBusyError(response.status, await readProblem(response), parseRetryAfter(response.headers.get("Retry-After")));
+}
+async function readJob(response) {
+    return (await response.json());
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, Math.max(0, ms)));
+}
+async function readProblem(response) {
+    try {
+        return (await response.json());
+    }
+    catch {
+        return undefined;
+    }
+}
+async function readChallengeError(response) {
+    const header = response.headers.get("PAYMENT-REQUIRED");
+    try {
+        return header !== null ? decodePaymentRequiredHeader(header).error : (await response.json()).error;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=client.js.map