@inno-isw/react-native-rtp 0.1.0 → 0.2.0

package/src/index.tsx

@@ -1,11 +1,13 @@
 // Core (platform-agnostic)
-export { createRtpClient } from './client';
+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';

package/src/mock/makeRtpPayload.ts

@@ -41,6 +41,9 @@ export function makeRtpPayload(
     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: {

package/src/mock/mockTransport.ts

@@ -7,8 +7,14 @@ export interface MockTransportOptions {
   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';
+  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 {
@@ -41,7 +47,10 @@ export function createMockTransport(
     latencyMs = 250,
     failAccept = false,
     failDecline = false,
+    failRetrieve = false,
     acceptStatus = 'ACCEPTED',
+    retrieveStatus = 'READY',
+    retrieveRequest,
   } = options;
 
   const calls: RecordedCall[] = [];
@@ -86,9 +95,16 @@ export function createMockTransport(
     ): 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: 'PENDING' } as T,
+        data: {
+          id: extractId(path),
+          status: retrieveStatus,
+          request: retrieveRequest,
+        } as T,
       };
     },
   };

package/src/react/RtpProvider.tsx

@@ -7,7 +7,13 @@ import React, {
   useRef,
   useState,
 } from 'react';
-import type { RtpClient, RtpCredential, RtpRequest, RtpResult } from '../types';
+import type {
+  RtpClient,
+  RtpCredential,
+  RtpReceiveOutcome,
+  RtpRequest,
+  RtpResult,
+} from '../types';
 import { RTP_STATUS } from '../constants';
 import type { RtpStatus } from '../constants';
 
@@ -46,14 +52,18 @@ export interface RtpContextValue {
   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) => void;
+  receive: (payload: unknown) => Promise<RtpReceiveOutcome | undefined>;
   /** Last terminal result, for rendering feedback. */
   lastResult: RtpResult | null;
 }
@@ -79,9 +89,9 @@ export function RtpProvider({
   const activeIdRef = useRef<string | null>(null);
 
   const receive = useCallback(
-    (payload: unknown) => {
+    async (payload: unknown) => {
       onIncomingPayload?.(payload);
-      client.receive(payload);
+      return client.receive(payload);
     },
     [client, onIncomingPayload]
   );
@@ -160,6 +170,17 @@ export function RtpProvider({
     [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);
@@ -168,19 +189,33 @@ export function RtpProvider({
   }, []);
 
   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, accept, decline, dismiss, receive, lastResult]
+    [
+      request,
+      status,
+      isReady,
+      isLoading,
+      accept,
+      decline,
+      retrieve,
+      dismiss,
+      receive,
+      lastResult,
+    ]
   );
 
   return <RtpContext.Provider value={value}>{children}</RtpContext.Provider>;

package/src/types.ts

@@ -27,6 +27,12 @@ export interface RtpPayload {
   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. */
@@ -53,6 +59,9 @@ export interface RtpRequest {
   payee: RtpParty;
   narration?: string;
   transactionRef?: string;
+  orderNumber?: string;
+  deepLink?: string;
+  actionMessage?: string;
   expiresAt: string;
   recipient?: string;
 }
@@ -145,6 +154,8 @@ export interface RtpEventMap {
 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;

package/src/validate.ts

@@ -78,11 +78,59 @@ export function toRtpRequest(payload: RtpPayload): RtpRequest {
     payee: payload.payee,
     narration: payload.narration,
     transactionRef: payload.transactionRef,
+    orderNumber: payload.orderNumber,
+    deepLink: payload.deepLink,
+    actionMessage: payload.actionMessage,
     expiresAt: payload.expiresAt,
     recipient: payload.recipient,
   };
 }
 
+/**
+ * Build a partial-request patch from an incoming payload, copying only the
+ * fields that are actually present. Used to overlay retrieved backend details
+ * without a partial response erasing data already held from the push.
+ */
+export function toRequestPatch(
+  payload: Partial<RtpPayload>
+): Partial<RtpRequest> {
+  const patch: Partial<RtpRequest> = {};
+  if (payload.rtpId !== undefined) patch.id = payload.rtpId;
+  if (payload.amount !== undefined) patch.amount = toAmount(payload.amount);
+  if (payload.currency !== undefined) patch.currency = payload.currency;
+  if (payload.payer !== undefined) patch.payer = payload.payer;
+  if (payload.payee !== undefined) patch.payee = payload.payee;
+  if (payload.narration !== undefined) patch.narration = payload.narration;
+  if (payload.transactionRef !== undefined)
+    patch.transactionRef = payload.transactionRef;
+  if (payload.orderNumber !== undefined)
+    patch.orderNumber = payload.orderNumber;
+  if (payload.deepLink !== undefined) patch.deepLink = payload.deepLink;
+  if (payload.actionMessage !== undefined)
+    patch.actionMessage = payload.actionMessage;
+  if (payload.expiresAt !== undefined) patch.expiresAt = payload.expiresAt;
+  if (payload.recipient !== undefined) patch.recipient = payload.recipient;
+  return patch;
+}
+
+/**
+ * Overlay a patch onto an existing request. Only defined, non-null values are
+ * copied so a partial response never erases information already held.
+ */
+export function mergeRequest(
+  current: RtpRequest,
+  patch: Partial<RtpRequest>
+): RtpRequest {
+  const next: RtpRequest = { ...current };
+  for (const key of Object.keys(patch) as (keyof RtpRequest)[]) {
+    const value = patch[key];
+    if (value !== undefined && value !== null) {
+      (next as any)[key] = value;
+    }
+  }
+  return next;
+}
+
 /** 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();