openpay-x402-sdk 0.1.0

package/src/client.mjs

@@ -0,0 +1,127 @@
+import { createCatalogResolver } from './catalog.mjs';
+import { createPaymentExecutor } from './executor.mjs';
+import {
+  createPaymentSession,
+  formatAtomicJpyc,
+  parseClientOptions,
+  safeErrorMessage,
+} from './guards.mjs';
+import { createSignerFromOptions } from './signer.mjs';
+
+function isObject(value) {
+  return typeof value === 'object' && value !== null;
+}
+
+function requireArgsObject(value, label) {
+  if (!isObject(value) || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  return value;
+}
+
+async function readJson(response) {
+  const text = await response.text();
+  if (text.length === 0) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+async function freeApiResponse(response, fallbackError) {
+  const body = await readJson(response);
+  if (response.ok) return { ok: true, status: response.status, body };
+  const error =
+    isObject(body) && typeof body.error === 'string'
+      ? body.error
+      : fallbackError;
+  return { ok: false, status: response.status, error, body };
+}
+
+function appendOptionalString(url, input, key) {
+  const value = input[key];
+  if (value === undefined) return;
+  if (typeof value !== 'string') throw new Error(`${key} must be a string`);
+  if (value.length > 0) url.searchParams.set(key, value);
+}
+
+function appendOptionalLimit(url, input) {
+  const value = input.limit;
+  if (value === undefined) return;
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw new Error('limit must be an integer >= 1');
+  }
+  url.searchParams.set('limit', String(value));
+}
+
+export function createOpenPayClient(options = {}) {
+  const config = parseClientOptions(options);
+  const fetchImpl = options.fetchImpl ?? fetch;
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('fetchImpl must be a function');
+  }
+  const signer = createSignerFromOptions(options, { fetchImpl });
+  const session = createPaymentSession();
+  const resolveCatalogListings = createCatalogResolver({ config, fetchImpl });
+  const executor = createPaymentExecutor({
+    config,
+    session,
+    signer,
+    fetchImpl,
+    nowSec: options.nowSec,
+    resolveCatalogListings,
+  });
+
+  async function withSafeErrors(operation) {
+    try {
+      return await operation();
+    } catch (error) {
+      throw new Error(safeErrorMessage(error, config));
+    }
+  }
+
+  async function discover(args = {}) {
+    return withSafeErrors(async () => {
+      const input = requireArgsObject(args, 'discover options');
+      const url = new URL(config.discoveryUrl);
+      appendOptionalString(url, input, 'query');
+      appendOptionalString(url, input, 'category');
+      const response = await fetchImpl(url.toString(), {
+        headers: { accept: 'application/json' },
+      });
+      return freeApiResponse(response, 'discovery_unavailable');
+    });
+  }
+
+  async function findShops(args = {}) {
+    return withSafeErrors(async () => {
+      const input = requireArgsObject(args, 'findShops options');
+      const url = new URL('/api/shops/find', new URL(config.discoveryUrl).origin);
+      appendOptionalString(url, input, 'q');
+      appendOptionalLimit(url, input);
+      const response = await fetchImpl(url.toString(), {
+        headers: { accept: 'application/json' },
+      });
+      return freeApiResponse(response, 'shops_find_unavailable');
+    });
+  }
+
+  const client = {
+    discover,
+    findShops,
+    quote: executor.quote,
+    pay: executor.pay,
+  };
+  Object.defineProperty(client, 'session', {
+    configurable: false,
+    enumerable: false,
+    get() {
+      return Object.freeze({
+        spentAtomic: session.spentAtomic,
+        spentJpyc: formatAtomicJpyc(session.spentAtomic),
+      });
+    },
+  });
+  return Object.freeze(client);
+}

package/src/executor.mjs

