@lacasoft/openrelay-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,118 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included
+      in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other
+      transformations represent, as a whole, an original work of authorship.
+
+      "Contribution" shall mean any work of authorship submitted to the
+      Licensor for inclusion in the Work by the copyright owner or by an
+      individual or Legal Entity authorized to submit on behalf of the
+      copyright owner.
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and included
+      within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, use, sell, offer for sale, import, and
+      otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work; and
+
+      (d) If the Work includes a "NOTICE" text file, You must include
+          a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution submitted for inclusion in the Work shall be under
+      the terms and conditions of this License, without any additional
+      terms or conditions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work on an "AS IS"
+      BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+   8. Limitation of Liability. In no event and under no legal theory
+      shall any Contributor be liable for any damages arising from this
+      Work, including direct, indirect, special, incidental, or
+      consequential damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work, You may offer acceptance of support, warranty, indemnity,
+      or other liability obligations consistent with this License.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2025 OpenRelay Contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

package/README.md

@@ -0,0 +1,135 @@
+# @lacasoft/openrelay-sdk
+
+The OpenRelay JavaScript/TypeScript SDK — **Stripe-compatible payments for the open web**.
+Accept **USDC on Base** with no gatekeepers: gasless settlement (ERC-3009), webhooks, and
+**x402** micropayments for AI agents. ~1% protocol fee (0.7% nodeit / 0.3% treasury), settled
+trustlessly on-chain.
+
+- ⛽ **Gasless for payers** — they sign an ERC-3009 authorization; the nodeit pays the gas.
+- 🤖 **x402 micropayments** — charge $0.001 per request (Stripe can't; OpenRelay can).
+- 🧩 **Stripe-like DX** — `paymentIntents.create`, `webhooks.verify`.
+- 🌐 **Open network** — no lock-in, self-host or use any nodeit.
+
+## Install
+
+```bash
+npm install @lacasoft/openrelay-sdk
+# pnpm add @lacasoft/openrelay-sdk   ·   yarn add @lacasoft/openrelay-sdk
+```
+
+> No need to clone the monorepo — `@lacasoft/openrelay-protocol` (types + constants) comes along
+> automatically; `viem` is a dependency.
+
+## Quick start
+
+```typescript
+import { OpenRelay } from '@lacasoft/openrelay-sdk'
+
+// Use a SECRET key, server-side only — never ship it to the browser.
+const relay = new OpenRelay({ apiKey: process.env.OPENRELAY_SECRET_KEY! })
+
+// Create a charge — amounts are USDC base units (6 decimals → 1 USDC = 1_000_000).
+const intent = await relay.paymentIntents.create({
+  amount: 10_000_000, // 10.00 USDC
+  currency: 'usdc',
+  chain: 'base',
+  metadata: { orderId: 'order_123' },
+})
+
+console.log(intent.id, intent.status) // "pi_…"  "created"
+```
+
+## Webhooks
+
+```typescript
+app.post('/webhooks', (req) => {
+  const event = relay.webhooks.verify(
+    req.body, // raw body
+    req.headers['openrelay-signature'],
+    process.env.OPENRELAY_WEBHOOK_SECRET!,
+  )
+  if (event.type === 'payment_intent.settled') {
+    fulfillOrder(event.data.metadata.orderId)
+  }
+})
+```
+
+## x402 — micropayments for AI agents
+
+```typescript
+// Gate any endpoint behind a per-request micropayment.
+app.addHook(
+  'preHandler',
+  relay.x402.middleware({
+    price: 1000, // 0.001 USDC per request
+    currency: 'usdc',
+    chain: 'base',
+  }),
+)
+```
+
+Any HTTP client that speaks x402 — including AI agents over MCP — can pay and consume your
+endpoint autonomously.
+
+### The HTTP flow (x402 spec)
+
+The middleware speaks the standard [x402](https://x402.org) protocol on the wire:
+
+```http
+# 1. Client requests the resource — no payment yet
+GET /api/data HTTP/1.1
+
+# 2. Server answers 402 with the payment requirements (x402 spec shape)
+HTTP/1.1 402 Payment Required
+Content-Type: application/json
+
+{
+  "x402Version": 1,
+  "accepts": [{
+    "scheme": "exact",
+    "network": "base",
+    "maxAmountRequired": "1000",         // 0.001 USDC (base units)
+    "resource": "/api/data",
+    "payTo": "0x742d35Cc…",              // merchant wallet
+    "asset": "0x833589fC…",              // USDC on Base
+    "maxTimeoutSeconds": 300,
+    "extra": { "name": "USDC", "version": "2" }
+  }]
+}
+
+# 3. Client pays and retries with the payment proof
+GET /api/data HTTP/1.1
+X-PAYMENT: <base64 payment payload>
+
+# 4. Server verifies on-chain (POST /v1/x402/verify) and serves the resource
+HTTP/1.1 200 OK
+```
+
+## Configuration
+
+```typescript
+new OpenRelay({
+  apiKey: 'sk_live_…', // required — secret key, server-side only
+  baseUrl: 'https://api.openrelay.site', // optional — your OpenRelay API host
+  timeout: 30_000, // optional — request timeout in ms
+})
+```
+
+## Links
+
+- Repo, docs & protocol spec: https://github.com/lacasoft/openrelay
+- Source: [`packages/sdk-js`](https://github.com/lacasoft/openrelay/tree/master/packages/sdk-js)
+- License: Apache-2.0
+
+---
+
+### Contributing / local dev
+
+The SDK lives in the [OpenRelay monorepo](https://github.com/lacasoft/openrelay). To work on it:
+
+```bash
+pnpm dev        # watch mode (cjs + esm + dts)
+pnpm build      # build with tsup
+pnpm test       # unit tests
+pnpm typecheck  # type-check without emitting
+```

package/dist/index.d.mts

@@ -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 };