@inflowpayai/x402-seller 0.5.0

package/dist/index.d.cts

@@ -0,0 +1,208 @@
+import { FacilitatorClient } from '@x402/core/server';
+import { Environment, X402ConfigResponse, X402FacilitatorSupportedResponse, PaymentScheme } from '@inflowpayai/x402';
+import { PaymentOption } from '@x402/core/http';
+import { Network, SchemeNetworkServer } from '@x402/core/types';
+
+/**
+ * Constructor options for {@link createInflowFacilitator}. The authed facilitator drops directly into the foundation V2
+ * middleware's `facilitatorClients` array (`@x402/express`, `@x402/hono`).
+ */
+interface InflowFacilitatorOptions {
+    /** Selects one of the public environments. */
+    environment: Environment;
+    /**
+     * InFlow API key. Sent as `X-API-KEY` on every outbound `verify` / `settle` / `getSupported` request. Required at the
+     * type level so a typo or env-var omission that leaves `apiKey` undefined can't silently degrade an authed deployment
+     * to facilitator-mode — sellers who want the authless path pick {@link createUnauthenticatedInflowFacilitator}
+     * explicitly.
+     */
+    apiKey: string;
+    /** Override the environment-derived URL. Takes precedence over `environment`. */
+    baseUrl?: string;
+}
+/**
+ * Constructor options for {@link createUnauthenticatedInflowFacilitator}.
+ *
+ * The unauthenticated factory is the explicit escape hatch for facilitator-only deployments (self-hosted,
+ * public-facilitator mode, test harnesses) that don't have a seller account. Sends no `X-API-KEY` header on outbound
+ * `verify` / `settle` / `getSupported` requests.
+ */
+interface InflowUnauthenticatedFacilitatorOptions {
+    /** Selects one of the public environments. */
+    environment: Environment;
+    /** Override the environment-derived URL. Takes precedence over `environment`. */
+    baseUrl?: string;
+}
+
+/**
+ * Construct an authed InFlow facilitator. The returned object satisfies the foundation V2 `FacilitatorClient` contract
+ * from `@x402/core` (`verify` / `settle` / `getSupported` only) and drops directly into the foundation middleware's
+ * `facilitatorClients` array (`@x402/express`, `@x402/hono`) — first claimer of a `(scheme, network)` in declaration
+ * order wins verify/settle routing.
+ *
+ * Seller-authed endpoints (`/v1/x402/config`, `getSignerAddresses`) live on the separate
+ * {@link createInflowSellerClient} factory; this client carries the seller's API key only for `verify` / `settle` /
+ * `getSupported`, where it enables server-side `payTo`-against-wallets validation.
+ *
+ * `getSupported()` is cached lazily in-memory for 60 minutes after the first call; concurrent callers share an
+ * in-flight refresh. There is no priming step — the foundation middleware calls `getSupported()` once at
+ * `x402ResourceServer.initialize()` and the cache is populated then.
+ *
+ * @param options - {@link InflowFacilitatorOptions}.
+ * @returns A foundation `FacilitatorClient`.
+ */
+declare function createInflowFacilitator(options: InflowFacilitatorOptions): FacilitatorClient;
+/**
+ * Anonymous sibling of {@link createInflowFacilitator} — same caches and contract, no `X-API-KEY` header. For
+ * facilitator-only deployments (self-hosted, public-facilitator mode, test harnesses).
+ */
+declare function createUnauthenticatedInflowFacilitator(options: InflowUnauthenticatedFacilitatorOptions): FacilitatorClient;
+
+/**
+ * Constructor options for {@link createInflowSellerClient}.
+ *
+ * `apiKey` is required at the type level. `/v1/x402/config` is a seller-authed endpoint — there's no facilitator-mode
+ * equivalent — so an unauthenticated seller client has no useful surface to expose.
+ */
+interface InflowSellerClientOptions {
+    /** Selects one of the public environments. */
+    environment: Environment;
+    /** InFlow API key sent on every request as `X-API-KEY`. Required. */
+    apiKey: string;
+    /** Override the environment-derived URL. Takes precedence over `environment`. */
+    baseUrl?: string;
+}
+/**
+ * Seller-authed InFlow client. Wraps the `/v1/x402/config` and `/v1/x402/supported` endpoints and surfaces
+ * signer-address discovery on top of `getSupported()`. Drives {@link inflowAccepts} and any operator- facing
+ * introspection.
+ *
+ * Construct via {@link createInflowSellerClient}. The factory primes both caches in parallel before resolving, so
+ * methods on the returned instance hit in-memory data for the lifetime of the 60-minute TTL.
+ *
+ * @see createInflowSellerClient
+ */
+interface InflowSellerClient {
+    /**
+     * Fetch the seller config (assets, wallets, payment methods, sellerId). Cached for 60 minutes after the factory's
+     * prime call.
+     *
+     * @returns The current `X402ConfigResponse` (re-exported from `@inflowpayai/x402`).
+     */
+    config(): Promise<X402ConfigResponse>;
+    /**
+     * Force a refetch of `GET /v1/x402/config` and replace the cached value.
+     *
+     * @returns The freshly fetched `X402ConfigResponse` (re-exported from `@inflowpayai/x402`).
+     */
+    refreshConfig(): Promise<X402ConfigResponse>;
+    /**
+     * Force a refetch of `GET /v1/x402/supported` and replace the cached value.
+     *
+     * @returns The freshly fetched `X402FacilitatorSupportedResponse` (re-exported from `@inflowpayai/x402`).
+     */
+    refreshSupported(): Promise<X402FacilitatorSupportedResponse>;
+    /**
+     * Signer addresses advertised by the facilitator for the given network.
+     *
+     * Lookup is exact-match on `network` first; if no entry exists and the input is CAIP-2 shaped
+     * (`<namespace>:<reference>`), it falls back to a `<namespace>:*` wildcard key so external facilitators that follow
+     * the V2 spec's wildcard form interop. Returns `[]` when nothing matches.
+     *
+     * @param network - CAIP-2 string (e.g. `'eip155:8453'` or `'inflow:1'`).
+     * @returns The configured signer addresses, or `[]` when none match.
+     */
+    getSignerAddresses(network: string): Promise<readonly string[]>;
+}
+/**
+ * Construct an {@link InflowSellerClient}.
+ *
+ * The factory primes the config and `getSupported()` caches in parallel before resolving, so the first downstream call
+ * ({@link inflowAccepts}, `getSignerAddresses`, etc.) is synchronous against in-memory data. Cost: one round trip at
+ * startup; benefit: synchronous downstream use.
+ *
+ * @param options - {@link InflowSellerClientOptions}.
+ * @returns A promise resolving to a primed {@link InflowSellerClient}.
+ */
+declare function createInflowSellerClient(options: InflowSellerClientOptions): Promise<InflowSellerClient>;
+
+/** Price spec accepted by {@link inflowAccepts}. */
+interface PriceSpec {
+    /**
+     * Amount string. Three accepted forms (all supporting up to 8 decimal places):
+     *
+     * - `'$<integer>(.<decimals>)?'` — implies USD (e.g. `'$0.01'`, `'$10.00000001'`).
+     * - `'<integer>(.<decimals>)? <CURRENCY>'` — currency from suffix (e.g. `'0.01 USDC'`, `'0.5 USDT'`, `'1 USD'`).
+     * - `'<integer>(.<decimals>)?'` — bare numeric; the {@link PriceSpec.currency} field is required in this case.
+     */
+    amount: string;
+    /**
+     * Currency override. When set, takes precedence over any currency embedded in {@link PriceSpec.amount}. Required when
+     * `amount` is in bare numeric form. `'USD'` is a wildcard that matches any stablecoin the seller has configured.
+     */
+    currency?: 'USD' | 'USDC' | 'USDT' | 'PYUSD' | (string & {});
+}
+/** Options accepted by {@link inflowAccepts}. */
+interface InflowAcceptsOptions {
+    /**
+     * Price for the protected resource. Either a {@link PriceSpec} or a string in any of the three forms accepted by
+     * {@link PriceSpec.amount}.
+     */
+    price: PriceSpec | string;
+    /**
+     * Maximum lifetime (seconds) attached to each emitted entry. Defaults to `300` — matches the server-side
+     * `X402Constants.INFLOW_MAX_TIMEOUT_SECONDS` constant.
+     */
+    maxTimeoutSeconds?: number;
+    /**
+     * Optional filter: emit only entries whose `scheme` is in this list. Combined with
+     * {@link InflowAcceptsOptions.networks} as logical AND. Omit (or pass `undefined`) for "any scheme."
+     */
+    schemes?: PaymentScheme[];
+    /**
+     * Optional filter: emit only entries whose `network` is in this list. Combined with
+     * {@link InflowAcceptsOptions.schemes} as logical AND. Omit (or pass `undefined`) for "any network."
+     */
+    networks?: string[];
+}
+/**
+ * Build the `RouteConfig.accepts` array from the seller's cached `/v1/x402/config`. Each entry's `price` is
+ * pre-resolved to `AssetAmount` form (asset contract address + atomic-unit amount), so the foundation middleware never
+ * needs to consult the config itself. See
+ * {@link https://github.com/inflowpayai/inflow-node/blob/main/docs/x402/architecture.md#inflowaccepts-algorithm | the architecture doc}
+ * for the full emission and ordering rules.
+ *
+ * @throws {@link X402PriceParseError} When `price` matches none of the accepted forms.
+ */
+declare function inflowAccepts(client: InflowSellerClient, options: InflowAcceptsOptions): Promise<PaymentOption[]>;
+
+/**
+ * Structural shape of `@x402/express` and `@x402/hono`'s `SchemeRegistration` interface — `{ network, server }` —
+ * declared locally so this package stays platform-neutral. Both adapter packages export a `SchemeRegistration`
+ * interface composed of the same `@x402/core/types` types, so {@link InflowSchemeRegistration} is structurally
+ * assignable to either.
+ */
+interface InflowSchemeRegistration {
+    network: Network;
+    server: SchemeNetworkServer;
+}
+/**
+ * Build the passthrough `SchemeRegistration[]` for every `(scheme, network)` pair the seller's `/v1/x402/config` can
+ * emit. Pass the result as the third argument to `paymentMiddlewareFromConfig` — the foundation refuses to boot
+ * otherwise (`hasRegisteredScheme` is checked before facilitator support). Deduplicated: multiple assets on the same
+ * network collapse to one registration. See the architecture doc for the rationale.
+ */
+declare function inflowSchemeRegistrations(client: InflowSellerClient): Promise<InflowSchemeRegistration[]>;
+
+/**
+ * Thrown by `inflowAccepts` when a price string doesn't match any accepted form. See {@link PriceSpec.amount} for the
+ * grammar.
+ */
+declare class X402PriceParseError extends Error {
+    /** The original input that failed parsing. */
+    readonly input: string;
+    /** @param input - The {@link PriceSpec.amount} value that failed parsing. */
+    constructor(input: string);
+}
+
+export { type InflowAcceptsOptions, type InflowFacilitatorOptions, type InflowSchemeRegistration, type InflowSellerClient, type InflowSellerClientOptions, type InflowUnauthenticatedFacilitatorOptions, type PriceSpec, X402PriceParseError, createInflowFacilitator, createInflowSellerClient, createUnauthenticatedInflowFacilitator, inflowAccepts, inflowSchemeRegistrations };

