openpay-x402-sdk 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.4.0
+
+- Add an opt-in persistent daily buyer limit with UTC signer/date keys, file and
+  injectable spend stores, quote-time visibility, and fail-closed reads.
+- Record daily spend only after successful 2xx unlocks while isolating store
+  write failures from already completed payment responses.
+
 ## 0.3.0
 
 - Add `createJpycGate` for seller-side x402 gates backed by the OpenPay catalog,

package/README.md

@@ -16,6 +16,7 @@ const client = createOpenPayClient({
   privateKey: process.env.BUYER_PRIVATE_KEY,
   maxPerCallJpyc: '10',
   maxSessionJpyc: '100',
+  maxDailyJpyc: '250',
   allowedHosts: 'open-pay.jp',
 });
 
@@ -99,6 +100,7 @@ gate; `createJpycGate` is its importable SDK counterpart with split settlement.
 |---|---:|---|
 | `maxPerCallJpyc` | `10` | Upper bound for the caller-provided `maxTotalJpyc`. |
 | `maxSessionJpyc` | `100` | Cumulative cap for successful payments made by this client instance. |
+| `maxDailyJpyc` | Not set | Persistent cumulative cap per signer and UTC calendar date. |
 | `allowedHosts` | `open-pay.jp` | Comma-separated bare host allowlist. |
 | `catalogTrust` | `true` | Also allows catalog URLs after the live challenge matches the catalog challenge. |
 | `discoveryUrl` | `https://open-pay.jp/api/discovery` | Catalog and OpenPay origin used by the client. |
@@ -109,7 +111,21 @@ money-field verification. Exact query-bearing catalog entries remain exact-only.
 `pay(url, { maxTotalJpyc })` always requires `maxTotalJpyc`. It is the maximum
 total—including the resource price and x402 fee—that this individual call is
 authorized to pay. It does not disable or raise `maxPerCallJpyc` or
-`maxSessionJpyc`; all three limits must allow the payment.
+`maxSessionJpyc`; every configured limit must allow the payment.
+
+`maxDailyJpyc` is opt-in. When set, the client stores successful 2xx unlocks in
+`~/.openpay-x402/spend.json`, keyed by the lower-cased signer address and UTC
+date. A missing entry starts at zero. A corrupt/unreadable store or a custom
+store returning `null` rejects quotes and payments with `daily_spend_unavailable`
+(fail-closed). Use `spendStore` to inject another implementation of
+`{ load(key), save(key, atomicString) }`; `MAX_DAILY_JPYC` is the equivalent
+optional setting for the exported environment config readers.
+
+The file store uses best-effort read-modify-write across processes: payments are
+serialized within one client process, but separate processes can race and lose
+an increment. Use an atomic shared store when multiple processes share a signer.
+Persistence runs only after a successful unlock; a save failure cannot change an
+already completed payment response.
 
 The client also rejects non-JPYC metadata, unsupported networks or schemes,
 non-OpenPay forwarder splits, amount inconsistencies, resource URL mismatches,

package/index.d.ts

@@ -37,13 +37,41 @@ export interface PaymentSigner {
   signTypedData(typedData: PaymentTypedData): Hex | Promise<Hex>;
 }
 
