@pybara/pybara-js 0.1.0 → 0.3.0

package/dist/modal/modal.d.ts

@@ -0,0 +1,160 @@
+/**
+ * CheckoutModal — the merchant page's side of the Pybara checkout.
+ *
+ * A backdrop and an iframe onto pybara-wallet's checkout frame (mode 2, `/pay?mode=embedded`), where wallet choice, sign-in, token selection, confirmation and the payment itself all happen.
+ * This package never touches a wallet, a balance or a price: it opens the frame, posts it the payment data, and reports the outcome.
+ *
+ * The constructor builds the iframe straight away, hidden, so the frame loads in the background while the buyer is still filling in the form.
+ * open() and show() then only reveal an already-loaded frame, at the moment latency matters most.
+ */
+export interface ModalData {
+    /** Order or donation total in USD; the frame converts it into whichever token the buyer picks. Left out with a `checkout`, whose amount the frame converts itself. */
+    amountUSD?: number;
+    /** The recipient's principal (merchant or donation recipient); the frame checks it against the connecting origin's DNS record before any transfer. */
+    beneficiary: string;
+    /** Base64 salt for the deposit subaccount: random per order or donation, never reused. */
+    salt: string;
+    /** The platform's name for this checkout, e.g. the site name. Echoed back in onSuccess; a subscription also stores it as the name the buyer's wallet shows. */
+    reference: string;
+}
+export interface CheckoutModalConfig {
+    /** Where the wallet lives, e.g. 'https://pybara.io' (prod) or the staging wallet URL. */
+    walletUrl: string;
+    /** Decides settle.pay_and_log() vs. donate_and_log() inside the frame. Known before the order exists, unlike PaymentData. */
+    context: 'payment' | 'donation';
+    /** Replaces the success screen's default title ("You're all set!"), e.g. pybara-donate's "Thank you message" setting. Plain text; the frame escapes it. */
+    thankYouMessage?: string;
+    /** The payment is complete: the frame's success screen has appeared, and the modal stays open until the buyer closes it (onClose). The moment to confirm the payment server-side. */
+    onSuccess?: (data: {
+        blockIndex: string;
+        reference: string;
+        payerPrincipal: string;
+        token: string;
+    }) => void;
+    /** The frame refused, with an EmbeddedError; the modal has closed. */
+    onError?: (error: Error) => void;
+    /** The modal has closed: a cancellation before any onSuccess, or the buyer leaving the success screen after one. */
+    onClose?: () => void;
+}
+/** What show() needs that only exists once the order or donation does — unlike CheckoutModalConfig, known at construction. */
+export interface PaymentData {
+    modalData: ModalData;
+    /**
+     * Present only for a recurring payment. totalPulls: 0 means unlimited, as in subs.mo's CreateSubscriptionArgs.
+     * With a `checkout`, totalPulls is left out: the frame computes it from durationMonths (absent: unlimited).
+     */
+    recurring?: {
+        frequency: string;
+        totalPulls?: number;
+        /** Months the donor chose, when bounded. totalPulls is derived from it; the checkout shows both. */
+        durationMonths?: number;
+    };
+    /** Opaque key-value metadata forwarded unchanged to settle's pay_and_log()/donate_and_log(): order or donor details the platform already has (email, WooCommerce order ID, …). The frame never interprets them. */
+    sdkFields?: [string, string][];
+    /** The semantic checkout, which the frame turns into the log fields and the USD amount itself; sent instead of `sdkFields` and `modalData.amountUSD`, never with them. */
+    checkout?: Checkout;
+}
+/**
+ * Mirrors pybara-wallet's EmbeddedCheckout (modes/mode-2-embedded/contract.ts), version 1: a core every kind of checkout shares, and the part for its kind, matching `context`.
+ * The frame validates it field by field and refuses it with INVALID_CHECKOUT, naming the faulty field.
+ */
+export interface Checkout {
+    v: 1;
+    /** A decimal string in the currency's major units: "12.34" is €12.34, "1000" is ¥1,000. The frame reads it with the currency's ISO 4217 minor units. */
+    amount: string;
+    /** ISO 4217, uppercase. */
+    currency: string;
+    site: {
+        url: string;
+        name: string;
+        country?: string;
+    };
+    /** The integration's slug (a-z, 0-9, -), logged as a label. */
+    platform?: string;
+    pluginVersion?: string;
+    siteTerms?: {
+        version?: string;
+        acceptedAt?: string;
+    };
+    notify?: {
+        email?: string;
+        enabled?: boolean;
+    };
+    donation?: {
+        donor?: {
+            email?: string;
+            firstName?: string;
+            lastName?: string;
+            company?: string;
+            country?: string;
+            address?: {
+                line1?: string;
+                line2?: string;
+                city?: string;
+                state?: string;
+                postalCode?: string;
+                country?: string;
+            };
+            tos?: {
+                version?: string;
+                acceptedAt?: string;
+            };
+        };
+        message?: string;
+        isAnonymous?: boolean;
+        wantsTaxReceipt?: boolean;
+    };
+}
+/**
+ * Mirrors pybara-wallet's EmbeddedErrorCode. Every value but RATE_UNAVAILABLE is a terminal refusal; the frame handles other transient failures with its own retry screen and never posts them.
+ * RATE_UNAVAILABLE: core's exchange rate for a checkout's currency could not be loaded, so the frame had no amount to show; worth trying again.
+ */
+declare const EMBEDDED_ERROR_CODES: readonly ["DESTINATION_REFUSED", "INVALID_BENEFICIARY", "INVALID_CHECKOUT", "NO_WALLET_AVAILABLE", "RATE_UNAVAILABLE", "SITE_MISMATCH"];
+type EmbeddedErrorCode = typeof EMBEDDED_ERROR_CODES[number];
+/**
+ * The error handed to onError() when the frame refuses.
+ * Carries `.code` so a platform branches on it rather than string-matching `.message`, which may be reworded or localised at any time.
+ */
+export declare class EmbeddedError extends Error {
+    readonly code: EmbeddedErrorCode | 'UNKNOWN';
+    constructor(code: EmbeddedErrorCode | 'UNKNOWN', message: string);
+}
+export declare class CheckoutModal {
+    private config;
+    private overlay;
+    private iframe;
+    /** Shown until the frame posts its first content height: the iframe starts at height 0, so the backdrop would otherwise look empty. */
+    private spinner;
+    private walletOrigin;
+    private handleMessage;
+    private handleEscapeKey;
+    /** False while the frame reports a payment or subscription in flight, so Escape cannot abandon it halfway. True by default, for a frame that never reports it. */
+    private closable;
+    /** Set once the iframe's `load` fires; until then show() cannot post to it. */
+    private iframeLoaded;
+    /** Held by show() when it runs before `load`; the `load` handler sends it. */
+    private pendingPaymentData;
+    constructor(config: CheckoutModalConfig);
+    /** Backdrop and iframe, built at construction and hidden until open() — see the file header for why. */
+    private createIframe;
+    private sendInitMessage;
+    /**
+     * Show the backdrop and its spinner now, before the payment data exists: a platform calls it on the buyer's click, while it still creates the order, so one overlay covers the whole sequence.
+     * Does nothing if already shown; show() calls it too. close() takes it down again if the platform fails before show().
+     */
+    open(): void;
+    /** Reveal the (usually already loaded) iframe, opening the backdrop if open() has not already, and post the frame its payment data. */
+    show(data: PaymentData): void;
+    /**
+     * A message box instead of the frame, for a platform-side check that fails before checkout opens (a suspended merchant or recipient, a missing principal).
+     * The caller supplies the text, translated: everything after opening is the frame's to report, so this package holds no error copy.
+     */
+    renderTerminalState(message: string): void;
+    /**
+     * Releases all state at once, so nothing can reach the frame any more; only the overlay element lingers for the close animation.
+     * renderTerminalState() relies on this: it builds its own overlay straight after, while the old one is still fading.
+     */
+    close(): void;
+}
+export {};
+//# sourceMappingURL=modal.d.ts.map

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

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

