@pybara/pybara-js 0.1.0 → 0.3.0

package/README.md

@@ -10,10 +10,14 @@ You keep your own UI — payment-method list, amount selector, form fields. `Pyb
 npm install @pybara/pybara-js
 ```
 
-No bundler? The IIFE build exposes `window.Pybara`:
+No bundler? The IIFE build exposes `window.Pybara` — the same calls as the module:
 
 ```html
 <script src="https://unpkg.com/@pybara/pybara-js/dist/pybara-js.iife.js"></script>
+<script>
+  const pybara = Pybara.checkout({ siteUrl, siteName, recipientPrincipal });
+  // await pybara.open({ amount: '100', currency: 'EUR' }) on click — identical to the ESM surface
+</script>
 ```
 
 ## Add Pybara as a payment method
@@ -26,12 +30,12 @@ const pybara = Pybara.checkout({
   siteUrl: 'https://example.com',        // your site, as registered in Pybara Wallet
   siteName: 'Example Org',
   recipientPrincipal: 'aaaaa-bbbbb-…',   // the wallet principal in your _pybara-payto DNS record
-  currency: 'EUR',
+  currency: 'EUR',                       // optional default for open(); one currency per site
 });
 
 // On your "Pybara" payment-option click — opens the checkout over your page:
 await pybara.open({
-  amount: 100,                            // in `currency`
+  amount: '100',                          // in EUR, as a decimal string: '12.34', '1000' for JPY
   donorEmail: 'laurens@example.org',      // optional — enables the receipt email + tax receipts
   onSuccess: (result) => showThanks(result),
 });
