@inno-isw/react-native-rtp 0.0.0-stage → 0.2.0

package/LICENSE

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

@@ -1,3 +1,386 @@
-# Temporary Holding Version
+# @inno-isw/react-native-rtp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Request to Pay (RTP) SDK for React Native.
+
+`@inno-isw/react-native-rtp` owns the **business logic** of a Request to Pay flow — payload
+validation, de-duplication, expiry, recipient matching, normalized status, and
+the accept / decline / status calls. The **host app owns all UI**: it renders the
+bottom sheet, collects the PIN, and decides navigation.
+
+It is pure JS/TS with **zero native code** and **zero runtime dependencies**
+(only `react` / `react-native` peer deps). Every external effect is injected, so
+the same contract can be re-implemented on Kotlin or Swift.
+
+---
+
+## Installation
+
+```sh
+yarn add @inno-isw/react-native-rtp
+# or: npm install @inno-isw/react-native-rtp
+```
+
+Peer dependencies: `react`, `react-native`.
+
+### Publishing (maintainers)
+
+The package is consumed as a normal npm dependency — do **not** link it locally.
+
+```sh
+yarn install
+yarn prepare            # builds lib/ (bob build) via the prepare script
+npm publish             # publishes @inno-isw/react-native-rtp to the npm registry
+```
+
+Consumer (e.g. QTM) then installs it like any other package:
+
+```sh
+yarn add @inno-isw/react-native-rtp
+# or: npm install @inno-isw/react-native-rtp
+```
+
+---
+
+## The portable contract
+
+The SDK never sees a push notification. It sees a **decoded RTP payload**. Each
+platform is responsible for mapping *its* push shape (RTCP, raw FCM, APNs,
+in-house PN) into this structure.
+
+```ts
+interface RtpPayload {
+  version?: string;                 // schema version; unknown values are ignored
+  type: 'RTP';                      // discriminator
+  rtpId: string;                    // stable id — the idempotency key
+  amount: number;                   // minor unit (e.g. kobo); integer, no floats
+  currency: string;                 // ISO 4217, e.g. "NGN"
+  payer: { name: string; accountNumber?: string; bank?: string; logoUrl?: string };
+  payee: { name: string; accountNumber?: string; bank?: string; logoUrl?: string };
+  narration?: string;
+  transactionRef?: string;
+  orderNumber?: string;             // merchant/issuer order no. (≠ transactionRef)
+  deepLink?: string;                // secure transaction / deep-link reference
+  actionMessage?: string;           // instruction shown to the customer
+  expiresAt: string;                // ISO 8601
+  recipient?: string;               // alias the request is addressed to
+  [key: string]: unknown;           // forward-compatible passthrough
+}
+```
+
+> `payer` is the party being asked to pay (your customer); `payee` is the party
+> that receives the money (the merchant).
+
+> Unknown fields are **ignored, not rejected**, so older SDKs keep working when
+> the backend adds fields.
+
+### `isRtp(payload)`
+
+The type guard operates on the **decoded payload**, not the notification
+envelope:
+
+```ts
+payload.type === 'RTP' && typeof payload.rtpId === 'string';
+```
+
+---
+
+## Quick start
+
+### 1. Create the client (injected seams)
+
+```ts
+import { createRtpClient } from '@inno-isw/react-native-rtp';
+import { api } from './api'; // your existing HTTP client / ky / axios instance
+
+export const rtpClient = createRtpClient({
+  // (required) minimal HTTP contract — the SDK never imports a network lib
+  transport: {
+    post: (path, body, headers) => api.post(path, { json: body, headers }),
+    get: (path, headers) => api.get(path, { headers }),
+  },
+
+  // (optional) auth headers, called per request so tokens/MACs stay fresh
+  getAuthHeaders: async () => ({ Authorization: `Bearer ${await getToken()}` }),
+
+  // (optional) drives the auth gate + recipient matching
+  getCurrentUser: () => authStore.user?.email ?? null,
+
+  // (optional) injectable clock for deterministic expiry
+  now: () => Date.now(),
+
+  // (optional) diagnostics sink
+  logger: (...args) => console.log('[rtp]', ...args),
+
+  // (optional) REST base path, default "/rtp"
+  basePath: '/rtp',
+});
+```
+
+### 2. Normalize your push notification → payload
+
+This is the **only** platform-specific input seam. Use the reference helper, or
+write your own:
+
+```ts
+import { mapPushToRtp } from '@inno-isw/react-native-rtp';
+
+// Works with RTCP/FCM shapes, including app_data JSON unwrapping:
+const payload = mapPushToRtp(notification);
+if (payload) {
+  rtpClient.receive(payload);
+}
+```
+
+For a bespoke PN system, pass your own data accessor:
+
+```ts
+const payload = mapPushToRtp(envelope, (e) => e.customKeys);
+```
+
+### 3. Mount the provider and build your UI
+
+```tsx
+import { RtpProvider, useRtp, RTP_STATUS } from '@inno-isw/react-native-rtp';
+import { rtpClient } from './rtpClient';
+
+export default function App() {
+  const isAuthenticated = useAuthStore((s) => Boolean(s.user));
+
+  return (
+    <RtpProvider
+      client={rtpClient}
+      isAuthenticated={isAuthenticated}
+      storage={persistence}          // optional — see "Cold start" below
+    >
+      <Dashboard />
+    </RtpProvider>
+  );
+}
+```
+
+Inside your screen, render your own sheet (e.g. QTM's `QTBottomSheet`):
+
+```tsx
+function Dashboard() {
+  const { request, status, isReady, isLoading, accept, decline, dismiss, lastResult } =
+    useRtp();
+
+  return (
+    <>
+      <YourDashboard />
+
+      <QTBottomSheet isOpen={status !== null} onClose={dismiss}>
+        {isLoading && <ActivityIndicator />}
+
+        {request && (
+          <>
+            <Text>{request.payee.name}</Text>
+            <Text>{request.currency} {request.amount}</Text>
+            <Text>{request.transactionRef}</Text>
+          </>
+        )}
+
+        {isReady && (
+          <>
+            {/* collect PIN yourself, produce an opaque credential, then: */}
+            <Button title="Accept" onPress={() => accept(credential)} />
+            <Button title="Decline" onPress={() => decline('USER_DECLINED')} />
+          </>
+        )}
+
+        {status === RTP_STATUS.ACCEPTED && <Text>Payment accepted</Text>}
+        {status === RTP_STATUS.FAILED && <Text>Something went wrong</Text>}
+        {lastResult?.error && <Text>{lastResult.error}</Text>}
+      </QTBottomSheet>
+    </>
+  );
+}
+```
+
+---
+
+## Status catalog
+
+The SDK computes status; the app only renders it.
+
+| Status | Meaning |
+| --- | --- |
+| `RECEIVED` | Payload arrived and passed validation. |
+| `RETRIEVING` | Details are being fetched from the backend (`retrieve`). |
+| `AWAITING_AUTH` | Valid, but the user is logged out (auth gate). |
+| `READY` | Valid, authenticated, actionable — show Accept / Decline. |
+| `PROCESSING` | Accept/decline in flight. |
+| `PENDING` | Backend accepted the action but a final decision is still pending. |
+| `ACCEPTED` | Backend confirmed acceptance. |
+| `DECLINED` | Backend confirmed (or user initiated) a decline. |
+| `EXPIRED` | Past `expiresAt`; no longer actionable. |
+| `FAILED` | Terminal failure. See `RtpError` for the reason. |
+
+`ACCEPTED`, `DECLINED`, `EXPIRED` and `FAILED` are terminal; `PENDING` is not.
+
+`RtpError` values: `INVALID_PAYLOAD`, `RECIPIENT_MISMATCH`, `RETRIEVE_FAILED`,
+`NETWORK_ERROR`, `BACKEND_REJECTED`, `UNKNOWN`.
+
+---
+
+## Events
+
+Subscribe via `client.on(event, handler)`. Every call returns an unsubscribe
+function.
+
+| Event | Payload | Fires when |
+| --- | --- | --- |
+| `request` | `RtpRequest` | A request becomes actionable (`READY`), or its details were refreshed. |
+| `state` | `{ id, status }` | Any status transition, including the in-place `EXPIRED` below. |
+| `result` | `RtpResult` | A terminal outcome (`ACCEPTED`/`DECLINED`/`EXPIRED`/`FAILED`). |
+
+```ts
+const off = rtpClient.on('result', (r) => {
+  if (r.status === 'ACCEPTED') showToast('Paid');
+});
+// later
+off();
+```
+
+---
+
+## Client API
+
+| Method | Description |
+| --- | --- |
+| `isRtp(payload)` | Type guard for decoded RTP payloads. |
+| `receive(payload)` | Validate, de-dupe, apply the auth gate/expiry, and emit. Returns an outcome. |
+| `retrieve(id)` | Fetch/refresh authorization details and reconcile the backend status. |
+| `accept({ id, credential })` | Authorize a request. `credential` is **opaque** — the SDK forwards it untouched. |
+| `decline({ id, reason })` | Decline a request. |
+| `getStatus(id)` | Current normalized status. |
+| `getRequest(id)` | The normalized request. |
+| `acknowledge(id)` | Forget a request (after you dismiss the UI). |
+| `resumeAuth()` | Release requests waiting on the auth gate. Usually called for you by the provider. |
+| `on(event, cb)` | Subscribe; returns an unsubscribe fn. |
+
+### The opaque credential
+
+`accept()` takes a `credential` that the SDK **never inspects** — no PIN, no
+crypto, no card-service output crosses the boundary as structured data:
+
+```ts
+const credential = await cardService.generateSecureData(pin); // stays in the app
+await accept(credential);
+```
+
+This is what makes the portability promise hold: a Kotlin or Swift host produces
+its own credential type and posts it opaquely.
+
+---
+
+## Edge cases handled for you
+
+- **Duplicate delivery** — the same `rtpId` arriving via foreground *and*
+  background (or a double tap) emits `request` exactly once.
+- **Expiry fires on its own** — a timer is armed at `expiresAt`, so a request
+  that lapses while the sheet is open transitions to `EXPIRED` in place (a
+  `state` + `result` event) instead of waiting for the next user action.
+- **Expiry re-checked on every transition** — `accept`/`decline`/`retrieve`
+  refuse an already-lapsed request and report `EXPIRED`.
+- **Backend status is never assumed** — an unrecognised status from
+  `accept`/`retrieve` fails closed (`FAILED` / `BACKEND_REJECTED`) rather than
+  being reported as an approved payment.
+- **Retrieve failure is contained** — a failed `retrieve` emits `FAILED` with
+  `RETRIEVE_FAILED`; the request is not silently dropped.
+- **Recipient mismatch** — if `payload.recipient` doesn't match `getCurrentUser()`,
+  the request fails with `RECIPIENT_MISMATCH` instead of being shown.
+- **Logged-out → login resume** — a request received while logged out sits in
+  `AWAITING_AUTH`; when `isAuthenticated` flips true the provider calls
+  `resumeAuth()` and emits `request`.
+
+### Cold start (killed app)
+
+Register your PN handler early (before React mounts) and persist the payload:
+
+```ts
+// index.js — before App renders
+rtcp.onNotificationTapped(async (notification) => {
+  const payload = mapPushToRtp(notification);
+  if (payload) await persistence.setItem('rtp.pendingPayload', JSON.stringify(payload));
+});
+```
+
+`RtpProvider` drains that key on mount. The storage key is
+`rtp.pendingPayload` (exported as `STORAGE_KEY` in the example).
+
+```ts
+export const persistence = {
+  getItem: (k) => AsyncStorage.getItem(k),
+  setItem: (k, v) => AsyncStorage.setItem(k, v),
+  removeItem: (k) => AsyncStorage.removeItem(k),
+};
+```
+
+---
+
+## Security notes
+
+- **Never trust the push body for money movement.** It carries an opaque
+  `rtpId`/token; `accept` is verified server-side.
+- **Recipient matching is enforced by the SDK** via `getCurrentUser()`, which
+  matters most in the logged-out flow where you have no session to lean on.
+- **Idempotency is keyed by `rtpId`**, so replays can't double-action a request.
+
+---
+
+## Cross-platform conformance
+
+This package is one of several implementations of the same spec. To keep them
+honest, `fixtures/conformance.json` holds platform-neutral test vectors with a
+**fixed clock**: valid, logged-out, expired, malformed, wrong-recipient,
+non-RTP, duplicate, and unknown-field cases.
+
+Every implementation (React Native, Kotlin, Swift) must produce the same
+outcome for each case. The vectors are the contract; the code is just one
+realization of it.
+
+> If you ever add signed payloads (HMAC), lock the canonical byte string
+> (field order, encoding, key/digest encoding, MAC placement) in these vectors
+> first — otherwise signatures silently diverge between platforms.
+
+---
+
+## Example app
+
+A runnable host app lives in [`example/`](./example). It ships a mock transport
+and a control panel to simulate incoming PNs and every edge case:
+
+```sh
+yarn example start        # then press i / a / w
+yarn example web          # or run it in a browser
+```
+
+Buttons: deliver valid / expired / duplicate requests, simulate a cold start
+(persist + remount provider), toggle authentication, and force accept failures.
+The event log shows the `request` / `state` / `result` stream live.
+
+---
+
+## Development
+
+```sh
+yarn typecheck
+yarn lint
+yarn test
+yarn prepare     # build lib/
+```
+
+## Contributing
+
+- [Development workflow](CONTRIBUTING.md#development-workflow)
+- [Sending a pull request](CONTRIBUTING.md#sending-a-pull-request)
+- [Code of conduct](./CODE_OF_CONDUCT.md)
+
+## License
+
+MIT
+
+---
+
+Made with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)