@maytes/checkout-button 1.1.1 → 1.2.1

package/docs/guides/angular.md

@@ -0,0 +1,56 @@
+# Angular
+
+Add the Split with Maytes button to an Angular app with a standalone component that also works with Angular's server-side rendering.
+
+You need an endpoint on your server that creates a Maytes checkout and returns `{ checkoutId, checkoutUrl }`. The example calls it `POST /api/maytes/checkout`; [Your server](https://github.com/kttipay/maytes-checkout-button/blob/main/docs/guides/server.md) shows how to build it.
+
+```bash
+npm install @maytes/checkout-button
+```
+
+```ts
+import { AfterViewInit, Component, ElementRef, Input, OnDestroy, PLATFORM_ID, ViewChild, inject } from '@angular/core';
+import { isPlatformBrowser } from '@angular/common';
+import { Maytes, type MaytesSDK } from '@maytes/checkout-button';
+
+@Component({
+  selector: 'app-split-with-maytes',
+  standalone: true,
+  template: '<div #slot></div>',
+})
+export class SplitWithMaytesComponent implements AfterViewInit, OnDestroy {
+  @Input({ required: true }) cartId!: string;
+  @ViewChild('slot', { static: true }) slot!: ElementRef<HTMLDivElement>;
+
+  private readonly platformId = inject(PLATFORM_ID);
+  private maytes: MaytesSDK | null = null;
+
+  ngAfterViewInit(): void {
+    if (!isPlatformBrowser(this.platformId)) return;
+    this.maytes = Maytes({
+      environment: 'sandbox',
+      createCheckout: async () => {
+        const res = await fetch('/api/maytes/checkout', {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({ cartId: this.cartId }),
+        });
+        if (!res.ok) throw new Error('Could not create the Maytes checkout');
+        return res.json(); // { checkoutId, checkoutUrl }
+      },
+    });
+    this.maytes.renderButton(this.slot.nativeElement, { block: true });
+  }
+
+  ngOnDestroy(): void {
+    this.maytes?.destroy();
+  }
+}
+```
+
+- The `isPlatformBrowser` check keeps the button out of server-side rendering; without SSR it is always true.
+- `this.cartId` is read when the shopper clicks, so it is always the latest value.
+
+Prefer a standard custom element? [`<maytes-checkout-button>`](https://github.com/kttipay/maytes-checkout-button/blob/main/docs/guides/web-component.md) works here too.
+
+Next: [API reference](https://github.com/kttipay/maytes-checkout-button/blob/main/docs/guides/api.md) · [Troubleshooting](https://github.com/kttipay/maytes-checkout-button/blob/main/docs/guides/troubleshooting.md)

package/docs/guides/api.md

@@ -0,0 +1,108 @@
+# API reference
+
+Every option, method and default of the `@maytes/checkout-button` browser SDK.
+
+`Maytes` is a callable factory, like `Stripe()`. Each call returns an isolated instance. From the script tag it is `window.Maytes`; from npm it is `import { Maytes } from '@maytes/checkout-button'`.
+
+## `Maytes(options)`
+
+| Option | Type | Description |
+|---|---|---|
+| `createCheckout` | `() => Promise<{ checkoutId: string; checkoutUrl?: string }>` | Required. Called when the shopper clicks; asks your server for a checkout. Throw (or reject) to report a failure. |
+| `environment` | `'sandbox' \| 'production'` | Required. Which Maytes environment the checkout opens in when you don't return `checkoutUrl`: `sandbox` opens `https://sandbox-checkout.maytes.co`, `production` opens `https://checkout.maytes.co`. |
+
+Returns a `MaytesSDK` instance. Invalid options throw `MaytesError` with `code: 'CONFIG'`.
+
+An optional second argument, `{ cspNonce }`, sets a nonce on the styles the SDK injects; see [Security and CSP](https://github.com/kttipay/maytes-checkout-button/blob/main/docs/guides/security-csp.md).
+
+## Instance methods
+
+| Method | Returns | Description |
+|---|---|---|
+| `renderButton(container, options?)` | `() => void` | Renders the button into `container` (an `HTMLElement`) and returns a function that removes it. |
+| `openCheckout({ mode?, redirectOverlay? })` | `Promise<OpenCheckoutResult>` | Starts the checkout from your own button, exactly as a click on the rendered button does. Takes the same `mode` and `redirectOverlay` as `renderButton()`. Call it inside your click handler, before any `await`. Resolves with how the launch ended and never rejects. See [Using your own button](https://github.com/kttipay/maytes-checkout-button/blob/main/docs/guides/own-button.md). |
+| `redirectToCheckout({ checkoutId, replace? })` | `void` | Sends the current tab to a checkout you already created, without a button. `replace: true` replaces the history entry. Inside an iframe it navigates the top-level window and throws `MaytesError` if the browser refuses. |
+| `instanceId` | `string` | Read-only id of this instance. Every `maytes:checkout-*` event carries it as `event.detail.instanceId`. |
+| `onBusyChange(listener)` | `() => void` | Calls `listener(true)` when a launch on this instance starts and `listener(false)` when it ends; returns a function that stops listening. Useful to disable your own Pay button. |
+| `checkoutUrl({ checkoutId })` | `string` | Builds the hosted checkout URL for a checkout you already created. |
+| `destroy()` | `void` | Tears down the instance: buttons, listeners, the overlay and a popup that hasn't loaded yet. Idempotent. |
+
+Call `destroy()` when the page or component goes away, or when you need an instance with a different `environment`. Don't call it because your own code saw the payment succeed: that can tear down a checkout that's still in progress. To remove one button, call the function `renderButton()` returned.
+
+## `renderButton` options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` | `'Split with'` | Text before the Maytes logo. The accessible name is `"<label> Maytes"`. |
+| `block` | `boolean` | `false` | `true` makes the button fill the width of its container. |
+| `mode` | `'popup' \| 'redirect'` | `'popup'` | `'popup'` opens a centred window on desktop and falls back to the same tab on phones or when the popup is blocked. `'redirect'` always uses the same tab. |
+| `radius` | `number` | the default pill | Corner radius in whole pixels, from 0 to 999, and at most half the `height` when `height` is set. Use it to match neighbouring buttons. |
+| `height` | `number` | the default height | Button height in whole pixels, from 40 to 55. A button with a `height` keeps its label on one line. |
+| `redirectOverlay` | `boolean` | `false` | `true` shows the Maytes loading overlay while `createCheckout` runs whenever the checkout opens in the same tab (redirect mode, phones, blocked popups). See [Popup, redirect and iframes](https://github.com/kttipay/maytes-checkout-button/blob/main/docs/guides/launch-behaviour.md). |
+
+Two buttons rendered from one instance share one checkout at a time: clicks and `openCheckout()` are ignored while that instance's `createCheckout` is running.
+
+## Fitting next to wallet buttons
+
+In an express-checkout row next to Apple Pay, Google Pay or Link, match the row's height and corners:
+
+```ts
+import { Maytes } from '@maytes/checkout-button';
+
+const maytes = Maytes({ createCheckout, environment: 'sandbox' });
+maytes.renderButton(document.getElementById('maytes-slot')!, { block: true, radius: 6, height: 48 });
+```
+
+That matches Stripe's Express Checkout Element at `buttonHeight: 48` with 6px corners. The colours, logo and label stay Maytes'. Without `radius` and `height` the button renders exactly as before. Invalid values throw `MaytesError` (`CONFIG`).
+
+## Styling with CSS custom properties
+
+The button reads three CSS custom properties, so you can style it from your own CSS or bind it to your design tokens:
+
+| Property | Default | Sets |
+|---|---|---|
+| `--maytes-button-height` | the button's natural height | Minimum height. Keep it from 40px to 55px. |
+| `--maytes-button-radius` | `999px` (the pill) | Corner radius. |
+| `--maytes-button-font-size` | `14px` | Label size. |
+
+```css
+.express-row {
+  --maytes-button-height: 48px;
+  --maytes-button-radius: var(--radius-md);
+}
+```
+
+Set them on the button's container; they're inherited. The `height` and `radius` options set the same properties on the button and validate them; values set in CSS aren't validated. A button given a `height` option also keeps its label on one line. Colours, logo and label stay Maytes'.
+
+## Examples
+
+```ts
+import { Maytes } from '@maytes/checkout-button';
+
+const maytes = Maytes({
+  environment: 'production',
+  createCheckout: async () => {
+    const res = await fetch('/api/maytes/checkout', { method: 'POST' });
+    if (!res.ok) throw new Error('Could not create the Maytes checkout');
+    return res.json();
+  },
+});
+
+const removeButton = maytes.renderButton(document.getElementById('maytes-button')!, {
+  label: 'Split with',
+  block: true,
+  mode: 'redirect',
+});
+
+const url = maytes.checkoutUrl({ checkoutId: '019fbb9e-ecd1-7059-99f3-f8bf47b63931' });
+maytes.redirectToCheckout({ checkoutId: '019fbb9e-ecd1-7059-99f3-f8bf47b63931', replace: true });
+
+removeButton();
+maytes.destroy();
+```
+
+## Errors
+
+`MaytesError` (exported from the package) is thrown for invalid configuration: options that aren't an object, a missing `createCheckout`, an unknown `environment`, a `renderButton` container that isn't an `HTMLElement`, an unknown `mode`, or a call on a destroyed instance. Its `code` is always `'CONFIG'`. Problems after the click (your request failing, the wrong response shape) are reported as [events](https://github.com/kttipay/maytes-checkout-button/blob/main/docs/guides/events.md), not thrown.
+
+Next: [Events](https://github.com/kttipay/maytes-checkout-button/blob/main/docs/guides/events.md) · [Popup, redirect and iframes](https://github.com/kttipay/maytes-checkout-button/blob/main/docs/guides/launch-behaviour.md)

package/docs/guides/events.md

@@ -0,0 +1,48 @@
+# Events
+
+The four `maytes:checkout-*` events the button dispatches, and how to listen to them.
+
+The button reports what happened with `CustomEvent`s on `document`. Use them for your own UI; your webhook and capture remain the source of truth for payment.
+
+| Event | When | `event.detail` |
+|---|---|---|
+| `maytes:checkout-opened` | The popup opened. | `{ instanceId, source }` |
+| `maytes:checkout-closed` | The popup was closed while your page was still open, usually by the shopper. (When the checkout finishes, it sends your page to your `return_url` instead.) | `{ instanceId, source }` |
+| `maytes:checkout-redirected` | The checkout opened without a popup. | `{ url, target, instanceId, source }`, where `target` is `'self'` (this tab), `'top'` (the page around your iframe) or `'tab'` (a new tab) |
+| `maytes:checkout-failed` | The checkout could not open. | `{ reason, cause?, instanceId, source }`, where `reason` is `'create-checkout-rejected'`, `'invalid-shape'` or `'navigation-blocked'` |
+
+```ts
+import type { CheckoutFailedDetail, CheckoutRedirectedDetail } from '@maytes/checkout-button';
+
+document.addEventListener('maytes:checkout-failed', (event) => {
+  const { reason } = (event as CustomEvent<CheckoutFailedDetail>).detail;
+  showMessage(reason === 'create-checkout-rejected'
+    ? 'We could not start Split with Maytes. Please try again.'
+    : 'Split with Maytes is unavailable right now.');
+});
+
+document.addEventListener('maytes:checkout-redirected', (event) => {
+  const { target } = (event as CustomEvent<CheckoutRedirectedDetail>).detail;
+  if (target === 'tab') showMessage('Split with Maytes opened in a new tab.');
+});
+```
+
+Every `detail` also carries `instanceId`, the id of the instance that sent it (`maytes.instanceId`), and `source`: `'button'` for a click on a rendered button, `'api'` for `openCheckout()`. With several instances on one page, filter by id:
+
+```ts
+import { Maytes } from '@maytes/checkout-button';
+
+const maytes = Maytes({ createCheckout, environment: 'sandbox' });
+
+document.addEventListener('maytes:checkout-closed', (event) => {
+  if (event.detail.instanceId !== maytes.instanceId) return;
+  showMessage('Split with Maytes was closed.');
+});
+```
+
+- `failed` reasons: `create-checkout-rejected` means your `createCheckout` threw or rejected; `invalid-shape` means it didn't resolve to `{ checkoutId, checkoutUrl? }`; `navigation-blocked` means the button is inside an iframe and the browser refused both the top-level navigation and a new tab.
+- A blocked popup is not a failure: the button opens the checkout in the same tab and dispatches `maytes:checkout-redirected`.
+- There are no completion callbacks by design: in redirect mode your page is gone before the checkout finishes, and the hosted checkout returns the shopper to your `return_url`.
+- In React, Vue or another framework, add listeners when the component mounts and remove them when it unmounts.
+
+Next: [Popup, redirect and iframes](https://github.com/kttipay/maytes-checkout-button/blob/main/docs/guides/launch-behaviour.md) · [Troubleshooting](https://github.com/kttipay/maytes-checkout-button/blob/main/docs/guides/troubleshooting.md)

package/docs/guides/launch-behaviour.md

@@ -0,0 +1,41 @@
+# Popup, redirect and iframes
+
+Where the Maytes checkout opens on desktop, on phones, when popups are blocked and inside an iframe.
+
+## Where the checkout opens
+
+- **Desktop, `mode: 'popup'` (default):** the button opens a 500 × 800 window immediately on click and shows a Maytes loading screen in it. Your page is covered with a dimmed "Completing checkout with Maytes…" overlay that has a "Return to Maytes" button. Once `createCheckout` resolves, the window loads the checkout. Pressing Esc closes the popup.
+- **Phones (viewport 600px wide or less):** the same tab, even in popup mode.
+- **Popup blocked:** the same tab. This is a normal outcome, reported with `maytes:checkout-redirected`, not `maytes:checkout-failed`.
+- **`mode: 'redirect'`:** always the same tab.
+
+When the shopper finishes, the hosted checkout returns them to your `return_url`. In popup mode it sends your page there and closes the popup.
+
+The popup opens synchronously inside the click, before your `createCheckout` runs, so browsers treat it as a direct result of the shopper's click.
+
+### A loading overlay for same-tab launches
+
+By default a same-tab launch shows only the button's spinner while `createCheckout` runs. Pass `redirectOverlay: true` to `renderButton()` or `openCheckout()` to cover the page with the Maytes overlay ("Taking you to Maytes…", without the "Return to Maytes" button) until the page leaves:
+
+```ts
+import { Maytes } from '@maytes/checkout-button';
+
+const maytes = Maytes({ createCheckout, environment: 'sandbox' });
+maytes.renderButton(document.getElementById('maytes-button')!, { mode: 'redirect', redirectOverlay: true });
+```
+
+The overlay goes away if `createCheckout` fails, and clears itself when the shopper comes back with the back button. Invalid values throw `MaytesError` (`CONFIG`).
+
+## Inside an iframe
+
+The hosted checkout must run in the top-level window, because its session cookie is refused inside a cross-site frame. If you render the button inside an iframe:
+
+1. The SDK navigates the top-level window.
+2. If the browser refuses, it opens a new tab.
+3. If both are refused, it dispatches `maytes:checkout-failed` with `reason: 'navigation-blocked'` and leaves the button usable.
+
+When the checkout opens in a new tab, no popup poll starts and no `maytes:checkout-opened` / `maytes:checkout-closed` pair fires; you'll only see `maytes:checkout-redirected` with `target: 'tab'`. Read `event.detail.target` (`'self'`, `'top'` or `'tab'`) if your page needs to know where the checkout went.
+
+A sandboxed iframe needs `allow-scripts allow-same-origin allow-top-navigation`, plus `allow-popups allow-popups-to-escape-sandbox` for the tab fallback. Rendering the button in the top-level page avoids all of this.
+
+Next: [Events](https://github.com/kttipay/maytes-checkout-button/blob/main/docs/guides/events.md) · [Troubleshooting](https://github.com/kttipay/maytes-checkout-button/blob/main/docs/guides/troubleshooting.md)

package/docs/guides/nextjs.md

@@ -0,0 +1,49 @@
+# Next.js
+
+Add the Split with Maytes button to a Next.js app with a client component, and keep your Maytes credentials in a Route Handler.
+
+```bash
+npm install @maytes/checkout-button
+```
+
+```tsx
+'use client';
+
+import { useEffect, useRef } from 'react';
+import { Maytes } from '@maytes/checkout-button';
+
+export default function SplitWithMaytesButton({ cartId }: { cartId: string }) {
+  const slotRef = useRef<HTMLDivElement>(null);
+  const cartIdRef = useRef(cartId);
+
+  useEffect(() => {
+    cartIdRef.current = cartId;
+  }, [cartId]);
+
+  useEffect(() => {
+    const maytes = Maytes({
+      environment: process.env.NEXT_PUBLIC_MAYTES_ENVIRONMENT === 'production' ? 'production' : 'sandbox',
+      createCheckout: async () => {
+        const res = await fetch('/api/maytes/checkout', {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({ cartId: cartIdRef.current }),
+        });
+        if (!res.ok) throw new Error('Could not create the Maytes checkout');
+        return res.json(); // { checkoutId, checkoutUrl }
+      },
+    });
+    maytes.renderButton(slotRef.current!, { block: true });
+    return () => maytes.destroy();
+  }, []);
+
+  return <div ref={slotRef} />;
+}
+```
+
+- **Server rendering is safe.** The package doesn't touch `window` when it's imported, and the button is created in `useEffect`, which only runs in the browser.
+- **The server half** goes in a Route Handler, `app/api/maytes/checkout/route.ts`, so your Maytes credentials never reach the browser. [Your server](https://github.com/kttipay/maytes-checkout-button/blob/main/docs/guides/server.md) shows what it must return.
+- **Prefer the CDN?** Load it with `next/script` (`<Script src="https://js.maytes.co/v1/checkout-button.js" strategy="afterInteractive" onReady={…} />`) and call `window.Maytes(…)` in `onReady` instead of importing.
+- The component follows the [React guide](https://github.com/kttipay/maytes-checkout-button/blob/main/docs/guides/react.md): one instance per mount, StrictMode-safe, the latest cart read through a ref.
+
+Next: [API reference](https://github.com/kttipay/maytes-checkout-button/blob/main/docs/guides/api.md) · [Troubleshooting](https://github.com/kttipay/maytes-checkout-button/blob/main/docs/guides/troubleshooting.md)

package/docs/guides/own-button.md

@@ -0,0 +1,41 @@
+# Using your own button
+
+Start the Maytes checkout from a button you already have, such as the Pay button of a Stripe Payment Element checkout.
+
+If your page already has its own Pay button, for example a Stripe Payment Element checkout that offers **Split with Maytes** as a Stripe custom payment method, start Maytes from that button with `openCheckout()`:
+
+```ts
+import { Maytes } from '@maytes/checkout-button';
+
+const maytes = Maytes({ createCheckout, environment: 'sandbox' });
+
+let maytesSelected = false;
+paymentElement.on('change', (event) => {
+  maytesSelected = event.value.type === MAYTES_CPM_ID;
+});
+
+payButton.addEventListener('click', async () => {
+  if (maytesSelected) {
+    const result = await maytes.openCheckout();
+    if (result.outcome === 'failed') showMessage('Could not start Split with Maytes. Please try again.');
+    return;
+  }
+  // ... your normal card flow
+});
+```
+
+**Call `openCheckout()` inside the click handler, before any `await`.** Browsers only allow a popup straight from a click: the SDK opens the window during the call and creates the checkout afterwards. Called later, the popup may be blocked; the SDK then redirects instead, so the payment still works.
+
+`openCheckout({ mode })` takes the same `mode` as `renderButton()`: `'popup'` (default) or `'redirect'`. It resolves with how the launch ended:
+
+| `outcome` | Meaning |
+|---|---|
+| `popup` | The popup loaded the Maytes checkout. |
+| `redirected` | The page (or the top window, or a new tab: `target`) went to the Maytes checkout. |
+| `failed` | `createCheckout` failed or returned the wrong shape, or every way out of an iframe was refused (`reason`, same as `maytes:checkout-failed`). |
+| `closed` | The customer closed the popup before the checkout loaded. |
+| `ignored` | A checkout launch from this instance was already in flight. |
+
+It never rejects. It throws `MaytesError` (`CONFIG`) synchronously on a destroyed instance or an invalid `mode`. Buttons rendered by the same instance ignore clicks while any launch is in flight.
+
+Next: [With Stripe's Payment Element](https://github.com/kttipay/maytes-checkout-button/blob/main/docs/guides/stripe-payment-element.md) · [API reference](https://github.com/kttipay/maytes-checkout-button/blob/main/docs/guides/api.md)

package/docs/guides/quickstart-html.md

@@ -0,0 +1,31 @@
+# Quickstart: plain HTML
+
+Add the Split with Maytes button to any page with a `<script>` tag: server-rendered HTML, PHP, Rails, Django, Laravel, WordPress or any page without a bundler.
+
+You need an endpoint on your server that creates a Maytes checkout and returns `{ checkoutId, checkoutUrl }`. The examples call it `POST /api/maytes/checkout`; [Your server](https://github.com/kttipay/maytes-checkout-button/blob/main/docs/guides/server.md) shows how to build it.
+
+```html
+<div id="maytes-button"></div>
+
+<script src="https://js.maytes.co/v1/checkout-button.js" crossorigin="anonymous"></script>
+<script>
+  const maytes = window.Maytes({
+    environment: 'sandbox',
+    createCheckout: async () => {
+      const res = await fetch('/api/maytes/checkout', { method: 'POST' });
+      if (!res.ok) throw new Error('Could not create the Maytes checkout');
+      return res.json(); // { checkoutId, checkoutUrl }
+    },
+  });
+
+  maytes.renderButton(document.getElementById('maytes-button'), { block: true });
+</script>
+```
+
+- The second script must run after the first, so keep them in this order, both without `async`.
+- Use `environment: 'sandbox'` with sandbox API credentials while you test, and `'production'` with production credentials when you go live.
+- `https://js.maytes.co/v1/checkout-button.js` always serves the newest `1.x` release. To freeze on a tested build with SRI, use a pinned URL from [Install and versioning](https://github.com/kttipay/maytes-checkout-button#install).
+
+Prefer a standard custom element? [`<maytes-checkout-button>`](https://github.com/kttipay/maytes-checkout-button/blob/main/docs/guides/web-component.md) works here too.
+
+Next: [API reference](https://github.com/kttipay/maytes-checkout-button/blob/main/docs/guides/api.md) · [Events](https://github.com/kttipay/maytes-checkout-button/blob/main/docs/guides/events.md) · [Troubleshooting](https://github.com/kttipay/maytes-checkout-button/blob/main/docs/guides/troubleshooting.md)

package/docs/guides/quickstart-npm.md

@@ -0,0 +1,34 @@
+# Quickstart: npm with a bundler
+
+Add the Split with Maytes button to a page built with Vite, webpack, esbuild or another bundler, without a UI framework.
+
+You need an endpoint on your server that creates a Maytes checkout and returns `{ checkoutId, checkoutUrl }`. The examples call it `POST /api/maytes/checkout`; [Your server](https://github.com/kttipay/maytes-checkout-button/blob/main/docs/guides/server.md) shows how to build it.
+
+```bash
+npm install @maytes/checkout-button
+```
+
+```ts
+import { Maytes } from '@maytes/checkout-button';
+
+const maytes = Maytes({
+  environment: 'sandbox',
+  createCheckout: async () => {
+    const res = await fetch('/api/maytes/checkout', { method: 'POST' });
+    if (!res.ok) throw new Error('Could not create the Maytes checkout');
+    return res.json(); // { checkoutId, checkoutUrl }
+  },
+});
+
+const removeButton = maytes.renderButton(document.getElementById('maytes-button')!, { block: true });
+
+// When the checkout page goes away:
+// removeButton();      removes just this button
+// maytes.destroy();    tears down the instance, its buttons and any open popup
+```
+
+- TypeScript types ship with the package: `MaytesSDK`, `MaytesOptions`, `RenderButtonOptions`, the event detail types and more.
+- Use `environment: 'sandbox'` with sandbox API credentials while you test, and `'production'` with production credentials when you go live.
+- ESM (`import`) and CommonJS (`require`) builds ship unminified; your bundler minifies them.
+
+Next: [API reference](https://github.com/kttipay/maytes-checkout-button/blob/main/docs/guides/api.md) · [Events](https://github.com/kttipay/maytes-checkout-button/blob/main/docs/guides/events.md) · [Troubleshooting](https://github.com/kttipay/maytes-checkout-button/blob/main/docs/guides/troubleshooting.md)

package/docs/guides/react.md

@@ -0,0 +1,88 @@
+# React
+
+Add the Split with Maytes button to a React app (Vite, Create React App, Remix) with a small component that is safe under StrictMode.
+
+You need an endpoint on your server that creates a Maytes checkout and returns `{ checkoutId, checkoutUrl }`. The example calls it `POST /api/maytes/checkout`; [Your server](https://github.com/kttipay/maytes-checkout-button/blob/main/docs/guides/server.md) shows how to build it.
+
+```bash
+npm install @maytes/checkout-button
+```
+
+```tsx
+import { useEffect, useRef } from 'react';
+import { Maytes } from '@maytes/checkout-button';
+
+export function SplitWithMaytesButton({ cartId }: { cartId: string }) {
+  const slotRef = useRef<HTMLDivElement>(null);
+  const cartIdRef = useRef(cartId);
+
+  useEffect(() => {
+    cartIdRef.current = cartId;
+  }, [cartId]);
+
+  useEffect(() => {
+    const maytes = Maytes({
+      environment: 'sandbox',
+      createCheckout: async () => {
+        const res = await fetch('/api/maytes/checkout', {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({ cartId: cartIdRef.current }),
+        });
+        if (!res.ok) throw new Error('Could not create the Maytes checkout');
+        return res.json(); // { checkoutId, checkoutUrl }
+      },
+    });
+    maytes.renderButton(slotRef.current!, { block: true });
+    return () => maytes.destroy();
+  }, []);
+
+  return <div ref={slotRef} />;
+}
+```
+
+- **One instance per mount.** The instance is created in an effect and destroyed in its cleanup. StrictMode mounts effects twice in development; the first instance is destroyed before the second is created, so one button remains.
+- **Latest cart, no rebuild.** `createCheckout` runs on click, so it reads `cartIdRef.current` rather than closing over the first render's `cartId`, and the button is not rebuilt when the cart changes.
+- **Reacting to the checkout.** To show your own message when the checkout can't open, add a [`maytes:checkout-*` event](https://github.com/kttipay/maytes-checkout-button/blob/main/docs/guides/events.md) listener in another `useEffect` and remove it in the cleanup.
+- Using Next.js? See the [Next.js guide](https://github.com/kttipay/maytes-checkout-button/blob/main/docs/guides/nextjs.md).
+
+## React bindings
+
+The package also ships React components at `@maytes/checkout-button/react`. They do the same as the component above, without writing it yourself:
+
+```tsx
+import { MaytesProvider, MaytesButton } from '@maytes/checkout-button/react';
+
+export function Checkout({ cartId }: { cartId: string }) {
+  return (
+    <MaytesProvider environment="sandbox" createCheckout={() => createMaytesCheckout(cartId)}>
+      <MaytesButton block mode="popup" onFailed={(detail) => showMessage(detail.reason)} />
+    </MaytesProvider>
+  );
+}
+```
+
+`MaytesButton` takes the same options as `renderButton()` (`mode`, `label`, `block`, `radius`, `height`, `redirectOverlay`) plus `onOpened`, `onClosed`, `onRedirected` and `onFailed`. The callbacks fire only for launches started by a `MaytesButton` under the same provider.
+
+From your own button, for example a Stripe Payment Element where Split with Maytes is a custom payment method:
+
+```tsx
+import { useMaytes } from '@maytes/checkout-button/react';
+
+export function PayButton({ maytesSelected }: { maytesSelected: boolean }) {
+  const { openCheckout, busy } = useMaytes();
+  return (
+    <button disabled={busy} onClick={() => (maytesSelected ? openCheckout() : payWithStripe())}>
+      Pay
+    </button>
+  );
+}
+```
+
+Track `maytesSelected` from the Payment Element's `change` event (`event.value.type === '<your cpmt_ id>'`) and call `openCheckout()` inside the click, before any `await`, so the popup isn't blocked.
+
+- `createCheckout` can change on every render; the provider always calls the latest one and never re-creates the SDK. Changing `environment` replaces the instance.
+- Works with React 18 and 19, StrictMode and server rendering (Next.js); the entry is marked `"use client"`.
+- React is an optional peer dependency: the core and the CDN script don't include it.
+
+Next: [API reference](https://github.com/kttipay/maytes-checkout-button/blob/main/docs/guides/api.md) · [Troubleshooting](https://github.com/kttipay/maytes-checkout-button/blob/main/docs/guides/troubleshooting.md)

package/docs/guides/security-csp.md

@@ -0,0 +1,32 @@
+# Security and CSP
+
+Where credentials live, and how to run the button under a strict Content Security Policy.
+
+- **Keep credentials on your server.** The browser only ever sees `checkoutId` and `checkoutUrl`. Treat `checkoutId` like a magic link: it identifies the shopper's checkout session.
+- **Price on the server.** Send a cart or order reference from the browser and price it from your own catalogue; never trust a browser-supplied total.
+
+## Scripts
+
+Allow the CDN:
+
+```
+Content-Security-Policy: script-src 'self' https://js.maytes.co;
+```
+
+With a pinned URL you can also add an `integrity` attribute (SRI); the evergreen `/v1/` URL can't have one because its bytes change with each `1.x` release. Pinned URLs and their SRI hashes are in [Install and versioning](https://github.com/kttipay/maytes-checkout-button#install) and the [CHANGELOG](https://github.com/kttipay/maytes-checkout-button/blob/main/CHANGELOG.md).
+
+## Styles
+
+The button injects a `<style>` tag. On a strict `style-src` policy, pass your nonce as the second argument so it's set on every style tag the SDK adds, including the popup's loading screen and the page overlay:
+
+```ts
+import { Maytes } from '@maytes/checkout-button';
+
+const maytes = Maytes({ createCheckout, environment: 'production' }, { cspNonce: 'your-nonce' });
+```
+
+## No eval
+
+The bundle uses no `eval`, `Function` or string-form timers, and every release is scanned for them, so `'unsafe-eval'` is never needed.
+
+Next: [Troubleshooting](https://github.com/kttipay/maytes-checkout-button/blob/main/docs/guides/troubleshooting.md)

package/docs/guides/server.md

@@ -0,0 +1,76 @@
+# Your server
+
+What the endpoint behind `createCheckout` must do and return, in any backend language, with a Node.js example.
+
+The button never holds your Maytes credentials. Your page calls your own endpoint; your endpoint creates the checkout with the [Maytes merchant API](https://developers.maytes.co/create-checkout) and returns two fields:
+
+```json
+{ "checkoutId": "019fbb9e-ecd1-7059-99f3-f8bf47b63931", "checkoutUrl": "https://sandbox-checkout.maytes.co/?id=019fbb9e-ecd1-7059-99f3-f8bf47b63931" }
+```
+
+- `checkoutId` is required. `checkoutUrl` is optional, but return it: the button then opens exactly the URL Maytes gave you.
+- The merchant API answers in snake_case (`checkout_uuid`, `checkout_url`). Map them to `checkoutId` and `checkoutUrl`; anything else makes the button report `invalid-shape`.
+- Price the cart on your server. Send a cart or order reference from the browser, never a total.
+
+## Node.js example
+
+Express with the Maytes backend SDK (`npm install @maytes/api-client-js`). SDKs for Python, PHP, Go, Java, Ruby and .NET are listed in [Build your integration](https://developers.maytes.co/build-your-integration).
+
+```ts
+import express from 'express';
+import { createMaytesApiClient } from '@maytes/api-client-js';
+
+const maytesApi = createMaytesApiClient({
+  endpoint: 'https://sandbox-api.maytes.co',   // https://api.maytes.co in production
+  clientId: process.env.MAYTES_CLIENT_ID!,
+  clientSecret: process.env.MAYTES_CLIENT_SECRET!,
+});
+
+const app = express();
+app.use(express.json());
+
+app.post('/api/maytes/checkout', async (req, res) => {
+  const cart = await loadCart(req.body.cartId);                // your catalogue, your prices
+  const merchantOrderId = await createPendingOrder(cart);
+
+  const created = await maytesApi.createCheckout({
+    createCheckoutRequest: {
+      merchantOrderId,
+      totalAmount: cart.total,                                 // minor units: 4500 = AUD 45.00
+      currency: 'AUD',
+      returnUrl: `https://shop.example.com/thanks?order=${merchantOrderId}`,
+      cancelUrl: 'https://shop.example.com/cart',
+      items: cart.lines.map((line) => ({
+        itemRef: line.sku,
+        name: line.name,
+        quantity: line.quantity,
+        unitPrice: line.unitPrice,
+        currency: 'AUD',
+        category: 'other',
+      })),
+    },
+  });
+
+  await saveCheckoutId(merchantOrderId, created.data.checkoutUuid);
+  res.json({ checkoutId: created.data.checkoutUuid, checkoutUrl: created.data.checkoutUrl });
+});
+```
+
+## Taking the money
+
+The button only opens the checkout. Your server finishes the payment:
+
+- [Webhooks](https://developers.maytes.co/webhooks): subscribe to `checkout.authorized` and verify the `X-Maytes-Signature` header.
+- [Capture and checkout status](https://developers.maytes.co/capture-and-status): capture within 2 minutes of `checkout.authorized`, or the hold is voided. A successful capture is your "order paid" signal.
+- The shopper comes back to the `return_url` you set. In popup mode the checkout sends your page there and closes the popup.
+
+## Environments
+
+| Browser `environment` | Hosted checkout | Merchant API |
+|---|---|---|
+| `'sandbox'` | `https://sandbox-checkout.maytes.co` | `https://sandbox-api.maytes.co` |
+| `'production'` | `https://checkout.maytes.co` | `https://api.maytes.co` |
+
+Sandbox credentials only work against the sandbox API. Keep the browser's `environment` on the same side as the credentials your server uses.
+
+Next: [Troubleshooting](https://github.com/kttipay/maytes-checkout-button/blob/main/docs/guides/troubleshooting.md) · [Security and CSP](https://github.com/kttipay/maytes-checkout-button/blob/main/docs/guides/security-csp.md)