openpay-x402-sdk 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # Changelog
 
+## 0.7.0
+
+- Add `hasLicense` for standard ERC-1155 ownership with a required chain/contract/
+  uint256 token identity, block-pinned reads, and typed RPC errors. Token IDs
+  accept bigint or hex, never JS numbers.
+- Add `verifyLicense` for the trusted HTTPS v1 status API, with schema and
+  address/product identity validation. Preserve `entitled: null` as unknown and
+  reject redirects; allow HTTP only on localhost/127.0.0.1.
+- Add `createLicenseGate`: five-minute EIP-4361-style EOA challenges, atomic
+  single-use nonces, on-chain ownership, and HMAC sessions bound to the service
+  origin and full license identity. Default sessions last five minutes; support
+  an injectable nonce store without adding other persistence.
+- Add TypeScript declarations, mocked RPC/fetch and real-signature unit tests,
+  and the entry-license + x402 pay-per-use README pattern. Keep existing exports'
+  behavior and spend defaults unchanged; add no dependencies.
+- Keep licenses standard ERC-1155; the ERC-8217 agent-binding format will be
+  published later. This release does not implement binding metadata.
+
+## 0.6.0
+
+- Add `createDualGate` — a dual-rail seller gate that serves both JPYC (Polygon,
+  OpenPay facilitator) and USDC (Base, standard x402 relayed via OpenPay to the
+  CDP facilitator). USDC payments settle directly to the seller wallet with 0%
+  OpenPay fee; if the USDC face cannot be fetched, the gate degrades to
+  JPYC-only and never blocks JPYC payments.
+- Add `createListingClient` — programmatic marketplace listing (register, list,
+  update, deactivate) with built-in SIWE sign-in, so sellers and agents can
+  publish listings without the web form. `register` requires an explicit
+  `attested: true` (the SDK never attests on your behalf); set `usdc` to also
+  appear on the x402 Bazaar after the first settled purchase.
+- Return an explicit `settlement` field from `pay()`, because HTTP `200` only
+  means the seller returned a body and is not evidence that the payment settled.
+  `verified` means a receipt header was present and the facilitator signature
+  bound it to this payment, `unverified` means a header was present but
+  unsigned, malformed, forged, or mismatched, and `receipt_unavailable` means no
+  header was returned or the facilitator signer could not be resolved. Treat
+  anything but `verified` as not proven paid. `receipt` keeps its previous
+  meaning and an unlocked response body is still never discarded.
+- Take over a spend lock left behind by a killed process instead of failing
+  budgeted payments forever. A lock whose last modification is older than
+  `SPEND_LOCK_STALE_MS` (60s, now exported) is moved aside with an atomic
+  `rename` — never `unlink` — and the mover re-inspects the moved file to prove
+  it took the very lock it measured, so two processes that observe the same
+  stale lock cannot both enter the critical section. A lock younger than the
+  window is left alone, so a live holder is never displaced.
+- Record the owning `pid` and `createdAt` in the lock file, name the lock path in
+  a new `detail` on `{ ok: false, reason: 'unavailable' }`, and treat an
+  already-absent lock at release time as a completed release. A custom `fsImpl`
+  without `stat`/`rename` keeps the previous fail-closed behavior and now warns
+  once instead of disabling the takeover silently.
+- Resolve the target hostname before calling an injected custom `fetchImpl`, so a
+  public name pointing at a private or link-local address is rejected before the
+  custom transport runs. Connection-time rebinding protection still requires
+  supplying `lookup`; a resolver failure does not block, since only the transport
+  that opens the socket can re-validate the address it connects to.
+- Require `DISCOVERY_URL` to be `https`, with plaintext `http` allowed only for
+  `localhost` / `127.0.0.1`. The discovery origin is the authority for catalog
+  trust — URLs it lists are payable without an `ALLOWED_HOSTS` entry — so a
+  substitutable plaintext catalog could pass an attacker's resource off as
+  reviewed. Both `readRuntimeConfig` and `parseClientOptions` enforce it.
+- Declare the new surface in `index.d.ts` (`SETTLEMENT`, `SettlementStatus`,
+  `PaymentResult.settlement`, `SPEND_LOCK_STALE_MS`, `SpendReservationResult.detail`,
+  `fsImpl.stat`, `createDualGate`, `createListingClient` and their inputs) and
+  document dual-rail selling, code-side listing, settlement truth, stale-lock
+  takeover, and the custom-transport boundary in the README.
+
 ## 0.5.0
 
 - Reserve session and daily capacity immediately before exposing a signed

