@zippypay/checkout 1.0.0

package/README.md

@@ -0,0 +1,270 @@
+# @zippypay/checkout
+
+Browser checkout SDK for **Zippy Pay** merchants. Embed payment UI inline on a checkout page or open it in a modal. Works with vanilla JavaScript, React, Vue, Angular, and any stack that runs modern JavaScript.
+
+Styles are scoped inside Shadow DOM — no extra CSS import is required.
+
+---
+
+## Install
+
+```bash
+npm install @zippypay/checkout
+```
+
+```bash
+yarn add @zippypay/checkout
+```
+
+---
+
+## Before the SDK runs
+
+Your **server** creates a payment session and passes credentials to the checkout page:
+
+| Field | Description |
+|---|---|
+| `sessionId` | UUID v4 from `POST /payment-sessions` — safe in URLs |
+| `clientToken` | `zps_…` from the create-session response — **server → browser only** |
+
+Never expose `X-Api-Key` or Clerk JWT from browser code. Never put `clientToken` in QR codes, query strings, logs, or analytics.
+
+---
+
+## Quick start
+
+### JavaScript / TypeScript
+
+```typescript
+import { ZippyPay } from '@zippypay/checkout';
+
+const checkout = ZippyPay.create({
+  environment: 'production',
+  sessionId: '11111111-1111-4111-8111-111111111111',
+  clientToken: 'zps_…',
+  mode: 'inline',
+  container: '#zippy-checkout',
+  theme: { primary: '#2563eb' },
+  onComplete: (session) => console.log('Paid', session),
+});
+```
+
+### Modal
+
+```typescript
+ZippyPay.create({
+  environment: 'production',
+  sessionId,
+  clientToken,
+  mode: 'modal',
+  closeOnBackdropClick: true,
+  closeOnEscape: true,
+  onClose: () => console.log('Modal closed'),
+});
+```
+
+### Web Component
+
+```html
+<script type="module">
+  import '@zippypay/checkout';
+</script>
+
+<zippy-pay-checkout
+  environment="production"
+  session-id="11111111-1111-4111-8111-111111111111"
+  mode="inline"
+  theme-primary="#2563eb"
+></zippy-pay-checkout>
+
+<script type="module">
+  const el = document.querySelector('zippy-pay-checkout');
+  el.clientToken = 'zps_…'; // property, not HTML attribute
+  el.addEventListener('zippy-complete', (e) => console.log(e.detail));
+</script>
+```
+
+### Script tag (UMD)
+
+Serve or bundle is not required — load from a public npm CDN:
+
+```html
+<script src="https://unpkg.com/@zippypay/checkout@1/dist/index.min.js"></script>
+<script>
+  ZippyPay.create({
+    environment: 'production',
+    sessionId: '…',
+    clientToken: 'zps_…',
+    mode: 'inline',
+    container: '#zippy-checkout',
+  });
+</script>
+```
+
+Pin the version in production (`@1.0.0` instead of `@1`).
+
+---
+
+## Environments
+
+Pass `environment` — the SDK resolves the API base URL:
+
+| Environment | API origin |
+|---|---|
+| `production` | `https://api.zippypay.io` |
+| `staging` | `https://staging.api.zippypay.io` |
+| `development` | Same-origin (empty base — for local proxies) |
+
+All requests use the prefix `/api/v1` (e.g. `GET https://api.zippypay.io/api/v1/payment-sessions/:id`).
+
+Use the environment where your merchant backend created the session.
+
+---
+
+## Configuration
+
+```typescript
+type ZippyPayConfig = {
+  environment: 'production' | 'staging' | 'development';
+  sessionId: string;
+  clientToken: string;
+  mode?: 'inline' | 'modal';
+  container?: HTMLElement | string; // required for inline
+  theme?: ZippyTheme;
+  redirectOnComplete?: boolean;
+  redirectOnFailure?: boolean;
+  closeOnBackdropClick?: boolean;
+  closeOnEscape?: boolean;
+  onReady?: (session) => void;
+  onSessionUpdate?: (session) => void;
+  onComplete?: (session) => void;
+  onExpired?: (session) => void;
+  onError?: (error: ZippyPayError) => void;
+  onClose?: () => void;
+};
+```
+
+**Instance methods:** `open()`, `close()` (modal), `destroy()`
+
+### Theming
+
+| Token | CSS variable | Default |
+|---|---|---|
+| `primary` | `--zippy-primary` | `#3f63f3` |
+| `primaryForeground` | `--zippy-primary-foreground` | `#ffffff` |
+| `background` | `--zippy-background` | `#ffffff` |
+| `surface` | `--zippy-surface` | `#f8fafc` |
+| `text` | `--zippy-text` | `#0f172a` |
+| `textMuted` | `--zippy-text-muted` | `#64748b` |
+| `border` | `--zippy-border` | `#e2e8f0` |
+| `borderRadius` | `--zippy-radius` | `20px` |
+| `fontFamily` | `--zippy-font-family` | DM Sans stack |
+| `mode` | — | `light` \| `dark` \| `auto` |
+
+Web component: use `theme-primary`, `theme-mode`, etc.
+
+---
+
+## Checkout flow
+
+1. **Choose method** — QR scan or manual Zippy ID (one-way; cannot switch)
+2. **QR** — `POST …/checkout/start { method: "QR" }` → show QR + pay timer → poll until paid
+3. **Manual** — verify ID → attach payer → pay timer → poll until paid
+
+Display the **amount from the GET session response**, not from your page props.
+
+Three time boundaries: `expiresAt` (idle), `paymentExpiryAt` (pay window), `absoluteExpiresAt` (hard max).
+
+---
+
+## Web component events
+
+| Event | When |
+|---|---|
+| `zippy-ready` | Session loaded |
+| `zippy-session-update` | Poll update |
+| `zippy-complete` | Payment succeeded |
+| `zippy-expired` | Session expired |
+| `zippy-error` | Terminal / API error |
+| `zippy-close` | Modal closed |
+
+---
+
+## Framework notes
+
+### React
+
+```tsx
+'use client';
+
+import { useEffect, useRef } from 'react';
+import '@zippypay/checkout';
+
+export function ZippyCheckout({ sessionId, clientToken }: Props) {
+  const ref = useRef<HTMLElement & { clientToken: string }>(null);
+
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    el.clientToken = clientToken;
+    const onComplete = (e: Event) => console.log((e as CustomEvent).detail);
+    el.addEventListener('zippy-complete', onComplete);
+    return () => el.removeEventListener('zippy-complete', onComplete);
+  }, [clientToken]);
+
+  return (
+    <zippy-pay-checkout
+      ref={ref}
+      environment="production"
+      session-id={sessionId}
+      mode="inline"
+    />
+  );
+}
+```
+
+Or imperative: `ZippyPay.create({ container: ref.current, … })` and `destroy()` on unmount.
+
+### Vue 3
+
+Import `@zippypay/checkout`, set `el.clientToken` in `onMounted`, listen for `@zippy-complete`.
+
+### Angular
+
+Import the package, use `CUSTOM_ELEMENTS_SCHEMA`, set `nativeElement.clientToken` in `ngAfterViewInit`.
+
+---
+
+## API authentication (SDK)
+
+| Header | Value |
+|---|---|
+| `X-Payment-Session-Token` | `zps_…` (preferred) |
+| `Authorization` | `Bearer zps_…` (fallback) |
+
+Errors are RFC 7807 `application/problem+json`, surfaced as `ZippyPayError` with `code`, `status`, and `detail`.
+
+On **401**: treat the token as invalid; create a new session — do not retry blindly.
+
+---
+
+## Security checklist
+
+1. Never bundle `X-Api-Key` in browser code.
+2. Keep `clientToken` in memory only.
+3. Encode only `sessionId` in QR / deep links — never the client token.
+4. Display amount from GET session, not merchant page props.
+5. Ensure your Zippy API environment allows your site origin in CORS for browser calls.
+
+---
+
+## Requirements
+
+- Modern browsers with ES2020, `fetch`, Shadow DOM, and Custom Elements
+- Node.js ≥ 18 for local development / bundlers
+
+---
+
+## License
+
+MIT © Imagine Innovation Limited