package/dist/index.d.ts

@@ -0,0 +1,208 @@
+import { FacilitatorClient } from '@x402/core/server';
+import { Environment, X402ConfigResponse, X402FacilitatorSupportedResponse, PaymentScheme } from '@inflowpayai/x402';
+import { PaymentOption } from '@x402/core/http';
+import { Network, SchemeNetworkServer } from '@x402/core/types';
+
+/**
+ * Constructor options for {@link createInflowFacilitator}. The authed facilitator drops directly into the foundation V2
+ * middleware's `facilitatorClients` array (`@x402/express`, `@x402/hono`).
+ */
+interface InflowFacilitatorOptions {
+    /** Selects one of the public environments. */
+    environment: Environment;
+    /**
+     * InFlow API key. Sent as `X-API-KEY` on every outbound `verify` / `settle` / `getSupported` request. Required at the
+     * type level so a typo or env-var omission that leaves `apiKey` undefined can't silently degrade an authed deployment
+     * to facilitator-mode — sellers who want the authless path pick {@link createUnauthenticatedInflowFacilitator}
+     * explicitly.
+     */
+    apiKey: string;
+    /** Override the environment-derived URL. Takes precedence over `environment`. */
+    baseUrl?: string;
+}
+/**
+ * Constructor options for {@link createUnauthenticatedInflowFacilitator}.
+ *
+ * The unauthenticated factory is the explicit escape hatch for facilitator-only deployments (self-hosted,
+ * public-facilitator mode, test harnesses) that don't have a seller account. Sends no `X-API-KEY` header on outbound
+ * `verify` / `settle` / `getSupported` requests.
+ */
+interface InflowUnauthenticatedFacilitatorOptions {
+    /** Selects one of the public environments. */
+    environment: Environment;
+    /** Override the environment-derived URL. Takes precedence over `environment`. */
+    baseUrl?: string;
+}
+
+/**
+ * Construct an authed InFlow facilitator. The returned object satisfies the foundation V2 `FacilitatorClient` contract
+ * from `@x402/core` (`verify` / `settle` / `getSupported` only) and drops directly into the foundation middleware's
+ * `facilitatorClients` array (`@x402/express`, `@x402/hono`) — first claimer of a `(scheme, network)` in declaration
+ * order wins verify/settle routing.
+ *
+ * Seller-authed endpoints (`/v1/x402/config`, `getSignerAddresses`) live on the separate
+ * {@link createInflowSellerClient} factory; this client carries the seller's API key only for `verify` / `settle` /
+ * `getSupported`, where it enables server-side `payTo`-against-wallets validation.
+ *
+ * `getSupported()` is cached lazily in-memory for 60 minutes after the first call; concurrent callers share an
+ * in-flight refresh. There is no priming step — the foundation middleware calls `getSupported()` once at
+ * `x402ResourceServer.initialize()` and the cache is populated then.
+ *
+ * @param options - {@link InflowFacilitatorOptions}.
+ * @returns A foundation `FacilitatorClient`.
+ */
+declare function createInflowFacilitator(options: InflowFacilitatorOptions): FacilitatorClient;
+/**
+ * Anonymous sibling of {@link createInflowFacilitator} — same caches and contract, no `X-API-KEY` header. For
+ * facilitator-only deployments (self-hosted, public-facilitator mode, test harnesses).
+ */
+declare function createUnauthenticatedInflowFacilitator(options: InflowUnauthenticatedFacilitatorOptions): FacilitatorClient;
+
+/**
+ * Constructor options for {@link createInflowSellerClient}.
+ *
+ * `apiKey` is required at the type level. `/v1/x402/config` is a seller-authed endpoint — there's no facilitator-mode
+ * equivalent — so an unauthenticated seller client has no useful surface to expose.
+ */
+interface InflowSellerClientOptions {
+    /** Selects one of the public environments. */
+    environment: Environment;
+    /** InFlow API key sent on every request as `X-API-KEY`. Required. */
+    apiKey: string;
+    /** Override the environment-derived URL. Takes precedence over `environment`. */
+    baseUrl?: string;
+}
+/**
+ * Seller-authed InFlow client. Wraps the `/v1/x402/config` and `/v1/x402/supported` endpoints and surfaces
+ * signer-address discovery on top of `getSupported()`. Drives {@link inflowAccepts} and any operator- facing
+ * introspection.
+ *
+ * Construct via {@link createInflowSellerClient}. The factory primes both caches in parallel before resolving, so
+ * methods on the returned instance hit in-memory data for the lifetime of the 60-minute TTL.
+ *
+ * @see createInflowSellerClient
+ */
+interface InflowSellerClient {
+    /**
+     * Fetch the seller config (assets, wallets, payment methods, sellerId). Cached for 60 minutes after the factory's
+     * prime call.
+     *
+     * @returns The current `X402ConfigResponse` (re-exported from `@inflowpayai/x402`).
+     */
+    config(): Promise<X402ConfigResponse>;
+    /**
+     * Force a refetch of `GET /v1/x402/config` and replace the cached value.
+     *
+     * @returns The freshly fetched `X402ConfigResponse` (re-exported from `@inflowpayai/x402`).
+     */
+    refreshConfig(): Promise<X402ConfigResponse>;
+    /**
+     * Force a refetch of `GET /v1/x402/supported` and replace the cached value.
+     *
+     * @returns The freshly fetched `X402FacilitatorSupportedResponse` (re-exported from `@inflowpayai/x402`).
+     */
+    refreshSupported(): Promise<X402FacilitatorSupportedResponse>;
+    /**
+     * Signer addresses advertised by the facilitator for the given network.
+     *
+     * Lookup is exact-match on `network` first; if no entry exists and the input is CAIP-2 shaped
+     * (`<namespace>:<reference>`), it falls back to a `<namespace>:*` wildcard key so external facilitators that follow
+     * the V2 spec's wildcard form interop. Returns `[]` when nothing matches.
+     *
+     * @param network - CAIP-2 string (e.g. `'eip155:8453'` or `'inflow:1'`).
+     * @returns The configured signer addresses, or `[]` when none match.
+     */
+    getSignerAddresses(network: string): Promise<readonly string[]>;
+}
+/**
+ * Construct an {@link InflowSellerClient}.
+ *
+ * The factory primes the config and `getSupported()` caches in parallel before resolving, so the first downstream call
+ * ({@link inflowAccepts}, `getSignerAddresses`, etc.) is synchronous against in-memory data. Cost: one round trip at
+ * startup; benefit: synchronous downstream use.
+ *
+ * @param options - {@link InflowSellerClientOptions}.
+ * @returns A promise resolving to a primed {@link InflowSellerClient}.
+ */
+declare function createInflowSellerClient(options: InflowSellerClientOptions): Promise<InflowSellerClient>;
+
+/** Price spec accepted by {@link inflowAccepts}. */
+interface PriceSpec {
+    /**
+     * Amount string. Three accepted forms (all supporting up to 8 decimal places):
+     *
+     * - `'$<integer>(.<decimals>)?'` — implies USD (e.g. `'$0.01'`, `'$10.00000001'`).
+     * - `'<integer>(.<decimals>)? <CURRENCY>'` — currency from suffix (e.g. `'0.01 USDC'`, `'0.5 USDT'`, `'1 USD'`).
+     * - `'<integer>(.<decimals>)?'` — bare numeric; the {@link PriceSpec.currency} field is required in this case.
+     */
+    amount: string;
+    /**
+     * Currency override. When set, takes precedence over any currency embedded in {@link PriceSpec.amount}. Required when
+     * `amount` is in bare numeric form. `'USD'` is a wildcard that matches any stablecoin the seller has configured.
+     */
+    currency?: 'USD' | 'USDC' | 'USDT' | 'PYUSD' | (string & {});
+}
+/** Options accepted by {@link inflowAccepts}. */
+interface InflowAcceptsOptions {
+    /**
+     * Price for the protected resource. Either a {@link PriceSpec} or a string in any of the three forms accepted by
+     * {@link PriceSpec.amount}.
+     */
+    price: PriceSpec | string;
+    /**
+     * Maximum lifetime (seconds) attached to each emitted entry. Defaults to `300` — matches the server-side
+     * `X402Constants.INFLOW_MAX_TIMEOUT_SECONDS` constant.
+     */
+    maxTimeoutSeconds?: number;
+    /**
+     * Optional filter: emit only entries whose `scheme` is in this list. Combined with
+     * {@link InflowAcceptsOptions.networks} as logical AND. Omit (or pass `undefined`) for "any scheme."
+     */
+    schemes?: PaymentScheme[];
+    /**
+     * Optional filter: emit only entries whose `network` is in this list. Combined with
+     * {@link InflowAcceptsOptions.schemes} as logical AND. Omit (or pass `undefined`) for "any network."
+     */
+    networks?: string[];
+}
+/**
+ * Build the `RouteConfig.accepts` array from the seller's cached `/v1/x402/config`. Each entry's `price` is
+ * pre-resolved to `AssetAmount` form (asset contract address + atomic-unit amount), so the foundation middleware never
+ * needs to consult the config itself. See
+ * {@link https://github.com/inflowpayai/inflow-node/blob/main/docs/x402/architecture.md#inflowaccepts-algorithm | the architecture doc}
+ * for the full emission and ordering rules.
+ *
+ * @throws {@link X402PriceParseError} When `price` matches none of the accepted forms.
+ */
+declare function inflowAccepts(client: InflowSellerClient, options: InflowAcceptsOptions): Promise<PaymentOption[]>;
+
+/**
+ * Structural shape of `@x402/express` and `@x402/hono`'s `SchemeRegistration` interface — `{ network, server }` —
+ * declared locally so this package stays platform-neutral. Both adapter packages export a `SchemeRegistration`
+ * interface composed of the same `@x402/core/types` types, so {@link InflowSchemeRegistration} is structurally
+ * assignable to either.
+ */
+interface InflowSchemeRegistration {
+    network: Network;
+    server: SchemeNetworkServer;
+}
+/**
+ * Build the passthrough `SchemeRegistration[]` for every `(scheme, network)` pair the seller's `/v1/x402/config` can
+ * emit. Pass the result as the third argument to `paymentMiddlewareFromConfig` — the foundation refuses to boot
+ * otherwise (`hasRegisteredScheme` is checked before facilitator support). Deduplicated: multiple assets on the same
+ * network collapse to one registration. See the architecture doc for the rationale.
+ */
+declare function inflowSchemeRegistrations(client: InflowSellerClient): Promise<InflowSchemeRegistration[]>;
+
+/**
+ * Thrown by `inflowAccepts` when a price string doesn't match any accepted form. See {@link PriceSpec.amount} for the
+ * grammar.
+ */
+declare class X402PriceParseError extends Error {
+    /** The original input that failed parsing. */
+    readonly input: string;
+    /** @param input - The {@link PriceSpec.amount} value that failed parsing. */
+    constructor(input: string);
+}
+
+export { type InflowAcceptsOptions, type InflowFacilitatorOptions, type InflowSchemeRegistration, type InflowSellerClient, type InflowSellerClientOptions, type InflowUnauthenticatedFacilitatorOptions, type PriceSpec, X402PriceParseError, createInflowFacilitator, createInflowSellerClient, createUnauthenticatedInflowFacilitator, inflowAccepts, inflowSchemeRegistrations };