package/README.md

@@ -121,6 +121,210 @@ ledger.
 The copy-paste paywall snippet generated by OpenPay provides the same one-shot
 gate; `createJpycGate` is its importable SDK counterpart with split settlement.
 
+### Dual-rail: also sell in USDC (Base) and appear on the x402 Bazaar
+
+If your listing has the USDC face enabled, use `createDualGate` with the listing
+id (shown as `MY_RESOURCE_ID` in the generated snippet). The 402 then carries
+both JPYC and USDC `accepts` plus a `PAYMENT-REQUIRED` header; USDC payments are
+relayed by OpenPay to the CDP facilitator and settle directly to your Base
+address with 0% OpenPay fee. If the USDC face cannot be fetched (relay off or
+unavailable), the gate degrades to JPYC-only — USDC never blocks JPYC payments.
+
+```js
+import { createDualGate } from 'openpay-x402-sdk';
+
+const gate = createDualGate({
+  resourceUrl: process.env.MY_RESOURCE_URL,
+  resourceId: process.env.MY_RESOURCE_ID,
+});
+```
+
+`handle()` / `verify()` work exactly like `createJpycGate`, on both rails.
+
+### Register listings without the web form
+
+`createListingClient` signs in with SIWE and manages your marketplace listings
+programmatically — so a seller (or an agent) can go from nothing to a dual-rail
+listing entirely in code:
+
+```js
+import { createListingClient } from 'openpay-x402-sdk';
+
+const listings = createListingClient({ privateKey: process.env.SELLER_PRIVATE_KEY });
+const { resource, paywallSnippet } = await listings.register({
+  url: 'https://api.example.com/paid/report',
+  description: 'What the purchase completes, in one paragraph.',
+  priceJpyc: '100',
+  category: 'api',
+  usdc: { priceUsd: '0.01', serviceName: 'Example Report API' }, // optional USDC face
+  attested: true, // your personal attestation — the SDK never sets this for you
+});
+// resource.id → pass to createDualGate; paywallSnippet → or paste the snippet instead
+```
+
+`register` refuses to run without an explicit `attested: true`: you must
+personally affirm that you have the right to provide and charge for the
+resource and that it is payment-gated (HTTP 402). `list()`, `update(id, input)`,
+and `deactivate(id)` complete the lifecycle; `update` without `usdc` removes the
+USDC face, so pass the previous value to keep it. The private key signs locally
+and is never transmitted.
+
+## 利用ライセンス (License NFT)
+
+SDK 0.7.0 adds license reads and a server-side entry gate. The two-line pattern is:
+
+```js
+const entry = createLicenseGate({ ...licenseIdentity, origin: 'https://service.example', session: { secret: sessionSecret } });
+const usage = createJpycGate({ resourceUrl: 'https://service.example/api/paid' });
+```
+
+Import these helpers from `openpay-x402-sdk`. `licenseIdentity` is the full
+`{ chainId, contract, tokenId }` tuple for your product; obtain it from the product
+definition or the trusted Verify API. `tokenId` must be a `bigint` or `0x` hex
+string representing a uint256, never a JS number or decimal string. OpenPay
+derives it as `keccak256(UTF8('openpay:license:' + productId))`, including the
+entire `h_…` product ID. A token ID alone does not identify a license across
+chains and contracts.
+
+### Read ownership or purchase rights
+
+```js
+import { hasLicense, verifyLicense, LicenseRpcError } from 'openpay-x402-sdk';
+
+const status = await verifyLicense({ address: walletAddress, product: productId });
+if (status.entitled === null) {
+  // UNKNOWN: retry later; do not treat this as non-ownership or ask for repurchase.
+} else if (status.entitled === true) {
+  // The trusted API reports rights. Authenticate the wallet separately.
+}
+
+try {
+  const { holder, balance, blockNumber } = await hasLicense({
+    address: walletAddress,
+    chainId: status.license.chainId,
+    contract: status.license.contract,
+    tokenId: status.license.tokenId,
+  });
+  console.log({ holder, balance, blockNumber });
+} catch (error) {
+  if (error instanceof LicenseRpcError) {
+    // Ownership is unconfirmed. Report/retry the failure; do not convert it to false.
+  } else throw error;
+}
+```
+
+`hasLicense` calls standard ERC-1155 `balanceOf(address, tokenId)` at the returned
+`blockNumber`, using the latest block (not a finality guarantee). It checks the
+RPC chain ID and returns `{ holder: boolean, balance: bigint, blockNumber: bigint }`.
+Zero balance is a successful negative result; network errors, a wrong chain,
+reverts and malformed RPC results throw `LicenseRpcError` (`code: 'rpc_error'`).
+Pass either `rpcUrl` or a viem `publicClient` implementing `getChainId`,
+`getBlockNumber` and `readContract`. Polygon (137) and Amoy (80002) use viem's
+public RPC defaults if neither is supplied; other chains need an explicit
+transport. Treat the chosen RPC/client as a trusted read source.
+
+`verifyLicense({ address, product, origin?, fetch? })` calls
+`GET /api/license/verify?address=…&product=…`. It validates version `1`, the
+address/product echoes, the full license identity and token derivation,
+`entitled`, `basis`, NFT status, optional mint transaction/observed block, and
+`checkedAt`. The typed response keeps `entitled: boolean | null`; **null means
+unknown**. `basis` is `purchase`, `holder` or `null`. NFT status is
+`awaiting_finality`, `pending`, `submitted`, `minted`, `registered`, `retryable`,
+`needs_repair` or `unknown`.
+
+This is a trusted HTTPS status API, not wallet authentication or portable signed
+proof. The default origin is `https://open-pay.jp`; an override must be a bare
+HTTPS origin without credentials, path, query or fragment. HTTP is allowed only
+for `localhost` and `127.0.0.1`. All redirects, including same-origin redirects,
+are rejected. Injected `fetch` must honor `redirect: 'manual'` and the 15-second
+AbortSignal. Invalid schemas, HTTP failures and transport failures throw
+`LicenseError` with `invalid_response`, `http_error` or `network_error`; redirects
+use `redirect`. Invalid caller options throw `TypeError`.
+
+### Authenticate at entry, charge separately for use
+
+Create one `entry` instance on your server using the two-line pattern above.
+Set `origin` to **your service's origin** (default `https://open-pay.jp`) so the
+signing domain and session audience are correct. `sessionSecret` must be a
+server-only, cryptographically random secret of at least 32 UTF-8 bytes, for
+example a random 32-byte value encoded as hex. All workers must use the same
+configuration and secret.
+
+```js
+// Server challenge endpoint: send this message to the wallet.
+const message = await entry.challenge(walletAddress);
+// Wallet: sign the exact message with signMessage({ message }).
+// Server verify endpoint: receive the message and signature from the wallet.
+const token = await entry.verify({ message, signature });
+// On protected requests, extract the token from your cookie or Authorization header.
+const { address, tokenId, exp } = entry.check(token);
+// After entry.check succeeds, charge each paid call with the existing usage gate.
+const payment = await usage.handle(request);
+if (payment instanceof Response) return payment;
+// Return the paid content with payment.paymentResponseHeader as X-PAYMENT-RESPONSE.
+```
+
+`challenge` returns a five-minute [EIP-4361-style message](https://eips.ethereum.org/EIPS/eip-4361)
+with a random nonce and the full license identity in its Resources field.
+`verify` uses viem's EOA `verifyMessage` recovery, checks the exact issued message,
+domain, URI, identity and expiry, atomically consumes its nonce, reads ownership,
+then returns an HMAC-SHA256 session token. This version supports EOA signatures;
+contract-wallet ERC-1271 verification is not implemented. The optional
+`statement` must be single-line ASCII.
+
+`check` is synchronous and returns `{ address, tokenId: bigint, exp }`, with `exp`
+in Unix seconds. It authenticates the token and checks its audience, full license
+identity and expiry. It performs no RPC: a transfer/burn after entry remains
+effective in an existing session until expiry. `session.ttlSeconds` defaults to
+300 (allowed 1–86400); use a short lifetime or call `hasLicense` again when fresh
+ownership is required. The helper does not set cookies or expose HTTP endpoints;
+your framework handles token transport, secure cookies and endpoint rate limits.
+
+Authentication failures throw `LicenseError`: `invalid_challenge`,
+`challenge_expired`, `invalid_signature`, `invalid_nonce`, `no_license`,
+`invalid_session` or `session_expired`. RPC failures remain `LicenseRpcError`.
+Once a valid signature consumes a nonce, even an RPC failure or zero balance
+requires a fresh challenge. No session is issued on a nonce-store failure
+(`nonce_store_error`).
+
+The default nonce store is in memory per gate instance, prunes expired entries
+on challenge creation and caps pending entries at 10,000. For multiple workers
+or restarts, inject only a `nonceStore` with:
+
+```ts
+set(nonce: string, record: { message: string; expiresAt: number }): void | Promise<void>;
+consume(nonce: string): LicenseNonceRecord | null | undefined | Promise<LicenseNonceRecord | null | undefined>;
+```
+
+`expiresAt` is Unix milliseconds. `consume` must return and delete the record
+**atomically** across workers (for example with a Redis GETDEL); a separate
+get/delete pair is unsafe. Expire records at `expiresAt` and throw on storage
+failure. The SDK has no other persistence. Session tokens are bearer credentials;
+keep the HMAC secret on the server and use HTTPS to carry the token.
+
+`hasLicense` and `createLicenseGate` check NFT ownership only. OpenPay purchase
+rights can exist before minting, and non-transferable licenses retain purchase
+rights after burn; use the Verify API after separately authenticating the wallet
+if your service needs that purchase-rights policy. For transferable licenses,
+post-mint rights follow the current holder. Licenses carry no usage allowance or
+spend balance; `createJpycGate` handles separate x402 pay-per-use. SDK spend
+defaults remain unchanged.
+
+ERC-8217 note: the license remains a standard ERC-1155. The agent-binding format
+will be published later; SDK 0.7.0 does not emit or validate binding metadata.
+
+### SDK verification in this repository
+
+```bash
+npm test --prefix packages/x402-sdk
+npx vitest run tests/packages/x402-sdk-*.test.ts
+```
+
+The package's unit tests use Node's built-in test runner with mocked RPC/fetch
+and real EOA signatures. Existing buyer/seller regression and tarball tests
+remain in the root Vitest suite; `npm run typecheck` also checks license API
+consumer types.
+
 ## Money guards
 
 | Option | Default | Guard |
@@ -159,9 +363,12 @@ atomic `reserve(key, amount, limit, reservation)` method; legacy
 config readers.
 
 An abrupt process or machine stop can leave `spend.json.lock`; reservations then
-fail closed instead of paying without a limit. Stop every process that uses the
-same store before inspecting and manually removing a stale lock. Never remove
-the lock while another process may still own it.
+fail closed instead of paying without a limit. The lock file records the owning
+`pid` and `createdAt`, and a lock whose last modification is older than 60
+seconds is taken over automatically on the next reservation, so a killed process
+no longer blocks budgeted payments forever. A lock younger than that is left
+alone and the rejection names the lock path in its `detail`. Stop every process
+that uses the same store before removing a lock by hand.
 
 The client also rejects non-JPYC metadata, unsupported networks or schemes,
 non-canonical JPYC contracts or EIP-712 domains, seller timeouts above
@@ -172,9 +379,14 @@ signature. `MAX_TIMEOUT_SECONDS` is the equivalent setting for the exported
 environment config readers. Target host/catalog admission and private-address
 checks run before buyer target requests. Those requests require HTTPS, do not
 follow redirects, and have a 15-second timeout. The default Node transport also
-validates DNS before and during connection to block rebinding; an explicitly
-injected custom `fetchImpl` is a trusted transport boundary and is responsible
-for equivalent connect-time enforcement.
+validates DNS before and during connection to block rebinding. A custom
+`fetchImpl` still gets the pre-connection resolution check — a hostname that
+resolves to a private or link-local address is rejected before the injected
+transport is called — but connection-time rebinding protection requires also
+supplying `lookup`, because only the transport that opens the socket can
+re-validate the address it actually connects to. A custom `fetchImpl` without
+`lookup` therefore remains a trusted transport boundary for connect-time
+enforcement.
 
 `pay()` returns a non-null `receipt` only when the facilitator signer advertised
 by `/api/facilitator/supported` signed it and the transaction, payer, network,
@@ -182,6 +394,14 @@ asset, merchant amount, fee, chain, and authorization nonce all match this
 payment. A missing, malformed, forged, or mismatched seller response header
 becomes `receipt: null` without discarding the unlocked response body.
 
+`pay()` also returns an explicit `settlement` field, because an HTTP `200` only
+means the seller returned a body and is not evidence that the payment settled.
+`verified` means a receipt header was present and its facilitator signature was
+bound to this payment; `unverified` means a header was present but unsigned,
+malformed, forged, or mismatched; `receipt_unavailable` means no header was
+returned or the facilitator signer could not be resolved. Treat `unverified` and
+`receipt_unavailable` as not proven paid.
+
 ## Signers
 
 Choose exactly one of `privateKey`, `steward`, or `signer`. Supplying more than

package/index.d.ts

@@ -1,4 +1,4 @@
-import type { Address, Hex } from 'viem';
+import type { Address, Hex, PublicClient } from 'viem';
 
 export type JpycAmount = string | number;
 
@@ -75,6 +75,11 @@ export type SpendReservationResult =
       ok: false;
       reason: 'limit_exceeded' | 'unavailable';
       totalAtomic?: string;
+      /**
+       * Operator-facing hint for `unavailable`, present only when the block came from the
+       * lock file (it names the lock path). Never parse it; it is diagnostic text.
+       */
+      detail?: string;
     };
 
 export type PaymentLookup = (
@@ -97,9 +102,21 @@ export interface FileSpendStoreOptions {
     ): Promise<{ close(): Promise<unknown> }>;
     rename?(from: string, to: string): Promise<unknown>;
     unlink?(path: string): Promise<unknown>;
+    /**
+     * Required (together with `rename`) for taking over a lock left behind by a killed
+     * process. When either is missing the takeover is disabled and the SDK warns once —
+     * a stale lock then blocks budgeted payments until it is removed by hand.
+     */
+    stat?(path: string): Promise<{ mtimeMs?: number; mtime?: Date | number }>;
   };
 }
 
