@relai-fi/x402 0.5.39 → 0.6.0-rc.0

package/dist/server-t9nKvoKl.d.cts

@@ -0,0 +1,713 @@
+import { a as RelaiNetwork } from './types-Y9ni5XwY.cjs';
+import './relay-feedback.cjs';
+
+interface PluginContext {
+    /** Network for this endpoint */
+    network: RelaiNetwork;
+    /** Price in USD */
+    price: number;
+    /** Request path */
+    path: string;
+    /** HTTP method */
+    method: string;
+}
+interface PluginResult {
+    /** If true, skip payment and serve content for free */
+    skip?: boolean;
+    /** If true, reject the request entirely (e.g. service unhealthy) */
+    reject?: boolean;
+    /** HTTP status code when rejecting (default: 503) */
+    rejectStatus?: number;
+    /** Error message when rejecting */
+    rejectMessage?: string;
+    /** Extra response headers to set */
+    headers?: Record<string, string>;
+    /** Metadata attached to req.pluginMeta */
+    meta?: Record<string, unknown>;
+}
+interface RelaiPlugin {
+    /** Unique plugin name */
+    name: string;
+    /**
+     * Called before the 402 payment check.
+     * Return { skip: true } to bypass payment entirely.
+     */
+    beforePaymentCheck?(req: any, ctx: PluginContext): Promise<PluginResult>;
+    /**
+     * Called after a successful payment settlement.
+     * Use for analytics, logging, webhooks, etc.
+     */
+    afterSettled?(req: any, result: SettleResult, ctx: PluginContext): Promise<void>;
+    /**
+     * Called once when the Relai instance initializes (server start).
+     * Use to sync config to RelAI backend or validate credentials.
+     */
+    onInit?(): Promise<void>;
+    /**
+     * Called before sending the 402 response. Allows plugins to add
+     * extensions or modify the response body (e.g. bridge info).
+     */
+    enrich402Response?(response: any, ctx: PluginContext): any;
+}
+interface FreeTierPluginConfig {
+    /** Service key (sk_live_...) for syncing with RelAI backend. If omitted, runs in local in-memory mode. */
+    serviceKey?: string;
+    /** Max free calls per buyer per period */
+    perBuyerLimit: number;
+    /** Reset period for per-buyer counters */
+    resetPeriod?: 'none' | 'daily' | 'monthly';
+    /** Optional global cap across all buyers */
+    globalCap?: number;
+    /** Specific paths to apply free tier to (default: '*' = all) */
+    paths?: string[];
+    /** Override RelAI API base URL (default: https://api.relai.fi) */
+    baseUrl?: string;
+    /** Cache TTL in ms for check results (default: 5000) */
+    cacheTtlMs?: number;
+}
+/**
+ * Free Tier plugin - gives buyers a number of free API calls
+ * before requiring payment.
+ *
+ * State is stored in the RelAI backend, keyed by your service key.
+ * Config can be set here (SDK-side) or overridden in the relai.fi dashboard.
+ *
+ * @example
+ * ```typescript
+ * import Relai from '@relai-fi/x402/server';
+ * import { freeTier } from '@relai-fi/x402/plugins';
+ *
+ * const relai = new Relai({
+ *   network: 'base',
+ *   plugins: [
+ *     freeTier({
+ *       serviceKey: process.env.RELAI_SERVICE_KEY!,
+ *       perBuyerLimit: 10,
+ *       resetPeriod: 'daily',
+ *     }),
+ *   ],
+ * });
+ *
+ * app.get('/api/data', relai.protect({
+ *   payTo: '0xYourWallet',
+ *   price: 0.01,
+ * }), (req, res) => {
+ *   res.json({ data: 'paid content' });
+ * });
+ * ```
+ */
+interface BridgePluginConfig {
+    /** Service key (sk_live_...) for tracking bridge usage per API owner */
+    serviceKey?: string;
+    /** RelAI API base URL (default: https://api.relai.fi) */
+    baseUrl?: string;
+    /** Override settle endpoint (auto-discovered from /bridge/info if not set) */
+    settleEndpoint?: string;
+    /** Override supported source chains (auto-discovered if not set) */
+    supportedSourceChains?: string[];
+    /** Override supported source assets (auto-discovered if not set) */
+    supportedSourceAssets?: string[];
+    /** Override bridge payTo map: { [caip2]: address } */
+    payTo?: Record<string, string>;
+    /** Override Solana fee payer address (auto-discovered if not set) */
+    feePayerSvm?: string;
+    /** Override payment facilitator URL */
+    paymentFacilitator?: string;
+    /** Bridge fee in basis points (default: auto-discovered) */
+    feeBps?: number;
+}
+/**
+ * Bridge plugin - enables cross-chain payments via the RelAI bridge.
+ *
+ * When a buyer's wallet is on a different chain than the merchant accepts,
+ * the client SDK can automatically route the payment through the bridge.
+ * This plugin adds `extensions.bridge` to the 402 response with all the
+ * info the client needs to execute a cross-chain payment.
+ *
+ * @example
+ * ```typescript
+ * import Relai from '@relai-fi/x402/server';
+ * import { bridge } from '@relai-fi/x402/plugins';
+ *
+ * const relai = new Relai({
+ *   network: 'skale-base',
+ *   plugins: [
+ *     bridge(), // auto-discovers from https://api.relai.fi
+ *   ],
+ * });
+ *
+ * // Buyer on Solana can now pay for a SKALE endpoint
+ * app.get('/api/data', relai.protect({
+ *   payTo: '0xYourWallet',
+ *   price: 0.05,
+ * }), (req, res) => {
+ *   res.json({ data: 'paid content' });
+ * });
+ * ```
+ */
+declare function bridge(config?: BridgePluginConfig): RelaiPlugin;
+/**
+ * Extended plugin interface with data export for free tier.
+ */
+interface FreeTierPlugin extends RelaiPlugin {
+    /** Export all in-memory usage data (local mode only). Returns null when using cloud mode. */
+    getUsageData(): FreeTierUsageExport | null;
+    /** Whether plugin is running in local (in-memory) or cloud (RelAI backend) mode. */
+    readonly mode: 'local' | 'cloud';
+}
+interface FreeTierUsageExport {
+    mode: 'local';
+    config: {
+        perBuyerLimit: number;
+        resetPeriod: string;
+        globalCap: number | null;
+        paths: string[];
+    };
+    /** Per-buyer usage entries */
+    usage: Array<{
+        buyerId: string;
+        path: string;
+        count: number;
+        periodStart: string;
+        lastCall: string;
+    }>;
+    globalCount: number;
+    exportedAt: string;
+}
+declare function freeTier(config: FreeTierPluginConfig): FreeTierPlugin;
+interface ShieldPluginConfig {
+    /**
+     * Custom health check function. Return true if the service is healthy.
+     * Takes priority over `healthUrl` if both are provided.
+     */
+    healthCheck?: () => Promise<boolean> | boolean;
+    /**
+     * URL to probe. A 2xx response means healthy.
+     * Ignored if `healthCheck` is provided.
+     */
+    healthUrl?: string;
+    /** Timeout in ms for the health probe (default: 5000) */
+    timeoutMs?: number;
+    /** Cache the health result for this many ms (default: 10000) */
+    cacheTtlMs?: number;
+    /** Message returned to the caller when unhealthy (default: 'Service temporarily unavailable. Please try again later.') */
+    unhealthyMessage?: string;
+    /** HTTP status code when unhealthy (default: 503) */
+    unhealthyStatus?: number;
+}
+/**
+ * Shield plugin — protects buyers from paying for unhealthy endpoints.
+ *
+ * Before the server returns a 402, Shield runs a health check (custom
+ * function or URL probe). If the service is down, the request is rejected
+ * with 503 instead of asking for payment.
+ *
+ * @example
+ * ```typescript
+ * import Relai from '@relai-fi/x402/server';
+ * import { shield } from '@relai-fi/x402/plugins';
+ *
+ * const relai = new Relai({
+ *   network: 'base',
+ *   plugins: [
+ *     shield({
+ *       healthUrl: 'https://my-api.com/health',
+ *       timeoutMs: 3000,
+ *     }),
+ *   ],
+ * });
+ *
+ * // If /health is down, buyers get 503 instead of 402
+ * app.get('/api/data', relai.protect({
+ *   payTo: '0xYourWallet',
+ *   price: 0.01,
+ * }), (req, res) => {
+ *   res.json({ data: 'premium content' });
+ * });
+ * ```
+ */
+declare function shield(config?: ShieldPluginConfig): RelaiPlugin;
+interface PreflightPluginConfig {
+    /**
+     * Base URL of the API server (e.g. 'https://my-api.com').
+     * The plugin appends the request path to form the probe URL.
+     * **Required** — the plugin needs to know where to send the probe.
+     */
+    baseUrl: string;
+    /** Timeout in ms for the preflight probe (default: 3000) */
+    timeoutMs?: number;
+    /** Cache the probe result for this many ms (default: 5000) */
+    cacheTtlMs?: number;
+    /** Custom unhealthy message (default: 'Endpoint not responding. Please try again later.') */
+    unhealthyMessage?: string;
+    /** HTTP status code when endpoint unreachable (default: 503) */
+    unhealthyStatus?: number;
+}
+/**
+ * Preflight plugin — verifies the specific endpoint responds before payment.
+ *
+ * Unlike Shield (global health check), Preflight probes the **actual endpoint**
+ * the buyer is requesting. It sends a HEAD request with `X-Preflight: true` —
+ * the Relai middleware responds 200 instantly without triggering payment.
+ * If the endpoint doesn't respond, the buyer gets 503 instead of 402.
+ *
+ * @example
+ * ```typescript
+ * import Relai from '@relai-fi/x402/server';
+ * import { preflight } from '@relai-fi/x402/plugins';
+ *
+ * const relai = new Relai({
+ *   network: 'base',
+ *   plugins: [
+ *     preflight({ baseUrl: 'https://my-api.com' }),
+ *   ],
+ * });
+ *
+ * app.get('/api/data', relai.protect({
+ *   payTo: '0xYourWallet',
+ *   price: 0.01,
+ * }), (req, res) => {
+ *   res.json({ data: 'premium content' });
+ * });
+ * ```
+ */
+declare function preflight(config: PreflightPluginConfig): RelaiPlugin;
+type CircuitState = 'closed' | 'open' | 'half-open';
+interface CircuitBreakerPluginConfig {
+    /**
+     * Number of consecutive failures before the circuit opens.
+     * Default: 5
+     */
+    failureThreshold?: number;
+    /**
+     * Time in ms the circuit stays open before moving to half-open.
+     * Default: 30000 (30 seconds)
+     */
+    resetTimeMs?: number;
+    /**
+     * Number of successful requests in half-open state before closing the circuit.
+     * Default: 2
+     */
+    halfOpenSuccesses?: number;
+    /** HTTP status code when circuit is open (default: 503) */
+    openStatus?: number;
+    /** Error message when circuit is open */
+    openMessage?: string;
+    /**
+     * HTTP status codes considered as failures.
+     * Default: [500, 502, 503, 504]
+     */
+    failureCodes?: number[];
+    /**
+     * Track failures globally or per-path.
+     * Default: 'per-path'
+     */
+    scope?: 'global' | 'per-path';
+}
+/**
+ * Circuit Breaker plugin — tracks failure history and opens the circuit
+ * after repeated failures, preventing buyers from paying for broken endpoints.
+ *
+ * Unlike Shield/Preflight (real-time probes), Circuit Breaker is **zero-latency** —
+ * it makes no additional HTTP requests. Instead, it tracks `afterSettled` outcomes
+ * and rejects requests when the failure rate exceeds the threshold.
+ *
+ * States:
+ * - **closed** — normal operation, requests flow through
+ * - **open** — too many failures, requests are rejected with 503
+ * - **half-open** — after resetTime, allows a few test requests through
+ *
+ * @example
+ * ```typescript
+ * import Relai from '@relai-fi/x402/server';
+ * import { circuitBreaker } from '@relai-fi/x402/plugins';
+ *
+ * const relai = new Relai({
+ *   network: 'base',
+ *   plugins: [
+ *     circuitBreaker({ failureThreshold: 5, resetTimeMs: 30000 }),
+ *   ],
+ * });
+ * ```
+ */
+declare function circuitBreaker(config?: CircuitBreakerPluginConfig): RelaiPlugin;
+interface RefundPluginConfig {
+    /**
+     * HTTP status codes that trigger a refund/credit after payment.
+     * Default: [500, 502, 503, 504]
+     */
+    triggerCodes?: number[];
+    /**
+     * What to do when a refund is triggered.
+     * - 'credit': record a credit that the free-tier plugin can consume later
+     * - 'log': just log the event (useful with a custom onRefund callback)
+     * Default: 'credit'
+     */
+    mode?: 'credit' | 'log';
+    /**
+     * Called whenever a refund event is triggered.
+     * Use for external refund processing, logging, or notifications.
+     */
+    onRefund?: (event: RefundEvent) => void | Promise<void>;
+    /**
+     * Also trigger refund when settlement itself fails (result.success === false).
+     * Default: true
+     */
+    refundOnSettlementFailure?: boolean;
+}
+interface RefundEvent {
+    /** Buyer wallet address */
+    payer: string;
+    /** Transaction ID of the original payment */
+    transactionId: string;
+    /** Network used */
+    network: string;
+    /** Amount paid in USD */
+    amount: number;
+    /** Request path */
+    path: string;
+    /** Reason for the refund */
+    reason: 'endpoint_error' | 'settlement_failure' | 'timeout';
+    /** HTTP status code that triggered the refund (if applicable) */
+    statusCode?: number;
+    /** Timestamp */
+    timestamp: number;
+}
+/**
+ * Refund plugin — automatically handles refund/credit when a paid request fails.
+ *
+ * After payment settles, if the endpoint returns an error (e.g. 500),
+ * the plugin records a credit or calls your custom `onRefund` handler.
+ * Credits can be consumed by the free-tier plugin on the next request.
+ *
+ * @example
+ * ```typescript
+ * import Relai from '@relai-fi/x402/server';
+ * import { refund } from '@relai-fi/x402/plugins';
+ *
+ * const relai = new Relai({
+ *   network: 'base',
+ *   plugins: [
+ *     refund({
+ *       triggerCodes: [500, 502, 503],
+ *       onRefund: (event) => {
+ *         console.log(`Refund for ${event.payer}: $${event.amount} on ${event.path}`);
+ *         // Notify buyer, record in DB, etc.
+ *       },
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+declare function refund(config?: RefundPluginConfig): RelaiPlugin;
+
+interface ScorePluginConfig {
+    /**
+     * ERC-8004 agentId (NFT tokenId) for this API.
+     * Find yours in the RelAI dashboard under "On-chain Identity".
+     */
+    agentId: string | number;
+    /**
+     * SKALE Base Sepolia RPC URL.
+     * Default: https://base-sepolia-testnet.skalenodes.com/v1/jubilant-horrible-ancha
+     */
+    rpcUrl?: string;
+    /**
+     * ERC-8004 IdentityRegistry contract address.
+     * Default: process.env.ERC8004_IDENTITY_REGISTRY
+     */
+    identityRegistryAddress?: string;
+    /**
+     * ERC-8004 ReputationRegistry contract address.
+     * Default: process.env.ERC8004_REPUTATION_REGISTRY
+     */
+    reputationRegistryAddress?: string;
+    /**
+     * Cache TTL in ms (default: 5 minutes).
+     */
+    cacheTtlMs?: number;
+}
+/**
+ * Score plugin — fetches ERC-8004 on-chain reputation for your API
+ * directly via RPC and injects it into the 402 response `extensions.score`.
+ *
+ * Agents can read the score **before paying**, enabling trust-based routing:
+ * - `feedbackCount` — number of on-chain feedback entries
+ * - `successRate` — 0–100 (% of successful calls)
+ * - `avgResponseMs` — average response time in milliseconds
+ * - `verified` — true if agentId is registered on-chain
+ *
+ * @example
+ * ```typescript
+ * import Relai from '@relai-fi/x402/server';
+ * import { score } from '@relai-fi/x402/plugins';
+ *
+ * const relai = new Relai({
+ *   network: 'base',
+ *   plugins: [
+ *     score({ agentId: '5' }),
+ *   ],
+ * });
+ * ```
+ */
+declare function score(config: ScorePluginConfig): RelaiPlugin;
+interface FeedbackPluginConfig {
+    /**
+     * ERC-8004 agentId (NFT tokenId) for this API.
+     */
+    agentId: string | number;
+    /**
+     * Private key of the wallet that signs feedback transactions.
+     * The wallet must hold CREDIT tokens on SKALE Base to pay gas.
+     * Default: process.env.BACKEND_WALLET_PRIVATE_KEY
+     */
+    walletPrivateKey?: string;
+    /**
+     * SKALE Base Sepolia RPC URL.
+     * Default: process.env.ERC8004_RPC_URL or SKALE Base Sepolia public RPC.
+     */
+    rpcUrl?: string;
+    /**
+     * ERC-8004 ReputationRegistry contract address.
+     * Default: process.env.ERC8004_REPUTATION_REGISTRY
+     */
+    reputationRegistryAddress?: string;
+    /**
+     * Tag2 label for all feedback entries (default: 'x402').
+     */
+    tag2?: string;
+    /**
+     * Whether to submit successRate feedback (default: true).
+     * Value: 1 (success) or 0 (failure).
+     */
+    submitSuccessRate?: boolean;
+    /**
+     * Whether to submit responseTime feedback (default: true).
+     * Value: milliseconds elapsed since request start.
+     * Requires req.x402StartTime (set automatically if using Relai.protect()).
+     */
+    submitResponseTime?: boolean;
+}
+/**
+ * Feedback plugin — submits ERC-8004 on-chain reputation after every successful x402 settlement.
+ *
+ * Records `successRate` and `responseTime` signals to the ReputationRegistry on SKALE Base.
+ * This is the mechanism that **builds** the score that `score()` plugin later reads.
+ *
+ * Runs fire-and-forget — never blocks the response.
+ *
+ * @example
+ * ```typescript
+ * import Relai from '@relai-fi/x402/server';
+ * import { score, feedback } from '@relai-fi/x402/plugins';
+ *
+ * const relai = new Relai({
+ *   network: 'base',
+ *   plugins: [
+ *     score({ agentId: '5' }),
+ *     feedback({ agentId: '5' }), // needs BACKEND_WALLET_PRIVATE_KEY in env
+ *   ],
+ * });
+ * ```
+ */
+declare function feedback(config: FeedbackPluginConfig): RelaiPlugin;
+interface SolanaFeedbackPluginConfig {
+    /**
+     * Solana MPL Core NFT public key (base58) of the registered agent.
+     * This is the `solanaAgentAsset` stored after calling /api/solana8004/register.
+     */
+    assetPubkey: string;
+    /**
+     * Private key of the feedback wallet — base58 or JSON array format.
+     * Should differ from the owner's registration wallet (avoids self-feedback restriction).
+     * Default: process.env.SOLANA_8004_FEEDBACK_KEY ?? process.env.SOLANA_8004_PRIVATE_KEY
+     */
+    feedbackWalletPrivateKey?: string;
+    /**
+     * Solana cluster to use.
+     * Default: process.env.SOLANA_8004_CLUSTER ?? 'mainnet-beta'
+     */
+    cluster?: 'mainnet-beta' | 'devnet';
+    /**
+     * Custom Solana RPC URL (Helius / QuickNode recommended).
+     * Default: process.env.SOLANA_8004_RPC_URL
+     */
+    rpcUrl?: string;
+    /**
+     * Whether to submit successRate feedback (default: true).
+     */
+    submitSuccessRate?: boolean;
+    /**
+     * Whether to submit responseTime feedback (default: true).
+     */
+    submitResponseTime?: boolean;
+}
+/**
+ * Solana Feedback plugin — submits 8004-solana on-chain reputation after x402 settlement.
+ *
+ * Uses the native Solana `8004-solana` program (MPL Core NFT registry),
+ * separate from the SKALE EVM ReputationRegistry used by `feedback()`.
+ *
+ * Requires `8004-solana` package to be installed:
+ * ```
+ * npm install 8004-solana
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import Relai from '@relai-fi/x402/server';
+ * import { solanaFeedback } from '@relai-fi/x402/plugins';
+ *
+ * const relai = new Relai({
+ *   network: 'solana',
+ *   plugins: [
+ *     solanaFeedback({
+ *       assetPubkey: process.env.SOLANA_AGENT_ASSET!, // e.g. 'GH93tGR8...'
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+declare function solanaFeedback(config: SolanaFeedbackPluginConfig): RelaiPlugin;
+
+interface RelaiServerConfig {
+    /** Network to accept payments on */
+    network: RelaiNetwork;
+    /** RelAI facilitator URL (default: https://facilitator.x402.fi) */
+    facilitatorUrl?: string;
+    /** Plugins to extend protect() behavior (e.g. freeTier, rateLimit) */
+    plugins?: RelaiPlugin[];
+}
+type DynamicPrice = number | ((req: any) => number | Promise<number>);
+type RelaiIntegritasFlow = 'single' | 'dual';
+interface RelaiIntegritasOptions {
+    /** Enable Integritas by default for this endpoint */
+    enabled?: boolean;
+    /** Default flow when Integritas is enabled */
+    flow?: RelaiIntegritasFlow;
+}
+interface ProtectOptions {
+    /** Price in USD (e.g., 0.01 for 1 cent) */
+    price: DynamicPrice;
+    /** Optional token asset address for networks supporting multiple tokens */
+    asset?: string;
+    /** Wallet address to receive payments, or stripePayTo() for Stripe settlement */
+    payTo: string | StripePayTo;
+    /** Description shown to payer */
+    description?: string;
+    /** MIME type of the response (default: application/json) */
+    mimeType?: string;
+    /** Maximum timeout in seconds (default: 60) */
+    maxTimeoutSeconds?: number;
+    /** Integritas options (or simple boolean enable flag) */
+    integritas?: boolean | RelaiIntegritasOptions;
+    /** Override network for this endpoint */
+    network?: RelaiNetwork;
+    /** Override feePayer address (Solana only) — bypasses facilitator /supported fetch */
+    feePayer?: string;
+    /** Custom validation after payment is settled */
+    customRules?: (req: any) => boolean | Promise<boolean>;
+    /** Callback when 402 is returned (no payment provided) */
+    onPaymentRequired?: (req: any, info: {
+        price: number;
+        network: RelaiNetwork;
+    }) => void;
+    /** Callback when payment is settled successfully */
+    onPaymentSettled?: (req: any, result: SettleResult) => void;
+    /** Callback on error */
+    onError?: (req: any, error: unknown) => void;
+}
+interface SettleResult {
+    success: boolean;
+    transaction?: string;
+    payer?: string;
+    network?: string;
+    splitTransfers?: Record<string, unknown>;
+    integritasFeePaid?: boolean;
+    provenance?: Record<string, unknown>;
+    integritas?: Record<string, unknown>;
+    error?: string;
+    errorReason?: string;
+}
+interface PaymentInfo {
+    verified: boolean;
+    transactionId?: string;
+    payer?: string;
+    network: RelaiNetwork;
+    amount: number;
+}
+/** Config returned by stripePayTo() - used by protect() to create Stripe deposit addresses */
+interface StripePayTo {
+    readonly __brand: 'stripePayTo';
+    readonly secretKey: string;
+    /** Stripe crypto deposits network (default: 'base') */
+    readonly stripeNetwork: string;
+}
+/**
+ * Create a Stripe pay-to configuration for x402 payments.
+ * Payments settle as USD in your Stripe Dashboard - no crypto knowledge required.
+ *
+ * Stripe creates a fresh PaymentIntent + deposit address per request.
+ * Network is auto-set to Base (Stripe settles USDC on Base).
+ *
+ * @example
+ * ```typescript
+ * import Relai, { stripePayTo } from '@relai-fi/x402/server';
+ *
+ * const relai = new Relai({ network: 'base' });
+ *
+ * app.get('/api/data', relai.protect({
+ *   price: 0.01,
+ *   payTo: stripePayTo(process.env.STRIPE_SECRET_KEY!),
+ * }), (req, res) => {
+ *   res.json({ data: 'paid content' });
+ * });
+ * ```
+ */
+declare function stripePayTo(stripeSecretKey: string, options?: {
+    network?: string;
+}): StripePayTo;
+/**
+ * Server-side SDK for protecting Express endpoints with x402 micropayments.
+ * Settles payments through the RelAI facilitator (zero gas fees for users).
+ *
+ * Supports: Solana, Base, Avalanche, SKALE Base, SKALE Base Sepolia, SKALE BITE, Polygon, and Ethereum.
+ *
+ * @example
+ * ```typescript
+ * import Relai from '@relai-fi/x402/server';
+ *
+ * const relai = new Relai({ network: 'base' });
+ *
+ * app.get('/api/data', relai.protect({
+ *   payTo: '0xYourWallet',
+ *   price: 0.01,  // $0.01 USDC
+ * }), (req, res) => {
+ *   res.json({ data: 'Protected content', payment: req.payment });
+ * });
+ * ```
+ */
+declare class Relai {
+    private network;
+    private facilitatorUrl;
+    private feePayerCache;
+    private plugins;
+    private pluginInitPromise;
+    constructor(config: RelaiServerConfig);
+    private runPluginInit;
+    /**
+     * Get feePayer address for a network (cached)
+     */
+    private getFeePayer;
+    /**
+     * Express middleware to protect an endpoint with x402 micropayments.
+     *
+     * Flow:
+     * 1. No payment header → returns 402 with payment requirements
+     * 2. Payment header present → calls RelAI facilitator `/settle`
+     * 3. Settlement success → sets `PAYMENT-RESPONSE` header, attaches `req.payment`, calls `next()`
+     */
+    protect(options: ProtectOptions): (req: any, res: any, next: any) => Promise<any>;
+}
+
+export { feedback as A, type BridgePluginConfig as B, type CircuitState as C, type DynamicPrice as D, solanaFeedback as E, type FreeTierPluginConfig as F, type ProtectOptions as P, Relai as R, type SettleResult as S, type RelaiServerConfig as a, type PaymentInfo as b, type StripePayTo as c, type RelaiIntegritasFlow as d, type RelaiIntegritasOptions as e, type RelaiPlugin as f, type PluginContext as g, type PluginResult as h, type ScorePluginConfig as i, type FeedbackPluginConfig as j, type SolanaFeedbackPluginConfig as k, bridge as l, type FreeTierPlugin as m, type FreeTierUsageExport as n, freeTier as o, type ShieldPluginConfig as p, shield as q, type PreflightPluginConfig as r, stripePayTo as s, preflight as t, type CircuitBreakerPluginConfig as u, circuitBreaker as v, type RefundPluginConfig as w, type RefundEvent as x, refund as y, score as z };