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

package/src/client.ts

@@ -0,0 +1,428 @@
+import { RTP_ERROR, RTP_EVENT, RTP_STATUS } from './constants';
+import type { RtpError, RtpStatus } from './constants';
+import { createEmitter, defaultNow, noopLogger } from './emitter';
+import {
+  findValidationErrors,
+  isExpired,
+  isRtpPayload,
+  mergeRequest,
+  toRequestPatch,
+  toRtpRequest,
+} from './validate';
+import type {
+  RtpClient,
+  RtpClientOptions,
+  RtpCredential,
+  RtpPayload,
+  RtpReceiveOutcome,
+  RtpRequest,
+  RtpResult,
+} from './types';
+
+interface Entry {
+  request: RtpRequest;
+  status: RtpStatus;
+}
+
+/** Statuses after which a request is finished with. */
+const TERMINAL_STATUSES: ReadonlySet<RtpStatus> = new Set([
+  RTP_STATUS.ACCEPTED,
+  RTP_STATUS.DECLINED,
+  RTP_STATUS.EXPIRED,
+  RTP_STATUS.FAILED,
+]);
+
+/**
+ * Map a backend status string onto the normalized SDK status.
+ *
+ * Unknown values are deliberately **not** treated as success — they map to
+ * `undefined` so the caller can decide, rather than silently reporting an
+ * approved payment for a status the client does not understand.
+ */
+export function normalizeBackendStatus(raw: unknown): RtpStatus | undefined {
+  if (typeof raw !== 'string') {
+    return undefined;
+  }
+  switch (raw.toUpperCase()) {
+    case 'ACCEPTED':
+    case 'APPROVED':
+    case 'SUCCESS':
+    case 'SUCCESSFUL':
+      return RTP_STATUS.ACCEPTED;
+    case 'DECLINED':
+    case 'USER_DECLINED':
+      return RTP_STATUS.DECLINED;
+    case 'EXPIRED':
+      return RTP_STATUS.EXPIRED;
+    case 'PENDING':
+    case 'PROCESSING':
+      return RTP_STATUS.PENDING;
+    case 'FAILED':
+    case 'REJECTED':
+      return RTP_STATUS.FAILED;
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Create a portable Request-to-Pay client.
+ *
+ * The client owns validation, de-duplication, expiry, status computation and
+ * the accept/decline/retrieve calls. It owns no UI, no navigation and no
+ * crypto. Every external effect is injected so the same contract can be
+ * re-implemented on other platforms.
+ */
+export function createRtpClient(options: RtpClientOptions): RtpClient {
+  const {
+    transport,
+    getAuthHeaders = async () => ({}),
+    getCurrentUser = () => null,
+    now = defaultNow,
+    logger = noopLogger,
+    basePath = '/rtp',
+  } = options;
+
+  if (!transport) {
+    throw new Error('[react-native-rtp] `transport` is required');
+  }
+
+  const emitter = createEmitter();
+  const entries = new Map<string, Entry>();
+
+  // --- expiry scheduling --------------------------------------------------
+  // Expiry is not only evaluated lazily: an inactive timer fires at `expiresAt`
+  // so a request cannot remain actionable after it has lapsed (INDV-3807/3808).
+  let expiryTimer: ReturnType<typeof setTimeout> | undefined;
+  let expiryTimerId: string | undefined;
+
+  function clearExpiryTimer(): void {
+    if (expiryTimer !== undefined) {
+      clearTimeout(expiryTimer);
+    }
+    expiryTimer = undefined;
+    expiryTimerId = undefined;
+  }
+
+  function scheduleExpiry(entry: Entry): void {
+    clearExpiryTimer();
+
+    const expiry = new Date(entry.request.expiresAt).getTime();
+    if (Number.isNaN(expiry)) {
+      return;
+    }
+
+    const id = entry.request.id;
+    expiryTimerId = id;
+    expiryTimer = setTimeout(
+      () => {
+        const current = entries.get(id);
+        if (!current || TERMINAL_STATUSES.has(current.status)) {
+          return;
+        }
+        logger('[react-native-rtp] request expired:', id);
+        emitResult({ id, status: RTP_STATUS.EXPIRED });
+      },
+      Math.max(0, expiry - now())
+    );
+
+    // Never keep a Node process (e.g. Jest) alive for a pending expiry.
+    const handle = expiryTimer as unknown as { unref?: () => void };
+    if (typeof handle?.unref === 'function') {
+      handle.unref();
+    }
+  }
+
+  function setStatus(id: string, status: RtpStatus): void {
+    const entry = entries.get(id);
+    if (entry) {
+      entry.status = status;
+    }
+    if (TERMINAL_STATUSES.has(status) && expiryTimerId === id) {
+      clearExpiryTimer();
+    }
+    emitter.emit(RTP_EVENT.STATE, { id, status });
+  }
+
+  function emitResult(result: RtpResult): RtpResult {
+    setStatus(result.id, result.status);
+    emitter.emit(RTP_EVENT.RESULT, result);
+    return result;
+  }
+
+  function fail(id: string, error: RtpError | string): RtpResult {
+    return emitResult({ id, status: RTP_STATUS.FAILED, error });
+  }
+
+  async function receive(payload: unknown): Promise<RtpReceiveOutcome> {
+    if (!isRtpPayload(payload)) {
+      return { handled: false };
+    }
+
+    const id = payload.rtpId;
+
+    // Idempotency: the same request can arrive twice (foreground + background,
+    // or a double tap). Never re-emit for an id we have already seen.
+    const existing = entries.get(id);
+    if (existing) {
+      return {
+        handled: true,
+        request: existing.request,
+        status: existing.status,
+      };
+    }
+
+    const errors = findValidationErrors(payload);
+    if (errors.length > 0) {
+      logger('[react-native-rtp] invalid payload, missing:', errors.join(', '));
+      return { handled: true, error: RTP_ERROR.INVALID_PAYLOAD };
+    }
+
+    const request = toRtpRequest(payload);
+    const entry: Entry = { request, status: RTP_STATUS.RECEIVED };
+    entries.set(id, entry);
+
+    if (isExpired(request, now())) {
+      const result = emitResult({ id, status: RTP_STATUS.EXPIRED });
+      return { handled: true, request, status: result.status };
+    }
+
+    const currentUser = getCurrentUser();
+
+    if (!currentUser) {
+      setStatus(id, RTP_STATUS.AWAITING_AUTH);
+      scheduleExpiry(entry);
+      return { handled: true, request, status: RTP_STATUS.AWAITING_AUTH };
+    }
+
+    if (request.recipient && currentUser !== request.recipient) {
+      const result = fail(id, RTP_ERROR.RECIPIENT_MISMATCH);
+      return {
+        handled: true,
+        request,
+        status: result.status,
+        error: result.error,
+      };
+    }
+
+    setStatus(id, RTP_STATUS.READY);
+    scheduleExpiry(entry);
+    emitter.emit(RTP_EVENT.REQUEST, request);
+    return { handled: true, request, status: RTP_STATUS.READY };
+  }
+
+  /**
+   * Fetch (or refresh) authorization details for a request from the backend,
+   * and reconcile the backend status. This is the "retrieve details" step the
+   * authorization page needs before it can be trusted (INDV-3804).
+   */
+  async function retrieve(id: string): Promise<RtpResult> {
+    const entry = entries.get(id);
+    if (!entry) {
+      return fail(id, RTP_ERROR.UNKNOWN);
+    }
+
+    if (isExpired(entry.request, now())) {
+      return emitResult({ id, status: RTP_STATUS.EXPIRED });
+    }
+
+    if (TERMINAL_STATUSES.has(entry.status)) {
+      return { id, status: entry.status };
+    }
+
+    setStatus(id, RTP_STATUS.RETRIEVING);
+
+    try {
+      const headers = await getAuthHeaders();
+      const res = await transport.get(`${basePath}/${id}`, headers);
+      const data = (res?.data ?? {}) as Record<string, unknown>;
+
+      const mapped = normalizeBackendStatus(data.status);
+
+      if (
+        mapped === RTP_STATUS.EXPIRED ||
+        mapped === RTP_STATUS.DECLINED ||
+        mapped === RTP_STATUS.FAILED
+      ) {
+        return emitResult({
+          id,
+          status: mapped,
+          data,
+          error:
+            mapped === RTP_STATUS.FAILED
+              ? RTP_ERROR.BACKEND_REJECTED
+              : undefined,
+        });
+      }
+
+      if (mapped === RTP_STATUS.ACCEPTED) {
+        return emitResult({ id, status: RTP_STATUS.ACCEPTED, data });
+      }
+
+      if (mapped === RTP_STATUS.PENDING) {
+        return emitResult({ id, status: RTP_STATUS.PENDING, data });
+      }
+
+      // Merge any returned details (a full payload, or nested under `request`).
+      const incoming = (data.request ?? data) as
+        Partial<RtpPayload> | undefined;
+      if (incoming && typeof incoming === 'object') {
+        entry.request = mergeRequest(entry.request, toRequestPatch(incoming));
+      }
+
+      if (isExpired(entry.request, now())) {
+        return emitResult({ id, status: RTP_STATUS.EXPIRED });
+      }
+
+      setStatus(id, RTP_STATUS.READY);
+      scheduleExpiry(entry);
+      emitter.emit(RTP_EVENT.REQUEST, entry.request);
+      return { id, status: RTP_STATUS.READY, data };
+    } catch (err) {
+      logger('[react-native-rtp] retrieve failed:', err);
+      return fail(id, RTP_ERROR.RETRIEVE_FAILED);
+    }
+  }
+
+  /**
+   * Called by the host after a successful login to release any requests that
+   * were waiting on the auth gate.
+   */
+  function resumeAuth(): void {
+    for (const [id, entry] of entries) {
+      if (entry.status !== RTP_STATUS.AWAITING_AUTH) {
+        continue;
+      }
+
+      if (isExpired(entry.request, now())) {
+        const result = emitResult({ id, status: RTP_STATUS.EXPIRED });
+        logger(
+          '[react-native-rtp] request expired while awaiting auth:',
+          id,
+          result.status
+        );
+        continue;
+      }
+
+      const currentUser = getCurrentUser();
+      if (
+        entry.request.recipient &&
+        currentUser &&
+        currentUser !== entry.request.recipient
+      ) {
+        fail(id, RTP_ERROR.RECIPIENT_MISMATCH);
+        continue;
+      }
+
+      setStatus(id, RTP_STATUS.READY);
+      scheduleExpiry(entry);
+      emitter.emit(RTP_EVENT.REQUEST, entry.request);
+    }
+  }
+
+  async function accept(params: {
+    id: string;
+    credential?: RtpCredential;
+  }): Promise<RtpResult> {
+    const { id, credential } = params;
+    const entry = entries.get(id);
+    if (!entry) {
+      return fail(id, RTP_ERROR.UNKNOWN);
+    }
+
+    if (isExpired(entry.request, now())) {
+      return emitResult({ id, status: RTP_STATUS.EXPIRED });
+    }
+
+    setStatus(id, RTP_STATUS.PROCESSING);
+
+    try {
+      const headers = await getAuthHeaders();
+      const res = await transport.post(
+        `${basePath}/${id}/accept`,
+        { credential },
+        headers
+      );
+      const data = (res?.data ?? {}) as Record<string, unknown>;
+
+      // If the backend returned a status we recognise, honour it. If it
+      // returned no status at all, the accept call itself succeeded. If it
+      // returned a status we do NOT understand, fail closed rather than
+      // showing the customer an approved payment we cannot vouch for.
+      const hasStatus = data.status !== undefined && data.status !== null;
+      const mapped = normalizeBackendStatus(data.status);
+      const status: RtpStatus = hasStatus
+        ? (mapped ?? RTP_STATUS.FAILED)
+        : RTP_STATUS.ACCEPTED;
+
+      return emitResult({
+        id,
+        status,
+        data,
+        error:
+          status === RTP_STATUS.FAILED ? RTP_ERROR.BACKEND_REJECTED : undefined,
+      });
+    } catch (err) {
+      logger('[react-native-rtp] accept failed:', err);
+      return fail(id, RTP_ERROR.NETWORK_ERROR);
+    }
+  }
+
+  async function decline(params: {
+    id: string;
+    reason?: string;
+  }): Promise<RtpResult> {
+    const { id, reason } = params;
+    const entry = entries.get(id);
+    if (!entry) {
+      return fail(id, RTP_ERROR.UNKNOWN);
+    }
+
+    setStatus(id, RTP_STATUS.PROCESSING);
+
+    try {
+      const headers = await getAuthHeaders();
+      const res = await transport.post(
+        `${basePath}/${id}/decline`,
+        { reason },
+        headers
+      );
+      const data = (res?.data ?? {}) as Record<string, unknown>;
+
+      const mapped = normalizeBackendStatus(data.status);
+      const status: RtpStatus =
+        mapped === RTP_STATUS.EXPIRED || mapped === RTP_STATUS.FAILED
+          ? mapped
+          : RTP_STATUS.DECLINED;
+
+      return emitResult({
+        id,
+        status,
+        data,
+        error:
+          status === RTP_STATUS.FAILED ? RTP_ERROR.BACKEND_REJECTED : undefined,
+      });
+    } catch (err) {
+      logger('[react-native-rtp] decline failed:', err);
+      return fail(id, RTP_ERROR.NETWORK_ERROR);
+    }
+  }
+
+  return {
+    isRtp: isRtpPayload,
+    receive,
+    retrieve,
+    resumeAuth,
+    accept,
+    decline,
+    getStatus: (id: string) => entries.get(id)?.status,
+    getRequest: (id: string) => entries.get(id)?.request,
+    acknowledge: (id: string) => {
+      if (expiryTimerId === id) {
+        clearExpiryTimer();
+      }
+      entries.delete(id);
+    },
+    on: emitter.on,
+  };
+}

package/src/constants.ts

@@ -0,0 +1,54 @@
+/**
+ * Normalized RTP status.
+ *
+ * The SDK is the single source of truth for these values so that every host
+ * platform (React Native, Kotlin, Swift) renders the same UI states.
+ */
+export const RTP_STATUS = {
+  /** Payload arrived and passed validation, but is not yet actionable. */
+  RECEIVED: 'RECEIVED',
+  /** Authorization details are being fetched from the backend. */
+  RETRIEVING: 'RETRIEVING',
+  /** Expired before it could be actioned. */
+  EXPIRED: 'EXPIRED',
+  /** Valid, but the user is not authenticated yet (login gate). */
+  AWAITING_AUTH: 'AWAITING_AUTH',
+  /** Valid, authenticated, and ready for the user to accept/decline. */
+  READY: 'READY',
+  /** Accept/decline in flight. */
+  PROCESSING: 'PROCESSING',
+  /** Backend accepted the action but a final decision is still pending. */
+  PENDING: 'PENDING',
+  /** Backend confirmed acceptance. */
+  ACCEPTED: 'ACCEPTED',
+  /** Backend confirmed (or user initiated) a decline. */
+  DECLINED: 'DECLINED',
+  /** Terminal failure (network, validation, recipient mismatch, etc.). */
+  FAILED: 'FAILED',
+} as const;
+
+export type RtpStatus = (typeof RTP_STATUS)[keyof typeof RTP_STATUS];
+
+/** Events emitted by the client. */
+export const RTP_EVENT = {
+  /** A new, actionable request is available. */
+  REQUEST: 'request',
+  /** Status transition for a request. */
+  STATE: 'state',
+  /** Terminal outcome for a request. */
+  RESULT: 'result',
+} as const;
+
+export type RtpEvent = (typeof RTP_EVENT)[keyof typeof RTP_EVENT];
+
+/** Reasons a request can end in FAILED, exposed for UI/diagnostics. */
+export const RTP_ERROR = {
+  INVALID_PAYLOAD: 'INVALID_PAYLOAD',
+  RECIPIENT_MISMATCH: 'RECIPIENT_MISMATCH',
+  RETRIEVE_FAILED: 'RETRIEVE_FAILED',
+  NETWORK_ERROR: 'NETWORK_ERROR',
+  BACKEND_REJECTED: 'BACKEND_REJECTED',
+  UNKNOWN: 'UNKNOWN',
+} as const;
+
+export type RtpError = (typeof RTP_ERROR)[keyof typeof RTP_ERROR];

package/src/emitter.ts

@@ -0,0 +1,53 @@
+import type { RtpClientOptions, RtpEventMap, RtpUnsubscribe } from './types';
+
+type AnyHandler = (payload: any) => void;
+
+/**
+ * Tiny typed event emitter. Deliberately dependency-free so the same contract
+ * is trivial to re-implement in Kotlin/Swift.
+ */
+export function createEmitter() {
+  const listeners: Record<keyof RtpEventMap, Set<AnyHandler>> = {
+    request: new Set(),
+    state: new Set(),
+    result: new Set(),
+  };
+
+  function on<E extends keyof RtpEventMap>(
+    event: E,
+    handler: RtpEventMap[E]
+  ): RtpUnsubscribe {
+    const set = listeners[event];
+    if (!set) {
+      throw new Error(`[react-native-rtp] Unknown event: ${String(event)}`);
+    }
+    set.add(handler as AnyHandler);
+    return () => {
+      set.delete(handler as AnyHandler);
+    };
+  }
+
+  function emit<E extends keyof RtpEventMap>(
+    event: E,
+    payload: Parameters<RtpEventMap[E]>[0]
+  ): void {
+    // Copy to a snapshot so handlers can unsubscribe during emit.
+    for (const handler of Array.from(listeners[event])) {
+      handler(payload);
+    }
+  }
+
+  function clear(): void {
+    listeners.request.clear();
+    listeners.state.clear();
+    listeners.result.clear();
+  }
+
+  return { on, emit, clear };
+}
+
+/** Default logger used when the host does not provide one. */
+export const noopLogger: NonNullable<RtpClientOptions['logger']> = () => {};
+
+/** Default clock. */
+export const defaultNow = () => Date.now();

package/src/index.tsx

@@ -0,0 +1,45 @@
+// Core (platform-agnostic)
+export { createRtpClient, normalizeBackendStatus } from './client';
+export { RTP_STATUS, RTP_EVENT, RTP_ERROR } from './constants';
+export type { RtpStatus, RtpEvent, RtpError } from './constants';
+export {
+  isRtpPayload,
+  findValidationErrors,
+  toRtpRequest,
+  toRequestPatch,
+  mergeRequest,
+  isExpired,
+} from './validate';
+export { mapPushToRtp } from './push';
+export type { PushEnvelope } from './push';
+
+// Types
+export type {
+  RtpPayload,
+  RtpParty,
+  RtpRequest,
+  RtpCredential,
+  RtpResult,
+  RtpReceiveOutcome,
+  RtpTransport,
+  RtpStorage,
+  RtpHttpResponse,
+  RtpClient,
+  RtpClientOptions,
+  RtpEventMap,
+  RtpUnsubscribe,
+} from './types';
+
+// React adapter
+export { RtpProvider, useRtp, RtpContext } from './react/RtpProvider';
+export type { RtpProviderProps, RtpContextValue } from './react/RtpProvider';
+
+// Mocks (for tests / example app)
+export { createMockTransport } from './mock/mockTransport';
+export type {
+  MockTransport,
+  MockTransportOptions,
+  RecordedCall,
+} from './mock/mockTransport';
+export { makeRtpPayload, makeExpiredPayload } from './mock/makeRtpPayload';
+export type { MakeRtpPayloadOverrides } from './mock/makeRtpPayload';

package/src/mock/makeRtpPayload.ts

@@ -0,0 +1,69 @@
+import type { RtpPayload } from '../types';
+
+/** Number of ms in a minute, for readable fixture offsets. */
+const MINUTE = 60_000;
+
+let counter = 0;
+
+export interface MakeRtpPayloadOverrides extends Partial<
+  Omit<RtpPayload, 'type' | 'payer' | 'payee' | 'expiresAt'>
+> {
+  payer?: Partial<RtpPayload['payer']>;
+  payee?: Partial<RtpPayload['payee']>;
+  /** Milliseconds from `now` until expiry (negative = already expired). */
+  expiresInMs?: number;
+  /** Base time to compute expiry from. Defaults to Date.now(). */
+  from?: number;
+}
+
+/**
+ * Build a valid RTP payload for tests, fixtures and the example app.
+ * Every field is overridable so edge cases are trivial to express.
+ */
+export function makeRtpPayload(
+  overrides: MakeRtpPayloadOverrides = {}
+): RtpPayload {
+  const {
+    payer,
+    payee,
+    expiresInMs = 15 * MINUTE,
+    from = Date.now(),
+    ...rest
+  } = overrides;
+
+  counter += 1;
+
+  return {
+    version: '1.0',
+    type: 'RTP',
+    rtpId: `RTP-${from}-${counter}`,
+    amount: 250000,
+    currency: 'NGN',
+    narration: 'Payment for invoice 1042',
+    transactionRef: `TRX-${from}-${counter}`,
+    orderNumber: `ORD-${from}-${counter}`,
+    deepLink: `quickteller://rtp/${from}-${counter}`,
+    actionMessage: 'Review and approve this payment request',
+    recipient: 'john.doe@quickteller.com',
+    expiresAt: new Date(from + expiresInMs).toISOString(),
+    payer: {
+      name: 'Ajibola Shadrach',
+      accountNumber: '0123456789',
+      bank: 'Quickteller MFB',
+      ...payer,
+    },
+    payee: {
+      name: 'Michael Chinweike',
+      accountNumber: '9876543210',
+      ...payee,
+    },
+    ...rest,
+  };
+}
+
+/** A payload that has already expired. */
+export function makeExpiredPayload(
+  overrides: MakeRtpPayloadOverrides = {}
+): RtpPayload {
+  return makeRtpPayload({ ...overrides, expiresInMs: -MINUTE });
+}