@@ -39,10 +43,12 @@ await pybara.open({
 
 That's the whole integration. `open()` resolves once the checkout is up; the result arrives on `onSuccess`.
 
+**Amounts** are decimal strings in the currency's major units — `'12.34'` for €12.34, `'1000'` for ¥1,000 — as PayPal's API takes them; a number is accepted too (`12.34`). The checkout reads them with the currency's ISO 4217 minor units, so your page never needs to know how many decimals a currency has, and it refuses an amount the currency can't hold (`'12.345'` EUR, `'1000.5'` JPY). It converts to USD itself, with Pybara's own rates, and shows the minimum in the payer's currency if the amount is below it.
+
 **Recurring** — same call, two extra params:
 
 ```ts
-await pybara.open({ amount: 25, frequency: 'monthly', durationMonths: 12 });
+await pybara.open({ amount: '25', frequency: 'monthly', durationMonths: 12 });
 // omit durationMonths for an open-ended subscription
 ```
 
@@ -59,12 +65,13 @@ The code above is all an AI builder needs. The one thing code can't do: the site
 | `recipientPrincipal` | `string` | ✓ | The recipient's wallet principal — the one in the `_pybara-payto` DNS record |
 | `siteUrl` | `string` | ✓ | Site registry key, e.g. `'https://example.com'` |
 | `siteName` | `string` | ✓ | Display name — shown in the checkout and stored on subscriptions |
-| `currency` | `string` | | Fiat for `open().amount`, ISO 4217 (default `'USD'`) |
+| `currency` | `string` | | Default currency for `open()`, ISO 4217 uppercase (`'EUR'`) — no default of its own |
 | `thankYouMessage` | `string` | | Success-screen title override |
 | `thankYouRedirectUrl` | `string` | | Redirect after the payer closes the success screen |
 | `siteCountry` | `string` | | ISO 3166-1 alpha-2 |
 | `notifyEmail` | `string` | | Operator email — terms warnings, payment notifications |
 | `notifyDonations` | `boolean` | | `false` silences per-payment emails (default `true`) |
+| `platform` | `string` | | Your integration's slug in the payment log, `a-z 0-9 -` (default `'pybara-js'`) |
 | `pluginVersion` | `string` | | Set by plugins — skips the autonomous-embed terms gate |
 | `staging` / `debug` | `boolean` | | Staging canisters + wallet / console logging |
 
@@ -72,8 +79,8 @@ The code above is all an AI builder needs. The one thing code can't do: the site
 
 | Field | Type | Description |
 |---|---|---|
-| `amount` | `number` | In the checkout's currency |
-| `currency` | `string` | Per-call override |
+| `amount` | `string` \| `number` | Decimal string in the currency's major units: `'12.34'`, `'1000'` (JPY) |
+| `currency` | `string` | ISO 4217 — required here unless set in `Pybara.checkout()`; a multi-currency site passes it on every call |
 | `frequency` | `'weekly' \| 'monthly' \| 'yearly'` | Omit for one-time |
 | `durationMonths` | `3 \| 6 \| 12 \| 24` | Omit for unlimited |
 | `donorEmail` `donorFirstName` `donorLastName` `donorCompany` `donorCountry` `donorAddress*` | `string` | Donor identity — pass what your form already collects |
@@ -81,7 +88,7 @@ The code above is all an AI builder needs. The one thing code can't do: the site
 | `donorMessage` | `string` | Stored with the payment log |
 | `wantsTaxReceipt` | `boolean` | Prefills the receipt checkbox (eligible sites only) |
 | `onSuccess(result)` | `function` | Payment confirmed — `result` carries block height, token, principals |
-| `onError(err)` `onClose()` | `function` | Frame-level errors / modal closed |
+| `onError(err)` `onClose()` | `function` | Checkout refusals (`EmbeddedError`, `err.code`) / modal closed |
 
 ### Errors
 
@@ -91,9 +98,10 @@ The code above is all an AI builder needs. The one thing code can't do: the site
 |---|---|
 | `GATE_REFUSED` | Site hasn't accepted the widget terms, or a kill switch is on — `err.message` says which |
 | `RECIPIENT_SUSPENDED` | Recipient can't accept payments right now |
-| `BELOW_MINIMUM` | Amount under $0.50 USD after conversion |
-| `INVALID_CONFIG` | Missing/invalid config or params |
-| `CHECKOUT_FAILED` | Modal couldn't initialise |
+| `INVALID_CONFIG` | Missing or malformed config or params — `err.message` names the field, e.g. `open(): "currency" is required` |
+| `CHECKOUT_FAILED` | The checkout modal couldn't initialise |
+
+Once open, the checkout reports a refusal to `onError` as an `EmbeddedError`, also with `err.code`. The ones an integration can cause: `INVALID_CHECKOUT` (the message names the field and what it must be, e.g. `checkout.amount "12.345" has more decimals than EUR has (2)`) and `RATE_UNAVAILABLE` (Pybara's rate for the currency couldn't be loaded — let the payer try again). An amount below the minimum isn't an error: the checkout shows the minimum itself.
 
 ## Scope
 
@@ -101,6 +109,10 @@ Today `checkout()` runs the **donation** flow (the `siteUrl` resolves a register
 
 If you want the whole donation *form* — presets, amount selector, frequency picker, styled button — that's [`@pybara/donate-widget`](https://github.com/pybara/pybara-widget), a product built on the same machinery.
 
+## Internal entry points
+
+`@pybara/pybara-js/modal` and `@pybara/pybara-js/admin` are Pybara's own machinery for its plugins: not part of the public API, with no compatibility promise between versions. Integrate with `Pybara.checkout()`.
+
 ## Links
 
 - Docs — <https://docs.pybara.com>

package/checkout.schema.json

@@ -0,0 +1,143 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://docs.pybara.com/pybara-js/checkout.schema.json",
+  "title": "Pybara.checkout() config",
+  "description": "Config object for Pybara.checkout() in @pybara/pybara-js — bind once per site. The checkout refuses to open until the site is verified in Pybara Wallet (_pybara-payto DNS record) and the widget terms are accepted. The open() payment params are under #/$defs/payment.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["recipientPrincipal", "siteUrl", "siteName"],
+  "properties": {
+    "recipientPrincipal": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Recipient's wallet principal — the same one the site's _pybara-payto DNS record lists. The registry does not serve it; the integrator passes it."
+    },
+    "siteUrl": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The site's URL as registered in Pybara Wallet, e.g. 'https://example.com'. Normalized by the SDK: a bare domain reads as https, query/fragment/default ports/trailing slashes drop, a path is kept."
+    },
+    "siteName": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Site display name — shown in the checkout frame and stored as the subscription name on recurring payments."
+    },
+    "currency": {
+      "type": "string",
+      "pattern": "^[A-Z]{3}$",
+      "description": "The currency open() charges in when its own currency is absent (ISO 4217, uppercase, e.g. 'EUR'): set it once on a single-currency site. No default — open() refuses when neither is set."
+    },
+    "platform": {
+      "type": "string",
+      "pattern": "^[a-z0-9-]{1,64}$",
+      "default": "pybara-js",
+      "description": "The integration surface reported in the payment log's platform field: a lowercase slug — first-party consumers set their own (e.g. 'pybara-donate'). A label, never used for a decision."
+    },
+    "siteCountry": {
+      "type": "string",
+      "pattern": "^[A-Za-z]{2}$",
+      "description": "Site base country (ISO 3166-1 alpha-2)."
+    },
+    "notifyEmail": {
+      "type": "string",
+      "description": "Site operator's contact email — terms warnings, per-payment notification emails."
+    },
+    "notifyDonations": {
+      "type": "boolean",
+      "default": true,
+      "description": "false silences the per-payment notification email at notifyEmail."
+    },
+    "thankYouMessage": {
+      "type": "string",
+      "description": "Replaces the success screen's default title."
+    },
+    "thankYouRedirectUrl": {
+      "type": "string",
+      "format": "uri",
+      "description": "Redirect target once the payer leaves the success screen (PDF receipt, member area)."
+    },
+    "recipientTosVersion": {
+      "type": "string",
+      "description": "The terms version the recipient (site operator) accepted, e.g. '1-0' — forwarded so settle stores it with the payment log."
+    },
+    "recipientTosAcceptedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Recipient terms acceptance timestamp (ISO 8601 UTC) — same forwarding role as recipientTosVersion."
+    },
+    "pluginVersion": {
+      "type": "string",
+      "description": "The integration version forwarding the payment — set by Pybara plugins only. When set, the widget terms gate is skipped: plugins check their own terms server-side."
+    },
+    "staging": {
+      "type": "boolean",
+      "default": false,
+      "description": "Staging environment — staging canisters and staging.pybara.io. Never on a live site."
+    },
+    "debug": {
+      "type": "boolean",
+      "default": false,
+      "description": "Console diagnostics."
+    }
+  },
+  "$defs": {
+    "payment": {
+      "title": "checkout.open() params",
+      "description": "One payment attempt — the params of a single open() call.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["amount"],
+      "properties": {
+        "amount": {
+          "oneOf": [
+            { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]+)?$" },
+            { "type": "number", "exclusiveMinimum": 0 }
+          ],
+          "examples": ["12.34", "1000", "5"],
+          "description": "The amount in the currency's major units, as a decimal string ('12.34' for €12.34, '1000' for ¥1,000); a number is accepted and turned into its decimal text. The checkout reads it with the currency's ISO 4217 minor units and refuses more decimals than the currency holds ('12.345' EUR, '1000.5' JPY), so the page never needs to know them. No minimum is checked here: the checkout shows its own, in the payer's currency."
+        },
+        "currency": {
+          "type": "string",
+          "pattern": "^[A-Z]{3}$",
+          "description": "The currency charged (ISO 4217, uppercase) — the checkout config's when absent; one of the two is required. A multi-currency site passes it on every call."
+        },
+        "frequency": {
+          "enum": ["weekly", "monthly", "yearly", "every2min"],
+          "description": "Recurring pull interval — omit for a one-time payment. 'every2min' exists for testing."
+        },
+        "durationMonths": {
+          "enum": [3, 6, 12, 24],
+          "description": "Recurring length in months, checked by the checkout — omit with frequency for an unlimited subscription."
+        },
+        "donorIsAnonymous": {
+          "type": "boolean",
+          "description": "Hide the payer's identity on the public record."
+        },
+        "donorMessage": {
+          "type": "string",
+          "description": "Message from the payer to the recipient — seeds the field the payer can edit on the confirm screen."
+        },
+        "wantsTaxReceipt": {
+          "type": "boolean",
+          "description": "Prefills the 'I'd like a tax receipt' checkbox — shown only when the recipient is registered and issues receipts."
+        },
+        "donorFirstName": { "type": "string" },
+        "donorLastName": { "type": "string" },
+        "donorEmail": { "type": "string", "description": "Prefills the receipt-address field — a payer who leaves an email gets a payment record." },
+        "donorCompany": { "type": "string" },
+        "donorCountry": { "type": "string" },
+        "donorAddressLine1": { "type": "string" },
+        "donorAddressLine2": { "type": "string" },
+        "donorAddressCity": { "type": "string" },
+        "donorAddressState": { "type": "string" },
+        "donorAddressPostalCode": { "type": "string" },
+        "donorAddressCountry": { "type": "string" },
+        "donorTosVersion": { "type": "string", "description": "Terms version the payer accepted, if the host collected one." },
+        "donorTosAcceptedAt": { "type": "string", "format": "date-time" },
+        "onSuccess": { "description": "function (CheckoutResult) => void — called once the payment is confirmed on-chain; not expressible in JSON." },
+        "onError": { "description": "function (Error) => void — called on frame-level errors; not expressible in JSON." },
+        "onClose": { "description": "function () => void — called when the payer closes the checkout; not expressible in JSON." }
+      }
+    }
+  }
+}