+export interface SpendStore {
+  /**
+   * Return the atomic JPYC spent for the key, `'0'` when no record exists, or
+   * `null` only on read failure. `null` fails closed (payments are refused),
+   * so an absent entry must be reported as `'0'`, never `null`.
+   */
+  load(key: string): Promise<string | null>;
+  /** Persist the new cumulative atomic amount. Failures must not throw. */
+  save(key: string, atomicString: string): Promise<void>;
+}
+
+export interface FileSpendStoreOptions {
+  path?: string;
+  fsImpl?: {
+    readFile(path: string, encoding: 'utf8'): Promise<string>;
+    mkdir(path: string, options: { recursive: true }): Promise<unknown>;
+    writeFile(
+      path: string,
+      data: string,
+      encoding: 'utf8',
+    ): Promise<unknown>;
+  };
+}
+
 interface ClientCommonOptions {
   maxPerCallJpyc?: JpycAmount;
   maxSessionJpyc?: JpycAmount;
+  maxDailyJpyc?: JpycAmount;
+  spendStore?: SpendStore;
   allowedHosts?: string;
   catalogTrust?: boolean;
   discoveryUrl?: string;
   fetchImpl?: typeof globalThis.fetch;
+  nowSec?: () => number;
+  now?: () => Date | number;
 }
 
 type NoSignerOptions = {
@@ -85,6 +113,7 @@ export interface RuntimeConfig {
   stewardSignerSecret: string | null;
   maxPerCallAtomic: bigint;
   maxSessionAtomic: bigint;
+  maxDailyAtomic: bigint | null;
   allowedHosts: string[];
   catalogTrust: boolean;
   discoveryUrl: string;
@@ -321,6 +350,8 @@ export const REASONS: {
   maxTotalAbovePerCallLimit: 'max_total_above_per_call_limit';
   perCallLimitExceeded: 'per_call_limit_exceeded';
   sessionLimitExceeded: 'session_limit_exceeded';
+  dailyLimitExceeded: 'daily_limit_exceeded';
+  dailySpendUnavailable: 'daily_spend_unavailable';
   buyerPrivateKeyMissing: 'buyer_private_key_missing';
   stewardSignerUnconfigured: 'steward_signer_unconfigured';
   catalogAcceptMismatch: 'catalog_accept_mismatch';
@@ -358,6 +389,9 @@ export function parseClientOptions(
   options?: OpenPayClientOptions,
 ): RuntimeConfig;
 export function createPaymentSession(initialSpentAtomic?: bigint): PaymentSession;
+export function createFileSpendStore(
+  options?: FileSpendStoreOptions,
+): SpendStore;
 export function recordSuccessfulPayment(
   session: PaymentSession,
   amountAtomic: bigint,
@@ -375,6 +409,7 @@ export function evaluatePaymentGuards(options: {
   accept: unknown;
   config: Omit<RuntimeConfig, 'discoveryUrl'> | RuntimeConfig;
   sessionSpentAtomic?: bigint;
+  dailySpentAtomic?: bigint | null;
   maxTotalJpyc?: JpycAmount;
   requireMaxTotal?: boolean;
   requirePrivateKey?: boolean;
@@ -444,7 +479,10 @@ export function createPaymentExecutor(options: {
   config: RuntimeConfig;
   session: PaymentSession;
   signer?: PaymentSigner | null;
+  signerAddress?: Address | null;
+  spendStore?: SpendStore | null;
   fetchImpl?: typeof globalThis.fetch;
   nowSec?: () => number;
+  now?: () => Date | number;
   resolveCatalogListings?: () => Promise<Map<string, unknown> | null>;
 }): PaymentExecutor;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openpay-x402-sdk",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Guarded Node.js buyer SDK for OpenPay x402 JPYC resources",
   "type": "module",
   "main": "./src/index.mjs",

package/src/client.mjs

@@ -7,6 +7,7 @@ import {
   safeErrorMessage,
 } from './guards.mjs';
 import { createSignerFromOptions } from './signer.mjs';
+import { createFileSpendStore } from './spendStore.mjs';
 
 function isObject(value) {
   return typeof value === 'object' && value !== null;
@@ -63,13 +64,20 @@ export function createOpenPayClient(options = {}) {
   }
   const signer = createSignerFromOptions(options, { fetchImpl });
   const session = createPaymentSession();
+  const spendStore =
+    config.maxDailyAtomic === null
+      ? null
+      : options.spendStore ?? createFileSpendStore();
   const resolveCatalogListings = createCatalogResolver({ config, fetchImpl });
   const executor = createPaymentExecutor({
     config,
     session,
     signer,
+    signerAddress: signer?.address ?? null,
+    spendStore,
     fetchImpl,
     nowSec: options.nowSec,
+    now: options.now,
     resolveCatalogListings,
   });
 

package/src/executor.mjs

@@ -55,10 +55,54 @@ export function createPaymentExecutor({
   config,
   session,
   signer = null,
+  signerAddress = signer?.address ?? null,
+  spendStore = null,
   fetchImpl = fetch,
   nowSec = () => Math.floor(Date.now() / 1000),
+  now = () => new Date(),
   resolveCatalogListings = async () => null,
 }) {
+  const dailyLimitEnabled =
+    config.maxDailyAtomic !== null &&
+    config.maxDailyAtomic !== undefined &&
+    spendStore !== null;
+  const guardConfig =
+    !dailyLimitEnabled && config.maxDailyAtomic != null
+      ? { ...config, maxDailyAtomic: null }
+      : config;
+
+  async function loadDailySpend() {
+    if (!dailyLimitEnabled || typeof signerAddress !== 'string') {
+      return { key: null, spentAtomic: null };
+    }
+    const current = now();
+    const date = (current instanceof Date ? current : new Date(current))
+      .toISOString()
+      .slice(0, 10);
+    const key = `${signerAddress.toLowerCase()}:${date}`;
+    try {
+      const stored = await spendStore.load(key);
+      if (typeof stored !== 'string' || !/^[0-9]+$/.test(stored)) {
+        return { key, spentAtomic: null };
+      }
+      return { key, spentAtomic: BigInt(stored) };
+    } catch {
+      return { key, spentAtomic: null };
+    }
+  }
+
+  async function saveDailySpend(dailySpend, amountAtomic) {
+    if (dailySpend.key === null || dailySpend.spentAtomic === null) return;
+    try {
+      await spendStore.save(
+        dailySpend.key,
+        (dailySpend.spentAtomic + amountAtomic).toString(),
+      );
+    } catch {
+      // The unlock already succeeded; store failure must not replace the payment response.
+    }
+  }
+
   async function quoteImpl(url) {
     if (typeof url !== 'string') throw new Error('url is required');
     const response = await fetchImpl(url, {
@@ -74,11 +118,13 @@ export function createPaymentExecutor({
         reasons: ['expected_402_with_accepts'],
       };
     }
+    const dailySpend = dailyLimitEnabled ? await loadDailySpend() : null;
     const guard = evaluatePaymentGuards({
       url,
       accept,
-      config,
+      config: guardConfig,
       sessionSpentAtomic: session.spentAtomic,
+      dailySpentAtomic: dailySpend?.spentAtomic ?? null,
       catalogListings: await resolveCatalogListings(),
     });
     return quoteShape(url, response.status, guard);
@@ -107,11 +153,13 @@ export function createPaymentExecutor({
         reasons: ['expected_402_with_accepts'],
       };
     }
+    const dailySpend = dailyLimitEnabled ? await loadDailySpend() : null;
     const guard = evaluatePaymentGuards({
       url,
       accept,
-      config,
+      config: guardConfig,
       sessionSpentAtomic: session.spentAtomic,
+      dailySpentAtomic: dailySpend?.spentAtomic ?? null,
       maxTotalJpyc,
       requireMaxTotal: true,
       requireSigner: true,
@@ -142,6 +190,9 @@ export function createPaymentExecutor({
     const unlockedBody = await readJson(unlocked);
     if (unlocked.status >= 200 && unlocked.status < 300) {
       recordSuccessfulPayment(session, guard.summary.totalAtomic);
+      if (dailySpend !== null) {
+        await saveDailySpend(dailySpend, guard.summary.totalAtomic);
+      }
     }
     const receipt = decodePaymentResponse(
       unlocked.headers.get('x-payment-response'),

package/src/guards.mjs

@@ -33,6 +33,8 @@ export const REASONS = {
   maxTotalAbovePerCallLimit: 'max_total_above_per_call_limit',
   perCallLimitExceeded: 'per_call_limit_exceeded',
   sessionLimitExceeded: 'session_limit_exceeded',
+  dailyLimitExceeded: 'daily_limit_exceeded',
+  dailySpendUnavailable: 'daily_spend_unavailable',
   buyerPrivateKeyMissing: 'buyer_private_key_missing',
   stewardSignerUnconfigured: 'steward_signer_unconfigured',
   // catalog trust 経由 (第三者ドメイン) の URL で、支払い時にライブ fetch した accept が
@@ -139,6 +141,10 @@ export function readMoneyConfig(env = process.env) {
       nonEmpty(env.MAX_SESSION_JPYC) ?? DEFAULT_MAX_SESSION_JPYC,
       'MAX_SESSION_JPYC',
     ),
+    maxDailyAtomic:
+      nonEmpty(env.MAX_DAILY_JPYC) === undefined
+        ? null
+        : parseJpycToAtomic(env.MAX_DAILY_JPYC, 'MAX_DAILY_JPYC'),
     allowedHosts: parseAllowedHosts(env.ALLOWED_HOSTS),
     catalogTrust:
       env.CATALOG_TRUST === undefined || env.CATALOG_TRUST === ''
@@ -198,6 +204,10 @@ export function parseClientOptions(options = {}) {
       optionAmount(options.maxSessionJpyc, DEFAULT_MAX_SESSION_JPYC),
       'MAX_SESSION_JPYC',
     ),
+    maxDailyAtomic:
+      options.maxDailyJpyc === undefined || options.maxDailyJpyc === ''
+        ? null
+        : parseJpycToAtomic(options.maxDailyJpyc, 'MAX_DAILY_JPYC'),
     allowedHosts: parseAllowedHosts(options.allowedHosts),
     catalogTrust: options.catalogTrust ?? DEFAULT_CATALOG_TRUST,
     discoveryUrl: requireHttpUrl(
@@ -368,6 +378,7 @@ export function evaluatePaymentGuards({
   accept,
   config,
   sessionSpentAtomic = 0n,
+  dailySpentAtomic = null,
   maxTotalJpyc,
   requireMaxTotal = false,
   requirePrivateKey = false,
@@ -378,6 +389,7 @@ export function evaluatePaymentGuards({
   catalogListings = null,
 }) {
   const reasons = [];
+  const maxDailyAtomic = config.maxDailyAtomic ?? null;
   const parsedUrl = parseHttpUrl(url, 'url');
   if (parsedUrl === null) {
     reasons.push(REASONS.invalidUrl);
@@ -430,6 +442,17 @@ export function evaluatePaymentGuards({
     if (sessionSpentAtomic + total > config.maxSessionAtomic) {
       reasons.push(REASONS.sessionLimitExceeded);
     }
+    if (
+      maxDailyAtomic !== null &&
+      dailySpentAtomic !== null &&
+      dailySpentAtomic + total > maxDailyAtomic
+    ) {
+      reasons.push(REASONS.dailyLimitExceeded);
+    }
+  }
+
+  if (maxDailyAtomic !== null && dailySpentAtomic === null) {
+    reasons.push(REASONS.dailySpendUnavailable);
   }
 
   if (requirePrivateKey || requireSigner) {

package/src/index.mjs

@@ -5,3 +5,4 @@ export * from './gate.mjs';
 export * from './guards.mjs';
 export * from './payment.mjs';
 export * from './signer.mjs';
+export * from './spendStore.mjs';

package/src/spendStore.mjs

@@ -0,0 +1,86 @@
+function isObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isMissingFile(error) {
+  return isObject(error) && error.code === 'ENOENT';
+}
+
+function isAtomicString(value) {
+  return typeof value === 'string' && /^[0-9]+$/.test(value);
+}
+
+export function createFileSpendStore({ path, fsImpl } = {}) {
+  let runtimePromise;
+
+  async function resolveRuntime() {
+    runtimePromise ??= (async () => {
+      const fileSystem = fsImpl ?? (await import('node:fs/promises'));
+      const pathModule = await import('node:path');
+      const targetPath =
+        path ??
+        pathModule.join(
+          (await import('node:os')).homedir(),
+          '.openpay-x402',
+          'spend.json',
+        );
+      return {
+        fileSystem,
+        targetPath,
+        directory: pathModule.dirname(targetPath),
+      };
+    })();
+    return runtimePromise;
+  }
+
+  async function load(key) {
+    try {
+      const { fileSystem, targetPath } = await resolveRuntime();
+      let raw;
+      try {
+        raw = await fileSystem.readFile(targetPath, 'utf8');
+      } catch (error) {
+        return isMissingFile(error) ? '0' : null;
+      }
+      const document = JSON.parse(raw);
+      if (!isObject(document)) return null;
+      const value = document[key];
+      return value === undefined ? '0' : isAtomicString(value) ? value : null;
+    } catch {
+      return null;
+    }
+  }
+
+  async function save(key, atomicString) {
+    try {
+      const { fileSystem, targetPath, directory } = await resolveRuntime();
+      let document = {};
+      try {
+        const raw = await fileSystem.readFile(targetPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (isObject(parsed)) document = parsed;
+      } catch {
+        document = {};
+      }
+
+      const date = key.slice(-10);
+      const current = Object.fromEntries(
+        Object.entries(document).filter(
+          ([storedKey, value]) =>
+            storedKey.endsWith(`:${date}`) && isAtomicString(value),
+        ),
+      );
+      current[key] = atomicString;
+      await fileSystem.mkdir(directory, { recursive: true });
+      await fileSystem.writeFile(
+        targetPath,
+        `${JSON.stringify(current, null, 2)}\n`,
+        'utf8',
+      );
+    } catch {
+      // The payment is already complete; persistence failure must not replace its response.
+    }
+  }
+
+  return { load, save };
+}