+/**
+ * A spend lock older than this cannot belong to a live holder, so it may be taken over.
+ * Exported so operators and tests can reason about the same window as the store.
+ */
+export const SPEND_LOCK_STALE_MS: number;
+
 interface ClientCommonOptions {
   maxPerCallJpyc?: JpycAmount;
   maxSessionJpyc?: JpycAmount;
@@ -243,10 +260,30 @@ export interface InvalidChallengeQuote {
 
 export type QuoteResult = GuardedQuote | InvalidChallengeQuote;
 
+/**
+ * Settlement truth for one paid call. `status: 200` alone is not evidence of settlement.
+ * - `verified`: a receipt header was present and the facilitator signature bound it to this payment.
+ * - `unverified`: a receipt header was present but unsigned, malformed, forged, or mismatched.
+ * - `receipt_unavailable`: no receipt header, or the facilitator signer could not be resolved.
+ */
+export type SettlementStatus = 'verified' | 'unverified' | 'receipt_unavailable';
+
+/** The `SettlementStatus` values as a runtime object (`unavailable` = `receipt_unavailable`). */
+export const SETTLEMENT: {
+  readonly verified: 'verified';
+  readonly unverified: 'unverified';
+  readonly unavailable: 'receipt_unavailable';
+};
+
 export interface PaymentResult {
   status: number;
   body: unknown;
   receipt: unknown;
+  /**
+   * Optional so objects built before this field existed stay source-compatible. Absent must be
+   * read the same way as `receipt_unavailable`: no settlement was proven.
+   */
+  settlement?: SettlementStatus;
 }
 
 export interface OpenPayClient {
@@ -296,6 +333,215 @@ export interface JpycGate {
 
 export function createJpycGate(options: JpycGateOptions): JpycGate;
 
+/** uint256 identity; JS numbers and decimal strings are intentionally unsupported. */
+export type LicenseTokenId = bigint | Hex;
+
+export interface LicenseIdentity {
+  chainId: number;
+  contract: Address;
+  tokenId: LicenseTokenId;
+}
+
+export type LicensePublicClient = Pick<PublicClient, 'getChainId' | 'getBlockNumber' | 'readContract'>;
+
+/** Polygon/Amoy public RPC defaults; other chains require an explicit transport. */
+export type LicenseTransport =
+  | { rpcUrl?: string; publicClient?: never }
+  | { rpcUrl?: never; publicClient: LicensePublicClient };
+
+export type HasLicenseOptions = LicenseIdentity & LicenseTransport & { address: Address };
+
+export interface LicenseBalance {
+  holder: boolean;
+  balance: bigint;
+  /** The block used for balanceOf, fetched without the viem block-number cache. */
+  blockNumber: bigint;
+}
+
+export type LicenseErrorCode =
+  | 'rpc_error' | 'network_error' | 'http_error' | 'redirect' | 'invalid_response'
+  | 'nonce_store_error' | 'invalid_challenge' | 'challenge_expired'
+  | 'invalid_signature' | 'invalid_nonce' | 'no_license'
+  | 'invalid_session' | 'session_expired';
+
+export class LicenseError extends Error {
+  readonly code: LicenseErrorCode;
+  constructor(code: LicenseErrorCode, message: string, options?: { cause?: unknown });
+}
+
+export class LicenseRpcError extends LicenseError {
+  readonly code: 'rpc_error';
+  constructor(message?: string, options?: { cause?: unknown });
+}
+
+/** RPC failures (including a wrong chain or malformed result) throw LicenseRpcError. */
+export function hasLicense(options: HasLicenseOptions): Promise<LicenseBalance>;
+
+export type LicenseNftStatus =
+  | 'awaiting_finality' | 'pending' | 'submitted' | 'minted' | 'registered'
+  | 'retryable' | 'needs_repair' | 'unknown';
+
+export interface VerifyLicenseOptions {
+  address: Address;
+  /** OpenPay hosted product ID: h_ followed by 32 lowercase hex digits. */
+  product: string;
+  /** Trusted HTTPS authority. Default: https://open-pay.jp. HTTP only on localhost/127.0.0.1. */
+  origin?: string;
+  /** Must honor redirect: 'manual' and the AbortSignal. */
+  fetch?: typeof globalThis.fetch;
+}
+
+export interface LicenseVerification {
+  version: 1;
+  address: Address;
+  license: { chainId: number; contract: Address; tokenId: Hex; productId: string };
+  /** null means UNKNOWN, never false. This status response is not authentication. */
+  entitled: boolean | null;
+  basis: 'purchase' | 'holder' | null;
+  nft: { status: LicenseNftStatus; mintTxHash?: Hex };
+  observedBlock?: string;
+  checkedAt: string;
+}
+
+/** Validates the v1 response and address/product identity. Rejects all redirects. */
+export function verifyLicense(options: VerifyLicenseOptions): Promise<LicenseVerification>;
+
+export interface LicenseNonceRecord {
+  message: string;
+  /** Unix milliseconds. */
+  expiresAt: number;
+}
+
+export interface LicenseNonceStore {
+  /** Persist until expiresAt. Throw on failure. */
+  set(nonce: string, record: LicenseNonceRecord): void | Promise<void>;
+  /** Atomically return AND delete once across workers. Never implement as separate get/delete. */
+  consume(nonce: string): LicenseNonceRecord | null | undefined | Promise<LicenseNonceRecord | null | undefined>;
+}
+
+export type LicenseGateOptions = LicenseIdentity & LicenseTransport & {
+  session: {
+    /** Server-only random secret, at least 32 UTF-8 bytes. */
+    secret: string;
+    /** Seconds, 1–86400. Default 300. Ownership is cached for this lifetime. */
+    ttlSeconds?: number;
+  };
+  /** Your service's signing origin and session audience. Default https://open-pay.jp. */
+  origin?: string;
+  /** Single-line ASCII SIWE statement. */
+  statement?: string;
+  /** Default: a bounded in-memory store for this gate instance. */
+  nonceStore?: LicenseNonceStore;
+  /** Clock in Unix milliseconds. Default Date.now. */
+  now?: () => number;
+};
+
+export interface LicenseSession {
+  address: Address;
+  tokenId: bigint;
+  /** Unix seconds. */
+  exp: number;
+}
+
+export interface LicenseGate {
+  /** An EIP-4361-style message, valid for five minutes. */
+  challenge(address: Address): Promise<string>;
+  /** EOA signature recovery, atomic nonce consumption, balanceOf, then HMAC session issuance. */
+  verify(input: { message: string; signature: Hex }): Promise<string>;
+  /** Synchronous signature/scope/expiry validation; no RPC and no ownership refresh. */
+  check(token: string): LicenseSession;
+}
+
+export function createLicenseGate(options: LicenseGateOptions): LicenseGate;
+
+export interface DualGateOptions extends JpycGateOptions {
+  /** OpenPay listing id (MY_RESOURCE_ID in the generated snippet). Enables the USDC (Base) rail. */
+  resourceId: string;
+}
+
+/**
+ * Dual-rail seller gate: JPYC (Polygon, OpenPay facilitator) plus USDC (Base, standard x402
+ * relayed to the CDP facilitator via OpenPay). If the USDC face cannot be fetched (relay off
+ * or unavailable), the gate degrades to JPYC-only — the USDC side never blocks JPYC payments.
+ */
+export function createDualGate(options: DualGateOptions): JpycGate;
+
+export interface ListingUsdcInput {
+  /** USD price without a $ sign, up to 6 decimals (e.g. "0.005"). */
+  priceUsd: string;
+  /** USDC (Base) receiving address. Defaults to the JPYC payTo. */
+  payTo?: string;
+  /** Display name for x402 Bazaar search (max 60 chars). */
+  serviceName?: string;
+}
+
+export interface ListingInput {
+  url: string;
+  description: string;
+  /** Integer JPYC price as a string (e.g. "100"). */
+  priceJpyc: string;
+  category: string;
+  docsUrl?: string;
+  license?: string;
+  /** JPYC receiving address. Defaults to the signed-in wallet. */
+  payTo?: string;
+  /** Enable the USDC (Base) face — also lists on the x402 Bazaar after the first settle. */
+  usdc?: ListingUsdcInput;
+}
+
+export interface RegisterListingInput extends ListingInput {
+  /**
+   * Required, must be literally true: your personal attestation that you have the right to
+   * provide and charge for this resource and that it is payment-gated (HTTP 402).
+   * The SDK never sets this for you.
+   */
+  attested: true;
+}
+
+export interface ListingRecord {
+  id: string;
+  url: string;
+  description: string;
+  priceJpyc: string;
+  category: string;
+  payTo: string;
+  docsUrl?: string;
+  license?: string;
+  usdc?: { payTo: string; priceUsd: string; serviceName?: string };
+  paywallSnippet?: string;
+  hidden?: boolean;
+}
+
+export interface RegisterListingResult {
+  resource: ListingRecord;
+  /** Copy-paste 402 gate for your server (dual-rail x402Gate when usdc is set). */
+  paywallSnippet: string;
+}
+
+export interface ListingClient {
+  /** The seller wallet address that signs in via SIWE (checksummed). */
+  address: Address;
+  register(input: RegisterListingInput): Promise<RegisterListingResult>;
+  list(): Promise<ListingRecord[]>;
+  update(id: string, input: ListingInput): Promise<{ resource: ListingRecord }>;
+  deactivate(id: string): Promise<boolean>;
+}
+
+/**
+ * Programmatic listing client — register, list, update, and deactivate OpenPay marketplace
+ * listings without the web form. Signs in with SIWE using the given private key on first use;
+ * the key is only used to sign locally and is never transmitted.
+ */
+export function createListingClient(options: {
+  privateKey: string;
+  openpayOrigin?: string;
+  fetchImpl?: typeof globalThis.fetch;
+  /** SIWE chainId (default 137 = Polygon). */
+  chainId?: number;
+  statement?: string;
+  now?: () => number;
+}): ListingClient;
+
 export const RECEIVE_WITH_AUTHORIZATION_TYPES: {
   ReceiveWithAuthorization: Array<{ name: string; type: string }>;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openpay-x402-sdk",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Guarded Node.js buyer SDK for OpenPay x402 JPYC resources",
   "type": "module",
   "main": "./src/index.mjs",
@@ -20,6 +20,9 @@
   "engines": {
     "node": ">=20"
   },
+  "scripts": {
+    "test": "node --test tests/*.test.mjs"
+  },
   "dependencies": {
     "viem": "^2.45.0"
   }