openpay-x402-sdk 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.3.0
+
+- Add `createJpycGate` for seller-side x402 gates backed by the OpenPay catalog,
+  including five-minute `accepts` caching and request-specific resource URLs.
+- Support both one-shot verify-to-settle handling and split verification followed
+  by settlement after an expensive upstream operation succeeds.
+- Use Edge-compatible UTF-8 base64 handling for payment and settlement headers.
+
 ## 0.2.1
 
 - Compare `accept.resource` against the requested URL using decoded query

package/README.md

@@ -32,6 +32,67 @@ inside `{ ok, status, body }`. `quote()` fetches and validates a 402 challenge b
 does not need a signer and never pays. `pay()` requires a signer and serializes
 concurrent calls so every call sees the latest session total.
 
+## Sell with the SDK
+
+Create a gate with the exact resource URL registered in OpenPay discovery. For
+inexpensive content, `handle()` verifies and settles the payment in one call:
+
+```js
+import { createJpycGate } from 'openpay-x402-sdk';
+
+const gate = createJpycGate({
+  resourceUrl: process.env.MY_RESOURCE_URL,
+});
+
+export async function GET(request) {
+  const payment = await gate.handle(request);
+  if (payment instanceof Response) return payment;
+
+  const response = Response.json({ your: 'paid content' });
+  response.headers.set(
+    'X-PAYMENT-RESPONSE',
+    payment.paymentResponseHeader,
+  );
+  return response;
+}
+```
+
+For an expensive upstream operation, verify first and settle only after the
+operation succeeds. If `callUpstream()` fails, return an error before calling
+`settle()` so the buyer remains uncharged:
+
+```js
+export async function GET(request) {
+  const payment = await gate.verify(request);
+  if (payment instanceof Response) return payment;
+
+  let data;
+  try {
+    data = await callUpstream();
+  } catch {
+    return Response.json({ error: 'upstream_failed' }, { status: 502 });
+  }
+
+  const settlement = await payment.settle();
+  if (settlement instanceof Response) return settlement;
+
+  const response = Response.json(data);
+  response.headers.set(
+    'X-PAYMENT-RESPONSE',
+    settlement.paymentResponseHeader,
+  );
+  return response;
+}
+```
+
+`createJpycGate` fetches `accepts` from `/api/discovery` and caches it for five
+minutes. Until `resourceUrl` is listed with a non-empty `accepts`, `handle()` and
+`verify()` throw; map that bootstrap condition to an HTTP 500 response. Pass
+`openpayOrigin` to use an origin other than `https://open-pay.jp`.
+
+The copy-paste paywall snippet generated by OpenPay provides the same one-shot
+gate; `createJpycGate` is its importable SDK counterpart with split settlement.
+
 ## Money guards
 
 | Option | Default | Guard |

package/index.d.ts

@@ -194,6 +194,28 @@ export function createOpenPayClient(
   options?: OpenPayClientOptions,
 ): OpenPayClient;
 
+export interface JpycGateOptions {
+  resourceUrl: string;
+  openpayOrigin?: string;
+  fetchImpl?: typeof globalThis.fetch;
+  now?: () => number;
+}
+
+export interface JpycGatePaymentResponse {
+  paymentResponseHeader: string;
+}
+
+export interface VerifiedJpycPayment {
+  settle(): Promise<Response | JpycGatePaymentResponse>;
+}
+
+export interface JpycGate {
+  handle(request: Request): Promise<Response | JpycGatePaymentResponse>;
+  verify(request: Request): Promise<Response | VerifiedJpycPayment>;
+}
+
+export function createJpycGate(options: JpycGateOptions): JpycGate;
+
 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.2.1",
+  "version": "0.3.0",
   "description": "Guarded Node.js buyer SDK for OpenPay x402 JPYC resources",
   "type": "module",
   "main": "./src/index.mjs",

package/src/gate.mjs

@@ -0,0 +1,119 @@
+const DEFAULT_OPENPAY_ORIGIN = 'https://open-pay.jp';
+const ACCEPTS_CACHE_MS = 5 * 60_000;
+
+function json402(accepts, error) {
+  return new Response(JSON.stringify({ x402Version: 1, accepts, error }), {
+    status: 402,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+function decodeBase64Json(value) {
+  const binary = atob(value);
+  const bytes = Uint8Array.from(binary, (character) => character.charCodeAt(0));
+  return JSON.parse(new TextDecoder().decode(bytes));
+}
+
+function encodeBase64Json(value) {
+  const bytes = new TextEncoder().encode(JSON.stringify(value));
+  let binary = '';
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+
+export function createJpycGate({
+  resourceUrl,
+  openpayOrigin = DEFAULT_OPENPAY_ORIGIN,
+  fetchImpl = globalThis.fetch,
+  now = Date.now,
+}) {
+  const origin = openpayOrigin.replace(/\/+$/, '');
+  let acceptsCache = null;
+  let acceptsCachedAt = 0;
+
+  async function catalogAccepts() {
+    if (
+      acceptsCache !== null &&
+      now() - acceptsCachedAt < ACCEPTS_CACHE_MS
+    ) {
+      return acceptsCache;
+    }
+
+    const response = await fetchImpl(`${origin}/api/discovery`);
+    const { items } = await response.json();
+    const mine = (items || []).find((item) => item.resource === resourceUrl);
+    if (!mine || !mine.accepts || mine.accepts.length === 0) {
+      throw new Error(`resource not found in OpenPay catalog: ${resourceUrl}`);
+    }
+    acceptsCache = mine.accepts;
+    acceptsCachedAt = now();
+    return acceptsCache;
+  }
+
+  async function facilitator(path, paymentPayload, paymentRequirements) {
+    const response = await fetchImpl(`${origin}/api/facilitator/${path}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        x402Version: 1,
+        paymentPayload,
+        paymentRequirements,
+      }),
+    });
+    return response.json();
+  }
+
+  async function verify(request) {
+    const accepts = (await catalogAccepts()).map((accept) => ({
+      ...accept,
+      resource: request.url,
+    }));
+    const header = request.headers.get('x-payment');
+    if (!header) return json402(accepts, 'payment_required');
+
+    let paymentPayload;
+    try {
+      paymentPayload = decodeBase64Json(header);
+    } catch {
+      return json402(accepts, 'invalid_payment_payload');
+    }
+
+    const paymentRequirements = accepts[0];
+    const verification = await facilitator(
+      'verify',
+      paymentPayload,
+      paymentRequirements,
+    );
+    if (verification.isValid !== true) {
+      return json402(
+        accepts,
+        verification.invalidReason || 'payment_invalid',
+      );
+    }
+
+    return {
+      async settle() {
+        const settlement = await facilitator(
+          'settle',
+          paymentPayload,
+          paymentRequirements,
+        );
+        if (settlement.success !== true) {
+          return json402(
+            accepts,
+            settlement.errorReason || 'settlement_failed',
+          );
+        }
+        return { paymentResponseHeader: encodeBase64Json(settlement) };
+      },
+    };
+  }
+
+  async function handle(request) {
+    const verification = await verify(request);
+    if (verification instanceof Response) return verification;
+    return verification.settle();
+  }
+
+  return { handle, verify };
+}

package/src/index.mjs

@@ -1,6 +1,7 @@
 export * from './catalog.mjs';
 export * from './client.mjs';
 export * from './executor.mjs';
+export * from './gate.mjs';
 export * from './guards.mjs';
 export * from './payment.mjs';
 export * from './signer.mjs';