@obbyx/sdk 0.0.0-stage → 0.1.1

package/dist/seller/x402-server.js

@@ -0,0 +1,173 @@
+import { decodePaymentSignatureHeader } from '@x402/core/http';
+import { ObbyxError, fromDisplay, getNetwork, isAssetId, networkKey, parseAmount, } from '@obbyx/obyte';
+import { moduleLogger } from '@obbyx/obyte/logger';
+import { EXACT_SCHEME, bindingsEqual, exactExtraSchema } from '@obbyx/x402-obyte';
+import { DEFAULT_QUOTE_TTL_SECONDS, DEFAULT_SERVING_LEASE_SECONDS } from './defaults.js';
+import { bodyHashOf, newQuote, offerBinding } from './quote.js';
+function requestOf(transportContext) {
+    const request = transportContext?.request;
+    const adapter = request?.['adapter'];
+    if (adapter === undefined)
+        return undefined;
+    const url = new URL(adapter.getUrl(), 'http://localhost');
+    return {
+        method: adapter.getMethod(),
+        url: url.pathname + url.search,
+        body: adapter.getBody?.(),
+        paymentHeader: typeof request?.['paymentHeader'] === 'string' ? request['paymentHeader'] : undefined,
+    };
+}
+export class ObyteExactServer {
+    options;
+    scheme = EXACT_SCHEME;
+    defaultAssetTransferMethod = 'default';
+    paymentFlows = {
+        default: { supported: ['upfront'], default: 'upfront' },
+    };
+    dynamicExtraFields = ['binding', 'quoteId', 'validUntil'];
+    schemeHooks;
+    log;
+    now;
+    constructor(options) {
+        this.options = options;
+        this.log = moduleLogger(options.logger, 'sdk.x402-server', { scheme: EXACT_SCHEME });
+        this.now = options.now ?? (() => Math.floor(Date.now() / 1000));
+        this.schemeHooks = {
+            onBeforeVerify: async (ctx) => {
+                const unit = ctx.paymentPayload.payload.unit?.unit;
+                const binding = ctx.requirements.extra.binding;
+                if (typeof unit !== 'string' || typeof binding !== 'string') {
+                    return { abort: true, reason: 'invalid_payload' };
+                }
+                const { record } = this.options.proofs.begin(this.key(ctx.requirements.network, unit), binding);
+                if (!bindingsEqual(record.binding, binding))
+                    return { abort: true, reason: 'invalid_payment_reused' };
+                if (record.state === 'served') {
+                    this.log.warn({ proofId: unit }, 'payment already served a request; refused');
+                    return { abort: true, reason: 'payment_already_used' };
+                }
+                return undefined;
+            },
+            // Claim the proof atomically (settling → serving) before settling, so two
+            // concurrent requests with the same payment can never both reach the
+            // handler: the official middleware runs the handler after a successful
+            // settle, and the facilitator answers success for both (idempotent).
+            onBeforeSettle: async (ctx) => {
+                const key = this.keyOf(ctx);
+                if (key === undefined)
+                    return { abort: true, reason: 'invalid_payload' };
+                const proofs = this.options.proofs;
+                // A claim left behind by a crashed process is taken over after the lease.
+                proofs.reclaimStale(key, this.options.servingLeaseSeconds ?? DEFAULT_SERVING_LEASE_SECONDS);
+                if (proofs.transition(key, 'settling', 'serving') ||
+                    // settled earlier, but the handler failed: serve it now (settle is idempotent)
+                    proofs.transition(key, 'paid_not_served', 'serving')) {
+                    return undefined;
+                }
+                const state = this.options.proofs.get(key)?.state;
+                this.log.warn({ state }, 'payment already in use by another request; refused');
+                return {
+                    abort: true,
+                    reason: state === 'served' ? 'payment_already_used' : 'payment_in_progress',
+                };
+            },
+            onAfterSettle: async (ctx) => {
+                const key = this.keyOf(ctx);
+                if (key === undefined)
+                    return;
+                // Success: one operation consumed the proof. Otherwise (pending, failed):
+                // release the claim so the SAME payment can be retried.
+                if (ctx.result.success)
+                    this.options.proofs.transition(key, 'serving', 'served');
+                else
+                    this.options.proofs.transition(key, 'serving', 'settling');
+            },
+            // The handler failed or threw after the payment was settled (upfront):
+            // the payment stays usable for the SAME operation instead of "already used".
+            onVerifiedPaymentCanceled: async (ctx) => {
+                const key = this.keyOf(ctx);
+                if (key === undefined)
+                    return;
+                if (ctx.settledPhases.includes('before-handler')) {
+                    this.options.proofs.transition(key, 'served', 'paid_not_served');
+                }
+                else {
+                    this.options.proofs.transition(key, 'serving', 'settling');
+                }
+                this.log.warn({ reason: ctx.reason }, 'paid request not served; the same payment can retry');
+            },
+            onSettleFailure: async (ctx) => {
+                const key = this.keyOf(ctx);
+                if (key !== undefined)
+                    this.options.proofs.transition(key, 'serving', 'settling');
+            },
+        };
+    }
+    /** `{asset, amount}` in atomic units, or "20000 bytes" / "0.00002 GBYTE". */
+    async parsePrice(price, network) {
+        getNetwork(network);
+        if (typeof price === 'object') {
+            if (!isAssetId(price.asset))
+                throw new ObbyxError('invalid_price', `Invalid asset ${price.asset}`);
+            return { asset: price.asset, amount: parseAmount(price.amount).toString() };
+        }
+        const [, value, unit] = /^\s*([0-9]+(?:\.[0-9]+)?)\s*(bytes|gbyte)\s*$/i.exec(String(price)) ?? [];
+        if (value === undefined || unit === undefined) {
+            throw new ObbyxError('invalid_price', 'Use {asset, amount} or "<n> bytes" / "<x> GBYTE" (no USD default asset on Obyte yet)');
+        }
+        const amount = unit.toLowerCase() === 'bytes' ? parseAmount(value) : fromDisplay(value, 9);
+        return { asset: 'base', amount: amount.toString() };
+    }
+    getAssetDecimals(asset) {
+        return asset === 'base' ? 9 : undefined;
+    }
+    /** Nothing to add from /supported for exact; the per-request fields come from the enrich hook. */
+    async enhancePaymentRequirements(requirements) {
+        return requirements;
+    }
+    /** Adds (or, for a valid paid request, re-confirms) the per-request binding and quote. */
+    enrichPaymentRequiredResponse = async (ctx) => {
+        const request = requestOf(ctx.transportContext);
+        if (request === undefined)
+            throw new ObbyxError('no_request', 'Obyte exact needs the HTTP request context');
+        const accepted = this.acceptedQuote(request);
+        return ctx.requirements.map((req) => {
+            if (req.scheme !== EXACT_SCHEME)
+                return req;
+            const quote = accepted !== undefined &&
+                bindingsEqual(this.bindingFor(req, request, accepted), accepted.binding)
+                ? accepted
+                : undefined;
+            if (quote !== undefined)
+                return { ...req, extra: { ...req.extra, ...quote } };
+            const fresh = newQuote(this.now(), this.options.quoteTtlSeconds ?? DEFAULT_QUOTE_TTL_SECONDS);
+            return {
+                ...req,
+                extra: { ...req.extra, binding: this.bindingFor(req, request, fresh), ...fresh },
+            };
+        });
+    };
+    acceptedQuote(request) {
+        if (request.paymentHeader === undefined)
+            return undefined;
+        try {
+            const extra = exactExtraSchema.safeParse(decodePaymentSignatureHeader(request.paymentHeader).accepted?.extra);
+            return extra.success ? extra.data : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    bindingFor(req, request, quote) {
+        return offerBinding(this.options, EXACT_SCHEME, quote, { method: request.method, url: request.url, bodyHash: bodyHashOf(request.body) }, { network: req.network, asset: req.asset, amount: req.amount, payTo: req.payTo });
+    }
+    /** Proof key of the payment in a hook context (undefined when malformed). */
+    keyOf(ctx) {
+        const unit = ctx.paymentPayload.payload.unit?.unit;
+        return typeof unit === 'string' ? this.key(ctx.requirements.network, unit) : undefined;
+    }
+    key(network, unit) {
+        return networkKey(getNetwork(network), 'unit', unit);
+    }
+}
+//# sourceMappingURL=x402-server.js.map

package/dist/seller/x402-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402-server.js","sourceRoot":"","sources":["../../src/seller/x402-server.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,71 @@
 {
   "name": "@obbyx/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Accept and make x402 payments on Obyte: Express paywall, adapter for the official @x402 servers, paying fetch with spending budgets",
+  "keywords": [
+    "x402",
+    "obyte",
+    "paywall",
+    "payments",
+    "express",
+    "agents",
+    "http-402"
+  ],
+  "license": "MIT",
+  "author": "Alexander Ponomarev",
+  "homepage": "https://github.com/Taump/obbyx/tree/master/packages/sdk#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Taump/obbyx.git",
+    "directory": "packages/sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/Taump/obbyx/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@obbyx/obyte": "^0.1.0",
+    "@obbyx/x402-obyte": "^0.2.0",
+    "@x402/core": "^2.29.0",
+    "obyte": "0.2.1",
+    "zod": "^4.6.7"
+  },
+  "peerDependencies": {
+    "express": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@x402/express": "2.29.0",
+    "@x402/extensions": "2.29.0",
+    "@x402/fetch": "2.29.0",
+    "express": "^5.3.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
 }

package/src/client/budget.ts

@@ -0,0 +1,88 @@
+import { ObbyxError } from '@obbyx/obyte';
+
+/**
+ * Spending limits for a paying client (agents, services).
+ *
+ * - `perCall`: the most one request may cost, per asset.
+ * - `total`: the most all requests may cost together, per asset.
+ *
+ * Amounts are RESERVED before a payment is signed (atomically: the event loop
+ * runs reserve() to completion), so concurrent calls can never overshoot the
+ * total. A reservation is then:
+ * - `spent` when the seller confirmed the payment,
+ * - `released` when the payment was definitely not made,
+ * - left in place when the outcome is unknown (invariant I7): the budget never
+ *   under-counts a payment that may still settle.
+ */
+export interface BudgetLimits {
+  readonly perCall?: ReadonlyMap<string, bigint>;
+  readonly total?: ReadonlyMap<string, bigint>;
+}
+
+export interface BudgetReservation {
+  readonly id: number;
+  readonly asset: string;
+  readonly amount: bigint;
+}
+
+export class BudgetExceededError extends ObbyxError {
+  constructor(message: string, details: Record<string, unknown>) {
+    super('budget_exceeded', message, { details });
+  }
+}
+
+export class SpendingBudget {
+  private readonly spent = new Map<string, bigint>();
+  private readonly reserved = new Map<number, BudgetReservation>();
+  private nextId = 1;
+
+  constructor(private readonly limits: BudgetLimits) {}
+
+  reserve(asset: string, amount: bigint): BudgetReservation {
+    const perCall = this.limits.perCall?.get(asset);
+    if (perCall !== undefined && amount > perCall) {
+      throw new BudgetExceededError(
+        `Price ${amount} exceeds the per-call limit ${perCall} (${asset})`,
+        {
+          asset,
+          amount: amount.toString(),
+          perCall: perCall.toString(),
+        },
+      );
+    }
+    const total = this.limits.total?.get(asset);
+    const committed = this.used(asset);
+    if (total !== undefined && committed + amount > total) {
+      throw new BudgetExceededError(
+        `Paying ${amount} would exceed the total budget ${total} (${asset}); already used or reserved: ${committed}`,
+        { asset, amount: amount.toString(), total: total.toString(), used: committed.toString() },
+      );
+    }
+    const reservation = { id: this.nextId++, asset, amount };
+    this.reserved.set(reservation.id, reservation);
+    return reservation;
+  }
+
+  /** The payment settled: the amount is spent. */
+  spend(r: BudgetReservation): void {
+    if (!this.reserved.delete(r.id)) return;
+    this.spent.set(r.asset, (this.spent.get(r.asset) ?? 0n) + r.amount);
+  }
+
+  /** The payment was definitely not made: give the amount back. */
+  release(r: BudgetReservation): void {
+    this.reserved.delete(r.id);
+  }
+
+  /** Spent + reserved (unknown outcomes included) for an asset. */
+  used(asset: string): bigint {
+    let sum = this.spent.get(asset) ?? 0n;
+    for (const r of this.reserved.values()) if (r.asset === asset) sum += r.amount;
+    return sum;
+  }
+
+  remaining(asset: string): bigint | undefined {
+    const total = this.limits.total?.get(asset);
+    return total === undefined ? undefined : total - this.used(asset);
+  }
+}

package/src/client/paying-fetch.ts

@@ -0,0 +1,256 @@
+import { z } from 'zod';
+import {
+  decodePaymentRequiredHeader,
+  decodePaymentResponseHeader,
+  decodePaymentSignatureHeader,
+  encodePaymentSignatureHeader,
+} from '@x402/core/http';
+import type { PaymentPayload, PaymentRequirements, SettleResponse } from '@x402/core/types';
+import { ObbyxError } from '@obbyx/obyte';
+import { type Logger, moduleLogger } from '@obbyx/obyte/logger';
+import type { BudgetReservation, SpendingBudget } from './budget.js';
+import {
+  BATCH_SCHEME,
+  type BatchObyteClient,
+  EXACT_SCHEME,
+  type ExactObyteClient,
+} from '@obbyx/x402-obyte';
+
+/**
+ * fetch() that pays x402 `exact` Obyte payments (buyer side).
+ *
+ * - Pays only offers within `maxAmount` (atomic units per asset).
+ * - Redirects are not followed automatically: a payment is never re-sent to
+ *   another origin.
+ * - `settlement_pending` is retried with the SAME payment (never a new one)
+ *   until `pendingTimeoutMs`; if still unknown, it throws `PaymentPendingError`
+ *   carrying the payment header so the caller can retry later (I7).
+ */
+export interface PayingFetchOptions {
+  /** Payment mechanisms; a channel (batch) is preferred when one exists to the seller. */
+  readonly mechanisms: { readonly exact?: ExactObyteClient; readonly batch?: BatchObyteClient };
+  readonly network: string;
+  readonly maxAmount: ReadonlyMap<string, bigint>;
+  readonly logger: Logger;
+  readonly pendingTimeoutMs?: number;
+  /** Shared spending budget (per-call and total limits, reserved atomically). */
+  readonly budget?: SpendingBudget;
+  readonly fetch?: typeof fetch;
+}
+
+export interface PaidResponse {
+  readonly response: Response;
+  readonly payment?: SettleResponse;
+  /** Base64 PAYMENT-SIGNATURE that was sent, for retries of the same operation. */
+  readonly paymentHeader?: string;
+}
+
+export class PaymentPendingError extends ObbyxError {
+  constructor(
+    readonly paymentHeader: string,
+    readonly transaction: string,
+  ) {
+    super(
+      'settlement_pending',
+      `Payment ${transaction} is not final yet; retry the same request later with the same payment`,
+    );
+  }
+}
+
+export async function payingFetch(
+  url: string,
+  init: RequestInit & {
+    paymentHeader?: string;
+    /** x402 payment-identifier for this operation (reuse it when retrying after a lost response). */
+    paymentId?: string;
+  },
+  options: PayingFetchOptions,
+): Promise<PaidResponse> {
+  const log = moduleLogger(options.logger, 'sdk.fetch');
+  const doFetch = options.fetch ?? fetch;
+  const request = (header?: string) =>
+    doFetch(url, {
+      ...init,
+      redirect: 'manual',
+      headers: { ...headersOf(init.headers), ...(header ? { 'PAYMENT-SIGNATURE': header } : {}) },
+    });
+
+  let header = init.paymentHeader;
+  let reservation: BudgetReservation | undefined;
+  let response = await request(header);
+  if (response.status !== 402 && header === undefined) return { response };
+
+  if (header === undefined) {
+    const required = response.headers.get('PAYMENT-REQUIRED');
+    if (required === null)
+      throw new ObbyxError('invalid_402', '402 without PAYMENT-REQUIRED header');
+    const offer = decodePaymentRequiredHeader(required);
+    // Offers in preference order (channel first). A channel that turns out to
+    // be unusable before anything is signed (not funded, closing, exhausted,
+    // busy) falls through to the next offer, normally `exact`.
+    let accepted: PaymentRequirements | undefined;
+    let result: Awaited<ReturnType<ExactObyteClient['createPaymentPayload']>> | undefined;
+    let lastChannelError: ObbyxError | undefined;
+    for (const candidate of chooseOffers(offer.accepts, options)) {
+      const mechanism =
+        candidate.scheme === BATCH_SCHEME ? options.mechanisms.batch : options.mechanisms.exact;
+      if (mechanism === undefined) continue;
+      log.info(
+        {
+          url,
+          scheme: candidate.scheme,
+          payTo: candidate.payTo,
+          asset: candidate.asset,
+          amount: candidate.amount,
+        },
+        'paying for request',
+      );
+      // Reserve the price BEFORE signing: concurrent calls cannot overshoot the budget.
+      reservation = options.budget?.reserve(candidate.asset, BigInt(candidate.amount));
+      try {
+        result = await mechanism.createPaymentPayload(2, candidate);
+        accepted = candidate;
+        break;
+      } catch (err) {
+        if (reservation) options.budget?.release(reservation); // nothing was signed or sent
+        reservation = undefined;
+        if (err instanceof ObbyxError && CHANNEL_UNUSABLE.has(err.code)) {
+          lastChannelError = err;
+          log.info(
+            { reason: err.code, detail: err.message },
+            'channel unusable; trying the next offer',
+          );
+          continue;
+        }
+        throw err;
+      }
+    }
+    if (accepted === undefined || result === undefined) {
+      // Nothing else to pay with: report why the channel could not (e.g. payment_pending).
+      throw lastChannelError ?? new ObbyxError('no_acceptable_offer', 'No offer could be paid');
+    }
+    const payload: PaymentPayload = {
+      x402Version: 2,
+      resource: offer.resource,
+      accepted,
+      payload: result.payload,
+      ...(offer.extensions ? { extensions: withPaymentId(offer.extensions, init.paymentId) } : {}),
+    };
+    header = encodePaymentSignatureHeader(payload);
+    response = await request(header);
+  }
+
+  const deadline = Date.now() + (options.pendingTimeoutMs ?? 120_000);
+  for (;;) {
+    const settle = readSettle(response);
+    if (response.status !== 402 || settle?.errorReason !== 'settlement_pending') {
+      const accepted = acceptedOf(header);
+      if (accepted?.scheme === BATCH_SCHEME) options.mechanisms.batch?.onSettled(accepted, settle);
+      if (reservation !== undefined && options.budget !== undefined) {
+        // I7: spend on success; release ONLY on a definite refusal (402: the
+        // payment was not used). Anything else (5xx, 409, no settlement info)
+        // is an unknown outcome: the reservation stays counted.
+        if (settle?.success === true || (response.ok && settle === undefined))
+          options.budget.spend(reservation);
+        else if (response.status === 402) options.budget.release(reservation);
+      }
+      return { response, ...(settle ? { payment: settle } : {}), paymentHeader: header };
+    }
+    if (Date.now() > deadline) throw new PaymentPendingError(header, settle.transaction);
+    const retryAfterMs = Math.min(15, Number(response.headers.get('Retry-After') ?? 5)) * 1000;
+    const wait = Math.max(0, Math.min(retryAfterMs, deadline - Date.now()));
+    log.info(
+      { transaction: settle.transaction, waitMs: wait },
+      'settlement pending; retrying with the same payment',
+    );
+    await response.body?.cancel();
+    await new Promise((r) => setTimeout(r, wait));
+    response = await request(header);
+  }
+}
+
+/** An offer from an untrusted seller: integer amount in smallest units, strings elsewhere. */
+const offerShape = z
+  .object({
+    scheme: z.string(),
+    network: z.string(),
+    asset: z.string(),
+    amount: z.string().regex(/^\d{1,30}$/),
+    payTo: z.string(),
+    maxTimeoutSeconds: z.number().int().positive(),
+    extra: z.record(z.string(), z.unknown()),
+  })
+  .loose();
+
+/** Channel states in which the client signs nothing and can pay another way. */
+const CHANNEL_UNUSABLE = new Set([
+  'channel_not_funded',
+  'channel_closing',
+  'channel_exhausted',
+  'payment_pending',
+]);
+
+/** Usable offers within the spending limit, a channel first (instant, no per-call fee). */
+function chooseOffers(
+  accepts: PaymentRequirements[],
+  options: PayingFetchOptions,
+): PaymentRequirements[] {
+  const usable = (a: PaymentRequirements) =>
+    offerShape.safeParse(a).success &&
+    a.network === options.network &&
+    ((a.scheme === BATCH_SCHEME && options.mechanisms.batch?.hasChannel(a) === true) ||
+      (a.scheme === EXACT_SCHEME && options.mechanisms.exact !== undefined));
+  const candidates = [
+    ...accepts.filter((a) => a.scheme === BATCH_SCHEME),
+    ...accepts.filter((a) => a.scheme !== BATCH_SCHEME),
+  ].filter(usable);
+  if (candidates.length === 0) {
+    throw new ObbyxError('no_acceptable_offer', `No usable offer on ${options.network}`);
+  }
+  const affordable = candidates.filter((offer) => {
+    const max = options.maxAmount.get(offer.asset);
+    return max !== undefined && BigInt(offer.amount) <= max;
+  });
+  if (affordable.length === 0) {
+    const prices = candidates.map((c) => `${c.amount} ${c.asset}`).join(', ');
+    throw new ObbyxError('amount_over_limit', `Price (${prices}) exceeds your spending limit`);
+  }
+  return affordable;
+}
+
+/** Echoes the seller's extensions; fills the payment-identifier id if declared. */
+function withPaymentId(
+  extensions: Record<string, unknown>,
+  id: string | undefined,
+): Record<string, unknown> {
+  const declared = extensions['payment-identifier'] as
+    { info?: Record<string, unknown> } | undefined;
+  if (declared === undefined) return extensions;
+  const paymentId = id ?? `pay_${globalThis.crypto.randomUUID().replaceAll('-', '')}`;
+  return {
+    ...extensions,
+    'payment-identifier': { ...declared, info: { ...declared.info, id: paymentId } },
+  };
+}
+
+function acceptedOf(header: string): PaymentRequirements | undefined {
+  try {
+    return decodePaymentSignatureHeader(header).accepted;
+  } catch {
+    return undefined;
+  }
+}
+
+function readSettle(response: Response): SettleResponse | undefined {
+  const header = response.headers.get('PAYMENT-RESPONSE');
+  if (header === null) return undefined;
+  try {
+    return decodePaymentResponseHeader(header);
+  } catch {
+    return undefined;
+  }
+}
+
+function headersOf(headers: RequestInit['headers']): Record<string, string> {
+  return Object.fromEntries(new Headers(headers).entries());
+}

package/src/index.ts

@@ -0,0 +1,35 @@
+export {
+  type BindingInput,
+  bindingsEqual,
+  computeBinding,
+  newQuoteId,
+  sha256Hex,
+} from './seller/binding.js';
+export {
+  ConsumedProofsStore,
+  type ProofRecord,
+  type ProofState,
+  type StoredResponse,
+} from './seller/consumed-proofs.js';
+export {
+  ObytePaywall,
+  type ObytePaywallOptions,
+  type PaidHandler,
+  type PaidResult,
+  type PaidRouteOptions,
+  type PaywallScheme,
+  type RoutePrice,
+} from './seller/paywall.js';
+export {
+  type PaidResponse,
+  PaymentPendingError,
+  type PayingFetchOptions,
+  payingFetch,
+} from './client/paying-fetch.js';
+export {
+  type BudgetLimits,
+  BudgetExceededError,
+  type BudgetReservation,
+  SpendingBudget,
+} from './client/budget.js';
+export { ObyteExactServer, type ObyteExactServerOptions } from './seller/x402-server.js';

package/src/seller/binding.ts

@@ -0,0 +1,8 @@
+// Moved to @obbyx/x402-obyte (shared by the paywall and the @x402 server adapter).
+export {
+  type BindingInput,
+  bindingsEqual,
+  computeBinding,
+  newQuoteId,
+  sha256Hex,
+} from '@obbyx/x402-obyte';