@pybara/pybara-js 0.1.0 → 0.2.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 }) on click — identical to the ESM surface
+</script>
 ```
 
 ## Add Pybara as a payment method

package/checkout.schema.json

@@ -0,0 +1,135 @@
+{
+  "$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-Za-z]{3}$",
+      "default": "USD",
+      "description": "Fiat currency the amounts passed to open() are in (ISO 4217, e.g. 'EUR'). Converted to USD for payment."
+    },
+    "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": {
+          "type": "number",
+          "exclusiveMinimum": 0,
+          "description": "Amount in the checkout's currency; the USD equivalent must be ≥ $0.50."
+        },
+        "currency": {
+          "type": "string",
+          "pattern": "^[A-Za-z]{3}$",
+          "description": "Per-call fiat override (ISO 4217) — defaults to the checkout's currency."
+        },
+        "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 — 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/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":"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;IAkEjD,4EAA4E;IAC5E,KAAK,IAAI,IAAI;YAIC,IAAI;IAqClB,OAAO,CAAC,iBAAiB;IAkDzB;;;OAGG;IACH,OAAO,CAAC,cAAc;IAgDtB,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,11 +1,12 @@
 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 CheckoutConfig, type CheckoutResult, type Frequency, type PaymentParams, PybaraError, type PybaraErrorCode, } from './types';

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,EACL,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,WAAW,EACX,KAAK,eAAe,GACrB,MAAM,SAAS,CAAC"}