@pulsebyshiga/collect-react-native 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shiga Digital
+
+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

@@ -0,0 +1,69 @@
+# @pulsebyshiga/collect-react-native
+
+React Native bindings for Pulse Collect — renders the same Pulse-hosted embed used on the
+web inside a WebView, with events delivered through the native message bridge.
+
+> **Status: pre-release (0.1.0).** Validate on physical devices before shipping — see
+> [docs/rn-validation.md](../../docs/rn-validation.md) for the Expo recipe.
+
+## Requirements
+
+- React ≥ 18 and `react-native-webview` ≥ 13 (peer dependencies)
+- A session token (`cs_*`) minted by your backend with [`@pulsebyshiga/node`](../node-sdk)
+
+## Installation
+
+```sh
+npm install @pulsebyshiga/collect-react-native react-native-webview
+# then: cd ios && pod install (bare RN) — Expo projects need no extra step
+```
+
+## Usage
+
+```tsx
+import { PulseCollectPayment } from '@pulsebyshiga/collect-react-native';
+
+export function FundScreen({ sessionToken }: { sessionToken: string }) {
+  return (
+    <PulseCollectPayment
+      sessionToken={sessionToken}
+      theme={{ primaryColor: '#083a9a' }}
+      onSuccess={(orderId) => showFunded(orderId)} // UX only — credit off the webhook
+      onError={(code, message) => report(code, message)}
+    />
+  );
+}
+```
+
+## Props
+
+| Prop                  | Type                          | Description                                                                                            |
+| --------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `sessionToken`        | `string` (required)           | Single-order session token from your backend.                                                          |
+| `flow`                | `"select" \| "direct"`        | Selection flow (default) or pinned asset/network.                                                      |
+| `networks` / `assets` | `string[]`                    | Narrow the selectable sets for this mount (narrowing only — see `@pulsebyshiga/collect-js`).           |
+| `theme` / `strings`   | `EmbedTheme` / `EmbedStrings` | Same tokens and placeholders as the web loader.                                                        |
+| `style`               | WebView style                 | When omitted, the WebView height follows the embed content.                                            |
+| `embedUrl` / `apiUrl` | `string`                      | Origin overrides for local development.                                                                |
+| callbacks             | —                             | `onReady`, `onStatusChange`, `onSuccess`, `onQuoteExpired`, `onQuoteRefreshed`, `onError`, `onResize`. |
+
+## Platform notes
+
+- **Configuration travels in the URL.** Theme and copy are applied via URL params at load —
+  there is no message-in channel on React Native, so changing `theme`/`strings` props
+  reloads the WebView (the memoized source changes).
+- **Height** — the embed reports its content height; the wrapper tracks it automatically
+  unless you pass `style`. `onResize(height)` exposes the raw signal.
+- **Events** — all embed events arrive through `onMessage` on the WebView; the wrapper
+  validates and dispatches them to your typed callbacks (`dispatchEmbedMessage` is exported
+  for custom WebView setups).
+
+## Security model
+
+Identical to the web: your `sk_*` key and user PII stay on your backend; the app receives
+only the single-order `cs_*` token, and the payment surface renders inside Pulse-hosted
+content. Credit users exclusively from the signed `disbursement.completed` webhook.
+
+## License
+
+[MIT](../../LICENSE) © Shiga Digital

package/dist/handleMessage.d.ts

@@ -0,0 +1,10 @@
+import { type MountOptions } from '@pulsebyshiga/collect-js';
+export type EmbedCallbacks = Pick<MountOptions, 'onReady' | 'onStatusChange' | 'onSuccess' | 'onQuoteExpired' | 'onQuoteRefreshed' | 'onError'> & {
+    onResize?: (height: number) => void;
+};
+/**
+ * Dispatch a WebView onMessage payload (JSON string posted by the embed via
+ * window.ReactNativeWebView) to the partner's callbacks. Non-JSON and
+ * unrelated messages are ignored.
+ */
+export declare function dispatchEmbedMessage(data: string, callbacks: EmbedCallbacks): void;

package/dist/handleMessage.js

