@kyciris/core 0.1.2 → 1.1.0

package/README.md

@@ -1,224 +1,337 @@
 # @kyciris/core
 
-Core SDK package with UI-agnostic KYC (Know Your Customer) functions. Use this package if you want to build your own UI while leveraging Paytesy's verification services.
-
-## Installation
+The UI-agnostic client for the [KYCiris](https://kyciris.com) identity
+verification API. Zero runtime dependencies — it uses the platform's own
+`fetch`, `FormData` and `Blob`, so it runs unchanged on Node 18+, in browsers,
+and in React Native.
 
 ```bash
 pnpm add @kyciris/core
 ```
 
-## Usage
+## Quickstart
+
+Point everything at the **sandbox gateway** while you build — the URL is in your
+onboarding details. Sandbox and production behave identically; only the data is
+throwaway. (The interactive `/docs` reference is served by a gateway running in
+development mode only, so it is off on the hosted sandbox — ask us for the
+endpoint reference if you need more than this page.)
+
+### 1. A token route on your backend
+
+This is the one piece you have to write, and the reason is worth a sentence:
+your API key can reach every identity in the project, so it stays on your
+server. What the client gets is a token scoped to one end user.
 
-### Initialization
+```ts
+// Express
+import express from 'express';
+import { createKycirisClient } from '@kyciris/core';
 
-```typescript
-import { createKYCClient } from '@kyciris/core';
+const kyciris = createKycirisClient({
+  baseUrl: process.env.KYCIRIS_BASE_URL, // your sandbox gateway
+  apiKey: process.env.KYCIRIS_API_KEY, // server-side only
+});
 
-const kyc = createKYCClient({
-  apiKey: 'your-api-key',
-  baseUrl: 'http://localhost:3000', // Your KYC API base URL
+app.post('/api/kyc/token', requireYourOwnAuth, async (req, res) => {
+  // `externalId` is YOUR id for this user. Take it from the session, never
+  // from the request body -- otherwise anyone can mint a token for anyone.
+  const { token } = await kyciris.verifications.createToken(req.user.id);
+  res.json({ token });
 });
 ```
 
-### Creating a Verification Token
+```ts
+// Next.js app router — app/api/kyc/token/route.ts
+import { createKycirisClient } from '@kyciris/core';
 
-Before starting verification, create a token for secure API access:
+const kyciris = createKycirisClient({
+  baseUrl: process.env.KYCIRIS_BASE_URL,
+  apiKey: process.env.KYCIRIS_API_KEY,
+});
 
-```typescript
-const { token, expiresIn } = await kyc.createVerificationToken(
-  'user-123', // externalId
-  '3' // expiry in hours (optional, default: 3)
-);
+export async function POST() {
+  const user = await requireYourOwnAuth();
+  const { token } = await kyciris.verifications.createToken(user.id);
+  return Response.json({ token });
+}
 ```
 
-### Starting a Verification
+### 2. The flow, in your app
 
-```typescript
-const session = await kyc.startVerification({
-  documentType: 'IDENTITY_CARD', // or 'DRIVING_LICENSE'
-  country: 'MZ', // Country code: MZ, AO, PT, etc.
-  identityId: 'optional-existing-identity-id', // optional
-  externalId: 'optional-external-ref', // optional
-});
+```tsx
+// React (@kyciris/web) — the same shape in React Native (@kyciris/mobile)
+import { KycirisVerification } from '@kyciris/web';
 
-console.log(session.verificationId);
-console.log(session.status); // 'PENDING'
+<KycirisVerification
+  baseUrl={process.env.NEXT_PUBLIC_KYCIRIS_BASE_URL}
+  verificationToken={() =>
+    fetch('/api/kyc/token')
+      .then((r) => r.json())
+      .then((b) => b.token)
+  }
+  country="AO"
+  documentType="ID_CARD"
+  levelName="basic-kyc"
+  onComplete={(state) => console.log(state.status, state.outcome)}
+/>;
 ```
 
-### Uploading Documents
+Passing a **function** rather than a string means an expired token is re-fetched
+instead of failing every request from then on.
 
-After starting verification, upload front and back of the document:
+### 3. Learn the result from a webhook, not from polling
 
-```typescript
-// Upload front of document
-const frontResult = await kyc.uploadDocument({
-  verificationId: session.verificationId,
-  type: 'front',
-  imageData: 'base64-encoded-image-data',
-});
+The component tells the user what happened. Your backend should hear it from a
+webhook, because a verification sent to a human reviewer can sit for hours:
 
-// Upload back of document
-const backResult = await kyc.uploadDocument({
-  verificationId: session.verificationId,
-  type: 'back',
-  imageData: 'base64-encoded-image-data',
+```ts
+await kyciris.webhooks.create({
+  url: 'https://your-app.example.com/hooks/kyciris',
+  eventTypes: ['*'], // every event, including ones added later
 });
 ```
 
-### Uploading Selfie
+The URL must be `https` with a public hostname — the gateway resolves it and
+refuses anything private.
+
+### Checklist before you go live
+
+- [ ] The API key is only ever read on the server (`process.env`, never
+      `NEXT_PUBLIC_*` / `EXPO_PUBLIC_*`). The SDK throws if it reaches a client.
+- [ ] `externalId` comes from your session, not from the request.
+- [ ] Your browser origin is in the gateway's `ALLOWED_ORIGINS`, or every
+      request fails CORS before it is even authenticated.
+- [ ] You branch on `outcome`, not `status` (see below).
+- [ ] A webhook endpoint is registered and reachable.
+
+## Two credentials, two places
+
+This is the part worth getting right.
+
+|          | `apiKey`                                 | `verificationToken`                |
+| -------- | ---------------------------------------- | ---------------------------------- |
+| Scope    | The whole project — every identity in it | One end user's verification        |
+| Lives    | On your server                           | In the app or page                 |
+| Header   | `X-API-Key`                              | `x-verification-token`             |
+| Lifetime | Until revoked                            | 10m by default; the gateway decides |
 
-```typescript
-const selfieResult = await kyc.uploadSelfie({
-  verificationId: session.verificationId,
-  imageData: 'base64-encoded-selfie-image',
+Constructing a client with `apiKey` inside a browser or React Native app
+**throws** (`CREDENTIAL_MISUSE`). A key in a shipped bundle is a key the end
+user has.
+
+```ts
+import { createKycirisClient } from '@kyciris/core';
+
+// --- On your server
+const server = createKycirisClient({
+  baseUrl: 'https://api.kyciris.com',
+  apiKey: process.env.KYCIRIS_API_KEY,
+});
+
+const { token } = await server.verifications.createToken('user-123');
+// hand `token` to the client
+
+// --- In the app
+const client = createKycirisClient({
+  baseUrl: 'https://api.kyciris.com',
+  verificationToken: token,
 });
 ```
 
-### Checking Status
-
-```typescript
-// Get current status
-const status = await kyc.getStatus(session.verificationId);
-console.log(status.status); // 'PENDING' | 'PROCESSING' | 'APPROVED' | 'REJECTED'
-console.log(status.ocrData); // Extracted document data
-console.log(status.faceMatchScore); // Face match similarity (0-1)
-
-// Poll until completion
-const finalStatus = await kyc.pollStatus(
-  session.verificationId,
-  3000, // poll interval in ms (optional, default: 3000)
-  120000 // timeout in ms (optional, default: 120000)
-);
+Pass a **function** as `verificationToken` to have it re-fetched when needed,
+rather than failing every request once it expires:
+
+```ts
+createKycirisClient({
+  baseUrl,
+  verificationToken: () =>
+    fetch('/api/kyc/token')
+      .then((r) => r.json())
+      .then((b) => b.token),
+});
 ```
 
-### Listening to Events
+## Running a verification
+
+`levelName` is required and must name an **active verification level** of your
+project: the level says which documents are accepted and whether a selfie is
+needed, and the gateway has no default. Create one once, from your backend:
+
+```ts
+await client.levels.create({
+  name: 'basic-kyc',
+  definition: {
+    requiredSteps: [
+      { step: 'IDENTITY_DOCUMENT', required: true, documents: [{ country: 'AO', types: ['ID_CARD'] }] },
+      { step: 'SELFIE', required: true },
+    ],
+  },
+});
+```
 
-```typescript
-// Subscribe to status changes
-const unsubscribe = kyc.onEvent((event) => {
-  if (event.type === 'statusChanged') {
-    console.log('Status changed to:', event.status);
-  } else if (event.type === 'error') {
-    console.log('Error:', event.error);
-  }
+```ts
+const { verificationId } = await client.verifications.start({
+  country: 'AO',
+  documentType: 'ID_CARD',
+  levelName: 'basic-kyc',
 });
 
-// Unsubscribe when done
-unsubscribe();
+await client.verifications.uploadDocument(verificationId, 'front', frontImage);
+await client.verifications.uploadDocument(verificationId, 'back', backImage);
+await client.verifications.uploadSelfie(verificationId, selfieImage);
+
+const result = await client.verifications.waitForResult(verificationId);
+console.log(result.status, result.outcome);
 ```
 
-## API Reference
+Images can be a `Blob`/`File`, raw bytes (`{ data: Uint8Array }`), a React
+Native `{ uri }`, a `data:` URI, or bare base64. The bytes are checked against
+the same magic-byte test the gateway applies, so a PDF renamed `.jpg` fails
+before the upload rather than after it.
 
-### Interfaces
+### Both document sides are required
 
-#### KYCCredentials
+All three catalog documents are two-sided, and the gateway only queues OCR once
+both `documentFrontPath` and `documentBackPath` exist. A flow that collects
+only the front leaves the verification sitting in `PENDING` with nothing
+running.
 
-```typescript
-{
-  apiKey: string; // Your API key for authentication
-  baseUrl: string; // Base URL of your KYC API
-}
+### The flow controller
+
+`VerificationFlow` is the sequencing above as a state machine — which step is
+next, what a resumed flow skips, when to poll. It is what `@kyciris/mobile` and
+`@kyciris/web` are built on.
+
+```ts
+import { VerificationFlow } from '@kyciris/core';
+
+const flow = new VerificationFlow(client, {
+  country: 'AO',
+  documentType: 'ID_CARD',
+  levelName: 'basic-kyc',
+});
+flow.subscribe((state) => render(state));
+
+await flow.start(); // or resumes what is in storage
+await flow.submit(image); // uploads state.currentStep, advances
 ```
 
-#### StartVerificationParams
+Failures land in `state.error` rather than rejecting, so a button handler needs
+no try/catch. `flow.cancel()` stops in-flight work on unmount.
 
-```typescript
-{
-  documentType: 'IDENTITY_CARD' | 'DRIVING_LICENSE';
-  country: string;      // Country code (e.g., 'MZ', 'AO', 'PT')
-  identityId?: string;  // Optional existing identity ID
-  externalId?: string;  // Optional external reference
-}
+### Resuming an interrupted flow
+
+Give the client a `storage` adapter and it remembers which verification is in
+progress:
+
+```ts
+import { createKycirisClient, createMemoryStorage } from '@kyciris/core';
+
+const client = createKycirisClient({ baseUrl, verificationToken, storage });
 ```
 
-#### VerificationStatus
-
-```typescript
-{
-  verificationId: string;
-  status: 'PENDING' | 'PROCESSING' | 'APPROVED' | 'REJECTED';
-  faceMatchScore?: number;  // Similarity score 0-1
-  ocrData?: {
-    fullName?: string;
-    idNumber?: string;
-    birthDate?: string;
-    expiryDate?: string;
-    // ... additional country-specific fields
-  };
-  createdAt: string;
-  updatedAt: string;
-}
+Progress itself is never trusted to local state — it is read back from the
+files the gateway actually holds (`GET /v1/verification/:id/media`), so it is
+right after a reinstall, on a second device, and when an upload succeeded but
+its response never arrived.
+
+```ts
+const progress = await client.verifications.getProgress();
+// { missingSteps: ['document_back', 'selfie'], isComplete: false, ... }
+
+await client.verifications.uploadStep({ step: 'document_back', file });
+// skipped: true, if it turns out to be there already
 ```
 
-## Supported Countries
+Only identifiers are stored. **The verification token is never written to
+storage** — it is a bearer credential, and where it lives is your decision.
 
-- **MZ** (Mozambique)
-- **AO** (Angola)
-- **PT** (Portugal)
+## Server-side
 
-## Error Handling
+With an API key, the client also reaches the review and operations endpoints:
 
-All methods throw `KYCSdkError` with the following properties:
+```ts
+const page = await server.verifications.list({ outcome: 'NEEDS_REVIEW' });
+const summary = await server.verifications.summary();
+const history = await server.verifications.events(verificationId);
 
-```typescript
-try {
-  await kyc.startVerification({ ... });
-} catch (error) {
-  if (error instanceof KYCSdkError) {
-    console.log(error.code);      // Error code
-    console.log(error.statusCode); // HTTP status code
-    console.log(error.message);   // Human-readable message
-  }
-}
+await server.verifications.decide(verificationId, {
+  decision: 'REJECTED',
+  reason: 'Document photo does not match the selfie.',
+});
 ```
 
-## Example
+Plus `identities`, `levels`, `media`, `ocr`, `webhooks` and `analytics`.
 
-```typescript
-import { createKYCClient } from '@kyciris/core';
+Images come out through a two-step, single-use flow — a 60-second token for one
+file, then the bytes:
 
-async function runKYC() {
-  const kyc = createKYCClient({
-    apiKey: process.env.KYC_API_KEY,
-    baseUrl: 'http://localhost:3000',
-  });
+```ts
+const response = await server.media.download(verificationId, 'document-front');
+```
 
-  // Start verification
-  const session = await kyc.startVerification({
-    documentType: 'IDENTITY_CARD',
-    country: 'MZ',
-    externalId: 'user-12345',
-  });
+## Status, and what it means
 
-  // Listen for events
-  kyc.onEvent((event) => {
-    console.log('KYC Event:', event);
-  });
+`status` is the pipeline's state machine. `outcome` is what a finished
+verification _means_, and it exists because `REJECTED` is written for two
+different events:
 
-  // Upload documents (you would get imageData from your UI)
-  await kyc.uploadDocument({
-    verificationId: session.verificationId,
-    type: 'front',
-    imageData: 'base64-encoded-image...',
-  });
+| `outcome`          | Meaning                                                      |
+| ------------------ | ------------------------------------------------------------ |
+| `APPROVED`         | Passed.                                                      |
+| `REJECTED`         | A real decision. Retrying will not change it.                |
+| `FAILED_TECHNICAL` | Our pipeline broke. Not the user's fault — `reanalyze()` it. |
+| `NEEDS_REVIEW`     | A person should look at the images.                          |
 
-  await kyc.uploadDocument({
-    verificationId: session.verificationId,
-    type: 'back',
-    imageData: 'base64-encoded-image...',
-  });
+Branch on `outcome`, not on `status`, when deciding what to tell a user.
 
-  // Upload selfie
-  await kyc.uploadSelfie({
-    verificationId: session.verificationId,
-    imageData: 'base64-encoded-selfie...',
-  });
+For anything longer than a spinner, use the webhooks rather than polling: a
+`REVIEW` sits with a human, potentially for hours.
 
-  // Wait for completion
-  const result = await kyc.pollStatus(session.verificationId);
-  console.log('Verification result:', result.status);
-}
+## Errors
+
+Everything thrown is a `KycirisError` with a `code` you can branch on, the
+gateway's `requestId`, and nothing from the request — the headers hold the
+credentials, and an error object is what gets logged whole.
 
-runKYC();
+```ts
+import { isKycirisError } from '@kyciris/core';
+
+try {
+  await client.verifications.start({
+    country: 'AO',
+    documentType: 'ID_CARD',
+    levelName: 'basic-kyc',
+  });
+} catch (error) {
+  if (isKycirisError(error) && error.code === 'UNAUTHORIZED') {
+    // the token expired — fetch a new one
+  }
+}
 ```
+
+Transient failures (429, 5xx, network) are retried with jittered backoff.
+Uploads are **not**, because a POST that timed out may well have landed; a 429
+is, because the gateway rejected it before doing any work.
+
+## Configuration
+
+| Option                         | Default |                                                                      |
+| ------------------------------ | ------- | -------------------------------------------------------------------- |
+| `baseUrl`                      | —       | Origin of the gateway. Plaintext `http` to a remote host is refused. |
+| `apiKey` / `verificationToken` | —       | One is required.                                                     |
+| `apiVersion`                   | `v1`    | URI version segment.                                                 |
+| `timeoutMs`                    | `30000` | Per attempt.                                                         |
+| `maxRetries`                   | `2`     | Retries of a failed attempt.                                         |
+| `storage`                      | —       | Enables resuming.                                                    |
+| `fetch`                        | global  | A custom implementation, for proxies or tests.                       |
+| `headers`                      | —       | Added to every request; cannot override the credentials.             |
+| `allowInsecureBaseUrl`         | `false` | Permits `http` to a private network.                                 |
+| `allowApiKeyInUntrustedClient` | `false` | Only for a trusted first-party console.                              |
+
+## Supported documents
+
+`AO`/`ID_CARD`, `AO`/`DRIVING_LICENSE`, `MZ`/`ID_CARD`. An unsupported pair is
+refused client-side, naming what the country does support, rather than costing
+a round trip.