@bosonprotocol/x402-server 0.1.0-alpha-0

package/dist/cjs/handlers/index.d.ts

@@ -0,0 +1,267 @@
+import { EscrowPaymentRequirements, Address } from '@bosonprotocol/x402-core/schemes/escrow';
+import { EscrowNextActions, ExchangeState, DisputeState, ChannelRegistry } from '@bosonprotocol/x402-actions';
+import { ExchangeReader } from '../onchain/index.js';
+import { F as FacilitatorClient } from '../client-tnrpqVMW.js';
+import { X as X402bServerConfig, F as FulfillmentRecoveryEntry, b as CoreSdkReadAdapter } from '../config-CBr9qMps.js';
+import { ExchangeActionId } from '@bosonprotocol/x402-core/state-machine';
+import { Hex } from 'viem';
+import '@bosonprotocol/x402-facilitator';
+import 'zod';
+import '@bosonprotocol/core-sdk';
+
+type HandlerStatus = 200 | 400 | 402 | 404 | 409 | 500 | 502;
+type HandlerResult<TBody> = {
+    ok: true;
+    status: 200;
+    body: TBody & {
+        nextActions: EscrowNextActions;
+    };
+} | {
+    ok: false;
+    status: Exclude<HandlerStatus, 200>;
+    body: HandlerErrorBody;
+};
+/**
+ * Result shape for handlers whose success body does NOT carry a
+ * `nextActions` envelope — used by entity-keyed actions
+ * (`boson-withdrawFunds`) and the read-only `available-funds`
+ * endpoint, neither of which advance the exchange state machine.
+ */
+type PlainHandlerResult<TBody> = {
+    ok: true;
+    status: 200;
+    body: TBody;
+} | {
+    ok: false;
+    status: Exclude<HandlerStatus, 200>;
+    body: HandlerErrorBody;
+};
+interface HandlerErrorBody {
+    /** Stable identifier — caller branches on this rather than the human-readable `reason`. */
+    code: string;
+    reason: string;
+    /** Optional rich detail — validator field/expected/got, facilitator code, etc. */
+    details?: unknown;
+}
+interface HandlerWarning {
+    /** Stable identifier — caller branches on this rather than the human-readable `reason`. */
+    code: string;
+    reason: string;
+    /** Optional rich detail — tx hash, exchange id, deferred operation, etc. */
+    details?: unknown;
+}
+declare function handlerOk<TBody>(body: TBody & {
+    nextActions: EscrowNextActions;
+}): HandlerResult<TBody>;
+declare function plainHandlerOk<TBody>(body: TBody): PlainHandlerResult<TBody>;
+declare function handlerErr(status: Exclude<HandlerStatus, 200>, code: string, reason: string, details?: unknown): HandlerResult<never> & PlainHandlerResult<never>;
+
+interface CommitHandlerInput {
+    /** Raw `X-PAYMENT` header value (base64'd JSON). */
+    paymentHeader: string | undefined | null;
+    /** The 402 `PaymentRequirements` the buyer is responding to. */
+    requirements: EscrowPaymentRequirements;
+}
+interface CommitHandlerContext {
+    config: X402bServerConfig;
+    facilitator: FacilitatorClient;
+    exchangeReader: ExchangeReader;
+    fulfillmentRecoveryStore: Map<string, FulfillmentRecoveryEntry>;
+    /**
+     * Per-exchange fulfillment option policy. Flow A writes the ids
+     * advertised by the original requirements so the redeem-time choice
+     * is constrained to the offer's own channel set.
+     */
+    exchangeFulfillmentOptionStore: Map<string, readonly string[]>;
+}
+interface CommitOk {
+    exchangeId: string;
+    txHash: string;
+    /**
+     * Non-fatal post-settle conditions. Today only Flow B uses this slot —
+     * the on-chain redeem may have succeeded while the configured channel
+     * adapter's `onCommit(...)` failed (the buyer's funds and voucher are
+     * already gone; the seller's host needs to recover the delivery target
+     * out-of-band). The exchange state is the wire-format source of truth;
+     * warnings are advisory.
+     */
+    warnings?: HandlerWarning[];
+}
+/**
+ * Flow A — `boson-createOfferAndCommit`. Settles via facilitator,
+ * expects the resulting exchange in `COMMITTED`, returns 200 with
+ * `nextActions` advertising the legal post-COMMITTED transitions.
+ */
+declare function handleCommit(input: CommitHandlerInput, ctx: CommitHandlerContext): Promise<HandlerResult<CommitOk>>;
+/**
+ * Flow B — `boson-createOfferCommitAndRedeem`. Same pipeline as
+ * `handleCommit` but verifies the exchange reached `REDEEMED`.
+ */
+declare function handleCommitAndRedeem(input: CommitHandlerInput, ctx: CommitHandlerContext): Promise<HandlerResult<CommitOk>>;
+
+/** Per-action inputs accepted by every post-commit convenience handler. */
+interface PerformActionInput {
+    exchangeId: string;
+    /** ABI-encoded `BosonMetaTx` tuple — see `encodeSignedPayload` in `@bosonprotocol/x402-facilitator`. */
+    signedPayload: Hex;
+}
+/**
+ * Redeem-time variant of `PerformActionInput`. Carries the buyer's
+ * `fulfillment` selection for Flow A — `data` is the delivery target
+ * the redeem-time channel adapter persists. Required when the
+ * original 402 advertised `fulfillment.required = true`; omitted
+ * otherwise.
+ */
+interface RedeemHandlerInput extends PerformActionInput {
+    fulfillment?: {
+        option: string;
+        data: Record<string, unknown> | null;
+    };
+}
+interface PerformActionContext {
+    config: X402bServerConfig;
+    facilitator: FacilitatorClient;
+    exchangeReader: ExchangeReader;
+}
+interface RedeemHandlerContext extends PerformActionContext {
+    exchangeFulfillmentOptionStore: Map<string, readonly string[]>;
+    fulfillmentRecoveryStore: Map<string, FulfillmentRecoveryEntry>;
+}
+interface PerformActionOk {
+    txHash: string;
+    warnings?: HandlerWarning[];
+}
+/**
+ * Generic exchange-keyed post-commit handler — wired from each of the
+ * per-action wrappers below. Entity-keyed actions (e.g. `withdrawFunds`)
+ * have their own handler in `./withdraw-funds.ts`.
+ */
+declare function handlePerformAction(action: ExchangeActionId, input: PerformActionInput, ctx: PerformActionContext): Promise<HandlerResult<PerformActionOk>>;
+/**
+ * Redeem handler. Validates the buyer's `fulfillment` selection (if
+ * present) against the offer's advertised option set and the host's
+ * channel registry, runs the channel's `validate` up-front, then
+ * forwards to the facilitator. The corresponding
+ * `onCommit(exchangeId, data)` upsert is deferred until *after* the
+ * facilitator + state verification confirm the exchange reached
+ * `REDEEMED`, so a failed redeem leaves the stored delivery target
+ * unchanged. The voucher NFT is transferable; whichever wallet signs
+ * `boson-redeem` supplies the delivery data — it's the redeemer's
+ * choice end-to-end.
+ */
+declare function handleRedeem(input: RedeemHandlerInput, ctx: RedeemHandlerContext): Promise<HandlerResult<PerformActionOk>>;
+/** Per-action sugar — preserves the action id at the type level. */
+declare const handleComplete: (input: PerformActionInput, ctx: PerformActionContext) => Promise<HandlerResult<PerformActionOk>>;
+declare const handleDisputeRaise: (input: PerformActionInput, ctx: PerformActionContext) => Promise<HandlerResult<PerformActionOk>>;
+declare const handleDisputeResolve: (input: PerformActionInput, ctx: PerformActionContext) => Promise<HandlerResult<PerformActionOk>>;
+declare const handleDisputeRetract: (input: PerformActionInput, ctx: PerformActionContext) => Promise<HandlerResult<PerformActionOk>>;
+declare const handleDisputeEscalate: (input: PerformActionInput, ctx: PerformActionContext) => Promise<HandlerResult<PerformActionOk>>;
+
+interface WithdrawFundsBaseInput {
+    /** ABI-encoded `BosonMetaTx` tuple — see `encodeSignedPayload` in `@bosonprotocol/x402-evm/codec`. */
+    signedPayload: Hex;
+}
+type WithdrawFundsInput = WithdrawFundsBaseInput & ({
+    entityId: string;
+} | {
+    address: string;
+    role?: "buyer" | "seller";
+});
+interface WithdrawFundsContext {
+    config: X402bServerConfig;
+    facilitator: FacilitatorClient;
+    coreSdkRead: CoreSdkReadAdapter;
+}
+interface WithdrawFundsOk {
+    txHash: string;
+    entityId: string;
+    role?: "buyer" | "seller";
+}
+declare function handleWithdrawFunds(input: WithdrawFundsInput, ctx: WithdrawFundsContext): Promise<PlainHandlerResult<WithdrawFundsOk>>;
+
+interface AvailableFundsEntry {
+    tokenAddress: Address;
+    tokenSymbol: string;
+    tokenName: string;
+    decimals: number;
+    availableAmount: string;
+}
+interface AvailableFundsBody {
+    entityId: string;
+    /** Present when the caller looked up by `address`; omitted when looked up by `entityId`. */
+    role?: "buyer" | "seller";
+    funds: AvailableFundsEntry[];
+}
+type AvailableFundsQuery = {
+    entityId: string;
+} | {
+    address: string;
+    role?: "buyer" | "seller";
+};
+interface AvailableFundsContext {
+    coreSdkRead: CoreSdkReadAdapter;
+}
+declare function handleGetAvailableFunds(query: AvailableFundsQuery, ctx: AvailableFundsContext): Promise<PlainHandlerResult<AvailableFundsBody>>;
+
+interface ResolveEntityInput {
+    address: string;
+    role?: "buyer" | "seller";
+}
+interface ResolveEntityOk {
+    ok: true;
+    entityId: string;
+    role: "buyer" | "seller";
+}
+type ResolveEntityError = {
+    ok: false;
+    code: "NOT_FOUND";
+    reason: string;
+} | {
+    ok: false;
+    code: "AMBIGUOUS";
+    reason: string;
+    /** Seller ids matching the address (one or many). Absent when no sellers matched. */
+    sellerIds?: string[];
+    /** Buyer ids matching the address (one or many). Absent when no buyers matched. */
+    buyerIds?: string[];
+} | {
+    ok: false;
+    code: "SUBGRAPH_FAILURE";
+    reason: string;
+};
+type ResolveEntityResult = ResolveEntityOk | ResolveEntityError;
+declare function resolveEntityId(coreSdk: CoreSdkReadAdapter, input: ResolveEntityInput): Promise<ResolveEntityResult>;
+
+/** Boson account `entityId` — uint256 in decimal-string form, no leading zeros. */
+declare const DECIMAL_UINT_RE: RegExp;
+/** 20-byte EVM address, 0x-prefixed, any letter case (we normalise downstream). */
+declare const ADDRESS_RE: RegExp;
+/**
+ * Hex-string check for `signedPayload`. Requires `0x` followed by an
+ * *even* number of hex digits so the body decodes to whole bytes —
+ * odd-length payloads like `0xabc` would surface as
+ * `signedPayload decode failed: …` deep in the facilitator pipeline,
+ * which is a less precise 502 than the adapter-level 400 this regex
+ * catches. Stricter than core's `HEX_BYTES` (which permits odd
+ * lengths) so we keep this one local.
+ */
+declare const HEX_BYTES_RE: RegExp;
+
+type EmitNextActionsInput = {
+    exchangeId: string;
+} & ({
+    exchangeState: Exclude<ExchangeState, typeof ExchangeState.DISPUTED>;
+    disputeState?: never;
+} | {
+    exchangeState: typeof ExchangeState.DISPUTED;
+    disputeState: DisputeState;
+});
+/**
+ * Build the `nextActions` envelope a handler attaches to its 200 body.
+ * Pure wrapper; the logic beyond `deriveNextActions` is the
+ * `DISPUTED → disputeState required` narrowing and the optional
+ * facilitator-endpoint stamp.
+ */
+declare function emitNextActions(input: EmitNextActionsInput, registry: ChannelRegistry, facilitatorUrl?: string): EscrowNextActions;
+
+export { ADDRESS_RE, type AvailableFundsBody, type AvailableFundsContext, type AvailableFundsEntry, type AvailableFundsQuery, type CommitHandlerContext, type CommitHandlerInput, type CommitOk, DECIMAL_UINT_RE, type EmitNextActionsInput, HEX_BYTES_RE, type HandlerErrorBody, type HandlerResult, type HandlerStatus, type HandlerWarning, type PerformActionContext, type PerformActionInput, type PerformActionOk, type PlainHandlerResult, type RedeemHandlerContext, type RedeemHandlerInput, type ResolveEntityError, type ResolveEntityInput, type ResolveEntityOk, type ResolveEntityResult, type WithdrawFundsContext, type WithdrawFundsInput, type WithdrawFundsOk, emitNextActions, handleCommit, handleCommitAndRedeem, handleComplete, handleDisputeEscalate, handleDisputeRaise, handleDisputeResolve, handleDisputeRetract, handleGetAvailableFunds, handlePerformAction, handleRedeem, handleWithdrawFunds, handlerErr, handlerOk, plainHandlerOk, resolveEntityId };