@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 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
+ }