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

package/src/mock/mockTransport.ts

@@ -0,0 +1,119 @@
+import type { RtpHttpResponse, RtpTransport } from '../types';
+
+export interface MockTransportOptions {
+  /** Simulated network latency in ms. */
+  latencyMs?: number;
+  /** Simulate a network failure on accept. */
+  failAccept?: boolean;
+  /** Simulate a network failure on decline. */
+  failDecline?: boolean;
+  /** Simulate a network failure on retrieve (details fetch). */
+  failRetrieve?: boolean;
+  /** Backend status to return for accept. */
+  acceptStatus?: 'ACCEPTED' | 'DECLINED' | 'FAILED' | 'PENDING' | 'EXPIRED';
+  /** Backend status to return for retrieve. Unknown values fall through to READY. */
+  retrieveStatus?: string;
+  /** Request details to return from retrieve (overlaid onto the held request). */
+  retrieveRequest?: Record<string, unknown>;
+}
+
+export interface RecordedCall {
+  method: 'post' | 'get';
+  path: string;
+  body?: unknown;
+  headers?: Record<string, string>;
+}
+
+export interface MockTransport {
+  transport: RtpTransport;
+  /** Recorded calls, for assertions in tests and the example app. */
+  calls: RecordedCall[];
+  /** Clear recorded calls. */
+  reset: () => void;
+}
+
+const extractId = (path: string): string => {
+  const parts = path.split('/');
+  return parts[parts.length - 2] ?? '';
+};
+
+/**
+ * Deterministic in-memory transport. No real network calls are made.
+ */
+export function createMockTransport(
+  options: MockTransportOptions = {}
+): MockTransport {
+  const {
+    latencyMs = 250,
+    failAccept = false,
+    failDecline = false,
+    failRetrieve = false,
+    acceptStatus = 'ACCEPTED',
+    retrieveStatus = 'READY',
+    retrieveRequest,
+  } = options;
+
+  const calls: RecordedCall[] = [];
+  const delay = () =>
+    new Promise<void>((resolve) => setTimeout(resolve, latencyMs));
+
+  const transport: RtpTransport = {
+    async post<T = any>(
+      path: string,
+      body?: unknown,
+      headers?: Record<string, string>
+    ): Promise<RtpHttpResponse<T>> {
+      calls.push({ method: 'post', path, body, headers });
+      await delay();
+
+      if (path.endsWith('/accept')) {
+        if (failAccept) {
+          throw new Error('Mock network failure on accept');
+        }
+        return {
+          status: 200,
+          data: { id: extractId(path), status: acceptStatus } as T,
+        };
+      }
+
+      if (path.endsWith('/decline')) {
+        if (failDecline) {
+          throw new Error('Mock network failure on decline');
+        }
+        return {
+          status: 200,
+          data: { id: extractId(path), status: 'DECLINED' } as T,
+        };
+      }
+
+      return { status: 200, data: {} as T };
+    },
+
+    async get<T = any>(
+      path: string,
+      headers?: Record<string, string>
+    ): Promise<RtpHttpResponse<T>> {
+      calls.push({ method: 'get', path, headers });
+      await delay();
+      if (failRetrieve) {
+        throw new Error('Mock network failure on retrieve');
+      }
+      return {
+        status: 200,
+        data: {
+          id: extractId(path),
+          status: retrieveStatus,
+          request: retrieveRequest,
+        } as T,
+      };
+    },
+  };
+
+  return {
+    transport,
+    calls,
+    reset: () => {
+      calls.length = 0;
+    },
+  };
+}

package/src/push.ts

