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

package/src/client.ts

@@ -0,0 +1,239 @@
+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,
+  toRtpRequest,
+} from './validate';
+import type {
+  RtpClient,
+  RtpClientOptions,
+  RtpCredential,
+  RtpReceiveOutcome,
+  RtpRequest,
+  RtpResult,
+} from './types';
+
+interface Entry {
+  request: RtpRequest;
+  status: RtpStatus;
+}
+
+/**
+ * Create a portable Request-to-Pay client.
+ *
+ * The client owns validation, de-duplication, expiry, status computation and
+ * the accept/decline/status 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>();
+
+  function setStatus(id: string, status: RtpStatus): void {
+    const entry = entries.get(id);
+    if (entry) {
+      entry.status = status;
+    }
+    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);
+    entries.set(id, { request, status: RTP_STATUS.RECEIVED });
+
+    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);
+      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);
+    emitter.emit(RTP_EVENT.REQUEST, request);
+    return { handled: true, request, status: RTP_STATUS.READY };
+  }
+
+  /**
+   * 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);
+      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 backendStatus = res?.data?.status;
+      const status: RtpStatus =
+        backendStatus === 'DECLINED'
+          ? RTP_STATUS.DECLINED
+          : backendStatus === 'FAILED'
+            ? RTP_STATUS.FAILED
+            : RTP_STATUS.ACCEPTED;
+
+      return emitResult({
+        id,
+        status,
+        data: res?.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
+      );
+      return emitResult({ id, status: RTP_STATUS.DECLINED, data: res?.data });
+    } catch (err) {
+      logger('[react-native-rtp] decline failed:', err);
+      return fail(id, RTP_ERROR.NETWORK_ERROR);
+    }
+  }
+
+  return {
+    isRtp: isRtpPayload,
+    receive,
+    resumeAuth,
+    accept,
+    decline,
+    getStatus: (id: string) => entries.get(id)?.status,
+    getRequest: (id: string) => entries.get(id)?.request,
+    acknowledge: (id: string) => {
+      entries.delete(id);
+    },
+    on: emitter.on,
+  };
+}

package/src/constants.ts

@@ -0,0 +1,49 @@
+/**
+ * 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',
+  /** 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 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',
+  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,43 @@
+// Core (platform-agnostic)
+export { createRtpClient } from './client';
+export { RTP_STATUS, RTP_EVENT, RTP_ERROR } from './constants';
+export type { RtpStatus, RtpEvent, RtpError } from './constants';
+export {
+  isRtpPayload,
+  findValidationErrors,
+  toRtpRequest,
+  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,66 @@
+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}`,
+    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 });
+}

package/src/mock/mockTransport.ts

@@ -0,0 +1,103 @@
+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;
+  /** Backend status to return for accept. */
+  acceptStatus?: 'ACCEPTED' | 'DECLINED' | 'FAILED';
+}
+
+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,
+    acceptStatus = 'ACCEPTED',
+  } = 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();
+      return {
+        status: 200,
+        data: { id: extractId(path), status: 'PENDING' } 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;
+}