@snapkyc-ooru/consent-handoff-react 0.1.0

package/README.md

@@ -0,0 +1,158 @@
+# @snapkyc/consent-handoff-react
+
+React + TypeScript SDK for the **integrations agreement → transaction initiate → QR _or_ intent → status polling** flow. `API_ORIGIN` is fixed in [`src/config.ts`](src/config.ts) (currently `http://127.0.0.1:8000`). Relying parties pass a single **`integrationToken`** (`Authorization: Token …`). See [`docs/HTTP_CONTRACT.md`](docs/HTTP_CONTRACT.md) for route assumptions.
+
+## Install
+
+```bash
+npm install @snapkyc/consent-handoff-react react react-dom
+```
+
+## Styles
+
+```tsx
+import "@snapkyc/consent-handoff-react/styles.css";
+```
+
+Design tokens are scoped to the SDK root (`.snap-consent-handoff`). If you previously overrode appearance by targeting **`:root`**, switch to the **`theme` prop** (see below) or to selectors under `.snap-consent-handoff` so you do not affect the host application.
+
+## Theme (optional)
+
+Pass **`theme`** with any subset of fields; the rest use the built-in warm default palette (orange primary, cream accents, light canvas). Changing **`primary`** alone updates accents and the default active border color unless you set **`borderActive`** explicitly.
+
+| Field | Role |
+|-------|------|
+| `primary` | Brand color — primary buttons, checkboxes, selected borders |
+| `onPrimary` | Text on primary buttons |
+| `canvas` | Sheet / panel background |
+| `surface` | Default “card” surfaces (e.g. unselected purpose rows) |
+| `surfaceMuted` | Agreement notice and selected purpose row background |
+| `text` / `textMuted` | Body and secondary text |
+| `border` / `borderActive` | Default and emphasized borders |
+| `modalOverlay` | Scrim behind the modal |
+| `danger` | Error text |
+| `success` | Success verification icon and status checkmarks |
+| `successStatusSurface` | Success screen status summary card background |
+| `successPurposesSurface` | Success screen “Confirmed purposes” panel background |
+| `successAccordionBorder` | Demographic accordion borders |
+| `radius` | Corner radius string (e.g. `"12px"`) |
+| `fontFamily` | UI font stack |
+| `gap`, `maxWidth`, `modalZ` | Layout tokens |
+
+```tsx
+import {
+  SnapConsentHandoffFlow,
+  DEFAULT_SNAP_CONSENT_THEME,
+  type SnapConsentHandoffTheme,
+} from "@snapkyc/consent-handoff-react";
+
+const brand: Partial<SnapConsentHandoffTheme> = {
+  primary: "#0f766e",
+  borderActive: "#0f766e",
+  surfaceMuted: "#f0fdfa",
+};
+
+<SnapConsentHandoffFlow {...props} theme={brand} />;
+```
+
+`DEFAULT_SNAP_CONSENT_THEME` and `resolveSnapConsentTheme` are exported if you need to merge or inspect defaults in app code.
+
+## Imperative opener (recommended for modals)
+
+```tsx
+import { openSnapConsentHandoffFlow } from "@snapkyc/consent-handoff-react";
+import "@snapkyc/consent-handoff-react/styles.css";
+
+const { dispose } = openSnapConsentHandoffFlow({
+  integrationToken,
+  rpContext: { reference_id: user.id, session_id },
+  /** Select exactly one post-initiation path — never both */
+  handoffMode: "qr", // or "intent"
+  /** Optional tweaks */
+  pollIntervalMs: 1500,
+  pollDeadlineMs: 120_000,
+  onFlowEvent(e) {},
+  onSuccess(result) {},
+  onError(err) {},
+});
+
+// On route change / unmount caller context
+dispose();
+```
+
+`openSnapConsentQrFlow` is a **deprecated alias** of the same function.
+
+### Intent platform detection
+
+With `handoffMode: "intent"`, the SDK infers **`android`** vs **`ios`** from the browser UA. If ambiguous (typical desktop browser), users pick **Continue with Android** or **Continue with iPhone/iPad**. For automated tests only, set `_dangerouslyForceIntentPlatform`.
+
+## Declarative
+
+On the consent step, the primary action is labelled **I Agree** (with **Cancel** beside it to dismiss). After a successful verification, **Done** dismisses the flow the same way as the modal close control.
+
+```tsx
+import { SnapConsentHandoffFlow } from "@snapkyc/consent-handoff-react";
+import "@snapkyc/consent-handoff-react/styles.css";
+
+<SnapConsentHandoffFlow
+  integrationToken={token}
+  rpContext={{ reference_id, session_id }}
+  handoffMode="intent"
+  displayMode="inline"
+/>;
+```
+
+## Props (summary)
+
+| Prop | Purpose |
+|------|---------|
+| `integrationToken` | Sent as `Authorization: Token …` on every request |
+| `rpContext.reference_id` | Sent as `rp_context.ref_id` on `POST …/transactions/initiate` |
+| `handoffMode` | `"qr"` → `POST …/generate-qr` (PNG). `"intent"` → `POST …/generate-intent?platform=` |
+| `agreementId?` | Reserved; agreement is implied by the integration token |
+| `acceptLanguage?` | `Accept-Language` + preference for `agreement_text` locale |
+| `qrRequestBody?` | QR overrides (`size`; `txn_id` is set by the SDK) |
+| `pollIntervalMs` / `pollDeadlineMs` | Polling behaviour after handoff |
+| `theme?` | Partial palette / layout overrides (see **Theme**) |
+| `onRequestClose?` | Called when the user closes the modal (**×**), taps **Cancel** on the consent step, or taps **Done** after success. With `openSnapConsentHandoffFlow`, this is wired to `dispose()`. If omitted (e.g. inline embed), the SDK hides its own UI after those actions. |
+
+## Credential hygiene
+
+`integrationToken` is a bearer credential in the browser. Prefer short-lived minted tokens from your backend rather than embedding long-lived secrets in static bundles.
+
+## Publishing / environments
+
+Bump `API_ORIGIN` when cutting staging/production builds (fork your publish pipeline per environment or maintain separate semver lines).
+
+### npm: `E404` — “Scope not found” (`@snapkyc/...`)
+
+Scoped packages like **`@snapkyc/consent-handoff-react`** can only be published if the **scope exists on npm** and **your logged-in user is allowed to publish** to it.
+
+**Option A — use the `snapkyc` org (intended for SnapKYC)**
+
+1. An org owner creates **[`snapkyc` on npm](https://www.npmjs.com/org/create)** (if it does not exist yet).
+2. They invite your npm user with a role that can **publish** (e.g. member with publish, or owner).
+3. You accept the invite, then run `npm login` and `npm publish --access public` again.
+
+**Option B — publish under your own scope**
+
+1. Change the `"name"` field in `package.json` to a scope you control, e.g. `"@<your-npm-username>/consent-handoff-react"`.
+2. Bump the version if you already published under another name, then `npm publish --access public`.
+
+**Option C — unscoped package**
+
+Use a unique unscoped name (e.g. `snapkyc-consent-handoff-react`) in `"name"` if you do not use npm orgs. Check name availability on [npmjs.com](https://www.npmjs.com/).
+
+After any rename, update install instructions and all `import` paths for consumers.
+
+## Develop
+
+```bash
+npm install
+npm test
+npm run build
+```
+
+## License
+
+MIT