@pulsebyshiga/collect-js 0.2.0 → 0.2.1

package/README.md

@@ -1,18 +1,20 @@
 # @pulsebyshiga/collect-js
 
-Web loader for Pulse Collect's embedded payment components. Mounts a Pulse-controlled
-iframe into your page and gives you a typed event surface around it — the payment surface,
-session token, and order data never enter your DOM. You own the layout, chrome, and brand.
+Drop Pulse's embedded payment experience into any web page. `collect-js` mounts a
+Pulse-controlled iframe and gives you a small, fully-typed API around it — you keep the
+page, the layout, and the brand; Pulse owns the payment surface. The session token,
+deposit addresses, QR codes, and order data never enter your DOM.
 
-> **Status: pre-release (0.1.0).** Published API may change until the Pulse contract is
-> reconciled.
+Framework-agnostic and dependency-free. The [React](https://www.npmjs.com/package/@pulsebyshiga/collect-react)
+and [React Native](https://www.npmjs.com/package/@pulsebyshiga/collect-react-native) SDKs build on it.
+
+> **Pre-release (0.2.0).** The public API may still change.
 
 ## Requirements
 
-- Any framework or none — the loader is dependency-free
-- ESM (`import`) for the npm package; a script-tag IIFE build is also shipped
-- A session token (`cs_*`) minted by your backend with [`@pulsebyshiga/node`](../node-sdk) —
-  secret keys never reach the browser
+- Any framework, or none — the loader has zero runtime dependencies.
+- A modern browser with ES2019 support. Ships an ESM build (`import`) and a script-tag IIFE build.
+- A session token (`cs_*`) minted by your backend with [`@pulsebyshiga/node`](https://www.npmjs.com/package/@pulsebyshiga/node). Your secret key never reaches the browser.
 
 ## Installation
 
@@ -20,43 +22,51 @@ session token, and order data never enter your DOM. You own the layout, chrome,
 npm install @pulsebyshiga/collect-js
 ```
 
-Or without a bundler:
+No bundler? Load the IIFE build from a script tag — it exposes a global `PulseCollect`:
 
 ```html
 <script src="https://embed.pulse.shiga.io/v1/collect.iife.js"></script>
 <script>
-  window.PulseCollect.mount(target, { sessionToken });
+  const handle = PulseCollect.mount(document.getElementById('pay'), { sessionToken });
 </script>
 ```
 
-## Usage
+## Quickstart
+
+Mint a single-order session token on your backend, pass it to the browser, and mount:
 
 ```ts
 import { PulseCollect } from '@pulsebyshiga/collect-js';
 
 const handle = PulseCollect.mount(document.getElementById('pay'), {
-  sessionToken, // cs_* from your backend
+  sessionToken, // cs_* from your backend — never a secret key
   theme: { primaryColor: '#083a9a', fontFamily: 'YourFont, sans-serif' },
-  strings: { title: 'Add {target} to your safe' },
-  onSuccess: (orderId) => showFunded(orderId), // UX only — credit off the webhook
+  onSuccess: (orderId) => showFunded(orderId), // UX signal only — credit off the webhook
   onError: (code, message) => report(code, message),
 });
 
-// later
+// later — on route change, modal close, unmount:
 handle.unmount();
 ```
 
-By default the component walks the user through **Select asset → Choose network → Pay**;
-the selection re-targets the order (new address, QR, re-locked quote) before payment.
-Pass `flow: "direct"` to pin the asset/network chosen at session creation and render the
-single payment view.
+By default the embed walks the user through **Select asset → Choose network → Pay**, and
+reports every transition through your callbacks. Pass `flow: "direct"` to skip selection and
+render the single payment view for the asset and network chosen at session creation.
+
+## How it works
+
+1. Your backend creates a collection session and gets a `cs_*` token ([`@pulsebyshiga/node`](https://www.npmjs.com/package/@pulsebyshiga/node)).
+2. You hand that token to the browser and call `PulseCollect.mount(target, { sessionToken })`.
+3. The loader renders a sandboxed, Pulse-hosted iframe inside `target` and connects a typed `postMessage` bridge.
+4. The user pays inside the iframe; you receive `onReady`, `onStatusChange`, `onSuccess`, and `onError` events.
+5. You credit the user from the signed `disbursement.completed` **webhook** — never from a client-side callback, which can be spoofed.
 
 ## API
 
 ### `PulseCollect.mount(target, options) → EmbedHandle`
 
 Creates the iframe inside `target` and wires the message bridge. Returns
-`{ iframe, unmount() }`. Throws if `sessionToken` is missing or not a `cs_*` token.
+`{ iframe, unmount() }`. Throws if `sessionToken` is missing or is not a `cs_*` token.
 
 ### Options
 
@@ -84,13 +94,13 @@ Creates the iframe inside `target` and wires the message bridge. Returns
 | `onQuoteRefreshed` | `(lockedUntil)`     | A new quote window was locked.                                                                     |
 | `onError`          | `(code, message)`   | Load, session, or action failures (e.g. `embed_load_timeout`, `session_load_failed`).              |
 
-Status values: `loading`, `awaiting_payment`, `deposit_detected`, `deposit_confirmed`,
+**Status values:** `loading`, `awaiting_payment`, `deposit_detected`, `deposit_confirmed`,
 `converting`, `completed`, `underpaid`, `overpaid`, `wrong_chain`, `expired`, `failed`.
 
 ## Theming
 
-All tokens are optional; unset tokens fall back to your dashboard configuration, then to
-the design defaults.
+Every token is optional; unset tokens fall back to your dashboard configuration, then to the
+design defaults.
 
 | Token                          | Applies to                                                                           |
 | ------------------------------ | ------------------------------------------------------------------------------------ |
@@ -116,33 +126,36 @@ Override any user-facing string via `strings`: `title`, `subtitle`, `heroLabel`,
 
 ## Server-driven configuration
 
-Networks, assets, theme, copy, attribution, and default flow can also be set once in the
-Pulse dashboard (`partner_config`); the embed applies them with no code change. Precedence
-is _defaults ← dashboard ← mount options_, except the network/asset lists, which only ever
-narrow: a mount cannot re-enable what the dashboard disabled, and the server rejects
-disabled values at session creation and re-selection.
+Networks, assets, theme, copy, attribution, and the default flow can also be set once in the
+Pulse dashboard (`partner_config`); the embed applies them with no code change. Precedence is
+_defaults ← dashboard ← mount options_ — except the network and asset lists, which only ever
+narrow: a mount cannot re-enable what the dashboard disabled, and the server rejects disabled
+values at session creation and re-selection.
 
 ## Security model
 
-- The session token travels in the URL **fragment** — it is never sent to any server in a
-  request line or stored in logs.
-- Messages are accepted only from the embed's origin and window; everything else is ignored.
+- The session token travels in the URL **fragment** — it is never sent to a server in a request line, and never stored in logs.
+- Messages are accepted only from the embed's own origin and window; everything else is ignored.
 - The iframe runs with a least-privilege `sandbox` (no top navigation, no downloads).
-- Keep your `sk_*` key and any user PII on your backend; this package needs neither.
+- Your `sk_*` key and any user PII stay on your backend — this package needs neither.
 
 ## Advanced
 
-- **`buildEmbedSrc(options)`** — returns the embed URL + origin without mounting; used by
-  the React Native wrapper and useful for Tier B (full-page, `layout=page`) links.
-- **`formatFiat(amount, currency)` / `formatAsset(amount)`** — the embed's own formatters,
-  exported so surrounding partner UI renders amounts identically.
+- **`buildEmbedSrc(options)`** — returns the embed URL and origin without mounting; used by the React Native wrapper, and handy for Tier B (full-page, `layout=page`) links.
+- **`formatFiat(amount, currency)` / `formatAsset(amount)`** — the embed's own formatters, exported so surrounding partner UI renders amounts identically.
+
+## TypeScript
+
+Written in TypeScript and ships its own type definitions — `MountOptions`, `EmbedHandle`,
+`EmbedTheme`, `EmbedStrings`, and the status/event unions are all exported. No `@types`
+package needed.
 
 ## Related packages
 
-React bindings: [`@pulsebyshiga/collect-react`](../collect-react) ·
-React Native: [`@pulsebyshiga/collect-react-native`](../collect-react-native) ·
-Backend: [`@pulsebyshiga/node`](../node-sdk)
+- [`@pulsebyshiga/collect-react`](https://www.npmjs.com/package/@pulsebyshiga/collect-react) — React bindings.
+- [`@pulsebyshiga/collect-react-native`](https://www.npmjs.com/package/@pulsebyshiga/collect-react-native) — React Native bindings.
+- [`@pulsebyshiga/node`](https://www.npmjs.com/package/@pulsebyshiga/node) — backend SDK: sessions, orders, and webhook verification.
 
 ## License
 
-[MIT](../../LICENSE) © Shiga Digital
+MIT © Shiga Digital

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pulsebyshiga/collect-js",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Tier A embed loader — mounts Pulse Collect payment components into a partner page via a sandboxed iframe and a typed postMessage bridge",
   "license": "MIT",
   "author": "Shiga Digital",