402-trinity-gaming 0.1.0

package/dist/seller.js

@@ -0,0 +1,136 @@
+const USDC = {
+  // Base only, matching the wrapper. Anything else needs explicit asset + extra.
+  "base": { asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", caip2: "eip155:8453", name: "USD Coin", version: "2" }
+};
+function createX402Seller(cfg) {
+  if (!/^0x[0-9a-fA-F]{40}$/.test(cfg.payTo)) throw new Error("x402 seller: payTo must be a 20-byte address");
+  if (!/^[0-9]+$/.test(cfg.price) || BigInt(cfg.price) <= 0n) throw new Error("x402 seller: price must be a positive integer in atomic units");
+  const key = cfg.network.toLowerCase();
+  const known = USDC[key] ?? Object.values(USDC).find((u) => u.caip2 === key);
+  if (!known && !(cfg.asset && cfg.extra)) throw new Error(`x402 seller: unknown network '${cfg.network}' - pass asset and extra explicitly`);
+  if (!cfg.facilitator || !/^https?:\/\//.test(cfg.facilitator)) {
+    throw new Error(
+      "x402 seller: `facilitator` is required and must be an http(s) URL. There is no default - the public x402.org facilitator settles testnet only, so defaulting to it would make every mainnet payment verify and then fail to settle."
+    );
+  }
+  const facilitator = cfg.facilitator.replace(/\/$/, "");
+  const timeout = cfg.maxTimeoutSeconds ?? 600;
+  const requirements = {
+    scheme: "exact",
+    network: known?.caip2 ?? cfg.network,
+    amount: cfg.price,
+    asset: cfg.asset ?? known.asset,
+    payTo: cfg.payTo,
+    maxTimeoutSeconds: timeout,
+    extra: cfg.extra ?? { name: known.name, version: known.version }
+  };
+  if (!cfg.nonceStore && !cfg.acknowledgeEphemeralReplayGuard) {
+    throw new Error(
+      `x402 seller: network '${cfg.network}' needs a durable nonceStore. The default replay guard is in-memory and forgets every settled payment on restart, so a buyer could re-present one and get the resource again for free. Pass nonceStore (see createFileNonceStore) or acknowledgeEphemeralReplayGuard: true.`
+    );
+  }
+  const seenLocal = /* @__PURE__ */ new Map();
+  let lastPrune = 0;
+  const store = cfg.nonceStore ?? {
+    seen: async (n) => {
+      const now = Math.floor(Date.now() / 1e3);
+      if (now - lastPrune > 60) {
+        lastPrune = now;
+        for (const [k, exp2] of seenLocal) if (exp2 <= now) seenLocal.delete(k);
+      }
+      const exp = seenLocal.get(n.toLowerCase());
+      return exp !== void 0 && exp > now;
+    },
+    add: async (n, expiresAt) => {
+      seenLocal.set(n.toLowerCase(), expiresAt);
+    }
+  };
+  const post = async (path, body) => {
+    const r = await fetch(facilitator + path, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(45e3)
+    });
+    const text = await r.text();
+    try {
+      return JSON.parse(text);
+    } catch {
+      return { _raw: text, _status: r.status };
+    }
+  };
+  const challenge = (url) => new Response(
+    JSON.stringify({ error: "payment required", price: cfg.price, payTo: cfg.payTo }),
+    {
+      status: 402,
+      headers: {
+        "content-type": "application/json",
+        // v2 transport: protocol data rides in the header, the body is the app's own
+        "payment-required": JSON.stringify({
+          x402Version: 2,
+          error: "PAYMENT-SIGNATURE header is required",
+          resource: { url, description: cfg.description ?? "paid resource", mimeType: "application/json" },
+          accepts: [requirements]
+        })
+      }
+    }
+  );
+  return {
+    requirements,
+    /** Returns {response} when the caller must NOT serve the resource. */
+    async guard(request) {
+      const url = request.url;
+      const header = request.headers.get("payment-signature") ?? request.headers.get("x-payment");
+      if (!header) return { response: challenge(url), reason: "no payment presented" };
+      let payload;
+      try {
+        payload = JSON.parse(atob(header));
+      } catch {
+        return { response: challenge(url), reason: "malformed payment header" };
+      }
+      const nonce = payload?.payload?.authorization?.nonce;
+      if (typeof nonce !== "string") return { response: challenge(url), reason: "payment missing an authorization nonce" };
+      if (await store.seen(nonce)) return { response: challenge(url), reason: "authorization nonce already used" };
+      const v = await post("/verify", { x402Version: 2, paymentPayload: payload, paymentRequirements: requirements });
+      if (v?.isValid !== true) {
+        return { response: challenge(url), reason: "facilitator rejected: " + (v?.invalidReason ?? JSON.stringify(v)) };
+      }
+      const attempts = Math.max(1, cfg.settleRetries ?? 3);
+      const backoff = cfg.settleBackoffMs ?? 1500;
+      let s = null;
+      for (let i = 0; i < attempts; i++) {
+        s = await post("/settle", { x402Version: 2, paymentPayload: payload, paymentRequirements: requirements });
+        if (s?.success === true) break;
+        if (i < attempts - 1) await new Promise((r) => setTimeout(r, backoff * (i + 1)));
+      }
+      if (s?.success !== true) {
+        const reason = "settlement failed after " + attempts + " attempts: " + (s?.errorReason ?? JSON.stringify(s));
+        cfg.onSettleFailure?.({ reason, attempts, nonce });
+        return {
+          settlementFailed: true,
+          reason,
+          response: new Response(JSON.stringify({
+            error: "settlement_unavailable",
+            detail: "Your payment was valid. Settlement failed on our side. Retry with the SAME payment header.",
+            reason: s?.errorReason ?? null
+          }), {
+            status: 503,
+            headers: { "content-type": "application/json", "retry-after": "5" }
+          })
+        };
+      }
+      const expiresAt = Number(payload?.payload?.authorization?.validBefore ?? 0) || Math.floor(Date.now() / 1e3) + timeout;
+      await store.add(nonce, expiresAt);
+      const settlement = { transaction: s.transaction, payer: s.payer, network: s.network };
+      cfg.onSettled?.({ ...settlement, amount: cfg.price });
+      return { response: null, settlement };
+    },
+    /** Header a paid response should carry, so the buyer can read the receipt. */
+    receiptHeader(settlement) {
+      return { "payment-response": btoa(JSON.stringify({ success: true, ...settlement })) };
+    }
+  };
+}
+export {
+  createX402Seller
+};

