@pybara/donate-widget 0.0.0-stage → 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pybara OÜ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,144 @@
-# Temporary Holding Version
+# Pybara Donate Widget
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A donation widget for any website: visitors give in crypto on the Internet Computer, from their own wallet, and the donation is paid to yours. One script, no server, no WordPress needed.
+
+## Quick start
+
+```html
+<div id="pybara-donate"></div>
+<script src="https://cdn.jsdelivr.net/npm/@pybara/donate-widget@beta/dist/pybara-donate.iife.js"></script>
+<script>
+  PybaraDonate.init({
+    target: '#pybara-donate',               // where the widget renders
+    recipientPrincipal: 'xxxxx-xxxxx-...',  // your Pybara Wallet's principal
+    siteUrl: 'https://example.com',         // your site's address
+    siteName: 'Example Charity',            // the name donors see
+  });
+</script>
+```
+
+These four options are required; every other one is optional, with the defaults in [Configuration](#configuration).
+
+`@beta` follows the latest beta. To stay on one version, use it instead, for example `@1.0.0-beta.1`.
+
+## ES module
+
+In a bundled app (Vite, Next.js, …), install the package instead of the script tag:
+
+```bash
+npm install @pybara/donate-widget@beta
+```
+
+```ts
+import { init } from '@pybara/donate-widget';
+
+init({
+  target: '#pybara-donate',
+  recipientPrincipal: 'xxxxx-xxxxx-...',
+  siteUrl: 'https://example.com',
+  siteName: 'Example Charity',
+});
+```
+
+The package also exports the `DonationWidget` class (what `init` returns), `destroyAll()`, and the config types — all typed.
+
+## Before it shows
+
+The widget stays hidden until your site is set up in [Pybara Wallet](https://pybara.io), under **Manage › Sites › Add a site without a plugin**:
+
+1. **Your site's DNS record** lists your wallet. This needs a domain of your own: a platform subdomain (`*.replit.app` and the like) cannot hold the record.
+2. **You accept the widget's terms** for that site, in the same place.
+
+Until then, and whenever Pybara pauses the widget, nothing is shown, and your browser's console says why. The checkout itself pays only a wallet your site's DNS record lists, whatever the page does.
+
+## Pricing
+
+A single platform fee per donation: no monthly fees, no setup fees. Your rate is set by the year of your site's first donation, and locked to it for life:
+
+- **Go live in 2026:** 1% per donation, locked for life (the founder rate)
+- **Go live in 2027:** 1.5% per donation, locked for life
+- **From 2028:** the then-current standard rate, published on [pybara.com](https://pybara.com)
+
+The fee also covers the network fees. Donors give the exact amount they choose, and you receive your full share: at the founder rate, exactly 99% of every donation. The split is made on-chain by a publicly auditable canister whose code cannot change, and which refuses any fee above 3%. Your site's rate is shown in Pybara Wallet, under **Manage › Sites**.
+
+The one exception is AutoStable: if you have a token converted to a stablecoin as it arrives, set in Pybara Wallet, the conversion's cost is deducted on top of the platform fee.
+
+## Configuration
+
+### Required
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `target` | `string \| HTMLElement` | CSS selector or element to render into |
+| `recipientPrincipal` | `string` | Your Pybara Wallet's principal, the one your DNS record lists |
+| `siteUrl` | `string` | Your site's address, e.g. `https://example.com`: the origin of the page the widget is on, or the checkout refuses the donation |
+| `siteName` | `string` | The name donors see |
+
+### Optional
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `presetAmounts` | `number[]` | `[5, 10, 25, 50]` | Up to 6 preset amounts, in the display currency, each at least 0.50 |
+| `allowCustom` | `boolean` | `true` | Let donors enter their own amount |
+| `allowRecurring` | `boolean` | `true` | Offer recurring donations |
+| `defaultFrequency` | `string` | `'monthly'` | `'weekly'`, `'monthly'` or `'yearly'` |
+| `defaultDurationInMonths` | `number \| null` | `12` | The recurring duration preselected: `3`, `6`, `12` or `24` months, or `null` for no end date; donors can change it |
+| `tokens` | `string[]` | All supported | Tokens donors may give: `'ckUSDC'`, `'ckUSDT'`, `'ckBTC'`, `'ckETH'`, `'ICP'` |
+| `title` | `string` | — | Shown above the amounts |
+| `description` | `string` | — | Shown below the title |
+| `buttonLabel` | `string` | Donate, in the widget's language | The button's label |
+| `thankYouMessage` | `string` | — | Replaces the success screen's title, which is otherwise shown in the donor's language |
+| `thankYouRedirectUrl` | `string` | — | Where to send donors afterwards |
+| `primaryColor` | `string` | `'#7c3aed'` | Accent colour (hex) |
+| `theme` | `'light' \| 'dark' \| 'auto'` | `'light'` | `'auto'` follows your page's background and its theme switcher |
+| `currency` | `string` | `'USD'` | Display currency (ISO 4217), e.g. `'EUR'` |
+| `locale` | `string` | Browser's | Interface language: `'en'`, `'fr'`, `'de'`, `'es'`, `'it'`, `'pt'`, `'nl'`, `'pl'`, `'ro'`, `'ja'`, `'ko'` or `'zh-CN'` |
+| `fontUrl` | `string` | — | A `.woff2` font of your own; none is loaded otherwise |
+| `onSuccess` | `function` | — | Called once the donation is made |
+| `onError` | `function` | — | Called on an error |
+| `onClose` | `function` | — | Called when the checkout is closed without donating |
+| `staging` | `boolean` | `false` | Use Pybara's staging environment, for testing |
+| `debug` | `boolean` | `false` | Log details to the console |
+
+### Example with options
+
+```js
+PybaraDonate.init({
+  target: '#pybara-donate',
+  recipientPrincipal: 'xxxxx-xxxxx-...',
+  siteUrl: 'https://example.com',
+  siteName: 'Example Charity',
+  primaryColor: '#e11d48',
+  currency: 'EUR',
+  locale: 'fr',
+  presetAmounts: [5, 10, 25],
+  tokens: ['ckUSDC', 'ICP'],
+  buttonLabel: 'Soutenir',
+});
+```
+
+## Theming
+
+- **`light`** (default) and **`dark`** cards, or **`auto`**, which samples your page's background and follows your theme switcher and the visitor's system setting.
+- **The accent colour** is adjusted where needed so text stays readable on the card; buttons keep your exact colour.
+
+## Languages
+
+English, French, German, Spanish, Italian, Portuguese, Dutch, Polish, Romanian, Japanese, Korean and Chinese (simplified), chosen from the visitor's browser unless `locale` is set. The checkout follows the same language.
+
+## Content Security Policy
+
+On a site with a strict Content Security Policy, allow:
+
+- `script-src`: `https://cdn.jsdelivr.net`
+- `frame-src`: `https://pybara.io`, where donors pay
+- `connect-src`: `https://icp-api.io`, `https://*.raw.icp0.io` and `https://api.frankfurter.app`, for Pybara's settings and the exchange rates
+- `img-src`: `https://assets.pybara.com`
+
+## Learn more
+
+[docs.pybara.com](https://docs.pybara.com/widget/overview/)
+
+## License
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,32 @@
+import { DonationWidgetConfig, Frequency } from './types.js';
+export declare const DEFAULT_PRESET_AMOUNTS: number[];
+export declare const DEFAULT_FREQUENCY: Frequency;
+export declare const DEFAULT_DURATION_IN_MONTHS = 12;
+export declare const DEFAULT_PRIMARY_COLOR = "#7c3aed";
+export declare const DEFAULT_THEME: "light";
+export declare const VALID_THEMES: readonly ["light", "dark", "auto"];
+export declare const DEFAULT_CURRENCY = "USD";
+/** Currency symbol map — add entries as needed */
+export declare const CURRENCY_SYMBOLS: Record<string, string>;
+/** Get the display symbol for a currency code */
+export declare function getCurrencySymbol(currency: string): string;
+export declare const DEFAULT_TOKENS: string[];
+export declare const VALID_FREQUENCIES: Frequency[];
+export declare const VALID_DURATION_MONTHS: number[];
+/**
+ * Seconds between pulls, per frequency. Must match subs.mo's allowedFrequencies, which is the canister that actually schedules them.
+ * A duration is wall-clock time, so the number of pulls it buys is the duration divided by one of these.
+ */
+export declare const FREQUENCY_SECONDS: Record<Frequency, number>;
+/** Seconds in a month, matching the 30 days subs.mo's `monthly` interval uses. */
+export declare const MONTH_SECONDS = 2592000;
+/** Minimum donation amount in USD */
+export declare const MIN_DONATION_USD = 0.5;
+/** Maximum preset amounts allowed */
+export declare const MAX_PRESET_COUNT = 6;
+/**
+ * Validate and merge user config with defaults.
+ * Throws on invalid required fields.
+ */
+export declare function resolveConfig(userConfig: DonationWidgetConfig): Required<Pick<DonationWidgetConfig, 'target' | 'recipientPrincipal' | 'siteUrl' | 'siteName' | 'presetAmounts' | 'allowCustom' | 'allowRecurring' | 'defaultFrequency' | 'defaultDurationInMonths' | 'tokens' | 'buttonLabel' | 'primaryColor' | 'theme' | 'currency' | 'debug' | 'staging'>> & Partial<Pick<DonationWidgetConfig, 'title' | 'description' | 'thankYouMessage' | 'thankYouRedirectUrl' | 'locale' | 'onSuccess' | 'onError' | 'onClose' | 'fontUrl'>>;
+//# sourceMappingURL=config.d.ts.map

package/dist/i18n/en.d.ts

@@ -0,0 +1,38 @@
+/**
+ * English translations (default)
+ */
+declare const en: {
+    amount: {
+        customPlaceholder: string;
+    };
+    recurring: {
+        toggleLabel: string;
+        frequency: string;
+        duration: string;
+        weekly: string;
+        monthly: string;
+        yearly: string;
+        every2min: string;
+        months3: string;
+        months6: string;
+        months12: string;
+        months24: string;
+        unlimited: string;
+        comingSoon: string;
+        notSupported: string;
+    };
+    widget: {
+        errorGeneric: string;
+        footerText: string;
+        donationFallbackName: string;
+        cryptoPayments: string;
+        donateButton: string;
+    };
+    errors: {
+        minimumDonation: string;
+        minimumToken: string;
+    };
+};
+export type Translations = typeof en;
+export default en;
+//# sourceMappingURL=en.d.ts.map

package/dist/i18n/index.d.ts

@@ -0,0 +1,10 @@
+import { default as enType } from './en.js';
+export type Translations = typeof enType;
+export declare const SUPPORTED_LOCALES: string[];
+/** Detect browser locale (normalized) */
+export declare function detectLocale(): string;
+/** Get translations for a locale, with English fallback */
+export declare function getTranslations(locale?: string): Translations;
+/** Interpolate {{variable}} placeholders in a string */
+export declare function t(template: string, values?: Record<string, string>): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+import { DonationResult, DonationWidgetConfig, Frequency, RecurringConfig } from './types.js';
+import { DonationWidget } from './widget.js';
+/**
+ * Initialize a donation widget on the page.
+ * Can be called multiple times with different targets.
+ */
+export declare function init(config: DonationWidgetConfig): DonationWidget;
+/**
+ * Destroy all active widget instances.
+ */
+export declare function destroyAll(): void;
+export type { DonationResult, DonationWidgetConfig, Frequency, RecurringConfig };
+export { DonationWidget };
+//# sourceMappingURL=index.d.ts.map