@kyvshield/rest-sdk 1.0.0

package/README.md

@@ -0,0 +1,372 @@
+# @kyvshield/rest-sdk
+
+Fully typed Node.js / TypeScript SDK for the [KyvShield](https://kyvshield.com) KYC REST API.
+
+Requires **Node.js 18+** (uses native `fetch` and `crypto`).
+
+---
+
+## Installation
+
+```bash
+npm install @kyvshield/rest-sdk
+# or
+yarn add @kyvshield/rest-sdk
+# or
+pnpm add @kyvshield/rest-sdk
+```
+
+---
+
+## Quick start
+
+```typescript
+import { KyvShield } from '@kyvshield/rest-sdk';
+
+const kyv = new KyvShield('your-api-key');
+
+const result = await kyv.verify({
+  steps: ['selfie', 'recto', 'verso'],
+  target: 'SN-CIN',
+  language: 'fr',
+  challengeMode: 'standard',
+  requireFaceMatch: true,
+  images: {
+    // key = {step}_{challenge}
+    selfie_center_face:    './images/selfie.jpg',
+    selfie_close_eyes:     './images/selfie_eyes_closed.jpg',
+    recto_center_document: './images/recto.jpg',
+    recto_tilt_left:       './images/recto_tilt_left.jpg',
+    verso_center_document: './images/verso.jpg',
+  },
+});
+
+if (result.overall_status === 'pass') {
+  console.log('KYC passed!', result.session_id);
+} else {
+  console.warn('KYC rejected:', result.steps.map(s => s.user_messages).flat());
+}
+```
+
+---
+
+## API Reference
+
+### `new KyvShield(apiKey, baseUrl?)`
+
+| Parameter | Type     | Default                                         | Description                    |
+|-----------|----------|-------------------------------------------------|--------------------------------|
+| `apiKey`  | `string` | —                                               | Your KyvShield API key         |
+| `baseUrl` | `string` | `https://kyvshield-naruto.innolinkcloud.com`    | Override for staging/local use |
+
+```typescript
+// Production (default)
+const kyv = new KyvShield('your-api-key');
+
+// Local development
+const kyv = new KyvShield('your-api-key', 'http://localhost:8080');
+```
+
+---
+
+### `kyv.getChallenges()`
+
+Returns the available challenge names grouped by type (`document` / `selfie`) and mode (`minimal` / `standard` / `strict`).
+
+Use this to discover which image keys you need to provide for a given `challengeMode`.
+
+```typescript
+const { challenges } = await kyv.getChallenges();
+
+// challenges.document.standard => ['center_document', 'tilt_left', 'tilt_right']
+// challenges.selfie.minimal    => ['center_face', 'close_eyes']
+```
+
+**Return type:** [`ChallengesResponse`](#challengesresponse)
+
+---
+
+### `kyv.verify(options)`
+
+Submit a KYC verification request. Reads image files from disk and sends them as multipart form data.
+
+```typescript
+const result = await kyv.verify({
+  steps: ['selfie', 'recto'],
+  target: 'SN-CIN',
+  language: 'en',
+  challengeMode: 'minimal',
+  requireFaceMatch: true,
+  kycIdentifier: 'user-ref-42',
+  images: {
+    selfie_center_face:    './selfie.jpg',
+    recto_center_document: './recto.jpg',
+  },
+});
+```
+
+**Options:** [`VerifyOptions`](#verifyoptions)
+
+**Return type:** [`KycResponse`](#kycresponse)
+
+---
+
+### `KyvShield.verifyWebhookSignature(payload, apiKey, signatureHeader)`
+
+Static method. Validates an incoming KyvShield webhook using HMAC-SHA256.
+
+```typescript
+// Express example
+import express from 'express';
+import { KyvShield } from '@kyvshield/rest-sdk';
+
+const app = express();
+
+app.post('/webhook', express.raw({ type: '*/*' }), (req, res) => {
+  const valid = KyvShield.verifyWebhookSignature(
+    req.body,                                        // Buffer
+    process.env.KYVSHIELD_API_KEY!,
+    req.headers['x-kyvshield-signature'] as string,
+  );
+
+  if (!valid) return res.status(401).send('Invalid signature');
+
+  const event = JSON.parse(req.body.toString());
+  console.log('Webhook event:', event);
+  res.sendStatus(200);
+});
+```
+
+| Parameter           | Type     | Description                                           |
+|---------------------|----------|-------------------------------------------------------|
+| `payload`           | `Buffer` | Raw request body                                      |
+| `apiKey`            | `string` | Your KyvShield API key                                |
+| `signatureHeader`   | `string` | Value of `X-KyvShield-Signature` from the HTTP header |
+
+Returns `true` if the signature is valid, `false` otherwise.
+
+---
+
+## Types Reference
+
+### `VerifyOptions`
+
+```typescript
+interface VerifyOptions {
+  /** Steps to execute in order. */
+  steps: Step[];                          // e.g. ['selfie', 'recto', 'verso']
+
+  /** Document type. */
+  target: DocumentTarget;                 // e.g. 'SN-CIN'
+
+  /** Response language. Default: 'fr' */
+  language?: Language;                    // 'fr' | 'en' | 'wo'
+
+  /** Global challenge intensity. Default: 'standard' */
+  challengeMode?: ChallengeMode;          // 'minimal' | 'standard' | 'strict'
+
+  /** Per-step overrides */
+  selfieChallengeMode?: ChallengeMode;
+  rectoChallengeMode?: ChallengeMode;
+  versoChallengeMode?: ChallengeMode;
+
+  /** Whether to match selfie face against document photo. Default: false */
+  requireFaceMatch?: boolean;
+
+  /** Your internal reference ID, echoed back in the response. */
+  kycIdentifier?: string;
+
+  /**
+   * Map of images to submit.
+   * Key format: `{step}_{challenge}`, e.g. 'recto_center_document'
+   * Value: path to the image file on disk.
+   */
+  images: Record<string, string>;
+}
+```
+
+### `KycResponse`
+
+```typescript
+interface KycResponse {
+  success: boolean;
+  session_id: string;
+  overall_status: 'pass' | 'reject';
+  overall_confidence: number;        // 0–1
+  processing_time_ms: number;
+  face_verification?: FaceVerification;
+  steps: StepResult[];
+}
+```
+
+### `StepResult`
+
+```typescript
+interface StepResult {
+  step_index: number;
+  step_type: 'selfie' | 'recto' | 'verso';
+  success: boolean;
+  processing_time_ms: number;
+
+  liveness: {
+    is_live: boolean;
+    score: number;                    // 0–1
+    confidence: 'HIGH' | 'MEDIUM' | 'LOW';
+  };
+
+  verification: {
+    is_authentic: boolean;
+    confidence: number;               // 0–1
+    checks_passed: string[];
+    fraud_indicators: string[];
+    warnings: string[];
+    issues: string[];
+  };
+
+  user_messages: string[];
+
+  // Document steps (recto / verso) only:
+  aligned_document?: string;          // base64 JPEG
+  extraction?: ExtractionField[];
+  extracted_photos?: ExtractedPhoto[];
+
+  // Selfie step only:
+  captured_image?: string;            // base64 JPEG
+}
+```
+
+### `ExtractionField`
+
+```typescript
+interface ExtractionField {
+  key: string;
+  document_key: string;
+  label: string;
+  value: string;
+  display_priority: number;
+  icon?: string;
+}
+```
+
+### `ExtractedPhoto`
+
+```typescript
+interface ExtractedPhoto {
+  image: string;          // base64 JPEG
+  confidence: number;     // 0–1
+  bbox: number[];         // [x, y, width, height]
+  area: number;
+  width: number;
+  height: number;
+}
+```
+
+### `FaceVerification`
+
+```typescript
+interface FaceVerification {
+  is_match: boolean;
+  similarity_score: number;   // 0–100
+}
+```
+
+### `ChallengesResponse`
+
+```typescript
+interface ChallengesResponse {
+  challenges: {
+    document: { minimal: string[]; standard: string[]; strict: string[] };
+    selfie:   { minimal: string[]; standard: string[]; strict: string[] };
+  };
+}
+```
+
+---
+
+## Error handling
+
+All API errors throw a `KyvShieldError`:
+
+```typescript
+import { KyvShield, KyvShieldError } from '@kyvshield/rest-sdk';
+
+try {
+  const result = await kyv.verify({ ... });
+} catch (e) {
+  if (e instanceof KyvShieldError) {
+    console.error('Status code:', e.statusCode);   // e.g. 401, 422, 500
+    console.error('Body:', e.body);                // parsed JSON body when available
+    console.error('Message:', e.message);
+  }
+}
+```
+
+The SDK also throws `KyvShieldError` (without a `statusCode`) for:
+- Empty API key in the constructor
+- Empty `steps` array
+- Empty `target` string
+- Empty `images` map
+- Image file path that does not exist on disk
+
+---
+
+## Building
+
+```bash
+npm install
+npm run build      # outputs to ./dist
+npm run lint       # type-check only, no emit
+npm run build:watch
+```
+
+---
+
+## Running the test suite
+
+Ensure the KyvShield backend is running locally on port 8080, then:
+
+```bash
+npx ts-node --esm test.ts
+```
+
+The test script covers:
+- Constructor validation
+- Webhook signature verification (HMAC-SHA256, timing-safe comparison)
+- `VerifyOptions` validation (no network)
+- `getChallenges()` (network)
+- `verify()` with a single recto step (network)
+- `verify()` with recto + verso steps (network)
+
+---
+
+## Challenge modes
+
+| Mode       | Document challenges                                                        | Selfie challenges                                               |
+|------------|----------------------------------------------------------------------------|-----------------------------------------------------------------|
+| `minimal`  | `center_document`                                                          | `center_face`, `close_eyes`                                     |
+| `standard` | `center_document`, `tilt_left`, `tilt_right`                               | `center_face`, `close_eyes`, `turn_left`, `turn_right`          |
+| `strict`   | `center_document`, `tilt_left`, `tilt_right`, `tilt_forward`, `tilt_back` | `center_face`, `close_eyes`, `turn_left`, `turn_right`, `smile`, `look_up`, `look_down` |
+
+The image map key for each image is `{step}_{challenge}`, e.g.:
+- `recto_center_document`
+- `recto_tilt_left`
+- `selfie_center_face`
+- `selfie_turn_right`
+
+---
+
+## Supported document targets
+
+| Value                 | Document                        |
+|-----------------------|---------------------------------|
+| `SN-CIN`              | Carte d'Identité Nationale (SN) |
+| `SN-PASSPORT`         | Passeport sénégalais            |
+| `SN-DRIVER-LICENCE`   | Permis de conduire (SN)         |
+
+Custom target strings are also accepted.
+
+---
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,163 @@
+/**
+ * KyvShield REST SDK — Node.js / TypeScript
+ *
+ * A fully typed SDK for the KyvShield KYC REST API.
+ * Requires Node.js 18+ (uses native fetch and crypto).
+ *
+ * @example
+ * ```ts
+ * import { KyvShield } from '@kyvshield/rest-sdk';
+ *
+ * const kyv = new KyvShield('your-api-key');
+ *
+ * const result = await kyv.verify({
+ *   steps: ['selfie', 'recto', 'verso'],
+ *   target: 'SN-CIN',
+ *   language: 'fr',
+ *   challengeMode: 'standard',
+ *   requireFaceMatch: true,
+ *   images: {
+ *     selfie_center_face:    './selfie.jpg',
+ *     recto_center_document: './recto.jpg',
+ *     verso_center_document: './verso.jpg',
+ *   },
+ * });
+ *
+ * console.log(result.overall_status); // 'pass' | 'reject'
+ * ```
+ */
+import type { ChallengesResponse, KycResponse, KyvShieldErrorDetails, VerifyOptions } from './types.js';
+export * from './types.js';
+/**
+ * Error thrown when the KyvShield API returns a non-2xx response
+ * or when a request cannot be completed.
+ */
+export declare class KyvShieldError extends Error {
+    readonly statusCode?: number;
+    readonly body?: unknown;
+    constructor(message: string, details?: KyvShieldErrorDetails);
+}
+/**
+ * KyvShield SDK client.
+ *
+ * Instantiate once and reuse across your application.
+ */
+export declare class KyvShield {
+    private readonly apiKey;
+    private readonly baseUrl;
+    /**
+     * Create a new KyvShield client.
+     *
+     * @param apiKey  - Your KyvShield API key (sent as the `X-API-Key` header).
+     * @param baseUrl - Optional base URL override. Defaults to the production endpoint.
+     *
+     * @example
+     * ```ts
+     * // Production
+     * const kyv = new KyvShield('your-api-key');
+     *
+     * // Local / staging
+     * const kyv = new KyvShield('your-api-key', 'http://localhost:8080');
+     * ```
+     */
+    constructor(apiKey: string, baseUrl?: string);
+    /**
+     * Retrieve the list of available challenges for each mode and step type.
+     *
+     * Useful for dynamically building the image map to pass to {@link verify}.
+     *
+     * @returns A {@link ChallengesResponse} object describing all available challenges.
+     *
+     * @example
+     * ```ts
+     * const { challenges } = await kyv.getChallenges();
+     * console.log(challenges.selfie.standard);
+     * // ['center_face', 'close_eyes', 'turn_left', 'turn_right']
+     * ```
+     */
+    getChallenges(): Promise<ChallengesResponse>;
+    /**
+     * Submit a KYC verification request.
+     *
+     * The SDK reads each image from disk, packages everything as a
+     * `multipart/form-data` request, and returns the fully typed response.
+     *
+     * @param options - Verification options. See {@link VerifyOptions} for full documentation.
+     * @returns A {@link KycResponse} with per-step results and an overall decision.
+     *
+     * @throws {@link KyvShieldError} on HTTP errors or missing image files.
+     *
+     * @example
+     * ```ts
+     * const result = await kyv.verify({
+     *   steps: ['selfie', 'recto'],
+     *   target: 'SN-CIN',
+     *   language: 'en',
+     *   challengeMode: 'minimal',
+     *   requireFaceMatch: true,
+     *   images: {
+     *     selfie_center_face:    './selfie.jpg',
+     *     recto_center_document: './recto.jpg',
+     *   },
+     * });
+     *
+     * if (result.overall_status === 'pass') {
+     *   console.log('Verification passed!', result.session_id);
+     * } else {
+     *   console.warn('Verification rejected', result.steps.map(s => s.user_messages));
+     * }
+     * ```
+     */
+    verify(options: VerifyOptions): Promise<KycResponse>;
+    /**
+     * Verify an incoming webhook signature.
+     *
+     * KyvShield signs webhook payloads with HMAC-SHA256 using your API key.
+     * Call this before processing any webhook to confirm it came from KyvShield.
+     *
+     * @param payload         - Raw request body as a `Buffer`.
+     * @param apiKey          - Your KyvShield API key (same one used to create the client).
+     * @param signatureHeader - Value of the `X-KyvShield-Signature` header sent with the webhook.
+     * @returns `true` if the signature is valid, `false` otherwise.
+     *
+     * @example
+     * ```ts
+     * // Express example
+     * app.post('/webhook', express.raw({ type: '*\/*' }), (req, res) => {
+     *   const valid = KyvShield.verifyWebhookSignature(
+     *     req.body,
+     *     process.env.KYVSHIELD_API_KEY!,
+     *     req.headers['x-kyvshield-signature'] as string,
+     *   );
+     *
+     *   if (!valid) return res.status(401).send('Invalid signature');
+     *
+     *   // process webhook ...
+     *   res.sendStatus(200);
+     * });
+     * ```
+     */
+    static verifyWebhookSignature(payload: Buffer, apiKey: string, signatureHeader: string): boolean;
+    /** Build the common headers used by all non-multipart requests. */
+    private buildHeaders;
+    /**
+     * Validate required fields in {@link VerifyOptions} before sending.
+     * Throws a descriptive {@link KyvShieldError} on the first problem found.
+     */
+    private validateVerifyOptions;
+    /**
+     * Build the `multipart/form-data` body from {@link VerifyOptions}.
+     *
+     * Text fields are appended first, followed by binary image fields.
+     */
+    private buildFormData;
+    /**
+     * Throw a {@link KyvShieldError} when the HTTP response is not successful (2xx).
+     * Tries to parse JSON error details from the body when available.
+     */
+    private assertOk;
+    /** Return a MIME type based on file extension. Defaults to `image/jpeg`. */
+    private guessMimeType;
+}
+export default KyvShield;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAOH,OAAO,KAAK,EACV,kBAAkB,EAClB,WAAW,EACX,qBAAqB,EACrB,aAAa,EACd,MAAM,YAAY,CAAC;AAEpB,cAAc,YAAY,CAAC;AAS3B;;;GAGG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,SAAgB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpC,SAAgB,IAAI,CAAC,EAAE,OAAO,CAAC;gBAEnB,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB;CAM7D;AAID;;;;GAIG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC;;;;;;;;;;;;;;OAcG;gBACS,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,MAAyB;IAW9D;;;;;;;;;;;;;OAaG;IACG,aAAa,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAYlD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACG,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,CAAC;IAwB1D;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,MAAM,CAAC,sBAAsB,CAC3B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,eAAe,EAAE,MAAM,GACtB,OAAO;IA0BV,mEAAmE;IACnE,OAAO,CAAC,YAAY;IAOpB;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IAsB7B;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAkDrB;;;OAGG;YACW,QAAQ;IAgBtB,4EAA4E;IAC5E,OAAO,CAAC,aAAa;CAWtB;AAED,eAAe,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,309 @@
+/**
+ * KyvShield REST SDK — Node.js / TypeScript
+ *
+ * A fully typed SDK for the KyvShield KYC REST API.
+ * Requires Node.js 18+ (uses native fetch and crypto).
+ *
+ * @example
+ * ```ts
+ * import { KyvShield } from '@kyvshield/rest-sdk';
+ *
+ * const kyv = new KyvShield('your-api-key');
+ *
+ * const result = await kyv.verify({
+ *   steps: ['selfie', 'recto', 'verso'],
+ *   target: 'SN-CIN',
+ *   language: 'fr',
+ *   challengeMode: 'standard',
+ *   requireFaceMatch: true,
+ *   images: {
+ *     selfie_center_face:    './selfie.jpg',
+ *     recto_center_document: './recto.jpg',
+ *     verso_center_document: './verso.jpg',
+ *   },
+ * });
+ *
+ * console.log(result.overall_status); // 'pass' | 'reject'
+ * ```
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import FormData from 'form-data';
+export * from './types.js';
+// ─── Constants ────────────────────────────────────────────────────────────────
+const DEFAULT_BASE_URL = 'https://kyvshield-naruto.innolinkcloud.com';
+const API_VERSION = '/api/v1';
+// ─── Error class ─────────────────────────────────────────────────────────────
+/**
+ * Error thrown when the KyvShield API returns a non-2xx response
+ * or when a request cannot be completed.
+ */
+export class KyvShieldError extends Error {
+    statusCode;
+    body;
+    constructor(message, details) {
+        super(message);
+        this.name = 'KyvShieldError';
+        this.statusCode = details?.statusCode;
+        this.body = details?.body;
+    }
+}
+// ─── SDK Class ────────────────────────────────────────────────────────────────
+/**
+ * KyvShield SDK client.
+ *
+ * Instantiate once and reuse across your application.
+ */
+export class KyvShield {
+    apiKey;
+    baseUrl;
+    /**
+     * Create a new KyvShield client.
+     *
+     * @param apiKey  - Your KyvShield API key (sent as the `X-API-Key` header).
+     * @param baseUrl - Optional base URL override. Defaults to the production endpoint.
+     *
+     * @example
+     * ```ts
+     * // Production
+     * const kyv = new KyvShield('your-api-key');
+     *
+     * // Local / staging
+     * const kyv = new KyvShield('your-api-key', 'http://localhost:8080');
+     * ```
+     */
+    constructor(apiKey, baseUrl = DEFAULT_BASE_URL) {
+        if (!apiKey || apiKey.trim() === '') {
+            throw new KyvShieldError('apiKey must be a non-empty string');
+        }
+        this.apiKey = apiKey;
+        // Normalise: remove trailing slash so we can always append '/api/v1/...'
+        this.baseUrl = baseUrl.replace(/\/+$/, '');
+    }
+    // ── Public methods ──────────────────────────────────────────────────────────
+    /**
+     * Retrieve the list of available challenges for each mode and step type.
+     *
+     * Useful for dynamically building the image map to pass to {@link verify}.
+     *
+     * @returns A {@link ChallengesResponse} object describing all available challenges.
+     *
+     * @example
+     * ```ts
+     * const { challenges } = await kyv.getChallenges();
+     * console.log(challenges.selfie.standard);
+     * // ['center_face', 'close_eyes', 'turn_left', 'turn_right']
+     * ```
+     */
+    async getChallenges() {
+        const url = `${this.baseUrl}${API_VERSION}/challenges`;
+        const response = await fetch(url, {
+            method: 'GET',
+            headers: this.buildHeaders(),
+        });
+        await this.assertOk(response);
+        return response.json();
+    }
+    /**
+     * Submit a KYC verification request.
+     *
+     * The SDK reads each image from disk, packages everything as a
+     * `multipart/form-data` request, and returns the fully typed response.
+     *
+     * @param options - Verification options. See {@link VerifyOptions} for full documentation.
+     * @returns A {@link KycResponse} with per-step results and an overall decision.
+     *
+     * @throws {@link KyvShieldError} on HTTP errors or missing image files.
+     *
+     * @example
+     * ```ts
+     * const result = await kyv.verify({
+     *   steps: ['selfie', 'recto'],
+     *   target: 'SN-CIN',
+     *   language: 'en',
+     *   challengeMode: 'minimal',
+     *   requireFaceMatch: true,
+     *   images: {
+     *     selfie_center_face:    './selfie.jpg',
+     *     recto_center_document: './recto.jpg',
+     *   },
+     * });
+     *
+     * if (result.overall_status === 'pass') {
+     *   console.log('Verification passed!', result.session_id);
+     * } else {
+     *   console.warn('Verification rejected', result.steps.map(s => s.user_messages));
+     * }
+     * ```
+     */
+    async verify(options) {
+        this.validateVerifyOptions(options);
+        const form = this.buildFormData(options);
+        const url = `${this.baseUrl}${API_VERSION}/kyc/verify`;
+        // form-data provides its own headers (with boundary); merge with our auth header
+        const headers = {
+            'X-API-Key': this.apiKey,
+            ...form.getHeaders(),
+        };
+        const response = await fetch(url, {
+            method: 'POST',
+            headers,
+            // form.getBuffer() returns a Buffer; Node 18 native fetch accepts it.
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            body: form.getBuffer(),
+        });
+        await this.assertOk(response);
+        return response.json();
+    }
+    /**
+     * Verify an incoming webhook signature.
+     *
+     * KyvShield signs webhook payloads with HMAC-SHA256 using your API key.
+     * Call this before processing any webhook to confirm it came from KyvShield.
+     *
+     * @param payload         - Raw request body as a `Buffer`.
+     * @param apiKey          - Your KyvShield API key (same one used to create the client).
+     * @param signatureHeader - Value of the `X-KyvShield-Signature` header sent with the webhook.
+     * @returns `true` if the signature is valid, `false` otherwise.
+     *
+     * @example
+     * ```ts
+     * // Express example
+     * app.post('/webhook', express.raw({ type: '*\/*' }), (req, res) => {
+     *   const valid = KyvShield.verifyWebhookSignature(
+     *     req.body,
+     *     process.env.KYVSHIELD_API_KEY!,
+     *     req.headers['x-kyvshield-signature'] as string,
+     *   );
+     *
+     *   if (!valid) return res.status(401).send('Invalid signature');
+     *
+     *   // process webhook ...
+     *   res.sendStatus(200);
+     * });
+     * ```
+     */
+    static verifyWebhookSignature(payload, apiKey, signatureHeader) {
+        if (!payload || !apiKey || !signatureHeader)
+            return false;
+        const expected = crypto
+            .createHmac('sha256', apiKey)
+            .update(payload)
+            .digest('hex');
+        // Use timingSafeEqual to prevent timing attacks
+        try {
+            const expectedBuf = Buffer.from(expected, 'hex');
+            // Strip an optional 'sha256=' prefix the server might prepend
+            const incomingSig = signatureHeader.startsWith('sha256=')
+                ? signatureHeader.slice(7)
+                : signatureHeader;
+            const incomingBuf = Buffer.from(incomingSig, 'hex');
+            if (expectedBuf.length !== incomingBuf.length)
+                return false;
+            return crypto.timingSafeEqual(expectedBuf, incomingBuf);
+        }
+        catch {
+            return false;
+        }
+    }
+    // ── Private helpers ─────────────────────────────────────────────────────────
+    /** Build the common headers used by all non-multipart requests. */
+    buildHeaders() {
+        return {
+            'X-API-Key': this.apiKey,
+            Accept: 'application/json',
+        };
+    }
+    /**
+     * Validate required fields in {@link VerifyOptions} before sending.
+     * Throws a descriptive {@link KyvShieldError} on the first problem found.
+     */
+    validateVerifyOptions(options) {
+        if (!options.steps || options.steps.length === 0) {
+            throw new KyvShieldError('VerifyOptions.steps must contain at least one step');
+        }
+        if (!options.target || options.target.trim() === '') {
+            throw new KyvShieldError('VerifyOptions.target must be a non-empty string');
+        }
+        if (!options.images || Object.keys(options.images).length === 0) {
+            throw new KyvShieldError('VerifyOptions.images must contain at least one entry');
+        }
+        // Validate that all image files exist on disk
+        for (const [key, filePath] of Object.entries(options.images)) {
+            const resolved = path.resolve(filePath);
+            if (!fs.existsSync(resolved)) {
+                throw new KyvShieldError(`Image file for "${key}" not found: ${resolved}`);
+            }
+        }
+    }
+    /**
+     * Build the `multipart/form-data` body from {@link VerifyOptions}.
+     *
+     * Text fields are appended first, followed by binary image fields.
+     */
+    buildFormData(options) {
+        const form = new FormData();
+        // ── Text fields ─────────────────────────────────────────────────────────
+        // steps is a JSON array string, e.g. '["selfie","recto","verso"]'
+        form.append('steps', JSON.stringify(options.steps));
+        form.append('target', options.target);
+        form.append('language', options.language ?? 'fr');
+        form.append('challenge_mode', options.challengeMode ?? 'standard');
+        if (options.selfieChallengeMode !== undefined) {
+            form.append('selfie_challenge_mode', options.selfieChallengeMode);
+        }
+        if (options.rectoChallengeMode !== undefined) {
+            form.append('recto_challenge_mode', options.rectoChallengeMode);
+        }
+        if (options.versoChallengeMode !== undefined) {
+            form.append('verso_challenge_mode', options.versoChallengeMode);
+        }
+        form.append('require_face_match', options.requireFaceMatch === true ? 'true' : 'false');
+        if (options.kycIdentifier !== undefined) {
+            form.append('kyc_identifier', options.kycIdentifier);
+        }
+        // ── Image files ─────────────────────────────────────────────────────────
+        for (const [key, filePath] of Object.entries(options.images)) {
+            const resolved = path.resolve(filePath);
+            const buffer = fs.readFileSync(resolved);
+            const filename = path.basename(resolved);
+            const mimeType = this.guessMimeType(filename);
+            form.append(key, buffer, {
+                filename,
+                contentType: mimeType,
+            });
+        }
+        return form;
+    }
+    /**
+     * Throw a {@link KyvShieldError} when the HTTP response is not successful (2xx).
+     * Tries to parse JSON error details from the body when available.
+     */
+    async assertOk(response) {
+        if (response.ok)
+            return;
+        let body;
+        try {
+            body = await response.json();
+        }
+        catch {
+            body = await response.text().catch(() => undefined);
+        }
+        throw new KyvShieldError(`KyvShield API error ${response.status}: ${response.statusText}`, { statusCode: response.status, body });
+    }
+    /** Return a MIME type based on file extension. Defaults to `image/jpeg`. */
+    guessMimeType(filename) {
+        const ext = path.extname(filename).toLowerCase();
+        const map = {
+            '.jpg': 'image/jpeg',
+            '.jpeg': 'image/jpeg',
+            '.png': 'image/png',
+            '.webp': 'image/webp',
+            '.gif': 'image/gif',
+        };
+        return map[ext] ?? 'image/jpeg';
+    }
+}
+export default KyvShield;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AACtC,OAAO,QAAQ,MAAM,WAAW,CAAC;AASjC,cAAc,YAAY,CAAC;AAE3B,iFAAiF;AAEjF,MAAM,gBAAgB,GAAG,4CAA4C,CAAC;AACtE,MAAM,WAAW,GAAG,SAAS,CAAC;AAE9B,gFAAgF;AAEhF;;;GAGG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IACvB,UAAU,CAAU;IACpB,IAAI,CAAW;IAE/B,YAAY,OAAe,EAAE,OAA+B;QAC1D,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,UAAU,GAAG,OAAO,EAAE,UAAU,CAAC;QACtC,IAAI,CAAC,IAAI,GAAG,OAAO,EAAE,IAAI,CAAC;IAC5B,CAAC;CACF;AAED,iFAAiF;AAEjF;;;;GAIG;AACH,MAAM,OAAO,SAAS;IACH,MAAM,CAAS;IACf,OAAO,CAAS;IAEjC;;;;;;;;;;;;;;OAcG;IACH,YAAY,MAAc,EAAE,UAAkB,gBAAgB;QAC5D,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YACpC,MAAM,IAAI,cAAc,CAAC,mCAAmC,CAAC,CAAC;QAChE,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,yEAAyE;QACzE,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC7C,CAAC;IAED,+EAA+E;IAE/E;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,aAAa;QACjB,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,OAAO,GAAG,WAAW,aAAa,CAAC;QAEvD,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAChC,MAAM,EAAE,KAAK;YACb,OAAO,EAAE,IAAI,CAAC,YAAY,EAAE;SAC7B,CAAC,CAAC;QAEH,MAAM,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QAC9B,OAAO,QAAQ,CAAC,IAAI,EAAiC,CAAC;IACxD,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,KAAK,CAAC,MAAM,CAAC,OAAsB;QACjC,IAAI,CAAC,qBAAqB,CAAC,OAAO,CAAC,CAAC;QAEpC,MAAM,IAAI,GAAG,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;QACzC,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,OAAO,GAAG,WAAW,aAAa,CAAC;QAEvD,iFAAiF;QACjF,MAAM,OAAO,GAAG;YACd,WAAW,EAAE,IAAI,CAAC,MAAM;YACxB,GAAG,IAAI,CAAC,UAAU,EAAE;SACrB,CAAC;QAEF,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAChC,MAAM,EAAE,MAAM;YACd,OAAO;YACP,sEAAsE;YACtE,8DAA8D;YAC9D,IAAI,EAAE,IAAI,CAAC,SAAS,EAAS;SAC9B,CAAC,CAAC;QAEH,MAAM,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QAC9B,OAAO,QAAQ,CAAC,IAAI,EAA0B,CAAC;IACjD,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,MAAM,CAAC,sBAAsB,CAC3B,OAAe,EACf,MAAc,EACd,eAAuB;QAEvB,IAAI,CAAC,OAAO,IAAI,CAAC,MAAM,IAAI,CAAC,eAAe;YAAE,OAAO,KAAK,CAAC;QAE1D,MAAM,QAAQ,GAAG,MAAM;aACpB,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC;aAC5B,MAAM,CAAC,OAAO,CAAC;aACf,MAAM,CAAC,KAAK,CAAC,CAAC;QAEjB,gDAAgD;QAChD,IAAI,CAAC;YACH,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;YACjD,8DAA8D;YAC9D,MAAM,WAAW,GAAG,eAAe,CAAC,UAAU,CAAC,SAAS,CAAC;gBACvD,CAAC,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC;gBAC1B,CAAC,CAAC,eAAe,CAAC;YACpB,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;YAEpD,IAAI,WAAW,CAAC,MAAM,KAAK,WAAW,CAAC,MAAM;gBAAE,OAAO,KAAK,CAAC;YAC5D,OAAO,MAAM,CAAC,eAAe,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;QAC1D,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,+EAA+E;IAE/E,mEAAmE;IAC3D,YAAY;QAClB,OAAO;YACL,WAAW,EAAE,IAAI,CAAC,MAAM;YACxB,MAAM,EAAE,kBAAkB;SAC3B,CAAC;IACJ,CAAC;IAED;;;OAGG;IACK,qBAAqB,CAAC,OAAsB;QAClD,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACjD,MAAM,IAAI,cAAc,CAAC,oDAAoD,CAAC,CAAC;QACjF,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YACpD,MAAM,IAAI,cAAc,CAAC,iDAAiD,CAAC,CAAC;QAC9E,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAChE,MAAM,IAAI,cAAc,CAAC,sDAAsD,CAAC,CAAC;QACnF,CAAC;QAED,8CAA8C;QAC9C,KAAK,MAAM,CAAC,GAAG,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC7D,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;YACxC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC7B,MAAM,IAAI,cAAc,CACtB,mBAAmB,GAAG,gBAAgB,QAAQ,EAAE,CACjD,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;;OAIG;IACK,aAAa,CAAC,OAAsB;QAC1C,MAAM,IAAI,GAAG,IAAI,QAAQ,EAAE,CAAC;QAE5B,2EAA2E;QAE3E,kEAAkE;QAClE,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;QAEpD,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;QAEtC,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,OAAO,CAAC,QAAQ,IAAI,IAAI,CAAC,CAAC;QAElD,IAAI,CAAC,MAAM,CAAC,gBAAgB,EAAE,OAAO,CAAC,aAAa,IAAI,UAAU,CAAC,CAAC;QAEnE,IAAI,OAAO,CAAC,mBAAmB,KAAK,SAAS,EAAE,CAAC;YAC9C,IAAI,CAAC,MAAM,CAAC,uBAAuB,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC;QACpE,CAAC;QACD,IAAI,OAAO,CAAC,kBAAkB,KAAK,SAAS,EAAE,CAAC;YAC7C,IAAI,CAAC,MAAM,CAAC,sBAAsB,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAC;QAClE,CAAC;QACD,IAAI,OAAO,CAAC,kBAAkB,KAAK,SAAS,EAAE,CAAC;YAC7C,IAAI,CAAC,MAAM,CAAC,sBAAsB,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAC;QAClE,CAAC;QAED,IAAI,CAAC,MAAM,CACT,oBAAoB,EACpB,OAAO,CAAC,gBAAgB,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CACrD,CAAC;QAEF,IAAI,OAAO,CAAC,aAAa,KAAK,SAAS,EAAE,CAAC;YACxC,IAAI,CAAC,MAAM,CAAC,gBAAgB,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;QACvD,CAAC;QAED,2EAA2E;QAE3E,KAAK,MAAM,CAAC,GAAG,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC7D,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;YACxC,MAAM,MAAM,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;YACzC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;YACzC,MAAM,QAAQ,GAAG,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;YAE9C,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE;gBACvB,QAAQ;gBACR,WAAW,EAAE,QAAQ;aACtB,CAAC,CAAC;QACL,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;OAGG;IACK,KAAK,CAAC,QAAQ,CAAC,QAAkB;QACvC,IAAI,QAAQ,CAAC,EAAE;YAAE,OAAO;QAExB,IAAI,IAAa,CAAC;QAClB,IAAI,CAAC;YACH,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;QAC/B,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QACtD,CAAC;QAED,MAAM,IAAI,cAAc,CACtB,uBAAuB,QAAQ,CAAC,MAAM,KAAK,QAAQ,CAAC,UAAU,EAAE,EAChE,EAAE,UAAU,EAAE,QAAQ,CAAC,MAAM,EAAE,IAAI,EAAE,CACtC,CAAC;IACJ,CAAC;IAED,4EAA4E;IACpE,aAAa,CAAC,QAAgB;QACpC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC;QACjD,MAAM,GAAG,GAA2B;YAClC,MAAM,EAAE,YAAY;YACpB,OAAO,EAAE,YAAY;YACrB,MAAM,EAAE,WAAW;YACnB,OAAO,EAAE,YAAY;YACrB,MAAM,EAAE,WAAW;SACpB,CAAC;QACF,OAAO,GAAG,CAAC,GAAG,CAAC,IAAI,YAAY,CAAC;IAClC,CAAC;CACF;AAED,eAAe,SAAS,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,208 @@
+/**
+ * KyvShield REST SDK - Type Definitions
+ * All TypeScript interfaces and types for the KyvShield KYC API.
+ */
+/** Challenge intensity mode */
+export type ChallengeMode = 'minimal' | 'standard' | 'strict';
+/** Verification step type */
+export type Step = 'selfie' | 'recto' | 'verso';
+/** Supported document target types */
+export type DocumentTarget = 'SN-CIN' | 'SN-PASSPORT' | 'SN-DRIVER-LICENCE' | string;
+/** Supported languages */
+export type Language = 'fr' | 'en' | 'wo';
+/** Overall verification outcome */
+export type OverallStatus = 'pass' | 'reject';
+/** Confidence level descriptor */
+export type ConfidenceLevel = 'HIGH' | 'MEDIUM' | 'LOW';
+/** Available challenges grouped by intensity for a single asset type */
+export interface ChallengeModeMap {
+    minimal: string[];
+    standard: string[];
+    strict: string[];
+}
+/** Full challenges response from GET /api/v1/challenges */
+export interface ChallengesResponse {
+    challenges: {
+        /** Challenges applicable to document steps (recto / verso) */
+        document: ChallengeModeMap;
+        /** Challenges applicable to selfie steps */
+        selfie: ChallengeModeMap;
+    };
+}
+/** A single extracted text field from a document */
+export interface ExtractionField {
+    /** Machine-readable field key */
+    key: string;
+    /** Key as used in the document specification */
+    document_key: string;
+    /** Human-readable label */
+    label: string;
+    /** Extracted value */
+    value: string;
+    /** Display ordering hint (lower = higher priority) */
+    display_priority: number;
+    /** Optional icon identifier */
+    icon?: string;
+}
+/** A photo extracted from a document image */
+export interface ExtractedPhoto {
+    /** Base-64-encoded JPEG image data */
+    image: string;
+    /** Model confidence for this extraction (0–1) */
+    confidence: number;
+    /** Bounding box [x, y, width, height] in pixels */
+    bbox: number[];
+    /** Area of the bounding box in pixels² */
+    area: number;
+    /** Width of the extracted region in pixels */
+    width: number;
+    /** Height of the extracted region in pixels */
+    height: number;
+}
+/** Liveness sub-result for a single step */
+export interface LivenessResult {
+    /** Whether the subject / document is considered live / physical */
+    is_live: boolean;
+    /** Liveness score (0–1) */
+    score: number;
+    /** Qualitative confidence descriptor */
+    confidence: ConfidenceLevel;
+}
+/** Authenticity & fraud sub-result for a single step */
+export interface VerificationResult {
+    /** Whether the document / selfie is considered authentic */
+    is_authentic: boolean;
+    /** Confidence of the authenticity decision (0–1) */
+    confidence: number;
+    /** List of checks that passed */
+    checks_passed: string[];
+    /** Detected fraud indicators */
+    fraud_indicators: string[];
+    /** Non-blocking warnings */
+    warnings: string[];
+    /** Blocking issues */
+    issues: string[];
+}
+/** Result for a single verification step */
+export interface StepResult {
+    /** Zero-based index of this step within the submitted steps array */
+    step_index: number;
+    /** Type of this step */
+    step_type: Step;
+    /** Whether this step succeeded overall */
+    success: boolean;
+    /** Server-side processing time for this step in milliseconds */
+    processing_time_ms: number;
+    /** Liveness detection result */
+    liveness: LivenessResult;
+    /** Document / selfie authenticity result */
+    verification: VerificationResult;
+    /** Localised messages intended for display to the end-user */
+    user_messages: string[];
+    /** Base-64-encoded aligned/deskewed document image (document steps only) */
+    aligned_document?: string;
+    /** Extracted text fields (document steps only) */
+    extraction?: ExtractionField[];
+    /** Extracted photos from the document (document steps only) */
+    extracted_photos?: ExtractedPhoto[];
+    /** Base-64-encoded captured selfie image (selfie step only) */
+    captured_image?: string;
+}
+/** Cross-step face-match result */
+export interface FaceVerification {
+    /** Whether the selfie face matches the document face */
+    is_match: boolean;
+    /** Cosine similarity score (0–100) */
+    similarity_score: number;
+}
+/** Top-level response from POST /api/v1/kyc/verify */
+export interface KycResponse {
+    /** Whether the API call itself succeeded (HTTP-level success) */
+    success: boolean;
+    /** Unique session identifier for this verification run */
+    session_id: string;
+    /** Aggregated pass / reject decision across all steps */
+    overall_status: OverallStatus;
+    /** Aggregated confidence score (0–1) */
+    overall_confidence: number;
+    /** Total server-side processing time in milliseconds */
+    processing_time_ms: number;
+    /** Face-match result (present when require_face_match was true) */
+    face_verification?: FaceVerification;
+    /** Per-step results in submission order */
+    steps: StepResult[];
+}
+/**
+ * Options for KyvShield.verify().
+ *
+ * @example
+ * ```ts
+ * const options: VerifyOptions = {
+ *   steps: ['selfie', 'recto', 'verso'],
+ *   target: 'SN-CIN',
+ *   language: 'fr',
+ *   challengeMode: 'standard',
+ *   requireFaceMatch: true,
+ *   images: {
+ *     selfie_center_face:     '/path/to/selfie.jpg',
+ *     recto_center_document:  '/path/to/recto.jpg',
+ *     verso_center_document:  '/path/to/verso.jpg',
+ *   },
+ * };
+ * ```
+ */
+export interface VerifyOptions {
+    /**
+     * Ordered list of steps to execute.
+     * Example: `['selfie', 'recto', 'verso']`
+     */
+    steps: Step[];
+    /**
+     * Document type to verify against.
+     * Example: `'SN-CIN'`
+     */
+    target: DocumentTarget;
+    /**
+     * Language for user-facing messages in the response.
+     * @default 'fr'
+     */
+    language?: Language;
+    /**
+     * Global fallback challenge mode applied to all steps unless overridden.
+     * @default 'standard'
+     */
+    challengeMode?: ChallengeMode;
+    /** Per-step challenge mode override for the selfie step */
+    selfieChallengeMode?: ChallengeMode;
+    /** Per-step challenge mode override for the recto step */
+    rectoChallengeMode?: ChallengeMode;
+    /** Per-step challenge mode override for the verso step */
+    versoChallengeMode?: ChallengeMode;
+    /**
+     * Whether to perform a cross-step face match between selfie and document photo.
+     * @default false
+     */
+    requireFaceMatch?: boolean;
+    /**
+     * Optional caller-provided identifier for correlating sessions in your system.
+     */
+    kycIdentifier?: string;
+    /**
+     * Map of image files to submit.
+     * Keys follow the pattern `{step}_{challenge}`, e.g.:
+     * - `'selfie_center_face'`
+     * - `'recto_center_document'`
+     * - `'recto_tilt_left'`
+     *
+     * Values are absolute or relative file-system paths to JPEG/PNG images.
+     */
+    images: Record<string, string>;
+}
+/** Structured error thrown by the SDK */
+export interface KyvShieldErrorDetails {
+    /** HTTP status code, if the error originated from an HTTP response */
+    statusCode?: number;
+    /** Raw response body, if available */
+    body?: unknown;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,6 @@
+/**
+ * KyvShield REST SDK - Type Definitions
+ * All TypeScript interfaces and types for the KyvShield KYC API.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@kyvshield/rest-sdk",
+  "version": "1.0.0",
+  "description": "Fully typed Node.js / TypeScript SDK for the KyvShield KYC REST API",
+  "author": "KyvShield",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "build:watch": "tsc --watch",
+    "clean": "rm -rf dist",
+    "prebuild": "npm run clean",
+    "test": "npx ts-node --esm test.ts",
+    "lint": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "kyc",
+    "kyvshield",
+    "identity-verification",
+    "liveness",
+    "ocr",
+    "sdk"
+  ],
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0"
+  }
+}