@@ -0,0 +1,109 @@
+import { isRtpPayload } from './validate';
+import type { RtpPayload } from './types';
+
+/**
+ * A generic push notification envelope.
+ *
+ * The SDK does not know or care what a push looks like — every host platform
+ * has a different shape, and this is the single seam where that difference is
+ * absorbed. A Kotlin/Swift integration implements the equivalent of
+ * `mapPushToRtp` against the same `RtpPayload` contract.
+ */
+export interface PushEnvelope {
+  id?: string;
+  title?: string;
+  message?: string;
+  foreground?: boolean;
+  /** RTCP `onRemoteNotification` style payload. */
+  data?: Record<string, unknown>;
+  /** RTCP `onNotificationTapped` flattens the body to the top level. */
+  body?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Extract an RTP payload from a push envelope, or return null if the push is
+ * not an RTP request.
+ *
+ * RTCP delivers two distinct shapes for the same notification:
+ *
+ *  1. `onRemoteNotification` (foreground/background):
+ *     `{ data: { app_data: { type: 'RTP', ... } } }`
+ *
+ *  2. `onNotificationTapped`: scalars are stringified and the custom payload
+ *     arrives as a JSON string:
+ *     `{ data: { app_data: '{"type":"RTP",...}' } }`
+ *
+ * Both are normalized here so callers only ever deal with `RtpPayload`.
+ *
+ * `getData` is injectable so hosts that expose push data differently (e.g. a
+ * Map-like object on native) can plug in their accessor without changing the
+ * rest of the SDK.
+ */
+export function mapPushToRtp(
+  envelope: PushEnvelope | null | undefined,
+  getData?: (envelope: PushEnvelope) => Record<string, unknown> | undefined
+): RtpPayload | null {
+  if (!envelope) {
+    return null;
+  }
+
+  const data = (getData ? getData(envelope) : envelope.data) ?? {};
+
+  // Some providers nest the custom payload under `app_data` (RTCP/FCM).
+  const candidate = unwrapAppData(data);
+
+  if (!isRtpPayload(candidate)) {
+    return null;
+  }
+
+  return normalizePayload(candidate);
+}
+
+/**
+ * RTCP/FCM delivers the custom payload as a JSON string under `app_data`.
+ * The tapped shape sits one level deeper, under `data` / `body`.
+ */
+function unwrapAppData(data: Record<string, unknown>): Record<string, unknown> {
+  let source = data;
+
+  // Tapped shape: `{ time, app_id, message, read, push_id, app_data }`
+  // Received shape: `{ app_data, message, app_id, push_id, time, read }`
+  // In both cases `app_data` holds the custom payload.
+  const appData = source.app_data;
+  if (appData === undefined) {
+    return source;
+  }
+
+  let parsed: Record<string, unknown> = {};
+  if (typeof appData === 'string') {
+    try {
+      parsed = JSON.parse(appData) as Record<string, unknown>;
+    } catch {
+      return source;
+    }
+  } else if (appData && typeof appData === 'object') {
+    parsed = appData as Record<string, unknown>;
+  }
+
+  return { ...source, ...parsed };
+}
+
+/**
+ * Push transports stringify scalars. Coerce the fields the SDK cares about so
+ * the decoded payload always has stable types (this is what makes the payload
+ * portable across platforms).
+ */
+function normalizePayload(payload: Record<string, unknown>): RtpPayload {
+  const normalized: Record<string, unknown> = { ...payload };
+
+  // `amount` may arrive as "250000" on tapped notifications.
+  if (typeof normalized.amount === 'string') {
+    const parsed = Number(normalized.amount);
+    if (!Number.isNaN(parsed)) {
+      normalized.amount = parsed;
+    }
+  }
+
+  return normalized as unknown as RtpPayload;
+}

package/src/react/RtpProvider.tsx

@@ -0,0 +1,235 @@
+import React, {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import type {
+  RtpClient,
+  RtpCredential,
+  RtpReceiveOutcome,
+  RtpRequest,
+  RtpResult,
+} from '../types';
+import { RTP_STATUS } from '../constants';
+import type { RtpStatus } from '../constants';
+
+const STORAGE_KEY = 'rtp.pendingPayload';
+
+/**
+ * A minimal persistence port for the provider. The host supplies its own
+ * storage (e.g. react-native-default-preference / AsyncStorage) so the SDK
+ * stays dependency-free. When omitted, persistence is in-memory only.
+ */
+export interface RtpProviderStorage {
+  getItem: (key: string) => Promise<string | null> | string | null;
+  setItem: (key: string, value: string) => Promise<void> | void;
+  removeItem: (key: string) => Promise<void> | void;
+}
+
+export interface RtpProviderProps {
+  /** The client created via `createRtpClient`. */
+  client: RtpClient;
+  /** Whether the user is currently authenticated. Drives the auth gate. */
+  isAuthenticated: boolean;
+  /** Optional persistence used to survive cold starts / logged-out flows. */
+  storage?: RtpProviderStorage;
+  /**
+   * Called with the raw decoded payload before it is fed to the client.
+   * Use this to persist the payload yourself, log it, etc.
+   */
+  onIncomingPayload?: (payload: unknown) => void;
+  children: React.ReactNode;
+}
+
+export interface RtpContextValue {
+  /** The active request, if any. */
+  request: RtpRequest | null;
+  /** The active request's normalized status. */
+  status: RtpStatus | null;
+  /** True when a request is ready for the user to act on. */
+  isReady: boolean;
+  /** True while authorization details are being fetched from the backend. */
+  isLoading: boolean;
+  /** Accept the active request with an opaque credential. */
+  accept: (credential?: RtpCredential) => Promise<RtpResult | undefined>;
+  /** Decline the active request. */
+  decline: (reason?: string) => Promise<RtpResult | undefined>;
+  /** Fetch/refresh authorization details for the active request. */
+  retrieve: (id?: string) => Promise<RtpResult | undefined>;
+  /** Dismiss the active request from the UI. */
+  dismiss: () => void;
+  /** Feed a raw decoded payload into the client (for host push adapters). */
+  receive: (payload: unknown) => Promise<RtpReceiveOutcome | undefined>;
+  /** Last terminal result, for rendering feedback. */
+  lastResult: RtpResult | null;
+}
+
+export const RtpContext = createContext<RtpContextValue | null>(null);
+
+/**
+ * Bridges the framework-agnostic RTP client into React. Owns no UI — hosts
+ * render their own bottom sheet / modal and react to `request` + `status`.
+ */
+export function RtpProvider({
+  client,
+  isAuthenticated,
+  storage,
+  onIncomingPayload,
+  children,
+}: RtpProviderProps) {
+  const [request, setRequest] = useState<RtpRequest | null>(null);
+  const [status, setStatus] = useState<RtpStatus | null>(null);
+  const [lastResult, setLastResult] = useState<RtpResult | null>(null);
+
+  // Keep the latest request id so async resume/drain can target it.
+  const activeIdRef = useRef<string | null>(null);
+
+  const receive = useCallback(
+    async (payload: unknown) => {
+      onIncomingPayload?.(payload);
+      return client.receive(payload);
+    },
+    [client, onIncomingPayload]
+  );
+
+  // Subscribe to client events exactly once per client.
+  useEffect(() => {
+    const offRequest = client.on('request', (req) => {
+      activeIdRef.current = req.id;
+      setRequest(req);
+    });
+
+    const offState = client.on('state', ({ id, status: next }) => {
+      if (activeIdRef.current && id !== activeIdRef.current) {
+        return;
+      }
+      setStatus(next);
+    });
+
+    const offResult = client.on('result', (result) => {
+      setLastResult(result);
+    });
+
+    return () => {
+      offRequest();
+      offState();
+      offResult();
+    };
+  }, [client]);
+
+  // Drain any payload persisted before React mounted (cold start / killed app).
+  useEffect(() => {
+    let cancelled = false;
+    async function drain() {
+      if (!storage) {
+        return;
+      }
+      const raw = await storage.getItem(STORAGE_KEY);
+      if (!raw || cancelled) {
+        return;
+      }
+      await storage.removeItem(STORAGE_KEY);
+      client.receive(JSON.parse(raw));
+    }
+    drain();
+    return () => {
+      cancelled = true;
+    };
+  }, [client, storage]);
+
+  // Auth gate: once authenticated, release any AWAITING_AUTH requests.
+  useEffect(() => {
+    if (isAuthenticated) {
+      client.resumeAuth();
+    }
+  }, [client, isAuthenticated]);
+
+  const accept = useCallback(
+    async (credential?: RtpCredential) => {
+      const id = request?.id ?? activeIdRef.current;
+      if (!id) {
+        return undefined;
+      }
+      return client.accept({ id, credential });
+    },
+    [client, request]
+  );
+
+  const decline = useCallback(
+    async (reason?: string) => {
+      const id = request?.id ?? activeIdRef.current;
+      if (!id) {
+        return undefined;
+      }
+      return client.decline({ id, reason });
+    },
+    [client, request]
+  );
+
+  const retrieve = useCallback(
+    async (id?: string) => {
+      const target = id ?? request?.id ?? activeIdRef.current;
+      if (!target) {
+        return undefined;
+      }
+      return client.retrieve(target);
+    },
+    [client, request]
+  );
+
+  const dismiss = useCallback(() => {
+    setRequest(null);
+    setStatus(null);
+    setLastResult(null);
+    activeIdRef.current = null;
+  }, []);
+
+  const isReady = status === RTP_STATUS.READY;
+  const isLoading = status === RTP_STATUS.RETRIEVING;
+
+  const value = useMemo<RtpContextValue>(
+    () => ({
+      request,
+      status,
+      isReady,
+      isLoading,
+      accept,
+      decline,
+      retrieve,
+      dismiss,
+      receive,
+      lastResult,
+    }),
+    [
+      request,
+      status,
+      isReady,
+      isLoading,
+      accept,
+      decline,
+      retrieve,
+      dismiss,
+      receive,
+      lastResult,
+    ]
+  );
+
+  return <RtpContext.Provider value={value}>{children}</RtpContext.Provider>;
+}
+
+/**
+ * Access the RTP context. Throws when used outside of an `<RtpProvider>`.
+ */
+export function useRtp(): RtpContextValue {
+  const context = useContext(RtpContext);
+  if (!context) {
+    throw new Error(
+      '[react-native-rtp] useRtp must be used within RtpProvider'
+    );
+  }
+  return context;
+}

package/src/types.ts

@@ -0,0 +1,172 @@
+import type { RtpError, RtpStatus } from './constants';
+
+/**
+ * The decoded RTP payload.
+ *
+ * IMPORTANT: this is the *decoded* payload, not a push notification envelope.
+ * Each host platform is responsible for mapping its own push shape (RTCP,
+ * raw FCM, APNs, etc.) into this structure via an adapter. This keeps the SDK
+ * portable across React Native, Kotlin and Swift.
+ */
+export interface RtpPayload {
+  /** Payload schema version. Unknown fields must be ignored, not rejected. */
+  version?: string;
+  /** Discriminator. Only `'RTP'` payloads are handled by this SDK. */
+  type: 'RTP';
+  /** Stable, unique id for the request (idempotency key). */
+  rtpId: string;
+  /** Amount in the currency's minor unit (e.g. kobo). Integer to avoid floats. */
+  amount: number;
+  /** ISO 4217 currency code. e.g. "NGN". */
+  currency: string;
+  /** Party being asked to pay. */
+  payer: RtpParty;
+  /** Party that will receive the money. */
+  payee: RtpParty;
+  /** Human-readable reason for the request. */
+  narration?: string;
+  /** Backend reference for the transaction. */
+  transactionRef?: string;
+  /** Merchant/issuer order number for the request (distinct from transactionRef). */
+  orderNumber?: string;
+  /** Secure transaction / deep-link reference the host can use to open the flow. */
+  deepLink?: string;
+  /** Instruction shown to the customer describing the action required. */
+  actionMessage?: string;
+  /** ISO 8601 timestamp after which the request can no longer be actioned. */
+  expiresAt: string;
+  /** Alias (phone/email) the request is addressed to, for identity matching. */
+  recipient?: string;
+  /** Arbitrary passthrough data. Ignored by the SDK. */
+  [key: string]: unknown;
+}
+
+/** A party on either side of a request (payer or payee). */
+export interface RtpParty {
+  name: string;
+  accountNumber?: string;
+  bank?: string;
+  /** Optional display URL for a logo/avatar. */
+  logoUrl?: string;
+}
+
+/** A normalized, validated request held by the SDK. */
+export interface RtpRequest {
+  id: string;
+  amount: number;
+  currency: string;
+  payer: RtpParty;
+  payee: RtpParty;
+  narration?: string;
+  transactionRef?: string;
+  orderNumber?: string;
+  deepLink?: string;
+  actionMessage?: string;
+  expiresAt: string;
+  recipient?: string;
+}
+
+/**
+ * Credential produced by the host platform to authorise an accept.
+ * The SDK never inspects this — it is opaque and forwarded to the backend.
+ *
+ * For React Native this is typically `{ secureData, pinBlock, authData }`
+ * produced by the app's card/PIN service.
+ */
+export type RtpCredential = Record<string, unknown>;
+
+export interface RtpResult {
+  id: string;
+  status: RtpStatus;
+  error?: RtpError | string;
+  data?: unknown;
+}
+
+/** Outcome of feeding a raw payload into the client. */
+export interface RtpReceiveOutcome {
+  /** False when the payload was not an RTP payload. */
+  handled: boolean;
+  request?: RtpRequest;
+  status?: RtpStatus;
+  error?: RtpError | string;
+}
+
+// --- Injected ports (the portability seams) -------------------------------
+
+export interface RtpHttpResponse<T = any> {
+  data?: T;
+  status?: number;
+}
+
+/**
+ * Minimal HTTP contract. Hosts inject an implementation backed by their own
+ * client (`ky`, `axios`, native, ...). The SDK never imports a network library.
+ */
+export interface RtpTransport {
+  post: <T = any>(
+    path: string,
+    body?: unknown,
+    headers?: Record<string, string>
+  ) => Promise<RtpHttpResponse<T>>;
+  get: <T = any>(
+    path: string,
+    headers?: Record<string, string>
+  ) => Promise<RtpHttpResponse<T>>;
+}
+
+/** Key/value storage for persistence across cold starts and auth gates. */
+export interface RtpStorage {
+  getItem: (key: string) => Promise<string | null> | string | null;
+  setItem: (key: string, value: string) => Promise<void> | void;
+  removeItem: (key: string) => Promise<void> | void;
+}
+
+export interface RtpClientOptions {
+  /** Injected HTTP client. */
+  transport: RtpTransport;
+  /**
+   * Returns auth headers for an outgoing request. Called per request so the
+   * host can refresh tokens / compute MACs.
+   */
+  getAuthHeaders?: () =>
+    Promise<Record<string, string>> | Record<string, string>;
+  /**
+   * Returns the currently authenticated user's alias (phone/email), or null
+   * when logged out. Used for the auth gate and recipient matching.
+   */
+  getCurrentUser?: () => string | null | undefined;
+  /** Injectable clock (ms since epoch) for deterministic expiry tests. */
+  now?: () => number;
+  /** Optional sink for diagnostics. */
+  logger?: (...args: unknown[]) => void;
+  /** Endpoint base path for RTP routes. Defaults to `/rtp`. */
+  basePath?: string;
+}
+
+export type RtpUnsubscribe = () => void;
+
+export interface RtpEventMap {
+  request: (request: RtpRequest) => void;
+  state: (event: { id: string; status: RtpStatus }) => void;
+  result: (result: RtpResult) => void;
+}
+
+export interface RtpClient {
+  isRtp: (payload: unknown) => payload is RtpPayload;
+  receive: (payload: unknown) => Promise<RtpReceiveOutcome>;
+  /** Fetch/refresh authorization details for a request from the backend. */
+  retrieve: (id: string) => Promise<RtpResult>;
+  resumeAuth: () => void;
+  accept: (params: {
+    id: string;
+    credential?: RtpCredential;
+  }) => Promise<RtpResult>;
+  decline: (params: { id: string; reason?: string }) => Promise<RtpResult>;
+  getStatus: (id: string) => RtpStatus | undefined;
+  getRequest: (id: string) => RtpRequest | undefined;
+  acknowledge: (id: string) => void;
+  on: <E extends keyof RtpEventMap>(
+    event: E,
+    handler: RtpEventMap[E]
+  ) => RtpUnsubscribe;
+}