package/dist/modal-BCDMoDW9.js

@@ -0,0 +1,192 @@
+/* Pybara.js - pybara.com */
+//#region src/modal/config.ts
+var e = {
+	Z_INDEX: 999999,
+	BACKGROUND: "rgba(0, 0, 0, 0.7)"
+}, t = {
+	OVERLAY_FADE_IN_MS: 200,
+	PANEL_OPEN_MS: 300,
+	PANEL_CLOSE_MS: 200,
+	OVERLAY_FADE_OUT_DELAY_MS: 50,
+	OVERLAY_FADE_OUT_MS: 150
+}, n = 0, r = 0, i = 0;
+function a(e) {
+	e.preventDefault();
+}
+function o(e) {
+	e.preventDefault();
+}
+function s(e) {
+	e.target instanceof HTMLInputElement || e.target instanceof HTMLTextAreaElement || [
+		"ArrowUp",
+		"ArrowDown",
+		"PageUp",
+		"PageDown",
+		"Home",
+		"End",
+		" "
+	].includes(e.key) && e.preventDefault();
+}
+function c() {
+	window.scrollTo(r, i);
+}
+function l() {
+	n === 0 && (r = window.scrollX, i = window.scrollY, window.addEventListener("wheel", a, { passive: !1 }), window.addEventListener("touchmove", o, { passive: !1 }), window.addEventListener("keydown", s), window.addEventListener("scroll", c)), n += 1;
+}
+function u() {
+	n !== 0 && (--n, n === 0 && (window.removeEventListener("wheel", a), window.removeEventListener("touchmove", o), window.removeEventListener("keydown", s), window.removeEventListener("scroll", c)));
+}
+//#endregion
+//#region src/modal/modal.ts
+function d() {
+	return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+var f = [
+	"DESTINATION_REFUSED",
+	"INVALID_BENEFICIARY",
+	"INVALID_CHECKOUT",
+	"NO_WALLET_AVAILABLE",
+	"RATE_UNAVAILABLE",
+	"SITE_MISMATCH"
+];
+function p(e) {
+	return f.includes(e) ? e : "UNKNOWN";
+}
+var m = class extends Error {
+	constructor(e, t) {
+		super(t), this.name = "EmbeddedError", this.code = e, Object.setPrototypeOf(this, new.target.prototype);
+	}
+};
+function h(e) {
+	return typeof e == "object" && !!e && typeof e.type == "string" && e.type.startsWith("pybara_embedded_");
+}
+var g = class {
+	constructor(e) {
+		this.overlay = null, this.iframe = null, this.spinner = null, this.handleMessage = null, this.handleEscapeKey = null, this.closable = !0, this.iframeLoaded = !1, this.pendingPaymentData = null, this.config = e, this.walletOrigin = new URL(e.walletUrl).origin, this.createIframe();
+	}
+	createIframe() {
+		let n = document.createElement("div");
+		n.className = "pybara-checkout-overlay", n.style.cssText = `
+            position: fixed;
+            top: 0;
+            left: 0;
+            right: 0;
+            bottom: 0;
+            background: ${e.BACKGROUND};
+            z-index: ${e.Z_INDEX};
+            display: none;
+            align-items: center;
+            justify-content: center;
+            overscroll-behavior: none;
+            user-select: none;
+        `;
+		let r = document.createElement("iframe");
+		r.src = `${this.config.walletUrl}/pay?mode=embedded`, r.title = "Pybara Wallet", r.style.cssText = "\n            width: 100%;\n            max-width: 500px;\n            height: 0;\n            max-height: 90vh;\n            border: none;\n            border-radius: 20px;\n            box-shadow: 0 20px 60px rgba(0, 0, 0, 0.5);\n            overscroll-behavior: none;\n        ";
+		let i = document.createElement("div");
+		i.setAttribute("aria-hidden", "true"), i.style.cssText = "\n            position: absolute;\n            inset: 0;\n            display: flex;\n            align-items: center;\n            justify-content: center;\n            pointer-events: none;\n        ", i.innerHTML = "\n            <svg viewBox=\"0 0 50 50\" width=\"50\" height=\"50\">\n                <circle cx=\"25\" cy=\"25\" r=\"20\" fill=\"none\" stroke=\"white\" stroke-width=\"3\" stroke-linecap=\"round\" stroke-dasharray=\"80\" stroke-dashoffset=\"20\"/>\n            </svg>\n        ", i.querySelector("svg")?.animate([{ transform: "rotate(0deg)" }, { transform: "rotate(360deg)" }], {
+			duration: 1e3,
+			iterations: Infinity
+		}), r.addEventListener("load", () => {
+			this.iframeLoaded = !0, this.pendingPaymentData &&= (this.sendInitMessage(this.pendingPaymentData), null);
+		}, { once: !0 }), this.handleMessage = (e) => {
+			if (e.origin === this.walletOrigin && e.source === r.contentWindow && h(e.data)) switch (e.data.type) {
+				case "pybara_embedded_result":
+					this.config.onSuccess?.({
+						blockIndex: e.data.blockIndex,
+						reference: e.data.reference,
+						payerPrincipal: e.data.payerPrincipal,
+						token: e.data.token
+					});
+					break;
+				case "pybara_embedded_error":
+					this.close(), this.config.onError?.(new m(p(e.data.code), e.data.message));
+					break;
+				case "pybara_embedded_closed":
+					this.close(), this.config.onClose?.();
+					break;
+				case "pybara_embedded_resize":
+					r.style.height !== `${e.data.height}px` && (r.style.height = `${e.data.height}px`), this.spinner && (this.spinner.remove(), this.spinner = null, d() || r.animate([{
+						transform: "translateY(20px)",
+						opacity: 0
+					}, {
+						transform: "none",
+						opacity: 1
+					}], {
+						duration: t.PANEL_OPEN_MS,
+						easing: "ease"
+					}));
+					break;
+				case "pybara_embedded_closable": this.closable = e.data.closable;
+			}
+		}, window.addEventListener("message", this.handleMessage), this.handleEscapeKey = (e) => {
+			e.key === "Escape" && this.closable && (this.close(), this.config.onClose?.());
+		}, document.addEventListener("keydown", this.handleEscapeKey), n.appendChild(i), n.appendChild(r), document.body.appendChild(n), this.overlay = n, this.iframe = r, this.spinner = i;
+	}
+	sendInitMessage(e) {
+		let t = {
+			type: "pybara_embedded_init",
+			beneficiary: e.modalData.beneficiary,
+			salt: e.modalData.salt,
+			...e.modalData.amountUSD === void 0 ? {} : { amountUSD: e.modalData.amountUSD },
+			reference: e.modalData.reference,
+			context: this.config.context,
+			...e.recurring ? { recurring: e.recurring } : {},
+			...e.sdkFields ? { sdkFields: e.sdkFields } : {},
+			...e.checkout ? { checkout: e.checkout } : {},
+			...this.config.thankYouMessage ? { thankYouMessage: this.config.thankYouMessage } : {}
+		};
+		this.iframe?.contentWindow?.postMessage(t, this.walletOrigin);
+	}
+	open() {
+		this.overlay && this.overlay.style.display !== "flex" && (l(), this.overlay.style.display = "flex", d() || this.overlay.animate([{ opacity: 0 }, { opacity: 1 }], {
+			duration: t.OVERLAY_FADE_IN_MS,
+			easing: "ease"
+		}));
+	}
+	show(e) {
+		this.open(), this.iframeLoaded ? this.sendInitMessage(e) : this.pendingPaymentData = e;
+	}
+	renderTerminalState(t) {
+		this.close(), l();
+		let n = document.createElement("div");
+		n.className = "pybara-checkout-overlay", n.style.cssText = `
+            position: fixed;
+            top: 0;
+            left: 0;
+            right: 0;
+            bottom: 0;
+            background: ${e.BACKGROUND};
+            z-index: ${e.Z_INDEX};
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            user-select: none;
+        `;
+		let r = document.createElement("div");
+		r.style.cssText = "\n            background: #fff;\n            border-radius: 12px;\n            color: #666;\n            padding: 2rem;\n            line-height: 1.4;\n            max-width: 360px;\n            text-align: center;\n            font-family: system-ui, sans-serif;\n            user-select: text;\n        ", r.textContent = t, n.appendChild(r), n.addEventListener("click", (e) => {
+			e.target === n && (n.remove(), u(), this.config.onClose?.());
+		}), document.body.appendChild(n), this.overlay = n;
+	}
+	close() {
+		this.handleMessage &&= (window.removeEventListener("message", this.handleMessage), null), this.handleEscapeKey &&= (document.removeEventListener("keydown", this.handleEscapeKey), null), u();
+		let e = this.overlay, n = this.iframe;
+		this.overlay = null, this.iframe = null, this.spinner = null, this.iframeLoaded = !1, this.pendingPaymentData = null, this.closable = !0, e && (e.style.display === "none" || d() ? e.remove() : (e.style.pointerEvents = "none", n?.animate([{
+			transform: "scale(1)",
+			opacity: 1
+		}, {
+			transform: "scale(0.95)",
+			opacity: 0
+		}], {
+			duration: t.PANEL_CLOSE_MS,
+			easing: "ease-out",
+			fill: "forwards"
+		}), e.animate([{ opacity: 1 }, { opacity: 0 }], {
+			duration: t.OVERLAY_FADE_OUT_MS,
+			delay: t.OVERLAY_FADE_OUT_DELAY_MS,
+			easing: "ease-out",
+			fill: "forwards"
+		}).finished.then(() => e.remove(), () => e.remove())));
+	}
+};
+//#endregion
+export { m as n, g as t };