@aifinpay/agent 1.7.0 → 1.8.0

package/dist/aifp1.d.ts

@@ -0,0 +1,301 @@
+import { AiFinPayError } from "./errors.js";
+export declare class Aifp1Error extends AiFinPayError {
+}
+/** /v1/quote refused, or answered something that is not a quote. */
+export declare class Aifp1QuoteError extends Aifp1Error {
+}
+/** The quote cannot be settled by this SDK (no asset we can send). */
+export declare class Aifp1SettlementUnsupportedError extends Aifp1Error {
+}
+/**
+ * Money moved on-chain but /v1/pay did not issue a receipt.
+ *
+ * Carries the tx hash because that is the only thing standing between the
+ * caller and a lost payment: the quote is still settleable through
+ * `POST /v1/pay` by hand with the same Idempotency-Key, and without the hash
+ * in the error there is nothing to retry with.
+ */
+export declare class Aifp1PayError extends Aifp1Error {
+    readonly txRef?: string | undefined;
+    readonly quoteId?: string | undefined;
+    constructor(msg: string, txRef?: string | undefined, quoteId?: string | undefined);
+}
+/** The gateway rejected a receipt we believed covered the request. */
+export declare class Aifp1ReceiptRejectedError extends Aifp1Error {
+}
+export type Aifp1Scope = "exact" | "prefix" | "merchant";
+/** The 402 body — routes/gateway.js payChallenge(). */
+export interface Aifp1Challenge {
+    error: string;
+    protocol: string;
+    detail?: string;
+    merchant_id: string;
+    resource: string;
+    unit_weight: number;
+    base_unit_price_usd?: string;
+    how_to_pay?: string[];
+    scopes?: {
+        note?: string;
+        examples?: string[];
+    };
+}
+/** POST /v1/quote 200 body — routes/aifp.js (`used` is stripped server-side). */
+export interface Aifp1Quote {
+    quote_id: string;
+    merchant_id: string;
+    resource: string;
+    scope: Aifp1Scope;
+    tier: string;
+    unit_price: string;
+    requests: number;
+    units: number;
+    unit_quota: number;
+    amount: string;
+    currency: string;
+    accepted_assets: string[];
+    accepted_chains: string[];
+    pay_to: Record<string, string>;
+    /** Present only when the backend had a live POL rate at quote time. */
+    native_settlement?: {
+        asset: string;
+        decimals: number;
+        rate_usd: string;
+        total_wei: string;
+        merchant_wei: string;
+        treasury_wei: string;
+        creator_wei: string;
+    };
+    settlement: {
+        batch_units: string;
+        total_units: string;
+        fee_on_top: {
+            provider: string;
+            treasury: string;
+            creator: string;
+        };
+    };
+    nonce: string;
+    expires_at: string;
+}
+/** POST /v1/pay 200 body — routes/aifp.js. */
+export interface Aifp1PayResult {
+    receipt_id: string;
+    receipt: string;
+    status: string;
+    tx_ref: string;
+    merchant_id: string;
+    resource: string;
+    scope: Aifp1Scope;
+    amount: string;
+    currency: string;
+    quota: number;
+    unit_quota: number;
+    asset: string;
+    chain: string;
+    settled_at: string;
+    expires_at: string;
+    policy_exceeded?: boolean;
+    policy_reason?: string;
+}
+/** Mirror of scope.js scopeCovers(). */
+export declare function scopeCovers(scope: string | undefined, resource: string, path: string): boolean;
+/**
+ * Mirror of routes/gateway.js prefixHint(): /articles/2026/thing → /articles/,
+ * and a single-segment path → "/" (the whole site).
+ */
+export declare function prefixHint(path: string): string;
+/**
+ * Split a gateway URL the way routes/gateway.js splits it: first path segment
+ * is the merchant slug, the rest is the merchant-relative resource, and the
+ * query string is not part of either.
+ *
+ * `site` (origin + slug) is the cache key. It is the only merchant identity
+ * available before the first 402 answers with a merchant_id, and slug →
+ * merchant is a 1:1 lookup server-side (gw.resolveSlug).
+ */
+/**
+ * Gateway origins this client will settle against.
+ *
+ * Without this the client paid whoever answered. parseGatewayUrl looked only
+ * at the path, so ANY host could return {error:"AIFP-402", protocol:"AIFP-1",
+ * merchant_id:"mrch_theirs"} and the agent would quote, settle real POL to the
+ * address in that quote, and hand over a receipt. The 402 is unauthenticated
+ * by construction — it is the answer to a request that carried no credentials —
+ * so the only thing separating a paywall from a trap is knowing whose paywall
+ * it is.
+ *
+ * Override for self-hosted gateways; an empty list is refused rather than
+ * treated as "allow all", because that is the shape a config bug takes.
+ */
+export declare const DEFAULT_GATEWAY_ORIGINS: readonly ["https://gateway.aifinpay.io"];
+export declare function parseGatewayUrl(url: string, allowedOrigins?: readonly string[]): {
+    site: string;
+    slug: string;
+    restPath: string;
+};
+/**
+ * The `exp` of a receipt JWT, in ms, without verifying it — we are not
+ * authenticating the token here, only recovering a expiry the response failed
+ * to state. Returns null if the claim is absent or unreadable.
+ */
+export declare function jwtExpiryMs(jwt: string): number | null;
+/**
+ * The Idempotency-Key for one /v1/pay call. Required by the server
+ * (routes/aifp.js: 400 without it) and load-bearing here for a different
+ * reason: it is what stops one settled transaction being turned into two
+ * receipts, or a network blip during /v1/pay from becoming a second on-chain
+ * payment on retry.
+ *
+ * Derived from exactly the four fields the server itself hashes into its
+ * idempotency record — quote_id, asset, chain, tx_ref. That equivalence is the
+ * point:
+ *
+ *   • the same payment retried ⇒ the same key ⇒ the server replays the first
+ *     response instead of issuing a second receipt;
+ *   • a different payment ⇒ a different key, because a different payment must
+ *     differ in at least one of those four (quote_id alone is single-use —
+ *     `quote.used` makes a second settlement of one quote a 409);
+ *   • and the server's "same key, different body → 409" branch is unreachable
+ *     from this client, since the key is a pure function of that body.
+ *
+ * A random key would satisfy the header requirement and none of the above.
+ */
+export declare function idempotencyKeyFor(p: {
+    quoteId: string;
+    chain: string;
+    asset: string;
+    txRef: string;
+}): string;
+export interface Aifp1CachedReceipt {
+    /** origin + slug, as parseGatewayUrl() computes it. */
+    site: string;
+    merchantId: string;
+    receiptId: string;
+    /** The bearer JWT. Never log this. */
+    jwt: string;
+    scope: Aifp1Scope;
+    resource: string;
+    unitQuota: number;
+    /** Billing units we believe are left. Corrected from AIFP-Quota-Remaining. */
+    remaining: number;
+    /** JWT expiry, ms epoch. */
+    expiresAt: number;
+    amountUsd: number;
+}
+/**
+ * The receipts this agent holds, and the rules for spending them.
+ *
+ * In-memory and per-agent-instance: a receipt is a bearer credential, and
+ * writing one to disk by default would be a bigger decision than a cache
+ * deserves. An agent that wants batches to survive a restart can hold the
+ * entries itself (they are plain data) and re-seed a cache.
+ */
+export declare class Aifp1ReceiptCache {
+    private readonly entries;
+    /**
+     * Batch purchases in flight, keyed by site.
+     *
+     * The cache is empty between deciding to buy and the receipt arriving, so
+     * ten workers sharing one agent all missed, all got a 402, and all settled
+     * their own batch — ten on-chain payments and ten minimum charges where one
+     * would have covered every worker. It recurred at each quota boundary, so
+     * the more traffic an agent had the more it overpaid.
+     *
+     * Second and later callers await the first purchase, then re-check the
+     * cache: whoever wins buys a batch wide enough that the rest find it
+     * covering their path too. If it does not cover them (a different prefix)
+     * they fall through and buy their own, which is correct — that is a
+     * different batch, not a duplicate.
+     */
+    private readonly inflight;
+    /** Run `buy` for `site`, or await the purchase already running for it. */
+    coalesce<T>(site: string, buy: () => Promise<T>): Promise<T | "retry">;
+    /**
+     * The receipt to send for this request, if we hold one.
+     *
+     * Three conditions, all necessary:
+     *   • same merchant — a receipt's `aud` is the merchant id, so sending one
+     *     elsewhere is at best a 403 and at worst paying the wrong party;
+     *   • the scope covers the path — the same test the gateway will apply;
+     *   • quota left and not expired.
+     *
+     * `remaining > 0` rather than `remaining >= weight`: we only learn a route's
+     * weight from a 402 refusing it, so the weight of a path we have not been
+     * refused on is genuinely unknown here. The gateway's meter is authoritative
+     * and answers 402 "quota exhausted" when the batch cannot cover the call —
+     * at which point we re-quote. Guessing a weight would only add a way to be
+     * wrong in the direction of not spending a batch we own.
+     */
+    find(site: string, restPath: string, merchantId?: string): Aifp1CachedReceipt | undefined;
+    put(entry: Aifp1CachedReceipt): void;
+    /** The gateway's own count wins over ours — it is the one doing the metering. */
+    noteQuotaRemaining(entry: Aifp1CachedReceipt, remaining: number): void;
+    evict(entry: Aifp1CachedReceipt): void;
+    /** Everything we still hold, expired entries dropped. Plain data, copyable. */
+    list(): Aifp1CachedReceipt[];
+    get size(): number;
+}
+export interface Aifp1FetchOptions {
+    /**
+     * How wide a batch to buy. Default "prefix" — see the comment on
+     * resolveScope() for why the default is not "exact".
+     */
+    scope?: Aifp1Scope;
+    /** Override the resource the batch is scoped to (ignored for "merchant"). */
+    resource?: string;
+    /** Billing units to prepay. Default 1000 = $0.10 at the base unit price. */
+    units?: number;
+    /** Where /v1/quote and /v1/pay live. Default https://api.aifinpay.io */
+    apiBaseUrl?: string;
+    /**
+     * Gateway origins this client will settle against. Defaults to
+     * DEFAULT_GATEWAY_ORIGINS — set it only for a self-hosted gateway, and
+     * never to a host you do not control the paywall of.
+     */
+    gatewayOrigins?: readonly string[];
+    /** Value for the AIFP-Agent-Id header; defaults to the agent's EVM address. */
+    agentId?: string;
+    /** How long to keep retrying /v1/pay while the chain catches up (AIFP-425). */
+    settlementConfirmMs?: number;
+}
+/**
+ * Everything the flow needs that is not the AIFP-1 protocol itself. The
+ * settlement and the budget hooks are AiFinPayAgent's; splitting them out is
+ * what lets the protocol be tested without a chain.
+ */
+export interface Aifp1Deps {
+    fetchImpl: typeof fetch;
+    cache: Aifp1ReceiptCache;
+    /** AIFP-Agent-Id / agent_id — a 0x address, or agent policies cannot key on it. */
+    agentId: string;
+    /**
+     * Settle `totalWei` to `merchantWallet` with `orderId`, returning a hash
+     * whose transaction was included AND succeeded.
+     */
+    settle(p: {
+        merchantWallet: `0x${string}`;
+        totalWei: bigint;
+        orderId: string;
+    }): Promise<`0x${string}`>;
+    /** Per-call cap. false ⇒ the caller asked to skip rather than throw. */
+    checkPerCall(usd: number): boolean;
+    /** Daily cap. "skip" ⇒ drop the call; a string is a reservation to resolve. */
+    reserveDaily(usd: number): Promise<string | null | "skip">;
+    commit(reservationId: string, usd: number): Promise<void>;
+    release(reservationId: string): Promise<void>;
+    onPaid?(info: {
+        merchantId: string;
+        amountUsd: number;
+        txRef: string;
+        receiptId: string;
+    }): void;
+}
+/**
+ * Fetch a gateway URL, paying the AIFP-1 paywall if it asks.
+ *
+ * Returns the merchant's response. Returns null only when a budget cap was hit
+ * and `on_limit_exceeded` is "skip" — the same contract AiFinPayAgent.call()
+ * already has.
+ */
+export declare function aifp1Fetch(deps: Aifp1Deps, url: string, init?: RequestInit, opts?: Aifp1FetchOptions): Promise<Response | null>;
+//# sourceMappingURL=aifp1.d.ts.map

package/dist/aifp1.d.ts.map

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