@lacasoft/openrelay-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,277 @@
+import { SupportedChain, CreatePaymentIntentParams, PaymentIntent, WebhookEvent, X402MiddlewareOptions } from '@lacasoft/openrelay-protocol';
+export { AuthError, CreatePaymentIntentParams, NetworkError, OpenRelayError, OpenRelayErrorCode, OpenRelaySDKError, PaymentIntent, RoutingError, SupportedChain, USDC_ADDRESSES, ValidationError, WebhookEvent, X402MiddlewareOptions, classifyError } from '@lacasoft/openrelay-protocol';
+import { Address, Hex } from 'viem';
+
+interface LogEntry {
+    request_id: string;
+    method: string;
+    path: string;
+    status: number;
+    latency_ms: number;
+    /** Nodeit wallet selected for routing, if returned by the API. */
+    node_route: string | null;
+}
+interface OpenRelayConfig {
+    apiKey: string;
+    baseUrl?: string;
+    timeout?: number;
+    merchantWallet?: string;
+    /** Optional structured-log hook called after every SDK request. */
+    logger?: (entry: LogEntry) => void;
+}
+
+interface BuildAuthorizationParams {
+    /** Payer address — the `from` of the USDC transfer. Must match the signer. */
+    payer: Address;
+    /** Amount in USDC base units (6 decimals). Must match the intent's amount. */
+    amount: bigint;
+    /** SettlementHub contract address — the `to` of the authorization. */
+    settlementHub: Address;
+    /** Which chain — picks USDC contract address + chainId. */
+    chain: SupportedChain;
+    /** Optional 32-byte random nonce. SDK generates one if omitted. */
+    nonce?: Hex;
+    /** Unix seconds; signature invalid before this. Default: 0 (always valid from start). */
+    validAfter?: bigint;
+    /** Unix seconds; signature invalid after this. Default: now + 30 minutes. */
+    validBefore?: bigint;
+}
+interface AuthorizationMessage {
+    from: Address;
+    to: Address;
+    value: bigint;
+    validAfter: bigint;
+    validBefore: bigint;
+    nonce: Hex;
+}
+interface AuthorizationTypedData {
+    domain: {
+        name: string;
+        version: string;
+        chainId: number;
+        verifyingContract: Address;
+    };
+    types: {
+        EIP712Domain: {
+            name: string;
+            type: string;
+        }[];
+        ReceiveWithAuthorization: {
+            name: string;
+            type: string;
+        }[];
+    };
+    primaryType: 'ReceiveWithAuthorization';
+    message: AuthorizationMessage;
+}
+declare function buildReceiveAuthorizationTypedData(params: BuildAuthorizationParams): AuthorizationTypedData;
+interface SignedAuthorization {
+    /** Payer address (the `from` of the USDC transfer). */
+    payer: Address;
+    /** Authorization validity window. */
+    validAfter: bigint;
+    validBefore: bigint;
+    /** 32-byte random nonce, hex-encoded. */
+    nonce: Hex;
+    /** ECDSA signature components. */
+    v: number;
+    r: Hex;
+    s: Hex;
+}
+declare function signReceiveAuthorization(params: BuildAuthorizationParams, privateKey: Hex): Promise<SignedAuthorization>;
+declare function splitSignature(signature: Hex): {
+    v: number;
+    r: Hex;
+    s: Hex;
+};
+declare function generateNonce(): Hex;
+
+interface SubmitAuthorizationResponse {
+    /** Echoed intent id. */
+    intent_id: string;
+    /** Server-side estimate of when the operator will submit it on-chain. */
+    estimated_settlement_at: string | null;
+    /** Authorization persisted server-side, awaiting operator pickup. */
+    status: 'queued';
+}
+interface SubmitAuthorizationBatchResponse {
+    /** Per-authorization queueing result. Order matches the input. */
+    results: Array<{
+        intent_id: string;
+        status: 'queued' | 'rejected';
+        reason?: string;
+    }>;
+    queued: number;
+    rejected: number;
+}
+declare class PaymentIntents {
+    private config;
+    constructor(config: OpenRelayConfig);
+    /**
+     * Create a new payment intent.
+     *
+     * @example
+     * const intent = await relay.paymentIntents.create({
+     *   amount: 1000,      // $0.001000 USDC (6 decimals)
+     *   currency: 'usdc',
+     *   chain: 'base',
+     *   metadata: { orderId: 'order_123' }
+     * })
+     */
+    create(params: CreatePaymentIntentParams): Promise<PaymentIntent>;
+    /**
+     * Retrieve a payment intent by ID.
+     */
+    retrieve(id: string): Promise<PaymentIntent>;
+    /**
+     * Cancel a payment intent (only valid while it is in 'created' state).
+     */
+    cancel(id: string): Promise<PaymentIntent>;
+    /**
+     * List payment intents for the authenticated merchant.
+     */
+    list(params?: {
+        limit?: number;
+        starting_after?: string;
+    }): Promise<{
+        data: PaymentIntent[];
+        has_more: boolean;
+    }>;
+    /**
+     * Build the EIP-712 typed-data structure for `ReceiveWithAuthorization`
+     * that USDC verifies on `payIntentWithAuthorization`. Hand the result to
+     * a wallet (viem `walletClient.signTypedData`, `window.ethereum`, etc.)
+     * to obtain a signature client-side.
+     *
+     * For server-side signing with a private key, prefer `signAuthorization`.
+     *
+     * @example (browser/wallet flow)
+     * const typed = relay.paymentIntents.buildAuthorizationTypedData({
+     *   payer: '0xPayer...',
+     *   amount: 5_000_000n,                          // 5 USDC (6 decimals)
+     *   settlementHub: '0xHub...',
+     *   chain: 'base-sepolia',
+     * })
+     * const signature = await walletClient.signTypedData(typed)
+     * const { v, r, s } = relay.paymentIntents.splitSignature(signature)
+     * await relay.paymentIntents.submitAuthorization(intentId, {
+     *   payer: typed.message.from,
+     *   validAfter: typed.message.validAfter,
+     *   validBefore: typed.message.validBefore,
+     *   nonce: typed.message.nonce,
+     *   v, r, s,
+     * })
+     */
+    buildAuthorizationTypedData(params: BuildAuthorizationParams): AuthorizationTypedData;
+    /**
+     * Server-side convenience: build + sign the `ReceiveWithAuthorization`
+     * message in one call. Returns everything needed for `submitAuthorization`.
+     *
+     * @example
+     * const auth = await relay.paymentIntents.signAuthorization(
+     *   { payer, amount: 5_000_000n, settlementHub, chain: 'base-sepolia' },
+     *   privateKey,
+     * )
+     * await relay.paymentIntents.submitAuthorization(intentId, auth)
+     */
+    signAuthorization(params: BuildAuthorizationParams, privateKey: Hex): Promise<SignedAuthorization>;
+    /**
+     * Submit a signed authorization for a registered intent. The API queues
+     * it for the assigned operator to settle on-chain (via
+     * `SettlementHub.payIntentWithAuthorization`).
+     *
+     * The endpoint is implemented in Phase B3; this client method targets
+     * the documented path so SDK + API can be developed in parallel.
+     */
+    submitAuthorization(intentId: string, auth: SignedAuthorization): Promise<SubmitAuthorizationResponse>;
+    /**
+     * Submit multiple signed authorizations in one HTTP request. The operator
+     * may settle them via `SettlementHub.payIntentBatchWithAuthorization`
+     * (skip-on-failure). Useful for x402 micropayment flows where many small
+     * payments are aggregated.
+     *
+     * Hard cap: `MAX_BATCH_SIZE` (matches `SettlementHub.MAX_BATCH_SIZE`,
+     * imported from `@lacasoft/openrelay-protocol` SSOT — never hardcode the literal).
+     */
+    submitAuthorizationBatch(items: Array<{
+        intent_id: string;
+        authorization: SignedAuthorization;
+    }>): Promise<SubmitAuthorizationBatchResponse>;
+    /**
+     * Helper to split a 65-byte signature (e.g. from `walletClient.signTypedData`)
+     * into the {v, r, s} triple that `submitAuthorization` expects.
+     */
+    splitSignature(signature: Hex): {
+        v: number;
+        r: Hex;
+        s: Hex;
+    };
+}
+
+declare class Webhooks {
+    private config;
+    constructor(config: OpenRelayConfig);
+    register(url: string, events: string[]): Promise<{
+        id: string;
+        url: string;
+        secret: string;
+    }>;
+    /**
+     * Verify a webhook payload signature.
+     * Call this in your webhook handler to ensure the request is from OpenRelay.
+     *
+     * Validates: (1) signature format, (2) timestamp freshness against
+     * `toleranceSeconds` to mitigate replay, (3) HMAC equality with
+     * timing-safe compare.
+     *
+     * @example
+     * const event = relay.webhooks.verify(rawBody, req.headers['openrelay-signature'], secret)
+     */
+    verify(payload: string, signature: string, secret: string, toleranceSeconds?: number): WebhookEvent;
+}
+
+declare class X402 {
+    private config;
+    constructor(config: OpenRelayConfig);
+    /**
+     * Returns a Fastify preHandler hook that requires x402 payment.
+     *
+     * @example
+     * app.addHook('preHandler', relay.x402.middleware({
+     *   price: 1000,       // $0.001 USDC
+     *   currency: 'usdc',
+     *   chain: 'base',
+     * }))
+     */
+    middleware(opts: X402MiddlewareOptions): (req: Request, reply: Response) => Promise<Response | undefined>;
+    /**
+     * Returns a Next.js App Router compatible handler that wraps a route with x402.
+     *
+     * @example
+     * export const GET = relay.x402.handler({
+     *   price: 1000,
+     *   handler: async (req) => Response.json({ data: 'protected' })
+     * })
+     */
+    handler(opts: X402MiddlewareOptions & {
+        handler: (req: Request) => Promise<Response>;
+    }): (req: Request) => Promise<Response>;
+    /**
+     * Shared gate: extract X-PAYMENT, verify against the API, and either
+     * return a 402 Response (challenge or rejection) or null when payment
+     * is valid and the caller should proceed.
+     */
+    private gate;
+    private buildPaymentRequired;
+    private verify;
+}
+
+declare class OpenRelay {
+    private config;
+    readonly paymentIntents: PaymentIntents;
+    readonly webhooks: Webhooks;
+    readonly x402: X402;
+    constructor(config: OpenRelayConfig);
+}
+
+export { type AuthorizationMessage, type AuthorizationTypedData, type BuildAuthorizationParams, type LogEntry, OpenRelay, type OpenRelayConfig, type SignedAuthorization, type SubmitAuthorizationBatchResponse, type SubmitAuthorizationResponse, buildReceiveAuthorizationTypedData, generateNonce, signReceiveAuthorization, splitSignature };