@@ -0,0 +1,177 @@
+import {
+  buildTypedDataFromPaymentRequirements,
+  createAuthorization,
+  decodePaymentResponse,
+  encodePaymentPayload,
+  paymentPayloadFor,
+} from './payment.mjs';
+import {
+  evaluatePaymentGuards,
+  recordSuccessfulPayment,
+  safeErrorMessage,
+} from './guards.mjs';
+
+function isObject(value) {
+  return typeof value === 'object' && value !== null;
+}
+
+async function readJson(response) {
+  const text = await response.text();
+  if (text.length === 0) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+function firstAccept(body) {
+  if (!isObject(body) || !Array.isArray(body.accepts) || body.accepts.length === 0) {
+    return null;
+  }
+  return body.accepts[0];
+}
+
+function quoteShape(url, status, guard) {
+  return {
+    url,
+    status,
+    ok: guard.ok,
+    reasons: guard.reasons,
+    priceJpyc: guard.summary?.priceJpyc ?? null,
+    feeJpyc: guard.summary?.feeJpyc ?? null,
+    totalJpyc: guard.summary?.totalJpyc ?? null,
+    network: guard.summary?.network ?? null,
+    asset: guard.summary?.asset ?? null,
+    description: undefined,
+  };
+}
+
+function sanitizedError(error, config) {
+  return new Error(safeErrorMessage(error, config));
+}
+
+export function createPaymentExecutor({
+  config,
+  session,
+  signer = null,
+  fetchImpl = fetch,
+  nowSec = () => Math.floor(Date.now() / 1000),
+  resolveCatalogListings = async () => null,
+}) {
+  async function quoteImpl(url) {
+    if (typeof url !== 'string') throw new Error('url is required');
+    const response = await fetchImpl(url, {
+      headers: { accept: 'application/json' },
+    });
+    const body = await readJson(response);
+    const accept = firstAccept(body);
+    if (response.status !== 402 || accept === null) {
+      return {
+        url,
+        status: response.status,
+        ok: false,
+        reasons: ['expected_402_with_accepts'],
+      };
+    }
+    const guard = evaluatePaymentGuards({
+      url,
+      accept,
+      config,
+      sessionSpentAtomic: session.spentAtomic,
+      catalogListings: await resolveCatalogListings(),
+    });
+    return quoteShape(url, response.status, guard);
+  }
+
+  async function quote(url) {
+    try {
+      return await quoteImpl(url);
+    } catch (error) {
+      throw sanitizedError(error, config);
+    }
+  }
+
+  async function payImpl(url, { maxTotalJpyc } = {}) {
+    if (typeof url !== 'string') throw new Error('url is required');
+    const response = await fetchImpl(url, {
+      headers: { accept: 'application/json' },
+    });
+    const body = await readJson(response);
+    const accept = firstAccept(body);
+    if (response.status !== 402 || accept === null) {
+      return {
+        url,
+        status: response.status,
+        ok: false,
+        reasons: ['expected_402_with_accepts'],
+      };
+    }
+    const guard = evaluatePaymentGuards({
+      url,
+      accept,
+      config,
+      sessionSpentAtomic: session.spentAtomic,
+      maxTotalJpyc,
+      requireMaxTotal: true,
+      requireSigner: true,
+      signerAvailable: signer !== null,
+      catalogListings: await resolveCatalogListings(),
+    });
+    if (!guard.ok) return quoteShape(url, response.status, guard);
+
+    const authorization = createAuthorization(
+      signer.address,
+      guard.accept.maxTimeoutSeconds,
+      nowSec(),
+    );
+    const { accept: normalizedAccept, typedData } =
+      buildTypedDataFromPaymentRequirements(accept, authorization);
+    const signature = await signer.signTypedData(typedData);
+    const paymentPayload = paymentPayloadFor(
+      normalizedAccept,
+      authorization,
+      signature,
+    );
+    const unlocked = await fetchImpl(url, {
+      headers: {
+        accept: 'application/json',
+        'X-PAYMENT': encodePaymentPayload(paymentPayload),
+      },
+    });
+    const unlockedBody = await readJson(unlocked);
+    if (unlocked.status >= 200 && unlocked.status < 300) {
+      recordSuccessfulPayment(session, guard.summary.totalAtomic);
+    }
+    const receipt = decodePaymentResponse(
+      unlocked.headers.get('x-payment-response'),
+    );
+    return {
+      status: unlocked.status,
+      body: unlockedBody,
+      receipt,
+    };
+  }
+
+  // Serialize the full read → sign → unlock → record path so concurrent calls cannot
+  // observe the same pre-payment session total and exceed the cumulative cap.
+  let payChain = Promise.resolve();
+  async function pay(url, options) {
+    const execute = async () => {
+      try {
+        return await payImpl(url, options);
+      } catch (error) {
+        throw sanitizedError(error, config);
+      }
+    };
+    const run = payChain.then(execute, execute);
+    // A failed payment must not prevent later independent payments from entering the queue.
+    payChain = run.then(
+      () => {},
+      () => {},
+    );
+    return run;
+  }
+
+  return { quote, pay };
+}