@kyciris/mobile 1.0.0
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 +110 -0
- package/package.json +63 -0
- package/src/KycirisVerification.tsx +298 -0
- package/src/capture.ts +148 -0
- package/src/index.tsx +56 -0
- package/src/storage.ts +31 -0
- package/src/useKycirisVerification.ts +197 -0
package/README.md
ADDED
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
# @kyciris/mobile
|
|
2
|
+
|
|
3
|
+
The [KYCiris](https://kyciris.com) verification flow for React Native.
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
pnpm add @kyciris/mobile @kyciris/core
|
|
7
|
+
npx expo install expo-image-picker
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
`expo-image-picker` is an optional peer — needed only for the built-in camera
|
|
11
|
+
capture. If you have your own camera screen, skip it and call `submit(file)`.
|
|
12
|
+
|
|
13
|
+
## Get a token first
|
|
14
|
+
|
|
15
|
+
The app authenticates with a **verification token**, minted on your server:
|
|
16
|
+
|
|
17
|
+
```
|
|
18
|
+
POST /v1/verification/token (X-API-Key) { externalId } -> { token }
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
The project API key must not reach the app; the SDK throws if it does.
|
|
22
|
+
|
|
23
|
+
## One component
|
|
24
|
+
|
|
25
|
+
```tsx
|
|
26
|
+
import AsyncStorage from '@react-native-async-storage/async-storage';
|
|
27
|
+
import { KycirisVerification, createAsyncStorage } from '@kyciris/mobile';
|
|
28
|
+
|
|
29
|
+
// Outside the component: a new storage object each render would rebuild the
|
|
30
|
+
// flow mid-upload.
|
|
31
|
+
const storage = createAsyncStorage(AsyncStorage);
|
|
32
|
+
|
|
33
|
+
export function Verify({ token }: { token: string }) {
|
|
34
|
+
return (
|
|
35
|
+
<KycirisVerification
|
|
36
|
+
baseUrl="https://api.kyciris.com"
|
|
37
|
+
verificationToken={token}
|
|
38
|
+
country="AO"
|
|
39
|
+
documentType="ID_CARD"
|
|
40
|
+
levelName="basic-kyc"
|
|
41
|
+
storage={storage}
|
|
42
|
+
onComplete={(state) => console.log(state.status, state.outcome)}
|
|
43
|
+
/>
|
|
44
|
+
);
|
|
45
|
+
}
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
It collects both document sides and a selfie, opening the rear camera for the
|
|
49
|
+
document and the front camera for the selfie, and reports the outcome.
|
|
50
|
+
|
|
51
|
+
Pass `labels` to change the wording, `styles` to restyle it.
|
|
52
|
+
|
|
53
|
+
## Your own screens
|
|
54
|
+
|
|
55
|
+
```tsx
|
|
56
|
+
import { useKycirisVerification } from '@kyciris/mobile';
|
|
57
|
+
|
|
58
|
+
const { state, capture, submit, start, reset } = useKycirisVerification({
|
|
59
|
+
baseUrl,
|
|
60
|
+
verificationToken,
|
|
61
|
+
country: 'AO',
|
|
62
|
+
documentType: 'ID_CARD',
|
|
63
|
+
levelName: 'basic-kyc',
|
|
64
|
+
storage,
|
|
65
|
+
});
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
`state` carries `phase`, `currentStep`, `missingSteps`, `uploaded`, `status`,
|
|
69
|
+
`outcome`, `error` and `busy`. `capture()` opens the right camera for the
|
|
70
|
+
current step; `submit(file)` uploads an image you captured yourself.
|
|
71
|
+
|
|
72
|
+
Or keep the component and replace only its screens:
|
|
73
|
+
|
|
74
|
+
```tsx
|
|
75
|
+
<KycirisVerification {...config}>
|
|
76
|
+
{({ state, capture }) => <YourScreens state={state} onCapture={capture} />}
|
|
77
|
+
</KycirisVerification>
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
## Resuming
|
|
81
|
+
|
|
82
|
+
With a `storage` adapter, an app killed between the document and the selfie
|
|
83
|
+
picks up where it stopped instead of asking for the document again. Progress is
|
|
84
|
+
read back from the files the gateway holds, not from anything the app
|
|
85
|
+
remembers, so it is also right after a reinstall or on a second device.
|
|
86
|
+
|
|
87
|
+
Only identifiers are stored — never the token.
|
|
88
|
+
|
|
89
|
+
## A different picker
|
|
90
|
+
|
|
91
|
+
The built-in capture uses `expo-image-picker`, found lazily. To use something
|
|
92
|
+
else, register it:
|
|
93
|
+
|
|
94
|
+
```ts
|
|
95
|
+
import { setImagePicker } from '@kyciris/mobile';
|
|
96
|
+
setImagePicker(myPicker); // anything matching ImagePickerModule
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
Photos are uploaded as `file://` URIs, which React Native streams from disk —
|
|
100
|
+
`base64` is never requested, so a multi-megabyte photo does not sit in the JS
|
|
101
|
+
heap as a string a third larger than the original.
|
|
102
|
+
|
|
103
|
+
## Notes
|
|
104
|
+
|
|
105
|
+
- Both document sides are required: the gateway only starts OCR once it has
|
|
106
|
+
both.
|
|
107
|
+
- Backing out of the camera is not an error; the step stays waiting.
|
|
108
|
+
- Unmounting cancels in-flight work, including a poll.
|
|
109
|
+
- See [`@kyciris/core`](https://www.npmjs.com/package/@kyciris/core) for the client itself,
|
|
110
|
+
the outcome model, and the server-side endpoints.
|
package/package.json
ADDED
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@kyciris/mobile",
|
|
3
|
+
"version": "1.0.0",
|
|
4
|
+
"description": "KYCiris identity verification flow for React Native",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"homepage": "https://kyciris.com",
|
|
7
|
+
"bugs": {
|
|
8
|
+
"email": "info@kyciris.com"
|
|
9
|
+
},
|
|
10
|
+
"keywords": [
|
|
11
|
+
"kyc",
|
|
12
|
+
"kyciris",
|
|
13
|
+
"identity-verification",
|
|
14
|
+
"react-native",
|
|
15
|
+
"expo",
|
|
16
|
+
"onboarding"
|
|
17
|
+
],
|
|
18
|
+
"main": "./src/index.tsx",
|
|
19
|
+
"types": "./src/index.tsx",
|
|
20
|
+
"peerDependencies": {
|
|
21
|
+
"expo": ">=54",
|
|
22
|
+
"expo-file-system": ">=18",
|
|
23
|
+
"expo-image-picker": ">=16",
|
|
24
|
+
"react": ">=19.0.0",
|
|
25
|
+
"react-native": ">=0.81"
|
|
26
|
+
},
|
|
27
|
+
"peerDependenciesMeta": {
|
|
28
|
+
"expo": {
|
|
29
|
+
"optional": true
|
|
30
|
+
},
|
|
31
|
+
"expo-file-system": {
|
|
32
|
+
"optional": true
|
|
33
|
+
},
|
|
34
|
+
"expo-image-picker": {
|
|
35
|
+
"optional": true
|
|
36
|
+
}
|
|
37
|
+
},
|
|
38
|
+
"dependencies": {
|
|
39
|
+
"@kyciris/core": "1.0.0"
|
|
40
|
+
},
|
|
41
|
+
"devDependencies": {
|
|
42
|
+
"@testing-library/dom": "^10.4.2",
|
|
43
|
+
"@testing-library/react": "^16.3.3",
|
|
44
|
+
"@types/react": "^19.3.0",
|
|
45
|
+
"jsdom": "^30.0.1",
|
|
46
|
+
"react": "^19.2.3",
|
|
47
|
+
"react-dom": "^19.2.3",
|
|
48
|
+
"typescript": "~6.0.3",
|
|
49
|
+
"vitest": "^5.0.1"
|
|
50
|
+
},
|
|
51
|
+
"files": [
|
|
52
|
+
"src"
|
|
53
|
+
],
|
|
54
|
+
"publishConfig": {
|
|
55
|
+
"access": "public"
|
|
56
|
+
},
|
|
57
|
+
"scripts": {
|
|
58
|
+
"typecheck": "tsc --noEmit",
|
|
59
|
+
"test": "vitest run",
|
|
60
|
+
"test:watch": "vitest",
|
|
61
|
+
"lint": "eslint src test --config ../../eslint.config.mjs"
|
|
62
|
+
}
|
|
63
|
+
}
|
|
@@ -0,0 +1,298 @@
|
|
|
1
|
+
import React from 'react';
|
|
2
|
+
import {
|
|
3
|
+
ActivityIndicator,
|
|
4
|
+
StyleSheet,
|
|
5
|
+
Text,
|
|
6
|
+
TouchableOpacity,
|
|
7
|
+
View,
|
|
8
|
+
type StyleProp,
|
|
9
|
+
type TextStyle,
|
|
10
|
+
type ViewStyle,
|
|
11
|
+
} from 'react-native';
|
|
12
|
+
import type { FlowState, VerificationStep } from '@kyciris/core';
|
|
13
|
+
|
|
14
|
+
import {
|
|
15
|
+
useKycirisVerification,
|
|
16
|
+
type KycirisVerificationConfig,
|
|
17
|
+
} from './useKycirisVerification';
|
|
18
|
+
|
|
19
|
+
export interface KycirisVerificationStyles {
|
|
20
|
+
container?: StyleProp<ViewStyle>;
|
|
21
|
+
title?: StyleProp<TextStyle>;
|
|
22
|
+
description?: StyleProp<TextStyle>;
|
|
23
|
+
button?: StyleProp<ViewStyle>;
|
|
24
|
+
buttonText?: StyleProp<TextStyle>;
|
|
25
|
+
error?: StyleProp<ViewStyle>;
|
|
26
|
+
errorText?: StyleProp<TextStyle>;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
export interface KycirisVerificationLabels {
|
|
30
|
+
documentFrontTitle?: string;
|
|
31
|
+
documentFrontDescription?: string;
|
|
32
|
+
documentBackTitle?: string;
|
|
33
|
+
documentBackDescription?: string;
|
|
34
|
+
selfieTitle?: string;
|
|
35
|
+
selfieDescription?: string;
|
|
36
|
+
captureButton?: string;
|
|
37
|
+
processingTitle?: string;
|
|
38
|
+
processingDescription?: string;
|
|
39
|
+
approvedTitle?: string;
|
|
40
|
+
approvedDescription?: string;
|
|
41
|
+
rejectedTitle?: string;
|
|
42
|
+
rejectedDescription?: string;
|
|
43
|
+
reviewTitle?: string;
|
|
44
|
+
reviewDescription?: string;
|
|
45
|
+
retryButton?: string;
|
|
46
|
+
startButton?: string;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
export interface KycirisVerificationProps extends KycirisVerificationConfig {
|
|
50
|
+
styles?: KycirisVerificationStyles;
|
|
51
|
+
labels?: KycirisVerificationLabels;
|
|
52
|
+
/**
|
|
53
|
+
* Replaces the built-in screens entirely while keeping the flow.
|
|
54
|
+
*
|
|
55
|
+
* The escape hatch for a design system: everything the default UI renders is
|
|
56
|
+
* derived from this same state.
|
|
57
|
+
*/
|
|
58
|
+
children?: (
|
|
59
|
+
controls: ReturnType<typeof useKycirisVerification>
|
|
60
|
+
) => React.ReactElement | null;
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
const DEFAULT_LABELS: Required<KycirisVerificationLabels> = {
|
|
64
|
+
documentFrontTitle: 'Front of your document',
|
|
65
|
+
documentFrontDescription:
|
|
66
|
+
'Photograph the front of your ID. Keep all four corners in frame and avoid glare.',
|
|
67
|
+
documentBackTitle: 'Back of your document',
|
|
68
|
+
documentBackDescription:
|
|
69
|
+
'Now the back. The details on this side are read too, so keep it sharp.',
|
|
70
|
+
selfieTitle: 'Take a selfie',
|
|
71
|
+
selfieDescription:
|
|
72
|
+
'Look straight at the camera in good light, with nothing covering your face.',
|
|
73
|
+
captureButton: 'Open camera',
|
|
74
|
+
processingTitle: 'Checking your documents',
|
|
75
|
+
processingDescription: 'This usually takes under a minute.',
|
|
76
|
+
approvedTitle: 'Verified',
|
|
77
|
+
approvedDescription: 'Your identity has been confirmed.',
|
|
78
|
+
rejectedTitle: 'Not verified',
|
|
79
|
+
rejectedDescription: 'We could not confirm your identity from what was submitted.',
|
|
80
|
+
reviewTitle: 'Being reviewed',
|
|
81
|
+
reviewDescription:
|
|
82
|
+
'Someone is checking your documents by hand. You do not need to stay on this screen.',
|
|
83
|
+
retryButton: 'Try again',
|
|
84
|
+
startButton: 'Start verification',
|
|
85
|
+
};
|
|
86
|
+
|
|
87
|
+
const STEP_LABELS: Record<VerificationStep, [keyof KycirisVerificationLabels, keyof KycirisVerificationLabels]> = {
|
|
88
|
+
document_front: ['documentFrontTitle', 'documentFrontDescription'],
|
|
89
|
+
document_back: ['documentBackTitle', 'documentBackDescription'],
|
|
90
|
+
selfie: ['selfieTitle', 'selfieDescription'],
|
|
91
|
+
};
|
|
92
|
+
|
|
93
|
+
/**
|
|
94
|
+
* A complete verification flow with prebuilt screens.
|
|
95
|
+
*
|
|
96
|
+
* Point it at the gateway with a verification token and it collects both
|
|
97
|
+
* document sides and a selfie, resumes anything already in progress, and
|
|
98
|
+
* reports the outcome.
|
|
99
|
+
*
|
|
100
|
+
* ```tsx
|
|
101
|
+
* <KycirisVerification
|
|
102
|
+
* baseUrl="https://api.kyciris.com"
|
|
103
|
+
* verificationToken={token}
|
|
104
|
+
* country="AO"
|
|
105
|
+
* documentType="ID_CARD"
|
|
106
|
+
* onComplete={(state) => console.log(state.status)}
|
|
107
|
+
* />
|
|
108
|
+
* ```
|
|
109
|
+
*
|
|
110
|
+
* Pass `children` to keep the flow and replace the screens.
|
|
111
|
+
*/
|
|
112
|
+
export function KycirisVerification(props: KycirisVerificationProps): React.ReactElement {
|
|
113
|
+
const { styles: custom, labels: overrides, children, ...config } = props;
|
|
114
|
+
const controls = useKycirisVerification(config);
|
|
115
|
+
const { state, capture, start, reset } = controls;
|
|
116
|
+
const labels = { ...DEFAULT_LABELS, ...overrides };
|
|
117
|
+
|
|
118
|
+
if (children) return children(controls) ?? <View />;
|
|
119
|
+
|
|
120
|
+
return (
|
|
121
|
+
<View style={[styles.container, custom?.container]}>
|
|
122
|
+
{state.error ? (
|
|
123
|
+
<View style={[styles.errorBox, custom?.error]}>
|
|
124
|
+
<Text style={[styles.errorText, custom?.errorText]}>{state.error.message}</Text>
|
|
125
|
+
</View>
|
|
126
|
+
) : null}
|
|
127
|
+
|
|
128
|
+
{renderBody()}
|
|
129
|
+
</View>
|
|
130
|
+
);
|
|
131
|
+
|
|
132
|
+
function renderBody(): React.ReactElement {
|
|
133
|
+
if (state.phase === 'failed') {
|
|
134
|
+
return (
|
|
135
|
+
<Action
|
|
136
|
+
label={labels.retryButton}
|
|
137
|
+
onPress={() => void start()}
|
|
138
|
+
busy={state.busy}
|
|
139
|
+
custom={custom}
|
|
140
|
+
/>
|
|
141
|
+
);
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
if (state.phase === 'idle' || state.phase === 'starting') {
|
|
145
|
+
return state.phase === 'starting' ? (
|
|
146
|
+
<Spinner label={labels.processingTitle} custom={custom} />
|
|
147
|
+
) : (
|
|
148
|
+
<Action
|
|
149
|
+
label={labels.startButton}
|
|
150
|
+
onPress={() => void start()}
|
|
151
|
+
busy={state.busy}
|
|
152
|
+
custom={custom}
|
|
153
|
+
/>
|
|
154
|
+
);
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
if (state.phase === 'processing') {
|
|
158
|
+
return (
|
|
159
|
+
<View style={styles.step}>
|
|
160
|
+
<ActivityIndicator size="large" color="#0F766E" />
|
|
161
|
+
<Text style={[styles.title, custom?.title]}>{labels.processingTitle}</Text>
|
|
162
|
+
<Text style={[styles.description, custom?.description]}>
|
|
163
|
+
{labels.processingDescription}
|
|
164
|
+
</Text>
|
|
165
|
+
</View>
|
|
166
|
+
);
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
if (state.phase === 'finished') {
|
|
170
|
+
const [title, description] = outcomeCopy(state, labels);
|
|
171
|
+
return (
|
|
172
|
+
<View style={styles.step}>
|
|
173
|
+
<Text style={[styles.title, custom?.title]}>{title}</Text>
|
|
174
|
+
<Text style={[styles.description, custom?.description]}>{description}</Text>
|
|
175
|
+
{state.status === 'REJECTED' ? (
|
|
176
|
+
<Action
|
|
177
|
+
label={labels.retryButton}
|
|
178
|
+
onPress={() => void reset().then(() => start({ fresh: true }))}
|
|
179
|
+
busy={state.busy}
|
|
180
|
+
custom={custom}
|
|
181
|
+
/>
|
|
182
|
+
) : null}
|
|
183
|
+
</View>
|
|
184
|
+
);
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
const step = state.currentStep;
|
|
188
|
+
if (!step) return <Spinner label={labels.processingTitle} custom={custom} />;
|
|
189
|
+
|
|
190
|
+
const [titleKey, descriptionKey] = STEP_LABELS[step];
|
|
191
|
+
return (
|
|
192
|
+
<View style={styles.step}>
|
|
193
|
+
<Text style={[styles.title, custom?.title]}>{labels[titleKey]}</Text>
|
|
194
|
+
<Text style={[styles.description, custom?.description]}>{labels[descriptionKey]}</Text>
|
|
195
|
+
<Action
|
|
196
|
+
label={labels.captureButton}
|
|
197
|
+
onPress={() => void capture()}
|
|
198
|
+
busy={state.busy}
|
|
199
|
+
custom={custom}
|
|
200
|
+
/>
|
|
201
|
+
</View>
|
|
202
|
+
);
|
|
203
|
+
}
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
function outcomeCopy(
|
|
207
|
+
state: FlowState,
|
|
208
|
+
labels: Required<KycirisVerificationLabels>
|
|
209
|
+
): [string, string] {
|
|
210
|
+
if (state.status === 'APPROVED') {
|
|
211
|
+
return [labels.approvedTitle, labels.approvedDescription];
|
|
212
|
+
}
|
|
213
|
+
if (state.status === 'REVIEW') {
|
|
214
|
+
return [labels.reviewTitle, labels.reviewDescription];
|
|
215
|
+
}
|
|
216
|
+
// A rejection reason is written for an operator, but it is the only specific
|
|
217
|
+
// thing available, and "not verified" alone leaves the user with nothing.
|
|
218
|
+
return [labels.rejectedTitle, state.rejectionReason ?? labels.rejectedDescription];
|
|
219
|
+
}
|
|
220
|
+
|
|
221
|
+
function Action({
|
|
222
|
+
label,
|
|
223
|
+
onPress,
|
|
224
|
+
busy,
|
|
225
|
+
custom,
|
|
226
|
+
}: {
|
|
227
|
+
label: string;
|
|
228
|
+
onPress: () => void;
|
|
229
|
+
busy: boolean;
|
|
230
|
+
custom?: KycirisVerificationStyles;
|
|
231
|
+
}): React.ReactElement {
|
|
232
|
+
return (
|
|
233
|
+
<TouchableOpacity
|
|
234
|
+
style={[styles.button, custom?.button, busy && styles.buttonBusy]}
|
|
235
|
+
onPress={onPress}
|
|
236
|
+
disabled={busy}
|
|
237
|
+
accessibilityRole="button"
|
|
238
|
+
accessibilityState={{ disabled: busy }}
|
|
239
|
+
>
|
|
240
|
+
{busy ? (
|
|
241
|
+
<ActivityIndicator color="#fff" />
|
|
242
|
+
) : (
|
|
243
|
+
<Text style={[styles.buttonText, custom?.buttonText]}>{label}</Text>
|
|
244
|
+
)}
|
|
245
|
+
</TouchableOpacity>
|
|
246
|
+
);
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
function Spinner({
|
|
250
|
+
label,
|
|
251
|
+
custom,
|
|
252
|
+
}: {
|
|
253
|
+
label: string;
|
|
254
|
+
custom?: KycirisVerificationStyles;
|
|
255
|
+
}): React.ReactElement {
|
|
256
|
+
return (
|
|
257
|
+
<View style={styles.step}>
|
|
258
|
+
<ActivityIndicator size="large" color="#0F766E" />
|
|
259
|
+
<Text style={[styles.description, custom?.description]}>{label}</Text>
|
|
260
|
+
</View>
|
|
261
|
+
);
|
|
262
|
+
}
|
|
263
|
+
|
|
264
|
+
const styles = StyleSheet.create({
|
|
265
|
+
container: { alignItems: 'center', justifyContent: 'center', padding: 16 },
|
|
266
|
+
step: { alignItems: 'center', justifyContent: 'center', padding: 8 },
|
|
267
|
+
title: { fontSize: 20, fontWeight: '600', color: '#0F172A', marginBottom: 8, textAlign: 'center' },
|
|
268
|
+
description: {
|
|
269
|
+
fontSize: 14,
|
|
270
|
+
color: '#475569',
|
|
271
|
+
textAlign: 'center',
|
|
272
|
+
marginBottom: 20,
|
|
273
|
+
lineHeight: 20,
|
|
274
|
+
},
|
|
275
|
+
button: {
|
|
276
|
+
backgroundColor: '#0F766E',
|
|
277
|
+
paddingVertical: 14,
|
|
278
|
+
paddingHorizontal: 24,
|
|
279
|
+
borderRadius: 10,
|
|
280
|
+
alignItems: 'center',
|
|
281
|
+
justifyContent: 'center',
|
|
282
|
+
minWidth: 220,
|
|
283
|
+
},
|
|
284
|
+
buttonBusy: { opacity: 0.7 },
|
|
285
|
+
buttonText: { color: '#fff', fontSize: 16, fontWeight: '600' },
|
|
286
|
+
errorBox: {
|
|
287
|
+
backgroundColor: '#FEF2F2',
|
|
288
|
+
borderColor: '#FECACA',
|
|
289
|
+
borderWidth: 1,
|
|
290
|
+
padding: 12,
|
|
291
|
+
borderRadius: 8,
|
|
292
|
+
marginBottom: 16,
|
|
293
|
+
width: '100%',
|
|
294
|
+
},
|
|
295
|
+
errorText: { color: '#B91C1C', fontSize: 14 },
|
|
296
|
+
});
|
|
297
|
+
|
|
298
|
+
export default KycirisVerification;
|
package/src/capture.ts
ADDED
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
import { KycirisError, type FileInput } from '@kyciris/core';
|
|
2
|
+
|
|
3
|
+
/** Which camera a step should open with. */
|
|
4
|
+
export type CameraFacing = 'front' | 'back';
|
|
5
|
+
|
|
6
|
+
export interface CaptureOptions {
|
|
7
|
+
facing?: CameraFacing;
|
|
8
|
+
/** JPEG quality, 0-1. Defaults to 0.8 — enough for OCR, small enough to send. */
|
|
9
|
+
quality?: number;
|
|
10
|
+
/** Open the photo library instead of the camera. */
|
|
11
|
+
fromLibrary?: boolean;
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* The subset of `expo-image-picker` used here, so the module can be optional.
|
|
16
|
+
*
|
|
17
|
+
* Exported because {@link setImagePicker} takes it: an app using a different
|
|
18
|
+
* picker only has to satisfy this shape.
|
|
19
|
+
*/
|
|
20
|
+
export interface ImagePickerModule {
|
|
21
|
+
requestCameraPermissionsAsync(): Promise<{ granted?: boolean; status: string }>;
|
|
22
|
+
requestMediaLibraryPermissionsAsync(): Promise<{ granted?: boolean; status: string }>;
|
|
23
|
+
launchCameraAsync(options: Record<string, unknown>): Promise<PickerResult>;
|
|
24
|
+
launchImageLibraryAsync(options: Record<string, unknown>): Promise<PickerResult>;
|
|
25
|
+
CameraType?: { front: unknown; back: unknown };
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
interface PickerResult {
|
|
29
|
+
canceled: boolean;
|
|
30
|
+
assets?: Array<{ uri?: string; mimeType?: string; fileName?: string }> | null;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
let registered: ImagePickerModule | null = null;
|
|
34
|
+
let cached: ImagePickerModule | null | undefined;
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* Supplies the picker explicitly, instead of letting the module be found.
|
|
38
|
+
*
|
|
39
|
+
* Two reasons it exists. An app may use something other than
|
|
40
|
+
* expo-image-picker — anything satisfying {@link ImagePickerModule} will do —
|
|
41
|
+
* and the automatic lookup is a CommonJS `require`, which resolves under
|
|
42
|
+
* Metro but not in an ES module environment such as a test runner.
|
|
43
|
+
*
|
|
44
|
+
* ```ts
|
|
45
|
+
* import * as ImagePicker from 'expo-image-picker';
|
|
46
|
+
* setImagePicker(ImagePicker);
|
|
47
|
+
* ```
|
|
48
|
+
*
|
|
49
|
+
* Pass null to go back to the automatic lookup.
|
|
50
|
+
*/
|
|
51
|
+
export function setImagePicker(picker: ImagePickerModule | null): void {
|
|
52
|
+
registered = picker;
|
|
53
|
+
cached = undefined;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/**
|
|
57
|
+
* Loads expo-image-picker on first use.
|
|
58
|
+
*
|
|
59
|
+
* Required lazily rather than imported, because it is an optional peer: an app
|
|
60
|
+
* with its own camera screen should not have to install it, and importing it
|
|
61
|
+
* at module scope would make that impossible.
|
|
62
|
+
*/
|
|
63
|
+
function loadImagePicker(): ImagePickerModule {
|
|
64
|
+
if (registered) return registered;
|
|
65
|
+
|
|
66
|
+
if (cached === undefined) {
|
|
67
|
+
try {
|
|
68
|
+
// `require` is what Metro resolves; it is absent in an ES module
|
|
69
|
+
// environment, hence the typeof guard and setImagePicker above.
|
|
70
|
+
cached =
|
|
71
|
+
typeof require === 'function'
|
|
72
|
+
? // eslint-disable-next-line @typescript-eslint/no-require-imports
|
|
73
|
+
(require('expo-image-picker') as ImagePickerModule)
|
|
74
|
+
: null;
|
|
75
|
+
} catch {
|
|
76
|
+
cached = null;
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
if (!cached) {
|
|
81
|
+
throw new KycirisError(
|
|
82
|
+
'expo-image-picker is not installed. Add it (`npx expo install expo-image-picker`), or register a picker with setImagePicker(), or capture the image yourself and pass it to submit().',
|
|
83
|
+
{ code: 'CONFIG_ERROR' }
|
|
84
|
+
);
|
|
85
|
+
}
|
|
86
|
+
return cached;
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/**
|
|
90
|
+
* Opens the camera (or the library) and returns the captured image.
|
|
91
|
+
*
|
|
92
|
+
* The image comes back as a `file://` URI rather than base64: React Native
|
|
93
|
+
* streams the file from disk, so a multi-megabyte photo never has to sit in
|
|
94
|
+
* the JS heap as a string a third larger than the original.
|
|
95
|
+
*
|
|
96
|
+
* Returns null when the user backs out, which is not an error.
|
|
97
|
+
*/
|
|
98
|
+
export async function captureImage(
|
|
99
|
+
options: CaptureOptions = {}
|
|
100
|
+
): Promise<FileInput | null> {
|
|
101
|
+
const picker = loadImagePicker();
|
|
102
|
+
const fromLibrary = options.fromLibrary ?? false;
|
|
103
|
+
|
|
104
|
+
const permission = fromLibrary
|
|
105
|
+
? await picker.requestMediaLibraryPermissionsAsync()
|
|
106
|
+
: await picker.requestCameraPermissionsAsync();
|
|
107
|
+
|
|
108
|
+
const granted = permission.granted ?? permission.status === 'granted';
|
|
109
|
+
if (!granted) {
|
|
110
|
+
throw new KycirisError(
|
|
111
|
+
fromLibrary
|
|
112
|
+
? 'Permission to open the photo library was denied.'
|
|
113
|
+
: 'Permission to use the camera was denied. It is needed to photograph the document and take the selfie.',
|
|
114
|
+
{ code: 'FORBIDDEN' }
|
|
115
|
+
);
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
const common = {
|
|
119
|
+
mediaTypes: ['images'],
|
|
120
|
+
quality: options.quality ?? 0.8,
|
|
121
|
+
// Deliberately false: base64 would put the whole photo in the JS heap for
|
|
122
|
+
// no benefit, since the URI is what gets uploaded.
|
|
123
|
+
base64: false,
|
|
124
|
+
allowsEditing: false,
|
|
125
|
+
};
|
|
126
|
+
|
|
127
|
+
const result = fromLibrary
|
|
128
|
+
? await picker.launchImageLibraryAsync(common)
|
|
129
|
+
: await picker.launchCameraAsync({
|
|
130
|
+
...common,
|
|
131
|
+
...(options.facing && picker.CameraType
|
|
132
|
+
? { cameraType: picker.CameraType[options.facing] }
|
|
133
|
+
: {}),
|
|
134
|
+
});
|
|
135
|
+
|
|
136
|
+
if (result.canceled) return null;
|
|
137
|
+
|
|
138
|
+
const asset = result.assets?.[0];
|
|
139
|
+
if (!asset?.uri) return null;
|
|
140
|
+
|
|
141
|
+
return {
|
|
142
|
+
uri: asset.uri,
|
|
143
|
+
name: asset.fileName ?? 'capture.jpg',
|
|
144
|
+
// The gateway sniffs the real type from the bytes, so a wrong hint here
|
|
145
|
+
// costs nothing; a missing one would make React Native send octet-stream.
|
|
146
|
+
type: asset.mimeType ?? 'image/jpeg',
|
|
147
|
+
};
|
|
148
|
+
}
|
package/src/index.tsx
ADDED
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `@kyciris/mobile` — the KYCiris verification flow for React Native.
|
|
3
|
+
*
|
|
4
|
+
* Three levels, all driving the same flow controller:
|
|
5
|
+
*
|
|
6
|
+
* - `KycirisVerification` — prebuilt screens, one component.
|
|
7
|
+
* - `useKycirisVerification` — the flow with your own screens.
|
|
8
|
+
* - `@kyciris/core` — the client, for anything else.
|
|
9
|
+
*
|
|
10
|
+
* The app authenticates with a **verification token**, minted on your server
|
|
11
|
+
* with the project API key. Constructing a client with the API key inside the
|
|
12
|
+
* app throws: a key in a shipped bundle is a key the end user has.
|
|
13
|
+
*/
|
|
14
|
+
|
|
15
|
+
export {
|
|
16
|
+
KycirisVerification,
|
|
17
|
+
default as KycirisVerificationComponent,
|
|
18
|
+
} from './KycirisVerification';
|
|
19
|
+
export type {
|
|
20
|
+
KycirisVerificationLabels,
|
|
21
|
+
KycirisVerificationProps,
|
|
22
|
+
KycirisVerificationStyles,
|
|
23
|
+
} from './KycirisVerification';
|
|
24
|
+
|
|
25
|
+
export { useKycirisVerification } from './useKycirisVerification';
|
|
26
|
+
export type {
|
|
27
|
+
KycirisVerificationConfig,
|
|
28
|
+
UseKycirisVerification,
|
|
29
|
+
} from './useKycirisVerification';
|
|
30
|
+
|
|
31
|
+
export { captureImage, setImagePicker } from './capture';
|
|
32
|
+
export type { CameraFacing, CaptureOptions, ImagePickerModule } from './capture';
|
|
33
|
+
|
|
34
|
+
export { createAsyncStorage } from './storage';
|
|
35
|
+
export type { AsyncStorageLike } from './storage';
|
|
36
|
+
|
|
37
|
+
// Re-exported so an app does not have to depend on @kyciris/core directly for
|
|
38
|
+
// the types that appear in this package's own signatures.
|
|
39
|
+
export {
|
|
40
|
+
KycirisClient,
|
|
41
|
+
KycirisError,
|
|
42
|
+
VerificationFlow,
|
|
43
|
+
createKycirisClient,
|
|
44
|
+
isKycirisError,
|
|
45
|
+
} from '@kyciris/core';
|
|
46
|
+
export type {
|
|
47
|
+
CatalogCountry,
|
|
48
|
+
DocumentType,
|
|
49
|
+
FileInput,
|
|
50
|
+
FlowPhase,
|
|
51
|
+
FlowState,
|
|
52
|
+
KycirisStorage,
|
|
53
|
+
VerificationOutcome,
|
|
54
|
+
VerificationStatus,
|
|
55
|
+
VerificationStep,
|
|
56
|
+
} from '@kyciris/core';
|
package/src/storage.ts
ADDED
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
import type { KycirisStorage } from '@kyciris/core';
|
|
2
|
+
|
|
3
|
+
/** The slice of `@react-native-async-storage/async-storage` the SDK needs. */
|
|
4
|
+
export interface AsyncStorageLike {
|
|
5
|
+
getItem(key: string): Promise<string | null>;
|
|
6
|
+
setItem(key: string, value: string): Promise<void>;
|
|
7
|
+
removeItem(key: string): Promise<void>;
|
|
8
|
+
}
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* Adapts AsyncStorage to the SDK's storage interface, so a verification
|
|
12
|
+
* survives the app being closed mid-flow.
|
|
13
|
+
*
|
|
14
|
+
* AsyncStorage is not a dependency of this package — an app may use MMKV, or
|
|
15
|
+
* an encrypted store — so it is passed in rather than imported.
|
|
16
|
+
*
|
|
17
|
+
* ```ts
|
|
18
|
+
* import AsyncStorage from '@react-native-async-storage/async-storage';
|
|
19
|
+
* const storage = createAsyncStorage(AsyncStorage);
|
|
20
|
+
* ```
|
|
21
|
+
*
|
|
22
|
+
* Nothing secret is written: the SDK stores identifiers only, never the
|
|
23
|
+
* verification token.
|
|
24
|
+
*/
|
|
25
|
+
export function createAsyncStorage(asyncStorage: AsyncStorageLike): KycirisStorage {
|
|
26
|
+
return {
|
|
27
|
+
getItem: (key) => asyncStorage.getItem(key),
|
|
28
|
+
setItem: (key, value) => asyncStorage.setItem(key, value),
|
|
29
|
+
removeItem: (key) => asyncStorage.removeItem(key),
|
|
30
|
+
};
|
|
31
|
+
}
|
|
@@ -0,0 +1,197 @@
|
|
|
1
|
+
import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
|
|
2
|
+
import {
|
|
3
|
+
KycirisClient,
|
|
4
|
+
VerificationFlow,
|
|
5
|
+
type CatalogCountry,
|
|
6
|
+
type DocumentType,
|
|
7
|
+
type FileInput,
|
|
8
|
+
type FlowState,
|
|
9
|
+
type KycirisError,
|
|
10
|
+
type KycirisStorage,
|
|
11
|
+
type VerificationStep,
|
|
12
|
+
type VerificationTokenProvider,
|
|
13
|
+
} from '@kyciris/core';
|
|
14
|
+
|
|
15
|
+
import { captureImage, type CameraFacing } from './capture';
|
|
16
|
+
|
|
17
|
+
export interface KycirisVerificationConfig {
|
|
18
|
+
/** Origin of the gateway, e.g. `https://api.kyciris.com`. */
|
|
19
|
+
baseUrl: string;
|
|
20
|
+
/**
|
|
21
|
+
* A verification token for this end user, or a function returning one.
|
|
22
|
+
*
|
|
23
|
+
* Mint it on your server with the project API key
|
|
24
|
+
* (`POST /v1/verification/token`). The project API key itself must never
|
|
25
|
+
* reach the app: the SDK refuses to use one here.
|
|
26
|
+
*/
|
|
27
|
+
verificationToken: string | VerificationTokenProvider;
|
|
28
|
+
country: CatalogCountry | (string & {});
|
|
29
|
+
documentType: DocumentType | (string & {});
|
|
30
|
+
/** The verification level to run under. Required: the gateway has no default. */
|
|
31
|
+
levelName: string;
|
|
32
|
+
/** Your own reference for the user, when starting with an API key. */
|
|
33
|
+
externalId?: string;
|
|
34
|
+
/** Set false when the level does not ask for a selfie. */
|
|
35
|
+
selfieRequired?: boolean;
|
|
36
|
+
/** Where to remember the verification, so a killed app can resume. */
|
|
37
|
+
storage?: KycirisStorage;
|
|
38
|
+
/** Poll for the decision once everything is uploaded. Defaults to true. */
|
|
39
|
+
waitForDecision?: boolean;
|
|
40
|
+
/** How long to poll before giving up, in ms. */
|
|
41
|
+
decisionTimeoutMs?: number;
|
|
42
|
+
/** Start the flow as soon as the hook mounts. Defaults to true. */
|
|
43
|
+
autoStart?: boolean;
|
|
44
|
+
onStateChange?: (state: FlowState) => void;
|
|
45
|
+
onComplete?: (state: FlowState) => void;
|
|
46
|
+
onError?: (error: KycirisError) => void;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
export interface UseKycirisVerification {
|
|
50
|
+
state: FlowState;
|
|
51
|
+
/** Starts, or resumes the verification already in storage. */
|
|
52
|
+
start: (options?: { fresh?: boolean }) => Promise<void>;
|
|
53
|
+
/** Opens the camera for the current step and uploads what comes back. */
|
|
54
|
+
capture: (options?: { fromLibrary?: boolean }) => Promise<void>;
|
|
55
|
+
/** Uploads an image you captured yourself. */
|
|
56
|
+
submit: (file: FileInput) => Promise<void>;
|
|
57
|
+
/** Re-reads what the gateway holds. */
|
|
58
|
+
refresh: () => Promise<void>;
|
|
59
|
+
/** Cancels, forgets the session, and returns to the start. */
|
|
60
|
+
reset: () => Promise<void>;
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/** Which camera each step should open with. */
|
|
64
|
+
const STEP_FACING: Record<VerificationStep, CameraFacing> = {
|
|
65
|
+
document_front: 'back',
|
|
66
|
+
document_back: 'back',
|
|
67
|
+
selfie: 'front',
|
|
68
|
+
};
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* Drives a verification from React Native, with no UI of its own.
|
|
72
|
+
*
|
|
73
|
+
* Use it when the screens are yours; use `KycirisVerification` for the
|
|
74
|
+
* prebuilt ones. Both run the same flow controller from `@kyciris/core`.
|
|
75
|
+
*
|
|
76
|
+
* The client is memoised on the values that actually identify it, so passing
|
|
77
|
+
* a fresh config object every render does not rebuild the flow mid-upload.
|
|
78
|
+
*/
|
|
79
|
+
export function useKycirisVerification(
|
|
80
|
+
config: KycirisVerificationConfig
|
|
81
|
+
): UseKycirisVerification {
|
|
82
|
+
const {
|
|
83
|
+
baseUrl,
|
|
84
|
+
verificationToken,
|
|
85
|
+
country,
|
|
86
|
+
documentType,
|
|
87
|
+
levelName,
|
|
88
|
+
externalId,
|
|
89
|
+
selfieRequired,
|
|
90
|
+
storage,
|
|
91
|
+
waitForDecision,
|
|
92
|
+
decisionTimeoutMs,
|
|
93
|
+
autoStart = true,
|
|
94
|
+
} = config;
|
|
95
|
+
|
|
96
|
+
// Callbacks live in a ref so that a parent re-rendering with new inline
|
|
97
|
+
// handlers does not tear down and restart the flow.
|
|
98
|
+
const handlers = useRef(config);
|
|
99
|
+
handlers.current = config;
|
|
100
|
+
|
|
101
|
+
const flow = useMemo(() => {
|
|
102
|
+
const client = new KycirisClient({ baseUrl, verificationToken, storage });
|
|
103
|
+
return new VerificationFlow(client, {
|
|
104
|
+
country,
|
|
105
|
+
documentType,
|
|
106
|
+
levelName,
|
|
107
|
+
externalId,
|
|
108
|
+
selfieRequired,
|
|
109
|
+
waitForDecision,
|
|
110
|
+
decisionTimeoutMs,
|
|
111
|
+
});
|
|
112
|
+
}, [
|
|
113
|
+
baseUrl,
|
|
114
|
+
verificationToken,
|
|
115
|
+
storage,
|
|
116
|
+
country,
|
|
117
|
+
documentType,
|
|
118
|
+
levelName,
|
|
119
|
+
externalId,
|
|
120
|
+
selfieRequired,
|
|
121
|
+
waitForDecision,
|
|
122
|
+
decisionTimeoutMs,
|
|
123
|
+
]);
|
|
124
|
+
|
|
125
|
+
const [state, setState] = useState<FlowState>(() => flow.getState());
|
|
126
|
+
|
|
127
|
+
useEffect(() => {
|
|
128
|
+
setState(flow.getState());
|
|
129
|
+
const unsubscribe = flow.subscribe((next) => {
|
|
130
|
+
setState(next);
|
|
131
|
+
handlers.current.onStateChange?.(next);
|
|
132
|
+
if (next.phase === 'finished') handlers.current.onComplete?.(next);
|
|
133
|
+
if (next.phase === 'failed' && next.error) handlers.current.onError?.(next.error);
|
|
134
|
+
});
|
|
135
|
+
|
|
136
|
+
// Cancels whatever is in flight, so a poll does not outlive the screen.
|
|
137
|
+
return () => {
|
|
138
|
+
unsubscribe();
|
|
139
|
+
flow.cancel();
|
|
140
|
+
};
|
|
141
|
+
}, [flow]);
|
|
142
|
+
|
|
143
|
+
const start = useCallback(
|
|
144
|
+
async (options?: { fresh?: boolean }) => {
|
|
145
|
+
await flow.start(options);
|
|
146
|
+
},
|
|
147
|
+
[flow]
|
|
148
|
+
);
|
|
149
|
+
|
|
150
|
+
useEffect(() => {
|
|
151
|
+
if (autoStart && flow.getState().phase === 'idle') void flow.start();
|
|
152
|
+
}, [autoStart, flow]);
|
|
153
|
+
|
|
154
|
+
const submit = useCallback(
|
|
155
|
+
async (file: FileInput) => {
|
|
156
|
+
await flow.submit(file);
|
|
157
|
+
},
|
|
158
|
+
[flow]
|
|
159
|
+
);
|
|
160
|
+
|
|
161
|
+
const capture = useCallback(
|
|
162
|
+
async (options?: { fromLibrary?: boolean }) => {
|
|
163
|
+
const step = flow.getState().currentStep;
|
|
164
|
+
if (!step) return;
|
|
165
|
+
try {
|
|
166
|
+
const file = await captureImage({
|
|
167
|
+
facing: STEP_FACING[step],
|
|
168
|
+
fromLibrary: options?.fromLibrary,
|
|
169
|
+
});
|
|
170
|
+
// Backing out of the camera is not a failure; leave the step waiting.
|
|
171
|
+
if (!file) return;
|
|
172
|
+
await flow.submit(file);
|
|
173
|
+
} catch (error) {
|
|
174
|
+
// A permission refusal comes from the picker, not the flow, so it has
|
|
175
|
+
// to be routed into the same place the UI already reads errors from.
|
|
176
|
+
handlers.current.onError?.(error as KycirisError);
|
|
177
|
+
setState((previous) => ({
|
|
178
|
+
...previous,
|
|
179
|
+
phase: 'failed',
|
|
180
|
+
busy: false,
|
|
181
|
+
error: error as KycirisError,
|
|
182
|
+
}));
|
|
183
|
+
}
|
|
184
|
+
},
|
|
185
|
+
[flow]
|
|
186
|
+
);
|
|
187
|
+
|
|
188
|
+
const refresh = useCallback(async () => {
|
|
189
|
+
await flow.refresh();
|
|
190
|
+
}, [flow]);
|
|
191
|
+
|
|
192
|
+
const reset = useCallback(async () => {
|
|
193
|
+
await flow.reset();
|
|
194
|
+
}, [flow]);
|
|
195
|
+
|
|
196
|
+
return { state, start, capture, submit, refresh, reset };
|
|
197
|
+
}
|