@omniretail/lending-mobile-sdk 3.0.0 → 3.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +323 -0
- package/package.json +2 -2
package/README.md
ADDED
|
@@ -0,0 +1,323 @@
|
|
|
1
|
+
# OmniRetail Lending SDK
|
|
2
|
+
|
|
3
|
+
React Native SDK for **OmniRetail Inventory Finance / Credit** (Paylater+, Flat Loan / Paylater Pro, brand limits, KYC agreement, bank statement, repay). Hosts embed a single `<Lending config={...} />` tree.
|
|
4
|
+
|
|
5
|
+
This is **not** DualCards, OmniDualCards, a card-management SDK, a Savings SDK, or Asset Financing.
|
|
6
|
+
|
|
7
|
+
| Package | Who uses it | Role |
|
|
8
|
+
| --- | --- | --- |
|
|
9
|
+
| `@omniretail/lending-mobile-sdk` | **Host apps** | Facade. Always opens Limit home. Re-exports helpers and types. |
|
|
10
|
+
| `@omniretail/lending` | This repo / the facade | Core UI, HTTP, boot, screens. |
|
|
11
|
+
|
|
12
|
+
Hosts should depend on **`@omniretail/lending-mobile-sdk`**, not the core package.
|
|
13
|
+
|
|
14
|
+
There is **no React Navigation** and **no React Query**. Screen changes are in-memory in `SDKRoot`. Apply steps are `BottomSheet` overlays on Limit home.
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## Table of contents
|
|
19
|
+
|
|
20
|
+
1. [Install](#install)
|
|
21
|
+
2. [Mint a session before rendering](#mint-a-session-before-rendering)
|
|
22
|
+
3. [Pass config](#pass-config)
|
|
23
|
+
4. [Config reference](#config-reference)
|
|
24
|
+
5. [Session, hash, and boot](#session-hash-and-boot)
|
|
25
|
+
6. [HTTP hosts and headers](#http-hosts-and-headers)
|
|
26
|
+
7. [Product flows](#product-flows)
|
|
27
|
+
8. [Public exports](#public-exports)
|
|
28
|
+
9. [Conventions](#conventions)
|
|
29
|
+
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
## Install
|
|
33
|
+
|
|
34
|
+
From the host app (Expo SDK 53 / RN 0.79, React 19):
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
npm install @omniretail/lending-mobile-sdk
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Install **peer dependencies** (versions must satisfy the facade `package.json`):
|
|
41
|
+
|
|
42
|
+
- `react`, `react-native`
|
|
43
|
+
- `expo-font`
|
|
44
|
+
- `react-native-gesture-handler`
|
|
45
|
+
- `react-native-safe-area-context`
|
|
46
|
+
- `react-native-svg`
|
|
47
|
+
- `expo-print`, `expo-sharing` (Sign and Download Agreement PDF)
|
|
48
|
+
- `expo-document-picker` (or another picker behind `onPickDocument`)
|
|
49
|
+
- `react-native-webview` (optional peer; unused by current Credit screens)
|
|
50
|
+
|
|
51
|
+
Rebuild the native iOS/Android binary so Expo modules (print, sharing, fonts, gesture handler) are linked. Reloading Metro is not enough for new native modules.
|
|
52
|
+
|
|
53
|
+
Import gesture-handler **once** at the host entry, before other RN imports:
|
|
54
|
+
|
|
55
|
+
```js
|
|
56
|
+
import "react-native-gesture-handler";
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
`<Lending />` wraps `SDKFontProvider`, which loads Gordita Regular / Medium / Bold from the package. The host does not need to load Gordita unless it uses `GorditaFamily` outside the SDK.
|
|
60
|
+
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
## Mint a session before rendering
|
|
64
|
+
|
|
65
|
+
The SDK does **not** log the user in. Do not render `<Lending />` until `sessionId` and `accessToken` exist.
|
|
66
|
+
|
|
67
|
+
**Host step A — access token.** Use the host wallet Bearer (same token the wallet already has). Do not prefix `"Bearer "`.
|
|
68
|
+
|
|
69
|
+
**Host step B — loan session.** Call **`createSdkSession`** (exported from `@omniretail/lending-mobile-sdk`) against the **loan** host:
|
|
70
|
+
|
|
71
|
+
```ts
|
|
72
|
+
import { createSdkSession } from "@omniretail/lending-mobile-sdk";
|
|
73
|
+
|
|
74
|
+
const sessionId = await createSdkSession({
|
|
75
|
+
accessToken,
|
|
76
|
+
customerRef,
|
|
77
|
+
customerPhone,
|
|
78
|
+
publicKey,
|
|
79
|
+
loanApiBaseUrl // e.g. https://api-dev.omnibiz.app
|
|
80
|
+
});
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
That is `POST {loanApiBaseUrl}/omnipayloan/api/v1/kyc/createSdkSession`. After mount, the SDK calls **`authenticateSdkSession`** with that `sessionId`.
|
|
84
|
+
|
|
85
|
+
Changing `sessionId` / identity fields remounts boot (`sdkSessionKey`). On `401`, `onTokenExpired` fires; mint a new token + session and remount.
|
|
86
|
+
|
|
87
|
+
---
|
|
88
|
+
|
|
89
|
+
## Pass config
|
|
90
|
+
|
|
91
|
+
```tsx
|
|
92
|
+
import { Lending, type LendingSDKConfig } from "@omniretail/lending-mobile-sdk";
|
|
93
|
+
|
|
94
|
+
function buildConfig(session: { accessToken: string; sessionId: string }): LendingSDKConfig {
|
|
95
|
+
return {
|
|
96
|
+
apiBaseUrl: "https://api-dev.ompy.ng",
|
|
97
|
+
loanApiBaseUrl: "https://api-dev.omnibiz.app",
|
|
98
|
+
publicKey,
|
|
99
|
+
customerPhone,
|
|
100
|
+
customerRef,
|
|
101
|
+
userRef: "",
|
|
102
|
+
accessToken: session.accessToken,
|
|
103
|
+
sessionId: session.sessionId,
|
|
104
|
+
color: "#0E0E0E",
|
|
105
|
+
businessLineId: 7,
|
|
106
|
+
countryCode: 1,
|
|
107
|
+
interceptedStatusCodes: [400],
|
|
108
|
+
onPickDocument: async (opts) => {
|
|
109
|
+
const DocumentPicker = require("expo-document-picker");
|
|
110
|
+
const result = await DocumentPicker.getDocumentAsync({
|
|
111
|
+
type: opts?.types ?? ["application/pdf", "image/png", "image/jpeg", "image/gif"],
|
|
112
|
+
copyToCacheDirectory: true,
|
|
113
|
+
multiple: opts?.multiple ?? true
|
|
114
|
+
});
|
|
115
|
+
if (result.canceled) return null;
|
|
116
|
+
return (result.assets ?? []).map((asset: { name?: string; uri: string; mimeType?: string }) => ({
|
|
117
|
+
name: asset.name ?? "document",
|
|
118
|
+
uri: asset.uri,
|
|
119
|
+
mimeType: asset.mimeType
|
|
120
|
+
}));
|
|
121
|
+
},
|
|
122
|
+
onTokenExpired: () => {
|
|
123
|
+
/* 401 — new wallet token + createSdkSession, remount with a new sessionId */
|
|
124
|
+
},
|
|
125
|
+
onEvent: () => {
|
|
126
|
+
/* sdk_mounted | sdk_init_error */
|
|
127
|
+
}
|
|
128
|
+
};
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
export function CreditEntry(session: { accessToken: string; sessionId: string }) {
|
|
132
|
+
return <Lending config={buildConfig(session)} />;
|
|
133
|
+
}
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
The facade always starts on Limit home. Do not pass unused fields (`env`, `hash`, `limit`, `activeCredit`, `entryScreen`, `entryParams`).
|
|
137
|
+
|
|
138
|
+
The host unmounts Credit from its own navigation (for example bottom nav). There is no SDK `onClose`.
|
|
139
|
+
|
|
140
|
+
**`onPickDocument`** is required for bank-statement file upload. The core does not `require()` Expo picker modules itself.
|
|
141
|
+
|
|
142
|
+
Optional: `deviceId` / `deviceName` for repay. If omitted, the SDK uses `Platform.OS` + a session uuid.
|
|
143
|
+
|
|
144
|
+
**`color`:** primary buttons and PIN chrome. Default `#000000`.
|
|
145
|
+
|
|
146
|
+
**Do not mount two `<Lending />` trees at once.** Runtime is process-wide.
|
|
147
|
+
|
|
148
|
+
---
|
|
149
|
+
|
|
150
|
+
## Config reference
|
|
151
|
+
|
|
152
|
+
`SDKConfig` lives in `src/sdk/types.ts`. Important fields:
|
|
153
|
+
|
|
154
|
+
| Field | Required | Purpose |
|
|
155
|
+
| --- | --- | --- |
|
|
156
|
+
| `publicKey` | yes | Gateway `publickey` / hash |
|
|
157
|
+
| `customerPhone` | yes | Identity + hash |
|
|
158
|
+
| `sessionId` | yes | Authenticated before customer details |
|
|
159
|
+
| `accessToken` | yes | Bearer for loan/KYC calls that use Authorization |
|
|
160
|
+
| `apiBaseUrl` | yes | ompy host (customer details, wallet banks, KYC, repay POST) |
|
|
161
|
+
| `loanApiBaseUrl` | yes | OmniPay loan host (session, brands, products, statements, repay list) |
|
|
162
|
+
| `onPickDocument` | yes for file upload | Host-owned document picker |
|
|
163
|
+
| `customerRef` / `userRef` | no | Queries and headers; boot also fills from getCustomerDetails |
|
|
164
|
+
| `redirectService` | no | Default `wallet` |
|
|
165
|
+
| `redirectUrl` | no | Default empty; **part of hash** |
|
|
166
|
+
| `businessLineId` | no | Host business-line option `value`. Default `7` (Others). `5` (Retailers) uses the PayLimit apply/home flow |
|
|
167
|
+
| `countryCode` | no | Numeric country code. Default `1` (Nigeria). Any other code uses the PayLimit apply/home flow |
|
|
168
|
+
| `interceptedStatusCodes` | no | Extra HTTP statuses that toast via `responseObserver` |
|
|
169
|
+
| `color` | no | Brand CTA / PIN |
|
|
170
|
+
| `deviceId` / `deviceName` | no | Sent on repay |
|
|
171
|
+
| `onTokenExpired` | no | HTTP `401` |
|
|
172
|
+
| `onEvent` | no | `sdk_mounted` / `sdk_init_error` |
|
|
173
|
+
|
|
174
|
+
Live Limit home status comes from `GET /bnpl/sublimitRequest` (and brand-credit summary). Repay list comes from `getLoans`. Gateway `hash` is computed per request.
|
|
175
|
+
|
|
176
|
+
---
|
|
177
|
+
|
|
178
|
+
## Session, hash, and boot
|
|
179
|
+
|
|
180
|
+
On mount (and when `sdkSessionKey` changes):
|
|
181
|
+
|
|
182
|
+
1. Validate `publicKey`, `customerPhone`, `sessionId`, `accessToken`, `apiBaseUrl`, `loanApiBaseUrl`.
|
|
183
|
+
2. Write module-level runtime (base URLs, token, phone, device, document picker).
|
|
184
|
+
3. **`authenticateSdkSession(sessionId)`**.
|
|
185
|
+
4. **`GET {apiBaseUrl}/sdk/getCustomerDetails`**. `data.token` becomes the service Bearer if returned.
|
|
186
|
+
5. **`getApplyLimitHome()`** — limit request + brand-credit summary (failures are swallowed so Limit home can still render).
|
|
187
|
+
6. Limit home renders. Unmount clears runtime and caches so a second `<Lending />` in the same JS process is safe **sequentially**, not in parallel.
|
|
188
|
+
|
|
189
|
+
### Hash (`getHash`)
|
|
190
|
+
|
|
191
|
+
```text
|
|
192
|
+
MD5( `${customerPhone}pn${redirectUrl}rul${publicKey}pbey` )
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
Exported as `getHash(headers)` from `@omniretail/lending-mobile-sdk`. Per-request hashes use that request’s `redirecturl`. Do not invent a different algorithm.
|
|
196
|
+
|
|
197
|
+
---
|
|
198
|
+
|
|
199
|
+
## HTTP hosts and headers
|
|
200
|
+
|
|
201
|
+
The SDK talks to **two** bases:
|
|
202
|
+
|
|
203
|
+
| Config | Typical host | Examples |
|
|
204
|
+
| --- | --- | --- |
|
|
205
|
+
| `apiBaseUrl` | ompy.ng | `GET /sdk/getCustomerDetails`, wallet banks, some `/sdk/sdkRequest/...` |
|
|
206
|
+
| `loanApiBaseUrl` | omnibiz.app | `/omnipayloan/api/v1/...` products, KYC, bank statement, session, brands |
|
|
207
|
+
|
|
208
|
+
`src/services/http.ts` (`GET` / `POST` / `PUT` / `DELETE`): JSON or `FormData`, optional Bearer, hashed gateway calls (`omitAuthorization`), toasts via `responseObserver`.
|
|
209
|
+
|
|
210
|
+
Amounts on loan APIs are often **kobo**. UI uses naira; convert with `nairaToKobo` before those calls.
|
|
211
|
+
|
|
212
|
+
---
|
|
213
|
+
|
|
214
|
+
## Product flows
|
|
215
|
+
|
|
216
|
+
### Limit home
|
|
217
|
+
|
|
218
|
+
| Status | Meaning |
|
|
219
|
+
| --- | --- |
|
|
220
|
+
| `none` | Never applied. |
|
|
221
|
+
| `pending` | Application in review. |
|
|
222
|
+
| `rejected` | Declined (reason may show). |
|
|
223
|
+
| `on` | Assigned limit / brand rows. |
|
|
224
|
+
|
|
225
|
+
- **No limit:** apply CTA; repay is still available if `getLoans` returns loans.
|
|
226
|
+
- **On:** brand cards, repay, transactions, history. If resolve returns a Paylater flow (`brandReferral: false`), home hides brand cards and labels the summary TOTAL LIMIT.
|
|
227
|
+
|
|
228
|
+
Host `businessLineId` is the selected option `value`. Keep the options in the host (exported from the SDK as `BUSINESS_LINE_OPTIONS`) and pass only the number:
|
|
229
|
+
|
|
230
|
+
```ts
|
|
231
|
+
import { BUSINESS_LINE_OPTIONS } from "@omniretail/lending-mobile-sdk";
|
|
232
|
+
|
|
233
|
+
[
|
|
234
|
+
{ label: "Manufacturer", value: 1 },
|
|
235
|
+
{ label: "Distributor", value: 2 },
|
|
236
|
+
{ label: "HORECA", value: 3 },
|
|
237
|
+
{ label: "Modern Trade", value: 4 },
|
|
238
|
+
{ label: "Retailers", value: 5 },
|
|
239
|
+
{ label: "Consumers", value: 6 },
|
|
240
|
+
{ label: "Others", value: 7 }
|
|
241
|
+
];
|
|
242
|
+
// BUSINESS_LINE_OPTIONS === that list
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
On boot the SDK calls `GET {loanApiBaseUrl}/omnipayloan/api/v1/product/application-flows/resolve?businessLineId=&countryId=` (`countryId` is `config.countryCode`). If that fails or `data` is empty, boot stops on the SDK error screen.
|
|
246
|
+
|
|
247
|
+
Find Credit loads `GET .../product/configurational-products/{countryId}?isFeatureAllowed=true&businessLineId=`.
|
|
248
|
+
|
|
249
|
+
### Apply for limit
|
|
250
|
+
|
|
251
|
+
Resolve `features` drive the steps:
|
|
252
|
+
|
|
253
|
+
- `brandReferral: false` — skip brand selection
|
|
254
|
+
- `referralCode: true` — field-officer + referral sheet (skip if already on customer details)
|
|
255
|
+
- `creditLifeInsurance` — product-agreement insurance checkbox
|
|
256
|
+
- `bankStatement: false` — skip proof of account / MBS / statement upload. Ghana upload-only still applies when this is true
|
|
257
|
+
- `customerAgreement: false` — skip sign and download
|
|
258
|
+
|
|
259
|
+
**Brand sublimit** (`brandReferral: true`):
|
|
260
|
+
|
|
261
|
+
1. Brand (`Product/customer-brands`). Referral sheet if `hasCustomerBrandReferral` is false.
|
|
262
|
+
2. Find Credit (configurational products for `countryId`).
|
|
263
|
+
3. Credit amount (saves manufacturer statement account).
|
|
264
|
+
4. Product agreement. Two checkboxes; Proceed stays off until both are ticked.
|
|
265
|
+
5. Repayment plan.
|
|
266
|
+
6. Proof of account / bank statement (MBS or manual upload).
|
|
267
|
+
7. Sign agreement if KYC is unsigned; otherwise Download Agreement.
|
|
268
|
+
|
|
269
|
+
`PUT .../product/customer-products/update` runs **after** a successful statement (`productId` + brand `subLimitId`).
|
|
270
|
+
|
|
271
|
+
**Paylater** (`flowType: "paylater"` or `brandReferral: false`): skip brand. If `referralCode` is true, referral first unless `fieldOfficerId` and `referralCode` are already on customer details / getRequestDetails. Then product → credit amount (no manufacturer-account call) → product bucket. Ghana proof uses a fixed bank list and always uploads the statement. Other customers keep MBS or upload.
|
|
272
|
+
|
|
273
|
+
Bank statement **upload** (Nigeria and Ghana) FormData and **confirm** JSON send `businessLineId`, naira `amount`, and `productid` on that PayLimit path (not `isPaylater`).
|
|
274
|
+
|
|
275
|
+
### Customer agreement
|
|
276
|
+
|
|
277
|
+
Copy is local TSX (`src/flows/lending/agreements/`). Sign is multipart `POST /kyc/submitAgreement`. Download uses `expo-print` + `expo-sharing` from the displayed HTML, not `agreementFile` in a browser.
|
|
278
|
+
|
|
279
|
+
### Repay
|
|
280
|
+
|
|
281
|
+
- `GET .../Bnpl/getLoansList?isPaid=` — **`0` Pending**, **`3` Outstanding**.
|
|
282
|
+
- Outstanding **Proceed to Pay** is disabled.
|
|
283
|
+
- `POST` repay uses kobo amounts, an idempotency key, and `device` from config.
|
|
284
|
+
|
|
285
|
+
---
|
|
286
|
+
|
|
287
|
+
## Public exports
|
|
288
|
+
|
|
289
|
+
```ts
|
|
290
|
+
export {
|
|
291
|
+
Lending,
|
|
292
|
+
createSdkSession,
|
|
293
|
+
getHash,
|
|
294
|
+
GorditaFamily,
|
|
295
|
+
getSdkFontLoadMap,
|
|
296
|
+
fontSz,
|
|
297
|
+
sdkTypography,
|
|
298
|
+
BUSINESS_LINE_OPTIONS,
|
|
299
|
+
resolveIsPayLimit,
|
|
300
|
+
resolveBusinessLineId,
|
|
301
|
+
resolveCountryCode
|
|
302
|
+
};
|
|
303
|
+
export type {
|
|
304
|
+
LendingSDKConfig,
|
|
305
|
+
SDKConfig,
|
|
306
|
+
SDKEvent,
|
|
307
|
+
LimitStatus,
|
|
308
|
+
BusinessLineId,
|
|
309
|
+
BusinessLineOption
|
|
310
|
+
};
|
|
311
|
+
```
|
|
312
|
+
|
|
313
|
+
---
|
|
314
|
+
|
|
315
|
+
## Conventions
|
|
316
|
+
|
|
317
|
+
- **One SDK tree per process.**
|
|
318
|
+
- **Host session first**, then mount. Missing `sessionId` / `accessToken` fails boot.
|
|
319
|
+
- **Kobo vs naira** on loan APIs.
|
|
320
|
+
- **`isPaid` is a query param** on getLoansList.
|
|
321
|
+
- **Download Agreement** needs `expo-print` + `expo-sharing` in the **host** binary.
|
|
322
|
+
- **Do not** open `getAgreementDetails.agreementFile` as the user-facing contract.
|
|
323
|
+
- **Do not** rename this product to DualCards or implement savings / card / asset-finance flows here.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@omniretail/lending-mobile-sdk",
|
|
3
|
-
"version": "3.0.
|
|
3
|
+
"version": "3.0.2",
|
|
4
4
|
"description": "OmniRetail Lending SDK (facade over @omniretail/lending)",
|
|
5
5
|
"private": false,
|
|
6
6
|
"main": "lib/index.js",
|
|
@@ -38,7 +38,7 @@
|
|
|
38
38
|
"typescript": "~5.8.3"
|
|
39
39
|
},
|
|
40
40
|
"dependencies": {
|
|
41
|
-
"@omniretail/lending": "^3.0.
|
|
41
|
+
"@omniretail/lending": "^3.0.2"
|
|
42
42
|
},
|
|
43
43
|
"engines": {
|
|
44
44
|
"node": ">=18"
|