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

package/src/react/RtpProvider.tsx

@@ -0,0 +1,200 @@
+import React, {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import type { RtpClient, RtpCredential, 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;
+  /** Accept the active request with an opaque credential. */
+  accept: (credential?: RtpCredential) => Promise<RtpResult | undefined>;
+  /** Decline the active request. */
+  decline: (reason?: 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) => void;
+  /** 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(
+    (payload: unknown) => {
+      onIncomingPayload?.(payload);
+      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 dismiss = useCallback(() => {
+    setRequest(null);
+    setStatus(null);
+    setLastResult(null);
+    activeIdRef.current = null;
+  }, []);
+
+  const isReady = status === RTP_STATUS.READY;
+
+  const value = useMemo<RtpContextValue>(
+    () => ({
+      request,
+      status,
+      isReady,
+      accept,
+      decline,
+      dismiss,
+      receive,
+      lastResult,
+    }),
+    [request, status, isReady, accept, decline, 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,161 @@
+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;
+  /** 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;
+  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>;
+  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;
+}

package/src/validate.ts

@@ -0,0 +1,93 @@
+import type { RtpParty, RtpPayload, RtpRequest } from './types';
+
+/** Required top-level fields for a valid RTP payload. */
+const REQUIRED_FIELDS = [
+  'rtpId',
+  'amount',
+  'currency',
+  'payer',
+  'payee',
+  'expiresAt',
+] as const;
+
+/**
+ * Type guard for RTP payloads.
+ *
+ * NOTE: this intentionally inspects the *decoded* payload, not a push
+ * envelope. Hosts are responsible for extracting the payload from their own
+ * notification system first.
+ *
+ * `amount` is accepted as either a number (minor units) or a numeric string,
+ * because push payloads frequently stringify scalars in transit.
+ */
+export function isRtpPayload(payload: unknown): payload is RtpPayload {
+  if (!payload || typeof payload !== 'object') {
+    return false;
+  }
+  const candidate = payload as Record<string, unknown>;
+  return candidate.type === 'RTP' && typeof candidate.rtpId === 'string';
+}
+
+/**
+ * Returns the list of missing/invalid required fields. Empty array means the
+ * payload is structurally valid.
+ */
+export function findValidationErrors(payload: RtpPayload): string[] {
+  const errors: string[] = [];
+  const record = payload as unknown as Record<string, unknown>;
+
+  for (const field of REQUIRED_FIELDS) {
+    if (record[field] === undefined || record[field] === null) {
+      errors.push(field);
+    }
+  }
+
+  if (
+    payload.expiresAt !== undefined &&
+    Number.isNaN(new Date(payload.expiresAt).getTime())
+  ) {
+    errors.push('expiresAt');
+  }
+
+  for (const side of ['payer', 'payee'] as const) {
+    const party = payload[side] as RtpParty | undefined;
+    if (!party || typeof party !== 'object' || typeof party.name !== 'string') {
+      errors.push(`${side}.name`);
+    }
+  }
+
+  return errors;
+}
+
+/** Coerce an amount that may arrive as a number or numeric string. */
+function toAmount(value: unknown): number {
+  if (typeof value === 'number') {
+    return value;
+  }
+  const parsed = Number(value);
+  return Number.isNaN(parsed) ? 0 : parsed;
+}
+
+/** Map a validated payload into the normalized request held by the SDK. */
+export function toRtpRequest(payload: RtpPayload): RtpRequest {
+  return {
+    id: payload.rtpId,
+    amount: toAmount(payload.amount),
+    currency: payload.currency,
+    payer: payload.payer,
+    payee: payload.payee,
+    narration: payload.narration,
+    transactionRef: payload.transactionRef,
+    expiresAt: payload.expiresAt,
+    recipient: payload.recipient,
+  };
+}
+
+/** Pure expiry check. Re-evaluated on every transition, not just on receive. */
+export function isExpired(request: RtpRequest, now: number): boolean {
+  const expiry = new Date(request.expiresAt).getTime();
+  if (Number.isNaN(expiry)) {
+    return false;
+  }
+  return expiry <= now;
+}