package/dist/seller.min.js

@@ -0,0 +1 @@
+const S={base:{asset:"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",caip2:"eip155:8453",name:"USD Coin",version:"2"}};function T(e){if(!/^0x[0-9a-fA-F]{40}$/.test(e.payTo))throw new Error("x402 seller: payTo must be a 20-byte address");if(!/^[0-9]+$/.test(e.price)||BigInt(e.price)<=0n)throw new Error("x402 seller: price must be a positive integer in atomic units");const y=e.network.toLowerCase(),l=S[y]??Object.values(S).find(t=>t.caip2===y);if(!l&&!(e.asset&&e.extra))throw new Error(`x402 seller: unknown network '${e.network}' - pass asset and extra explicitly`);if(!e.facilitator||!/^https?:\/\//.test(e.facilitator))throw new Error("x402 seller: `facilitator` is required and must be an http(s) URL. There is no default - the public x402.org facilitator settles testnet only, so defaulting to it would make every mainnet payment verify and then fail to settle.");const b=e.facilitator.replace(/\/$/,""),w=e.maxTimeoutSeconds??600,c={scheme:"exact",network:l?.caip2??e.network,amount:e.price,asset:e.asset??l.asset,payTo:e.payTo,maxTimeoutSeconds:w,extra:e.extra??{name:l.name,version:l.version}};if(!e.nonceStore&&!e.acknowledgeEphemeralReplayGuard)throw new Error(`x402 seller: network '${e.network}' needs a durable nonceStore. The default replay guard is in-memory and forgets every settled payment on restart, so a buyer could re-present one and get the resource again for free. Pass nonceStore (see createFileNonceStore) or acknowledgeEphemeralReplayGuard: true.`);const u=new Map;let f=0;const h=e.nonceStore??{seen:async t=>{const n=Math.floor(Date.now()/1e3);if(n-f>60){f=n;for(const[r,i]of u)i<=n&&u.delete(r)}const a=u.get(t.toLowerCase());return a!==void 0&&a>n},add:async(t,n)=>{u.set(t.toLowerCase(),n)}},g=async(t,n)=>{const a=await fetch(b+t,{method:"POST",headers:{"content-type":"application/json"},body:JSON.stringify(n),signal:AbortSignal.timeout(45e3)}),r=await a.text();try{return JSON.parse(r)}catch{return{_raw:r,_status:a.status}}},p=t=>new Response(JSON.stringify({error:"payment required",price:e.price,payTo:e.payTo}),{status:402,headers:{"content-type":"application/json","payment-required":JSON.stringify({x402Version:2,error:"PAYMENT-SIGNATURE header is required",resource:{url:t,description:e.description??"paid resource",mimeType:"application/json"},accepts:[c]})}});return{requirements:c,async guard(t){const n=t.url,a=t.headers.get("payment-signature")??t.headers.get("x-payment");if(!a)return{response:p(n),reason:"no payment presented"};let r;try{r=JSON.parse(atob(a))}catch{return{response:p(n),reason:"malformed payment header"}}const i=r?.payload?.authorization?.nonce;if(typeof i!="string")return{response:p(n),reason:"payment missing an authorization nonce"};if(await h.seen(i))return{response:p(n),reason:"authorization nonce already used"};const m=await g("/verify",{x402Version:2,paymentPayload:r,paymentRequirements:c});if(m?.isValid!==!0)return{response:p(n),reason:"facilitator rejected: "+(m?.invalidReason??JSON.stringify(m))};const d=Math.max(1,e.settleRetries??3),k=e.settleBackoffMs??1500;let s=null;for(let o=0;o<d&&(s=await g("/settle",{x402Version:2,paymentPayload:r,paymentRequirements:c}),s?.success!==!0);o++)o<d-1&&await new Promise(v=>setTimeout(v,k*(o+1)));if(s?.success!==!0){const o="settlement failed after "+d+" attempts: "+(s?.errorReason??JSON.stringify(s));return e.onSettleFailure?.({reason:o,attempts:d,nonce:i}),{settlementFailed:!0,reason:o,response:new Response(JSON.stringify({error:"settlement_unavailable",detail:"Your payment was valid. Settlement failed on our side. Retry with the SAME payment header.",reason:s?.errorReason??null}),{status:503,headers:{"content-type":"application/json","retry-after":"5"}})}}const R=Number(r?.payload?.authorization?.validBefore??0)||Math.floor(Date.now()/1e3)+w;await h.add(i,R);const x={transaction:s.transaction,payer:s.payer,network:s.network};return e.onSettled?.({...x,amount:e.price}),{response:null,settlement:x}},receiptHeader(t){return{"payment-response":btoa(JSON.stringify({success:!0,...t}))}}}}export{T as createX402Seller};

package/dist/signer.d.ts

@@ -0,0 +1,64 @@
+/**
+ * THE CLIENT SIGNER.
+ *
+ * The only piece that touches the player's key, and the only piece that has to be ported to
+ * C# and C++ later. It makes ONE EIP-712 signature and returns. No network, no protocol, no
+ * state - a pure function of (quote, key).
+ *
+ *     const { authorization, signature } = signPurchase(quote, playerKey);
+ *     // POST { itemId, playerId, playerAddress, authorization, signature } to your backend
+ *
+ * WHY THIS IS SEPARATE. The studio's server runs the protocol but must never hold a player's
+ * key - that is what keeps them out of custody and out of money transmission. So the key
+ * stays with the player, and the only thing that crosses the wire is a signature that can
+ * buy exactly one item, once, before it expires.
+ *
+ * WHAT A LEAKED KEY COSTS. A player's key protects only that player's own balance. That is
+ * why per-player wallets are safe where a shared studio wallet would not be: extraction is
+ * bounded by what the player themselves funded.
+ */
+import { type Authorization } from './x402.js';
+export interface Quote {
+    /** CAIP-2 chain id, e.g. 'eip155:8453'. */
+    network: string;
+    /** Atomic units, as a decimal string. */
+    amount?: string;
+    maxAmountRequired?: string;
+    /** Who is paid - the studio's wallet. */
+    payTo: string;
+    /** The asset contract. USDC on Base by default. */
+    asset?: string;
+    /** How long the quote is good for, in seconds. */
+    maxTimeoutSeconds?: number;
+    /** EIP-712 domain fields. A wrong name or version signs something the contract rejects. */
+    extra?: {
+        name?: string;
+        version?: string;
+    };
+}
+export interface SignedPurchase {
+    authorization: Authorization;
+    /** 65 bytes, 0x-prefixed. */
+    signature: string;
+    /** The address that signed - hand this to the backend as playerAddress. */
+    playerAddress: string;
+}
+/** Derive a player's wallet address from their key, without signing anything. */
+export declare function addressFor(privateKey: string): string;
+/**
+ * Generate a fresh player wallet. Returns the key ONCE - store it encrypted, and give the
+ * player a way to back it up. There is no recovery path: whoever holds the key holds the
+ * funds, and losing it loses whatever the player put in.
+ */
+export declare function createPlayerWallet(): {
+    privateKey: string;
+    address: string;
+};
+/**
+ * Sign one purchase.
+ *
+ * The authorization is bounded three ways: it names the exact recipient, it names the exact
+ * amount, and it expires. It carries a random 32-byte nonce that the asset contract redeems
+ * once - so even if the signature is captured in flight it can buy that one item, once.
+ */
+export declare function signPurchase(quote: Quote, privateKey: string): SignedPurchase;

package/dist/signer.js

@@ -0,0 +1,61 @@
+import { toHex, fromHex, __internals } from "./x402.js";
+const { addressOf, digest, domainSep, makeNonce, signWith, toBig, CHAINS } = __internals;
+function addressFor(privateKey) {
+  const d = toBig(fromHex(privateKey));
+  if (d === 0n || d >= __internals.N) throw new Error("signer: invalid key material");
+  return addressOf(d);
+}
+function createPlayerWallet() {
+  const b = new Uint8Array(32);
+  for (; ; ) {
+    crypto.getRandomValues(b);
+    const d = toBig(b);
+    if (d > 0n && d < __internals.N) return { privateKey: toHex(b), address: addressOf(d) };
+  }
+}
+function signPurchase(quote, privateKey) {
+  const d = toBig(fromHex(privateKey));
+  if (d === 0n || d >= __internals.N) throw new Error("signer: invalid key material");
+  const from = addressOf(d);
+  const value = quote.amount ?? quote.maxAmountRequired;
+  if (typeof value !== "string" || !/^[0-9]+$/.test(value) || BigInt(value) <= 0n) {
+    throw new Error("signer: quote must carry a positive integer amount in atomic units");
+  }
+  if (!/^0x[0-9a-fA-F]{40}$/.test(quote.payTo)) {
+    throw new Error("signer: quote.payTo must be a 20-byte address");
+  }
+  const chain = CHAINS[quote.network.toLowerCase()] ?? Object.values(CHAINS).find((c) => c.caip2 === quote.network);
+  if (!chain && !(quote.asset && quote.extra?.name && quote.extra?.version)) {
+    throw new Error(
+      `signer: unknown network '${quote.network}' - pass asset and extra (name, version) explicitly`
+    );
+  }
+  const asset = quote.asset ?? chain.asset;
+  const name = quote.extra?.name ?? chain.name;
+  const version = quote.extra?.version ?? chain.version;
+  const chainId = chain?.id ?? Number(quote.network.split(":")[1]);
+  if (!Number.isInteger(chainId) || chainId <= 0) {
+    throw new Error(`signer: cannot determine chain id from '${quote.network}'`);
+  }
+  const now = Math.floor(Date.now() / 1e3);
+  const n32 = new Uint8Array(32);
+  crypto.getRandomValues(n32);
+  const authorization = {
+    from,
+    to: quote.payTo,
+    value,
+    // Sixty seconds of slack: a player's clock is not the chain's, and a validAfter in the
+    // future makes the transfer revert.
+    validAfter: String(now - 60),
+    validBefore: String(now + (quote.maxTimeoutSeconds ?? 600)),
+    nonce: toHex(n32)
+  };
+  const dsep = domainSep(name, version, chainId, asset);
+  const signature = signWith(makeNonce(), digest(dsep, authorization), d);
+  return { authorization, signature, playerAddress: from };
+}
+export {
+  addressFor,
+  createPlayerWallet,
+  signPurchase
+};

package/dist/signer.min.js

@@ -0,0 +1 @@
+import{toHex as u,fromHex as y,__internals as i}from"./x402.js";const{addressOf:o,digest:k,domainSep:S,makeNonce:b,signWith:N,toBig:c,CHAINS:w}=i;function T(n){const r=c(y(n));if(r===0n||r>=i.N)throw new Error("signer: invalid key material");return o(r)}function z(){const n=new Uint8Array(32);for(;;){crypto.getRandomValues(n);const r=c(n);if(r>0n&&r<i.N)return{privateKey:u(n),address:o(r)}}}function R(n,r){const t=c(y(r));if(t===0n||t>=i.N)throw new Error("signer: invalid key material");const d=o(t),s=n.amount??n.maxAmountRequired;if(typeof s!="string"||!/^[0-9]+$/.test(s)||BigInt(s)<=0n)throw new Error("signer: quote must carry a positive integer amount in atomic units");if(!/^0x[0-9a-fA-F]{40}$/.test(n.payTo))throw new Error("signer: quote.payTo must be a 20-byte address");const e=w[n.network.toLowerCase()]??Object.values(w).find(A=>A.caip2===n.network);if(!e&&!(n.asset&&n.extra?.name&&n.extra?.version))throw new Error(`signer: unknown network '${n.network}' - pass asset and extra (name, version) explicitly`);const f=n.asset??e.asset,l=n.extra?.name??e.name,h=n.extra?.version??e.version,a=e?.id??Number(n.network.split(":")[1]);if(!Number.isInteger(a)||a<=0)throw new Error(`signer: cannot determine chain id from '${n.network}'`);const g=Math.floor(Date.now()/1e3),m=new Uint8Array(32);crypto.getRandomValues(m);const p={from:d,to:n.payTo,value:s,validAfter:String(g-60),validBefore:String(g+(n.maxTimeoutSeconds??600)),nonce:u(m)},x=S(l,h,a,f),v=N(b(),k(x,p),t);return{authorization:p,signature:v,playerAddress:d}}export{T as addressFor,z as createPlayerWallet,R as signPurchase};

package/dist/storefront.d.ts

@@ -0,0 +1,143 @@
+/**
+ * THE HEADLESS STOREFRONT BRIDGE.
+ *
+ * A studio's own UI calls in; events come back out. Nothing here renders, opens a browser,
+ * takes over input, or writes to the console. The player never learns this exists.
+ *
+ *     const store = createStorefront({
+ *       payTo: '0x...',                       // where the studio is paid
+ *       network: 'base',
+ *       facilitator: 'https://...',
+ *       catalog: { vanguard_skin_01: '1500000' },   // atomic units: 1.50 USDC
+ *       nonceStore,                            // durable - see below
+ *     });
+ *
+ *     store.on('settled', e => grantItem(e.playerId, e.itemId));
+ *     store.on('declined', e => showRefusal(e.reason));
+ *
+ *     const quote = store.quote('vanguard_skin_01');   // client signs this
+ *     await store.purchase({ itemId, playerId, playerAddress, authorization, signature });
+ *
+ * WHY THE SPLIT. The signature is the only thing that needs the player's key, and it is a
+ * pure function - no network, no protocol. So it happens on the client, and everything
+ * else happens here, on the studio's server, using the payment path that has been settling
+ * real money on mainnet. The studio never holds a key and never holds a balance.
+ */
+import { type SellerConfig } from './seller.js';
+import { type ProceedsFeeConfig } from './proceeds-fee.js';
+import type { Authorization } from './x402.js';
+export interface PurchaseAccepted {
+    itemId: string;
+    playerId: string;
+    playerAddress: string;
+    /** Atomic units of the asset - NOT a float. 1.50 USDC is '1500000'. */
+    amount: string;
+}
+export interface PurchaseSettled extends PurchaseAccepted {
+    /** On-chain transaction hash. The money has moved. */
+    transaction: string;
+    network: string;
+}
+export interface PurchaseDeclined {
+    itemId: string;
+    playerId: string;
+    /**
+     * Machine-readable. Switch on this, do not parse `message`.
+     *
+     *   unknown_item          - not in the catalog
+     *   already_used          - this authorization was already redeemed (replay)
+     *   rejected              - the facilitator refused the signature or the amount
+     *   settlement_failed     - VALID payment, our side could not complete it
+     *   malformed             - the client sent something we could not read
+     */
+    code: 'unknown_item' | 'already_used' | 'rejected' | 'settlement_failed' | 'malformed';
+    /** Human-readable detail for the studio's logs. Never shown to a player by us. */
+    message: string;
+    /**
+     * True when the player's money is NOT at risk and the same authorization may be retried
+     * unchanged. False means mint a fresh one - re-sending would risk paying twice.
+     */
+    retryable: boolean;
+}
+interface Events {
+    accepted: PurchaseAccepted;
+    settled: PurchaseSettled;
+    declined: PurchaseDeclined;
+}
+export interface StorefrontConfig extends Omit<SellerConfig, 'price' | 'description'> {
+    /**
+     * itemId -> price in ATOMIC units of the asset, as a decimal string. USDC has 6 decimals,
+     * so 1.50 is '1500000'. Strings, not numbers: a float cannot represent money exactly and
+     * this value ends up inside a signature.
+     */
+    catalog: Record<string, string>;
+    /**
+     * Diagnostics for the studio's own logger. Nothing is ever printed - if this is absent,
+     * problems are silent and purchases simply fail closed.
+     */
+    onDiagnostic?: (d: {
+        code: string;
+        message: string;
+    }) => void;
+    /**
+     * The network fee, taken out of PROCEEDS - the player is debited exactly the sticker
+     * price and nothing is added on top. Requires `proceedsKey`, the key for the wallet named
+     * in `payTo`, because moving money out of that wallet needs its own authorization.
+     * Omit this and no fee is charged.
+     */
+    surcharge?: Omit<ProceedsFeeConfig, 'network' | 'onDiagnostic'>;
+}
+export interface PurchaseRequest {
+    itemId: string;
+    /** The studio's own player identifier. Passed through untouched, echoed on every event. */
+    playerId: string;
+    /** The wallet the player funds. Must match the authorization's `from`. */
+    playerAddress: string;
+    /** The EIP-3009 authorization the client signed. */
+    authorization: Authorization;
+    /** Its 65-byte signature, 0x-prefixed. */
+    signature: string;
+}
+export declare function createStorefront(cfg: StorefrontConfig): {
+    /** Item ids this storefront will sell. */
+    readonly items: string[];
+    /** The network fee taken from proceeds: whether it is on, and what it has collected. */
+    fee: {
+        readonly enabled: boolean;
+        stats: () => Promise<{
+            enabled: boolean;
+            salesSinceLastSweep: string;
+            accrued: string;
+            collected: string;
+            held: string;
+            lost: string;
+        }>;
+    };
+    /**
+     * What the client must sign to buy `itemId`: price, recipient, chain and the EIP-712
+     * domain. Costs nothing and moves nothing.
+     */
+    quote(itemId: string): {
+        scheme: string;
+        network: string;
+        amount: string;
+        asset: string;
+        payTo: string;
+        maxTimeoutSeconds: number;
+        extra: {
+            name: string;
+            version: string;
+        };
+        itemId: string;
+    } | null;
+    on<K extends keyof Events>(name: K, handler: (e: Events[K]) => void): () => void;
+    /**
+     * Redeem a signed authorization for an item.
+     *
+     * Emits `accepted` as soon as the request is well-formed and the item is real, then
+     * `settled` or `declined`. The studio decides which one grants the item: `accepted` is
+     * optimistic and fast, `settled` means the money has actually moved on-chain.
+     */
+    purchase(req: PurchaseRequest): Promise<PurchaseSettled | PurchaseDeclined>;
+};
+export {};

package/dist/storefront.js

@@ -0,0 +1,173 @@
+import { createX402Seller } from "./seller.js";
+import { createProceedsFee } from "./proceeds-fee.js";
+function createStorefront(cfg) {
+  const items = Object.keys(cfg.catalog);
+  if (items.length === 0) throw new Error("storefront: catalog is empty");
+  for (const [id, price] of Object.entries(cfg.catalog)) {
+    if (!/^[0-9]+$/.test(price) || BigInt(price) <= 0n) {
+      throw new Error(`storefront: price for '${id}' must be a positive integer in atomic units, got '${price}'`);
+    }
+  }
+  const sellers = /* @__PURE__ */ new Map();
+  const sellerFor = (itemId) => {
+    let s = sellers.get(itemId);
+    if (!s) {
+      s = createX402Seller({ ...cfg, price: cfg.catalog[itemId], description: itemId });
+      sellers.set(itemId, s);
+    }
+    return s;
+  };
+  const fee = createProceedsFee({
+    ...cfg.surcharge,
+    network: cfg.network,
+    onDiagnostic: cfg.onDiagnostic
+  });
+  if (fee.enabled && fee.from.toLowerCase() !== cfg.payTo.toLowerCase()) {
+    throw new Error(
+      `storefront: surcharge.proceedsKey belongs to ${fee.from}, but payTo is ${cfg.payTo}. The fee is taken from proceeds, so the key must be for the wallet that receives them.`
+    );
+  }
+  const handlers = { accepted: [], settled: [], declined: [] };
+  const emit = (name, e) => {
+    for (const h of handlers[name]) {
+      try {
+        h(e);
+      } catch (err) {
+        cfg.onDiagnostic?.({
+          code: "handler_threw",
+          message: `${name} handler threw: ${err instanceof Error ? err.message : String(err)}`
+        });
+      }
+    }
+  };
+  const decline = (e) => {
+    emit("declined", e);
+    return e;
+  };
+  return {
+    /** Item ids this storefront will sell. */
+    get items() {
+      return [...items];
+    },
+    /** The network fee taken from proceeds: whether it is on, and what it has collected. */
+    fee: { get enabled() {
+      return fee.enabled;
+    }, stats: () => fee.stats() },
+    /**
+     * What the client must sign to buy `itemId`: price, recipient, chain and the EIP-712
+     * domain. Costs nothing and moves nothing.
+     */
+    quote(itemId) {
+      if (!(itemId in cfg.catalog)) return null;
+      return { itemId, ...sellerFor(itemId).requirements };
+    },
+    on(name, handler) {
+      handlers[name].push(handler);
+      return () => {
+        const i = handlers[name].indexOf(handler);
+        if (i >= 0) handlers[name].splice(i, 1);
+      };
+    },
+    /**
+     * Redeem a signed authorization for an item.
+     *
+     * Emits `accepted` as soon as the request is well-formed and the item is real, then
+     * `settled` or `declined`. The studio decides which one grants the item: `accepted` is
+     * optimistic and fast, `settled` means the money has actually moved on-chain.
+     */
+    async purchase(req) {
+      const { itemId, playerId, playerAddress, authorization, signature } = req;
+      const amount = cfg.catalog[itemId];
+      if (!amount) {
+        return decline({
+          itemId,
+          playerId,
+          code: "unknown_item",
+          message: `no such item '${itemId}'`,
+          retryable: false
+        });
+      }
+      if (typeof signature !== "string" || !/^0x[0-9a-fA-F]{130}$/.test(signature)) {
+        return decline({
+          itemId,
+          playerId,
+          code: "malformed",
+          message: "signature must be a 0x-prefixed 65-byte hex string",
+          retryable: false
+        });
+      }
+      if (authorization?.from?.toLowerCase() !== playerAddress.toLowerCase()) {
+        return decline({
+          itemId,
+          playerId,
+          code: "malformed",
+          message: "authorization.from does not match playerAddress",
+          retryable: false
+        });
+      }
+      if (authorization?.value !== amount) {
+        return decline({
+          itemId,
+          playerId,
+          code: "malformed",
+          message: `authorization is for ${authorization?.value}, item costs ${amount}`,
+          retryable: false
+        });
+      }
+      emit("accepted", { itemId, playerId, playerAddress, amount });
+      const payload = {
+        x402Version: 2,
+        scheme: "exact",
+        network: sellerFor(itemId).requirements.network,
+        payload: { authorization, signature }
+      };
+      const request = new Request(`https://storefront.invalid/${encodeURIComponent(itemId)}`, {
+        headers: { "payment-signature": btoa(JSON.stringify(payload)) }
+      });
+      let gate;
+      try {
+        gate = await sellerFor(itemId).guard(request);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        cfg.onDiagnostic?.({ code: "guard_threw", message });
+        return decline({ itemId, playerId, code: "settlement_failed", message, retryable: true });
+      }
+      if (gate.settlement) {
+        const e = {
+          itemId,
+          playerId,
+          playerAddress,
+          amount,
+          transaction: gate.settlement.transaction,
+          network: gate.settlement.network
+        };
+        emit("settled", e);
+        await fee.record(BigInt(amount));
+        return e;
+      }
+      if (gate.settlementFailed) {
+        return decline({
+          itemId,
+          playerId,
+          code: "settlement_failed",
+          message: gate.reason ?? "settlement failed",
+          retryable: true
+        });
+      }
+      const reason = gate.reason ?? "refused";
+      const alreadyUsed = reason.includes("nonce already used");
+      return decline({
+        itemId,
+        playerId,
+        code: alreadyUsed ? "already_used" : "rejected",
+        message: reason,
+        // A spent nonce will never become unspent, and a rejected signature will not become
+        // valid. Both need a fresh authorization, not a retry.
+        retryable: false
+      });
+    }
+  };
+}
+export {
+  createStorefront
+};

package/dist/storefront.min.js

@@ -0,0 +1 @@
+import{createX402Seller as v}from"./seller.js";import{createProceedsFee as k}from"./proceeds-fee.js";function $(s){const p=Object.keys(s.catalog);if(p.length===0)throw new Error("storefront: catalog is empty");for(const[t,e]of Object.entries(s.catalog))if(!/^[0-9]+$/.test(e)||BigInt(e)<=0n)throw new Error(`storefront: price for '${t}' must be a positive integer in atomic units, got '${e}'`);const h=new Map,g=t=>{let e=h.get(t);return e||(e=v({...s,price:s.catalog[t],description:t}),h.set(t,e)),e},i=k({...s.surcharge,network:s.network,onDiagnostic:s.onDiagnostic});if(i.enabled&&i.from.toLowerCase()!==s.payTo.toLowerCase())throw new Error(`storefront: surcharge.proceedsKey belongs to ${i.from}, but payTo is ${s.payTo}. The fee is taken from proceeds, so the key must be for the wallet that receives them.`);const l={accepted:[],settled:[],declined:[]},f=(t,e)=>{for(const r of l[t])try{r(e)}catch(o){s.onDiagnostic?.({code:"handler_threw",message:`${t} handler threw: ${o instanceof Error?o.message:String(o)}`})}},n=t=>(f("declined",t),t);return{get items(){return[...p]},fee:{get enabled(){return i.enabled},stats:()=>i.stats()},quote(t){return t in s.catalog?{itemId:t,...g(t).requirements}:null},on(t,e){return l[t].push(e),()=>{const r=l[t].indexOf(e);r>=0&&l[t].splice(r,1)}},async purchase(t){const{itemId:e,playerId:r,playerAddress:o,authorization:u,signature:m}=t,c=s.catalog[e];if(!c)return n({itemId:e,playerId:r,code:"unknown_item",message:`no such item '${e}'`,retryable:!1});if(typeof m!="string"||!/^0x[0-9a-fA-F]{130}$/.test(m))return n({itemId:e,playerId:r,code:"malformed",message:"signature must be a 0x-prefixed 65-byte hex string",retryable:!1});if(u?.from?.toLowerCase()!==o.toLowerCase())return n({itemId:e,playerId:r,code:"malformed",message:"authorization.from does not match playerAddress",retryable:!1});if(u?.value!==c)return n({itemId:e,playerId:r,code:"malformed",message:`authorization is for ${u?.value}, item costs ${c}`,retryable:!1});f("accepted",{itemId:e,playerId:r,playerAddress:o,amount:c});const b={x402Version:2,scheme:"exact",network:g(e).requirements.network,payload:{authorization:u,signature:m}},x=new Request(`https://storefront.invalid/${encodeURIComponent(e)}`,{headers:{"payment-signature":btoa(JSON.stringify(b))}});let a;try{a=await g(e).guard(x)}catch(d){const w=d instanceof Error?d.message:String(d);return s.onDiagnostic?.({code:"guard_threw",message:w}),n({itemId:e,playerId:r,code:"settlement_failed",message:w,retryable:!0})}if(a.settlement){const d={itemId:e,playerId:r,playerAddress:o,amount:c,transaction:a.settlement.transaction,network:a.settlement.network};return f("settled",d),await i.record(BigInt(c)),d}if(a.settlementFailed)return n({itemId:e,playerId:r,code:"settlement_failed",message:a.reason??"settlement failed",retryable:!0});const y=a.reason??"refused",P=y.includes("nonce already used");return n({itemId:e,playerId:r,code:P?"already_used":"rejected",message:y,retryable:!1})}}}export{$ as createStorefront};