@bosonprotocol/x402-client 0.1.0-alpha-0

package/dist/esm/index.js

@@ -0,0 +1,557 @@
+import { NoCompatibleActionError, FulfillmentValidationError, createCoreSdkFactory, UnsupportedTokenAuthError, buildAndSignTokenAuth, MaxAmountExceededError, randomUint256 } from './chunk-JTTWAQGC.js';
+export { FulfillmentValidationError, MaxAmountExceededError, NoCompatibleActionError, UnsupportedSchemeError, UnsupportedTokenAuthError, parseChainId } from './chunk-JTTWAQGC.js';
+import Ajv from 'ajv';
+import { parseEscrowPaymentRequirements, DECIMAL_UINT, parseEscrowPaymentPayload } from '@bosonprotocol/x402-core/schemes/escrow';
+import { encodeSignedPayload } from '@bosonprotocol/x402-evm/codec';
+import { serializeTypedData, getAddress } from 'viem';
+
+// src/action.ts
+var FLOW_A = "boson-createOfferAndCommit";
+var FLOW_B = "boson-createOfferCommitAndRedeem";
+function pickAction(requirements, policy) {
+  const redeemMode = policy?.redeemMode ?? "auto";
+  const flowAOffered = requirements.actions.next.some(
+    (a) => a.id === FLOW_A && a.channels.includes("server")
+  );
+  const flowBOffered = requirements.actions.next.some(
+    (a) => a.id === FLOW_B && a.channels.includes("server")
+  );
+  if (redeemMode === "commit-and-redeem") {
+    if (flowBOffered) return FLOW_B;
+    throw new NoCompatibleActionError(
+      `policy.redeemMode='commit-and-redeem' requires '${FLOW_B}' on the server channel; requirements only advertise [${requirements.actions.next.map((a) => a.id).join(", ")}]`
+    );
+  }
+  if (redeemMode === "commit-only") {
+    if (flowAOffered) return FLOW_A;
+    throw new NoCompatibleActionError(
+      `policy.redeemMode='commit-only' requires '${FLOW_A}' on the server channel; requirements only advertise [${requirements.actions.next.map((a) => a.id).join(", ")}]`
+    );
+  }
+  if (flowAOffered) return FLOW_A;
+  if (flowBOffered) return FLOW_B;
+  throw new NoCompatibleActionError(
+    `no commit-time action ('${FLOW_A}' or '${FLOW_B}') with 'server' channel found in requirements.actions.next`
+  );
+}
+function resolveFulfillment(requirements, config) {
+  const required = requirements.fulfillment?.required ?? false;
+  if (!required) {
+    return void 0;
+  }
+  const fulfillmentConfig = config.fulfillment;
+  if (!fulfillmentConfig) {
+    throw new FulfillmentValidationError(
+      "requirements.fulfillment.required is true but client config did not supply a fulfillment selection"
+    );
+  }
+  const option = requirements.fulfillment?.options.find((o) => o.id === fulfillmentConfig.option);
+  if (!option) {
+    const advertised = requirements.fulfillment?.options.map((o) => o.id).join(", ") ?? "<none>";
+    throw new FulfillmentValidationError(
+      `fulfillment option '${fulfillmentConfig.option}' not advertised by requirements (advertised: ${advertised})`
+    );
+  }
+  if (option.schema === null) {
+    if (fulfillmentConfig.data !== null) {
+      throw new FulfillmentValidationError(
+        `fulfillment option '${option.id}' accepts no buyer data; use null`
+      );
+    }
+  } else {
+    const ajv = new Ajv({ allErrors: true, strict: false });
+    const validate = ajv.compile(option.schema);
+    const ok = validate(fulfillmentConfig.data);
+    if (!ok) {
+      throw new FulfillmentValidationError(
+        `fulfillment data does not match option '${option.id}' schema: ${ajv.errorsText(validate.errors)}`
+      );
+    }
+  }
+  return { option: fulfillmentConfig.option, data: fulfillmentConfig.data };
+}
+
+// src/response.ts
+var HEADER_NAME = "X-PAYMENT-RESPONSE";
+function parsePaymentResponse(response) {
+  const raw = response.headers.get(HEADER_NAME);
+  if (!raw) {
+    return void 0;
+  }
+  const json = decodeBase64(raw);
+  const parsed = JSON.parse(json);
+  const summary = { raw: parsed };
+  if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+    const obj = parsed;
+    const exchangeId = pickString(obj, ["exchangeId", "exchange_id"]);
+    if (exchangeId !== void 0) {
+      summary.exchangeId = exchangeId;
+    }
+    if (isClientStateShape(obj.state)) {
+      summary.state = obj.state;
+    }
+    if (summary.state === void 0 && typeof obj.nextActions === "object" && obj.nextActions !== null && !Array.isArray(obj.nextActions)) {
+      const na = obj.nextActions;
+      const exchange = pickString(na, ["exchangeState"]);
+      const dispute = pickString(na, ["disputeState"]);
+      if (exchange !== void 0) {
+        let candidate;
+        if (exchange === "DISPUTED") {
+          candidate = dispute !== void 0 ? { exchange, dispute } : void 0;
+        } else {
+          candidate = { exchange };
+        }
+        if (isClientStateShape(candidate)) {
+          summary.state = candidate;
+        }
+      }
+    }
+  }
+  return summary;
+}
+function isClientStateShape(v) {
+  if (typeof v === "string") return v.length > 0;
+  if (typeof v !== "object" || v === null || Array.isArray(v)) return false;
+  const rec = v;
+  if (typeof rec.exchange !== "string" || rec.exchange.length === 0) return false;
+  if ("dispute" in rec && rec.dispute !== void 0 && typeof rec.dispute !== "string") {
+    return false;
+  }
+  return true;
+}
+function decodeBase64(value) {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(value, "base64").toString("utf8");
+  }
+  const binary = atob(value);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return new TextDecoder().decode(bytes);
+}
+function pickString(obj, keys) {
+  for (const key of keys) {
+    const v = obj[key];
+    if (typeof v === "string" && v.length > 0) {
+      return v;
+    }
+  }
+  return void 0;
+}
+var X402_VERSION = 2;
+function assemblePayload({
+  requirements,
+  action,
+  tokenAuthStrategy,
+  metaTx,
+  tokenAuth,
+  fulfillment,
+  buyer
+}) {
+  const fulfillmentSlot = fulfillment === void 0 ? void 0 : action === "boson-createOfferCommitAndRedeem" ? { option: fulfillment.option, data: fulfillment.data } : { option: fulfillment.option };
+  const payload = {
+    x402Version: X402_VERSION,
+    scheme: "escrow",
+    network: requirements.network,
+    payload: {
+      action,
+      tokenAuthStrategy,
+      offerRef: {
+        fullOffer: requirements.offer.fullOffer,
+        sellerSig: requirements.offer.sellerSig
+      },
+      buyer,
+      metaTx,
+      ...tokenAuth ? { tokenAuth } : {}
+    },
+    ...fulfillmentSlot ? { fulfillment: fulfillmentSlot } : {}
+  };
+  parseEscrowPaymentPayload(payload);
+  return payload;
+}
+function assembleAndEncodePayload(args) {
+  const payload = assemblePayload(args);
+  const json = JSON.stringify(payload);
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(json, "utf8").toString("base64");
+  }
+  const bytes = new TextEncoder().encode(json);
+  let binary = "";
+  for (const b of bytes) {
+    binary += String.fromCharCode(b);
+  }
+  return btoa(binary);
+}
+
+// src/pre-commit.ts
+async function signCreateOfferAndCommit({
+  requirements,
+  coreSdk,
+  buyer
+}) {
+  const nonce = randomUint256();
+  const createOfferAndCommitArgs = buildCreateOfferAndCommitArgs(requirements, buyer);
+  const signed = await coreSdk.signMetaTxCreateOfferAndCommit({
+    nonce: nonce.toString(),
+    createOfferAndCommitArgs
+  });
+  return reshape(signed, buyer, nonce);
+}
+async function signCreateOfferCommitAndRedeem({
+  requirements,
+  coreSdk,
+  buyer
+}) {
+  const nonce = randomUint256();
+  const createOfferAndCommitArgs = buildCreateOfferAndCommitArgs(requirements, buyer);
+  const signed = await coreSdk.signMetaTxCreateOfferCommitAndRedeem({
+    nonce: nonce.toString(),
+    createOfferAndCommitArgs
+  });
+  return reshape(signed, buyer, nonce);
+}
+function buildCreateOfferAndCommitArgs(requirements, buyer) {
+  return {
+    ...requirements.offer.fullOffer,
+    signature: requirements.offer.sellerSig,
+    committer: buyer
+  };
+}
+function reshape(signed, buyer, nonce) {
+  return {
+    from: buyer,
+    nonce: nonce.toString(),
+    functionName: signed.functionName,
+    functionSignature: signed.functionSignature,
+    sig: {
+      v: Number(signed.v),
+      r: signed.r,
+      s: signed.s
+    }
+  };
+}
+async function signPostCommitAction(args, deps) {
+  const nonce = randomUint256();
+  const buyer = await deps.getBuyerAddress();
+  const { coreSdk } = deps.buildCoreSdk(args.network, args.escrowAddress);
+  const signed = await callSignMetaTx(coreSdk, args, nonce);
+  const metaTx = {
+    from: buyer,
+    nonce: nonce.toString(),
+    functionName: signed.functionName,
+    functionSignature: signed.functionSignature,
+    sig: {
+      v: Number(signed.v),
+      r: signed.r,
+      s: signed.s
+    }
+  };
+  return { metaTx, signedPayload: encodeSignedPayload(metaTx) };
+}
+async function callSignMetaTx(coreSdk, args, nonce) {
+  const nonceStr = nonce.toString();
+  const exchangeId = args.exchangeId;
+  switch (args.actionId) {
+    case "boson-redeem":
+      return coreSdk.signMetaTxRedeemVoucher({ nonce: nonceStr, exchangeId });
+    case "boson-cancelVoucher":
+      return coreSdk.signMetaTxCancelVoucher({ nonce: nonceStr, exchangeId });
+    case "boson-completeExchange":
+      return coreSdk.signMetaTxCompleteExchange({ nonce: nonceStr, exchangeId });
+    case "boson-raiseDispute":
+      return coreSdk.signMetaTxRaiseDispute({ nonce: nonceStr, exchangeId });
+    case "boson-retractDispute":
+      return coreSdk.signMetaTxRetractDispute({ nonce: nonceStr, exchangeId });
+    case "boson-escalateDispute":
+      return coreSdk.signMetaTxEscalateDispute({ nonce: nonceStr, exchangeId });
+    case "boson-resolveDispute":
+      return coreSdk.signMetaTxResolveDispute({
+        nonce: nonceStr,
+        exchangeId,
+        buyerPercent: args.buyerPercent,
+        counterpartySig: args.counterpartySig
+      });
+    default: {
+      const _exhaustive = args;
+      throw new Error(
+        `x402-client: unsupported post-commit action '${_exhaustive.actionId}'`
+      );
+    }
+  }
+}
+function normalizeEntityId(value) {
+  if (typeof value === "bigint") {
+    if (value < 0n) throw new Error(`entityId must be non-negative, got ${value.toString()}`);
+    return value.toString();
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || !Number.isInteger(value) || value < 0) {
+      throw new Error(`entityId must be a non-negative integer, got ${String(value)}`);
+    }
+    return value.toString();
+  }
+  const trimmed = value.trim();
+  if (trimmed.length === 0 || !DECIMAL_UINT.test(trimmed)) {
+    throw new Error(`entityId must be a decimal non-negative integer string, got "${value}"`);
+  }
+  return trimmed;
+}
+async function signWithdrawFunds(args, deps) {
+  const normalised = {
+    ...args,
+    entityId: normalizeEntityId(args.entityId)
+  };
+  const { coreSdk } = deps.buildCoreSdk(normalised.network, normalised.escrowAddress);
+  const from = await deps.getSignerAddress();
+  return signWithdrawFundsInternal(normalised, coreSdk, from);
+}
+async function signWithdrawAllAvailableFunds(args, deps) {
+  const { coreSdk } = deps.buildCoreSdk(args.network, args.escrowAddress);
+  const sdk = coreSdk;
+  const from = await deps.getSignerAddress();
+  const entityId = await resolveEntityIdClientSide(sdk, args);
+  const funds = await sdk.getFunds({ fundsFilter: { accountId: entityId } });
+  const nonZero = funds.filter((f) => f.availableAmount !== "0" && BigInt(f.availableAmount) > 0n);
+  if (nonZero.length === 0) {
+    throw new Error(
+      `signWithdrawAllAvailableFunds: entity ${entityId} has no available funds to withdraw`
+    );
+  }
+  return signWithdrawFundsInternal(
+    {
+      entityId,
+      network: args.network,
+      escrowAddress: args.escrowAddress,
+      tokenList: nonZero.map((f) => f.token.address),
+      tokenAmounts: nonZero.map((f) => f.availableAmount)
+    },
+    sdk,
+    from
+  );
+}
+async function signWithdrawFundsInternal(args, coreSdk, from) {
+  if (args.tokenList.length !== args.tokenAmounts.length) {
+    throw new Error(
+      `signWithdrawFunds: tokenList (${args.tokenList.length}) and tokenAmounts (${args.tokenAmounts.length}) must be the same length`
+    );
+  }
+  const nonce = randomUint256();
+  const nonceStr = nonce.toString();
+  const signed = await coreSdk.signMetaTxWithdrawFunds({
+    nonce: nonceStr,
+    entityId: args.entityId,
+    tokenList: args.tokenList.map((t) => t),
+    tokenAmounts: args.tokenAmounts.map((a) => a)
+  });
+  const metaTx = {
+    from,
+    nonce: nonceStr,
+    functionName: signed.functionName,
+    functionSignature: signed.functionSignature,
+    sig: {
+      v: Number(signed.v),
+      r: signed.r,
+      s: signed.s
+    }
+  };
+  return {
+    metaTx,
+    signedPayload: encodeSignedPayload(metaTx),
+    entityId: normalizeEntityId(args.entityId),
+    tokenList: args.tokenList,
+    tokenAmounts: args.tokenAmounts.map((a) => String(a))
+  };
+}
+async function resolveEntityIdClientSide(coreSdk, selector) {
+  if ("entityId" in selector) return normalizeEntityId(selector.entityId);
+  const address = selector.address.toLowerCase();
+  const role = selector.role;
+  const [sellers, buyers] = await Promise.all([
+    role === "buyer" ? Promise.resolve([]) : coreSdk.getSellersByAddress(address),
+    role === "seller" ? Promise.resolve([]) : coreSdk.getBuyers({ buyersFilter: { wallet: address } })
+  ]);
+  const sellerIds = sellers.map((s) => s.id);
+  const buyerIds = buyers.map((b) => b.id);
+  if (role === "seller") {
+    if (sellerIds.length === 0) {
+      throw new Error(
+        `signWithdrawAllAvailableFunds: no seller entity found for address ${address}`
+      );
+    }
+    if (sellerIds.length > 1) {
+      throw new Error(
+        `signWithdrawAllAvailableFunds: address ${address} resolves to multiple seller entities (ids ${sellerIds.join(", ")}); pass entityId to disambiguate`
+      );
+    }
+    return sellerIds[0];
+  }
+  if (role === "buyer") {
+    if (buyerIds.length === 0) {
+      throw new Error(
+        `signWithdrawAllAvailableFunds: no buyer entity found for address ${address}`
+      );
+    }
+    if (buyerIds.length > 1) {
+      throw new Error(
+        `signWithdrawAllAvailableFunds: address ${address} resolves to multiple buyer entities (ids ${buyerIds.join(", ")}); pass entityId to disambiguate`
+      );
+    }
+    return buyerIds[0];
+  }
+  const totalMatches = sellerIds.length + buyerIds.length;
+  if (totalMatches === 0) {
+    throw new Error(
+      `signWithdrawAllAvailableFunds: no seller or buyer entity found for address ${address}`
+    );
+  }
+  if (totalMatches > 1) {
+    throw new Error(
+      `signWithdrawAllAvailableFunds: address ${address} resolves to ${describeClientMatches(sellerIds, buyerIds)}; pass role and/or entityId to disambiguate`
+    );
+  }
+  if (sellerIds.length === 1) return sellerIds[0];
+  return buyerIds[0];
+}
+function describeClientMatches(sellerIds, buyerIds) {
+  const parts = [];
+  if (sellerIds.length > 0) {
+    parts.push(
+      sellerIds.length === 1 ? `seller (id ${sellerIds[0]})` : `${sellerIds.length} sellers (ids ${sellerIds.join(", ")})`
+    );
+  }
+  if (buyerIds.length > 0) {
+    parts.push(
+      buyerIds.length === 1 ? `buyer (id ${buyerIds[0]})` : `${buyerIds.length} buyers (ids ${buyerIds.join(", ")})`
+    );
+  }
+  return parts.join(" and ");
+}
+
+// src/client.ts
+function createX402bClient(config) {
+  const buildCoreSdk = createCoreSdkFactory(config.signer, config);
+  const getBuyerAddress = async () => await config.signer.getAddress();
+  return {
+    async handle402(rawRequirements) {
+      const requirements = parseEscrowPaymentRequirements(rawRequirements);
+      const action = pickAction(requirements, config.policy);
+      const fulfillment = resolveFulfillment(requirements, config);
+      enforceMaxAmount(requirements.amount, config.policy?.maxAmount);
+      const buyer = await getBuyerAddress();
+      const { coreSdk, chainId } = buildCoreSdk(
+        requirements.network,
+        requirements.escrowAddress
+      );
+      let tokenAuth;
+      let strategy;
+      const forcedStrategy = config.policy?.tokenAuthStrategy;
+      if (forcedStrategy !== void 0) {
+        if (!requirements.tokenAuthStrategies.includes(forcedStrategy)) {
+          throw new UnsupportedTokenAuthError(
+            `policy.tokenAuthStrategy "${forcedStrategy}" is not in requirements.tokenAuthStrategies (${requirements.tokenAuthStrategies.join(", ")})`
+          );
+        }
+        if (forcedStrategy === "none") {
+          strategy = "none";
+          tokenAuth = void 0;
+        } else {
+          const built = await buildAndSignTokenAuth({
+            requirements: { ...requirements, tokenAuthStrategies: [forcedStrategy] },
+            buyer,
+            coreSdk,
+            tokenDomainResolver: config.tokenDomainResolver,
+            publicClient: config.publicClients?.[chainId]
+          });
+          strategy = built.strategy;
+          tokenAuth = built.tokenAuth;
+        }
+      } else {
+        const built = await buildAndSignTokenAuth({
+          requirements,
+          buyer,
+          coreSdk,
+          tokenDomainResolver: config.tokenDomainResolver,
+          publicClient: config.publicClients?.[chainId]
+        });
+        strategy = built.strategy;
+        tokenAuth = built.tokenAuth;
+      }
+      const signMetaTx = action === "boson-createOfferCommitAndRedeem" ? signCreateOfferCommitAndRedeem : signCreateOfferAndCommit;
+      const metaTx = await signMetaTx({ requirements, coreSdk, buyer });
+      return assembleAndEncodePayload({
+        requirements,
+        action,
+        tokenAuthStrategy: strategy,
+        metaTx,
+        tokenAuth,
+        fulfillment,
+        buyer
+      });
+    },
+    signAction(args) {
+      return signPostCommitAction(args, { buildCoreSdk, getBuyerAddress });
+    },
+    signWithdrawFunds(args) {
+      return signWithdrawFunds(args, { buildCoreSdk, getSignerAddress: getBuyerAddress });
+    },
+    signWithdrawAllAvailableFunds(args) {
+      return signWithdrawAllAvailableFunds(args, {
+        buildCoreSdk,
+        getSignerAddress: getBuyerAddress
+      });
+    },
+    parsePaymentResponse(response) {
+      return parsePaymentResponse(response);
+    }
+  };
+}
+function enforceMaxAmount(amount, maxAmount) {
+  if (maxAmount === void 0) {
+    return;
+  }
+  const amountBigInt = BigInt(amount);
+  const maxAmountBigInt = BigInt(maxAmount);
+  if (amountBigInt > maxAmountBigInt) {
+    throw new MaxAmountExceededError(
+      `x402-client: requirements.amount ${amount} exceeds policy.maxAmount ${maxAmount}`
+    );
+  }
+}
+function signerFromEthersAdapter(adapter) {
+  const resolveAddress = async () => getAddress(await adapter.getSignerAddress());
+  return {
+    getAddress: resolveAddress,
+    signTypedData: async ({ domain, types, primaryType, message }) => {
+      const from = await resolveAddress();
+      const typedData = {
+        domain,
+        types: { ...types, EIP712Domain: deriveEip712DomainType(domain) },
+        primaryType,
+        message
+      };
+      const json = serializeTypedData(typedData);
+      const sig = await adapter.send("eth_signTypedData_v4", [from, json]);
+      if (typeof sig !== "string" || !/^0x[0-9a-fA-F]+$/.test(sig)) {
+        throw new Error(
+          "signerFromEthersAdapter: adapter.send did not return a hex signature string"
+        );
+      }
+      return sig;
+    }
+  };
+}
+function deriveEip712DomainType(domain) {
+  const fields = [];
+  if (domain.name !== void 0) fields.push({ name: "name", type: "string" });
+  if (domain.version !== void 0) fields.push({ name: "version", type: "string" });
+  if (domain.chainId !== void 0) fields.push({ name: "chainId", type: "uint256" });
+  if (domain.verifyingContract !== void 0)
+    fields.push({ name: "verifyingContract", type: "address" });
+  if (domain.salt !== void 0) fields.push({ name: "salt", type: "bytes32" });
+  return fields;
+}
+
+export { createX402bClient, parsePaymentResponse, pickAction, resolveFulfillment, signerFromEthersAdapter };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map