@@ -0,0 +1,40 @@
+import { isEmbedToHostMessage } from '@pulsebyshiga/collect-js';
+/**
+ * Dispatch a WebView onMessage payload (JSON string posted by the embed via
+ * window.ReactNativeWebView) to the partner's callbacks. Non-JSON and
+ * unrelated messages are ignored.
+ */
+export function dispatchEmbedMessage(data, callbacks) {
+    let parsed;
+    try {
+        parsed = JSON.parse(data);
+    }
+    catch {
+        return;
+    }
+    if (!isEmbedToHostMessage(parsed))
+        return;
+    switch (parsed.type) {
+        case 'ready':
+            callbacks.onReady?.();
+            break;
+        case 'resize':
+            callbacks.onResize?.(parsed.height);
+            break;
+        case 'status_change':
+            callbacks.onStatusChange?.(parsed.status, parsed.orderId);
+            break;
+        case 'quote_expired':
+            callbacks.onQuoteExpired?.();
+            break;
+        case 'quote_refreshed':
+            callbacks.onQuoteRefreshed?.(parsed.lockedUntil);
+            break;
+        case 'success':
+            callbacks.onSuccess?.(parsed.orderId);
+            break;
+        case 'error':
+            callbacks.onError?.(parsed.code, parsed.message);
+            break;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+import { type EmbedStrings, type EmbedTheme } from '@pulsebyshiga/collect-js';
+import { type ReactElement } from 'react';
+import { type EmbedCallbacks } from './handleMessage.js';
+export type PulseCollectPaymentProps = EmbedCallbacks & {
+    /** Single-order session token from the partner backend. */
+    sessionToken: string;
+    embedUrl?: string;
+    apiUrl?: string;
+    /** "select" (default): in-embed asset/network selection; "direct": pinned. */
+    flow?: 'select' | 'direct';
+    /** Narrow selectable networks (intersected with the partner config; never widens). */
+    networks?: string[];
+    /** Narrow payable assets (same narrowing rules as `networks`). */
+    assets?: string[];
+    theme?: EmbedTheme;
+    /** Copy overrides travel via URL params on React Native. */
+    strings?: EmbedStrings;
+    /** WebView style. When omitted, height follows the embed content. */
+    style?: unknown;
+};
+/**
+ * Payment component for React Native. Renders the same Pulse-controlled embed
+ * used on the web inside a WebView; theme and copy arrive via URL params, and
+ * embed events arrive through the WebView message bridge.
+ */
+export declare function PulseCollectPayment(props: PulseCollectPaymentProps): ReactElement;
+export { dispatchEmbedMessage, type EmbedCallbacks } from './handleMessage.js';
+export type { EmbedStatus, EmbedStrings, EmbedTheme } from '@pulsebyshiga/collect-js';

package/dist/index.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { buildEmbedSrc } from '@pulsebyshiga/collect-js';
+import { useMemo, useState } from 'react';
+import { WebView } from 'react-native-webview';
+import { dispatchEmbedMessage } from './handleMessage.js';
+/**
+ * Payment component for React Native. Renders the same Pulse-controlled embed
+ * used on the web inside a WebView; theme and copy arrive via URL params, and
+ * embed events arrive through the WebView message bridge.
+ */
+export function PulseCollectPayment(props) {
+    const { sessionToken, embedUrl, apiUrl, flow, networks, assets, theme, strings, style, ...callbacks } = props;
+    const [height, setHeight] = useState(420);
+    const src = useMemo(() => buildEmbedSrc({ sessionToken, embedUrl, apiUrl, flow, networks, assets, theme, strings }).src, [sessionToken, embedUrl, apiUrl, flow, networks, assets, theme, strings]);
+    return (_jsx(WebView, { source: { uri: src }, javaScriptEnabled: true, originWhitelist: ['https://*', 'http://*'], style: style ?? { height }, onMessage: (event) => dispatchEmbedMessage(event.nativeEvent.data, {
+            ...callbacks,
+            onResize: (nextHeight) => {
+                callbacks.onResize?.(nextHeight);
+                setHeight(nextHeight);
+            },
+        }) }));
+}
+export { dispatchEmbedMessage } from './handleMessage.js';

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@pulsebyshiga/collect-react-native",
+  "version": "0.2.0",
+  "description": "React Native bindings for Pulse Collect — <PulseCollectPayment /> rendering the same Pulse-controlled embed in a WebView",
+  "license": "MIT",
+  "author": "Shiga Digital",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Pulse-Digital/pulse-collect.git",
+    "directory": "packages/collect-react-native"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "react": ">=18",
+    "react-native-webview": ">=13"
+  },
+  "dependencies": {
+    "@pulsebyshiga/collect-js": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.12",
+    "react": "^18.3.1",
+    "typescript": "^5.6.3",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}