package/dist/admin/core/PybaraAdminClient.d.ts

@@ -10,6 +10,9 @@ export declare class PybaraAdminClient {
     /** null is cached too: a site not registered yet (before its first payment) is the common case on a new store, and would otherwise cost a regs query on every click. */
     private merchantDataCache;
     private recipientDataCache;
+    /** In-flight fetches — a click during the page-load prewarm shares the one query instead of issuing a second. */
+    private merchantDataInFlight;
+    private recipientDataInFlight;
     private readonly adminCoreCanisterId;
     /** The admin regs of adminCoreCanisterId's environment: staging's for staging's core, prod's otherwise. */
     private readonly adminRegsCanisterId;
@@ -48,6 +51,7 @@ export declare class PybaraAdminClient {
      * @throws Error if the merchant is suspended.
      */
     getMerchantDataWithCache(siteUrl: string): Promise<MerchantRecord | null>;
+    private fetchMerchantData;
     /**
      * Recipient record for a site, with a 5-minute in-memory cache. Same cache-before-validate reasoning as getMerchantDataWithCache().
      *
@@ -56,6 +60,7 @@ export declare class PybaraAdminClient {
      * @throws Error if a registered recipient is suspended.
      */
     getRecipientDataWithCache(siteUrl: string): Promise<RecipientRecord | null>;
+    private fetchRecipientData;
     /**
      * The kill switch. Call early in the checkout flow, before showing any payment UI.
      *

package/dist/admin/core/PybaraAdminClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PybaraAdminClient.d.ts","sourceRoot":"","sources":["../../../src/admin/core/PybaraAdminClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,EAKN,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,KAAK,EAAE,WAAW,EAAE,wBAAwB,EAAE,MAAM,SAAS,CAAC;AAKrE,qBAAa,iBAAiB;IAC7B,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,KAAK,CAAU;IACvB,oGAAoG;IACpG,OAAO,CAAC,WAAW,CAA4B;IAC/C,wKAAwK;IACxK,OAAO,CAAC,iBAAiB,CAGX;IACd,OAAO,CAAC,kBAAkB,CAGZ;IAEd,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,2GAA2G;IAC3G,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;gBAEjC,OAAO,EAAE,wBAAwB;IAS7C;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAY3B;;;;;OAKG;YACW,YAAY;IAuB1B,+DAA+D;IACzD,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAqB3D;;;;OAIG;IACG,oBAAoB,IAAI,OAAO,CAAC,WAAW,CAAC;IA+ClD;;;;;;;;;;;OAWG;IACG,wBAAwB,CAC7B,OAAO,EAAE,MAAM,GACb,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAsBjC;;;;;;OAMG;IACG,yBAAyB,CAC9B,OAAO,EAAE,MAAM,GACb,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAoBlC;;;;;;OAMG;IACG,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBvE,sEAAsE;YACxD,QAAQ;YAMR,aAAa;YAab,YAAY;IAa1B;;;OAGG;YACW,sBAAsB;IAsBpC,OAAO,CAAC,sBAAsB;IAQ9B,qEAAqE;IACrE,OAAO,CAAC,uBAAuB;CAO/B"}
+{"version":3,"file":"PybaraAdminClient.d.ts","sourceRoot":"","sources":["../../../src/admin/core/PybaraAdminClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,EAKN,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,KAAK,EAAE,WAAW,EAAE,wBAAwB,EAAE,MAAM,SAAS,CAAC;AAKrE,qBAAa,iBAAiB;IAC7B,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,KAAK,CAAU;IACvB,oGAAoG;IACpG,OAAO,CAAC,WAAW,CAA4B;IAC/C,wKAAwK;IACxK,OAAO,CAAC,iBAAiB,CAGX;IACd,OAAO,CAAC,kBAAkB,CAGZ;IACd,iHAAiH;IACjH,OAAO,CAAC,oBAAoB,CAA0D;IACtF,OAAO,CAAC,qBAAqB,CAA2D;IAExF,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,2GAA2G;IAC3G,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;gBAEjC,OAAO,EAAE,wBAAwB;IAS7C;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAY3B;;;;;OAKG;YACW,YAAY;IAuB1B,+DAA+D;IACzD,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAqB3D;;;;OAIG;IACG,oBAAoB,IAAI,OAAO,CAAC,WAAW,CAAC;IA+ClD;;;;;;;;;;;OAWG;IACG,wBAAwB,CAC7B,OAAO,EAAE,MAAM,GACb,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;YAqBnB,iBAAiB;IAiB/B;;;;;;OAMG;IACG,yBAAyB,CAC9B,OAAO,EAAE,MAAM,GACb,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;YAqBpB,kBAAkB;IAehC;;;;;;OAMG;IACG,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBvE,sEAAsE;YACxD,QAAQ;YAMR,aAAa;YAab,YAAY;IAa1B;;;OAGG;YACW,sBAAsB;IAsBpC,OAAO,CAAC,sBAAsB;IAQ9B,qEAAqE;IACrE,OAAO,CAAC,uBAAuB;CAO/B"}

package/dist/admin/index.d.ts

@@ -1,9 +1,14 @@
 /**
  * @pybara/pybara-js/admin
  *
- * Read client for pybara-admin's `core` and `regs` canisters, plus the constants a first-party consumer needs to reach the Pybara protocol. Consumed by pybara-for-woocommerce and the donate widget.
+ * Read client for pybara-admin's `core` and `regs` canisters — internal machinery for
+ * first-party consumers (the plugins). Integrations taking payments or donations use
+ * `Pybara.checkout()` on the package root, not this subpath.
  *
- * It signs nothing and moves no funds. Payments and donations are executed by the buyer's own wallet inside pybara-wallet's checkout frame, which consumers reach through pybara-ux's CheckoutModal.
+ * @internal Not part of the public API: no compatibility promise between versions, even minor ones.
+ *
+ * It signs nothing and moves no funds. Payments and donations are executed by the buyer's
+ * own wallet inside pybara-wallet's checkout frame, which `Pybara.checkout()` opens.
  *
  * This was `@pybara/pybara-sdk` — absorbed into pybara-js so the browser SDK and its machinery version together.
  */

package/dist/admin/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/admin/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAE5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/admin/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAE5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/admin/index.js

@@ -1 +1 @@
-export { n as CANISTER_IDS, r as PYBARA_WALLET_URLS, t as PybaraAdminClient } from "../admin-D2vUTEg1.js";
+export { n as CANISTER_IDS, r as PYBARA_WALLET_URLS, t as PybaraAdminClient } from "../admin-B1pVP25-.js";

package/dist/{admin-D2vUTEg1.js → admin-B1pVP25-.js}

@@ -7958,7 +7958,7 @@ var Fu = ({ IDL: e }) => e.Service({
 	});
 }, Lu = "https://icp-api.io", Ru = class {
 	constructor(e) {
-		this.agent = null, this.adminCoreActor = null, this.adminRegsActor = null, this.adminConfig = null, this.merchantDataCache = /* @__PURE__ */ new Map(), this.recipientDataCache = /* @__PURE__ */ new Map(), this.adminCoreCanisterId = e.adminCoreCanisterId, this.adminRegsCanisterId = e.adminCoreCanisterId === r.staging.admin_core ? r.staging.admin_regs : r.prod.admin_regs, this.debug = e.debug ?? !1;
+		this.agent = null, this.adminCoreActor = null, this.adminRegsActor = null, this.adminConfig = null, this.merchantDataCache = /* @__PURE__ */ new Map(), this.recipientDataCache = /* @__PURE__ */ new Map(), this.merchantDataInFlight = /* @__PURE__ */ new Map(), this.recipientDataInFlight = /* @__PURE__ */ new Map(), this.adminCoreCanisterId = e.adminCoreCanisterId, this.adminRegsCanisterId = e.adminCoreCanisterId === r.staging.admin_core ? r.staging.admin_regs : r.prod.admin_regs, this.debug = e.debug ?? !1;
 	}
 	async init() {
 		this.agent = await Tu.create({ host: Lu }), this.adminCoreActor = ku.createActor(Fu, {
@@ -8019,20 +8019,42 @@ var Fu = ({ IDL: e }) => e.Service({
 	async getMerchantDataWithCache(e) {
 		let t = Date.now(), n = this.merchantDataCache.get(e);
 		if (n && t - n.timestamp < 3e5) return this.validateMerchantAccess(n.data), n.data;
-		let r = (await (await this.getRegsActor()).get_merchant(e))?.[0] ?? null;
+		let r = this.merchantDataInFlight.get(e);
+		if (r) return r;
+		let i = this.fetchMerchantData(e, t);
+		this.merchantDataInFlight.set(e, i);
+		try {
+			return await i;
+		} finally {
+			this.merchantDataInFlight.delete(e);
+		}
+	}
+	async fetchMerchantData(e, t) {
+		let n = (await (await this.getRegsActor()).get_merchant(e))?.[0] ?? null;
 		return this.merchantDataCache.set(e, {
-			data: r,
+			data: n,
 			timestamp: t
-		}), this.validateMerchantAccess(r), r;
+		}), this.validateMerchantAccess(n), n;
 	}
 	async getRecipientDataWithCache(e) {
 		let t = Date.now(), n = this.recipientDataCache.get(e);
 		if (n && t - n.timestamp < 3e5) return this.validateRecipientAccess(n.data), n.data;
-		let r = (await (await this.getRegsActor()).get_recipient(e))?.[0] ?? null;
+		let r = this.recipientDataInFlight.get(e);
+		if (r) return r;
+		let i = this.fetchRecipientData(e, t);
+		this.recipientDataInFlight.set(e, i);
+		try {
+			return await i;
+		} finally {
+			this.recipientDataInFlight.delete(e);
+		}
+	}
+	async fetchRecipientData(e, t) {
+		let n = (await (await this.getRegsActor()).get_recipient(e))?.[0] ?? null;
 		return this.recipientDataCache.set(e, {
-			data: r,
+			data: n,
 			timestamp: t
-		}), this.validateRecipientAccess(r), r;
+		}), this.validateRecipientAccess(n), n;
 	}
 	async validatePlugin(e, t) {
 		this.adminConfig || await this.getPybaraAdminConfig();

package/dist/checkout.d.ts

@@ -1,26 +1,31 @@
+import { WidgetGate } from './gate';
 import { CheckoutConfig, PaymentParams } from './types';
 /**
  * A bound checkout — what Pybara.checkout() returns.
  *
- * checkout() is the "mount": it resolves the admin client, fetches the fiat rate, runs the terms/kill-switch gate
- * for autonomous embeds, and loads the hidden checkout iframe, so open() is instant on the payer's click.
+ * checkout() is the "mount": it resolves the admin client, runs the terms/kill-switch gate for autonomous embeds, and loads the hidden checkout iframe, so open() is instant on the payer's click.
  * The host keeps its own DOM entirely — there is nothing to render here.
+ * open() sends what the page knows, in its own terms (a `checkout`); the checkout frame converts the amount with core's rate and records the payment, so this package holds neither a rate nor the log's field format.
  */
 export declare class PybaraCheckout {
     private readonly config;
     private adminClient;
-    private fiatRate;
     private modal;
-    private gate;
+    private gateOutcome;
     private isOpen;
+    /** Set by onSuccess while the success screen is up — the close that follows redirects instead of counting as a cancellation. */
+    private completedPayment;
     private activePayment;
-    /** All async binding work — open() awaits it so the gate, the rate and the iframe prewarm are resolved first. */
-    private readonly ready;
+    /** All async binding work — open() awaits it so the gate and the iframe prewarm are resolved first. */
+    readonly ready: Promise<void>;
     constructor(userConfig: CheckoutConfig);
+    /** The autonomous-embed gate outcome once `ready` resolves — null while pending or under plugin terms (a plugin's host checks its own). */
+    get gate(): WidgetGate | null;
     /**
      * Open the Pybara checkout for one payment attempt.
      * Resolves once the checkout surface is up; the payment result arrives on the params' onSuccess/onError/onClose callbacks.
-     * Rejects with a PybaraError when the checkout cannot open at all (gate, invalid params, below minimum).
+     * Rejects with a PybaraError when the checkout cannot open at all (gate, invalid params).
+     * The params' shape is checked here, so a typo fails at the call; the checkout checks everything again, plus what only it knows (the currency's decimals, the minimum), and reports a refusal to onError.
      */
     open(payment: PaymentParams): Promise<void>;
     /** Close an open modal — teardown is final, the next open() rebuilds it. */
@@ -28,10 +33,11 @@ export declare class PybaraCheckout {
     private init;
     private initCheckoutModal;
     /**
-     * The fields settle stores with the payment log — the same bag the donate widget fills,
-     * so a custom-form payment is indistinguishable downstream (notifications, tax receipts, stats).
+     * The checkout as the frame reads it (pybara-wallet's EmbeddedCheckout, version 1): what the page knows, in its own terms.
+     * The frame turns it into the payment log's fields; their names and encodings live there, not here, so no installed version of this package can drift from them.
+     * Values are passed as given, nulls included — a config read from JSON (pybara-donate's, from PHP) carries null for a setting that is not set, which the frame reads as absent.
      */
-    private buildSdkFields;
+    private checkoutFor;
     /** Warm the TLS handshake to the wallet origin so the iframe's first real load is faster. */
     private preconnectWallet;
 }

package/dist/checkout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"checkout.d.ts","sourceRoot":"","sources":["../src/checkout.ts"],"names":[],"mappings":"AAaA,OAAO,EACL,KAAK,cAAc,EAEnB,KAAK,aAAa,EAEnB,MAAM,SAAS,CAAC;AAUjB;;;;;;GAMG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyB;IAChD,OAAO,CAAC,WAAW,CAAkC;IACrD,OAAO,CAAC,QAAQ,CAAO;IACvB,OAAO,CAAC,KAAK,CAA8B;IAC3C,OAAO,CAAC,IAAI,CAA2B;IACvC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,aAAa,CAA8B;IACnD,iHAAiH;IACjH,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;gBAE1B,UAAU,EAAE,cAAc;IAKtC;;;;OAIG;IACG,IAAI,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IA+DjD,4EAA4E;IAC5E,KAAK,IAAI,IAAI;YAIC,IAAI;IAqClB,OAAO,CAAC,iBAAiB;IAkDzB;;;OAGG;IACH,OAAO,CAAC,cAAc;IAgDtB,6FAA6F;IAC7F,OAAO,CAAC,gBAAgB;CAOzB"}
+{"version":3,"file":"checkout.d.ts","sourceRoot":"","sources":["../src/checkout.ts"],"names":[],"mappings":"AAMA,OAAO,EAAmB,KAAK,UAAU,EAAE,MAAM,QAAQ,CAAC;AAC1D,OAAO,EACL,KAAK,cAAc,EAEnB,KAAK,aAAa,EAEnB,MAAM,SAAS,CAAC;AAcjB;;;;;;GAMG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyB;IAChD,OAAO,CAAC,WAAW,CAAkC;IACrD,OAAO,CAAC,KAAK,CAA8B;IAC3C,OAAO,CAAC,WAAW,CAA2B;IAC9C,OAAO,CAAC,MAAM,CAAS;IACvB,gIAAgI;IAChI,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,aAAa,CAA8B;IACnD,uGAAuG;IACvG,SAAgB,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;gBAEzB,UAAU,EAAE,cAAc;IAKtC,2IAA2I;IAC3I,IAAI,IAAI,IAAI,UAAU,GAAG,IAAI,CAE5B;IAED;;;;;OAKG;IACG,IAAI,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IA8EjD,4EAA4E;IAC5E,KAAK,IAAI,IAAI;YAIC,IAAI;IA8ClB,OAAO,CAAC,iBAAiB;IAqDzB;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAmCnB,6FAA6F;IAC7F,OAAO,CAAC,gBAAgB;CAOzB"}

package/dist/gate.d.ts

@@ -1,14 +1,20 @@
 /**
- * Gate for autonomous embeds (no plugin): kill switches + the widget's terms of service.
+ * Gate for autonomous embeds (no plugin): the widget terms + the donate kill switches.
  *
  * A custom form built on Pybara.checkout() is the same product surface as the donate widget — a site embeds it under the widget's terms.
  * The two packages share no code, so the gate is duplicated on each side: keep the response shape and the semantics in sync with widget-core/src/gate.ts.
  */
-export interface WidgetGate {
-    show: boolean;
-    reason: string | null;
-}
-/** Old signature pages are superseded by the floor — a signature below the floor counts as unsigned. */
+/** The widget terms version this release requires: raised only by a release that needs new terms, so most updates keep showing on sites that accepted older ones. */
 export declare const REQUIRED_WIDGET_TERMS_VERSION = "1-0";
-export declare function checkWidgetGate(env: 'prod' | 'staging', siteOrigin: string, principal: string): Promise<WidgetGate>;
+export type WidgetGate = {
+    show: false;
+    reason: string;
+} | {
+    show: true;
+    recurring: boolean;
+};
+/** Whether `accepted` is at least `required`, both `major-minor`, compared as numbers. */
+export declare function versionAtLeast(accepted: string, required: string): boolean;
+/** Reads core's /widget-config and regs' /widget-terms in parallel, and says whether the checkout may open, and with recurring. */
+export declare function checkWidgetGate(env: 'prod' | 'staging', siteUrl: string, recipientPrincipal: string): Promise<WidgetGate>;
 //# sourceMappingURL=gate.d.ts.map

package/dist/gate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../src/gate.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,wGAAwG;AACxG,eAAO,MAAM,6BAA6B,QAAQ,CAAC;AAoBnD,wBAAsB,eAAe,CACnC,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,UAAU,CAAC,CA4CrB"}
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../src/gate.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,qKAAqK;AACrK,eAAO,MAAM,6BAA6B,QAAQ,CAAC;AAKnD,MAAM,MAAM,UAAU,GAAG;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAAC;AAW9F,0FAA0F;AAC1F,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAS1E;AAQD,mIAAmI;AACnI,wBAAsB,eAAe,CACnC,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,OAAO,EAAE,MAAM,EACf,kBAAkB,EAAE,MAAM,GACzB,OAAO,CAAC,UAAU,CAAC,CAkCrB"}

package/dist/index.d.ts

@@ -1,12 +1,14 @@
 import { PybaraCheckout } from './checkout';
 import { CheckoutConfig } from './types';
+/**
+ * Bind a site once — resolves the recipient record, the fiat rate and the terms gate,
+ * and prewarms the checkout iframe so open() is instant on the payer's click.
+ */
+export declare function checkout(config: CheckoutConfig): PybaraCheckout;
 export declare const Pybara: {
-    /**
-     * Bind a site once — resolves the recipient record, the fiat rate and the terms gate,
-     * and prewarms the checkout iframe so open() is instant on the payer's click.
-     */
-    checkout(config: CheckoutConfig): PybaraCheckout;
+    checkout: typeof checkout;
 };
 export { PybaraCheckout } from './checkout';
+export { type WidgetGate } from './gate';
 export { type CheckoutConfig, type CheckoutResult, type Frequency, type PaymentParams, PybaraError, type PybaraErrorCode, } from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,eAAO,MAAM,MAAM;IACjB;;;OAGG;qBACc,cAAc,GAAG,cAAc;CAGjD,CAAC;AAEF,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,WAAW,EACX,KAAK,eAAe,GACrB,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CAE/D;AAID,eAAO,MAAM,MAAM;;CAAe,CAAC;AAEnC,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,WAAW,EACX,KAAK,eAAe,GACrB,MAAM,SAAS,CAAC"}

package/dist/modal/config.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Modal Configuration
+ */
+export declare const OVERLAY_STYLES: {
+    Z_INDEX: number;
+    BACKGROUND: string;
+};
+/** Show/hide motion, the same timings as pybara-ux-v0's modal (its styles/animations.css and MODAL_TIMINGS). */
+export declare const MODAL_MOTION: {
+    OVERLAY_FADE_IN_MS: number;
+    /** The panel slides up 20px while fading in, once the frame has content to show. */
+    PANEL_OPEN_MS: number;
+    /** The panel scales down to 95% while fading out. */
+    PANEL_CLOSE_MS: number;
+    /** The backdrop starts fading this long after the panel, for a layered close. */
+    OVERLAY_FADE_OUT_DELAY_MS: number;
+    OVERLAY_FADE_OUT_MS: number;
+};
+//# sourceMappingURL=config.d.ts.map

package/dist/modal/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/modal/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,eAAO,MAAM,cAAc;;;CAG1B,CAAC;AAEF,gHAAgH;AAChH,eAAO,MAAM,YAAY;;IAExB,oFAAoF;;IAEpF,qDAAqD;;IAErD,iFAAiF;;;CAGjF,CAAC"}

package/dist/modal/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @pybara/pybara-js/modal
+ *
+ * The checkout surface itself: a backdrop and an iframe onto Pybara Wallet's
+ * mode-2 frame, plus the error type its callbacks report. Internal machinery —
+ * integrations use `Pybara.checkout()` on the package root; first-party
+ * consumers that drive the modal directly (the plugins) import it from here.
+ *
+ * @internal Not part of the public API: no compatibility promise between versions, even minor ones.
+ * Its raw `sdkFields` are the payment log's own field format, which `Pybara.checkout()` never asks an integrator to hold.
+ *
+ * This was `@pybara/pybara-ux` — absorbed into pybara-js so the SDK and its
+ * modal kit version together.
+ */
+export { CheckoutModal, EmbeddedError, type Checkout, type CheckoutModalConfig, type ModalData, type PaymentData, } from './modal.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/modal/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/modal/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,aAAa,EACb,aAAa,EACb,KAAK,QAAQ,EACb,KAAK,mBAAmB,EACxB,KAAK,SAAS,EACd,KAAK,WAAW,GACjB,MAAM,YAAY,CAAC"}

package/dist/modal/index.js

@@ -0,0 +1 @@
+export { t as CheckoutModal, n as EmbeddedError } from "../modal-BCDMoDW9.js";

package/dist/modal/lock-page-scroll.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Freezes the host page under a checkout overlay without hiding the page scrollbar.
+ * overflow:hidden + padding compensation never matches OS scrollbar width exactly, so the page still jumps.
+ * Wheel/touch/keys on the parent document are cancelled. Wheel inside the wallet iframe never reaches those listeners (separate document) and overscroll-chains to the parent instead — a scroll listener pins window.scrollX/Y so that chain cannot move the page.
+ * Locks are counted, so two checkouts on one page (a WooCommerce checkout and a donation widget, say) never unlock each other.
+ */
+export declare function lockPageScroll(): void;
+export declare function unlockPageScroll(): void;
+//# sourceMappingURL=lock-page-scroll.d.ts.map

package/dist/modal/lock-page-scroll.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock-page-scroll.d.ts","sourceRoot":"","sources":["../../src/modal/lock-page-scroll.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAyBH,wBAAgB,cAAc,IAAI,IAAI,CAUrC;AAED,wBAAgB,gBAAgB,IAAI,IAAI,CASvC"}