@vpdev2/metakyc 1.0.48 → 1.0.51

package/README.md

@@ -13,6 +13,7 @@ A comprehensive React SDK for MetaKYC due diligence workflows with configurable
 - ✅ **Dynamic Form Validation** - Automatic zod schema generation from API rules
 - ✅ **Identity Provider Integration** - Sumsub, Onfido, and SardinAI support
 - ✅ **TypeScript** - Full type safety with types generated from C# DTOs
+- ✅ **Session Token Auth** - Server-side token creation with optional `externalRefId` scoping guard
 - ✅ **Dark Mode** - Built-in dark mode support
 
 ## Installation
@@ -27,20 +28,53 @@ pnpm add @metakyc/sdk
 
 ## Quick Start
 
-### 1. Wrap your app with MetaKYCProvider
+### Step 1 — Server: create a session token
+
+Create a short-lived session token on your backend. The API key and secret never leave your server.
+
+```typescript
+// ── Server-side (Next.js API route, Express, etc.) ──
+import { MetaKYCSession } from '@vpdev2/metakyc';
+
+export async function POST() {
+  const { accessToken, expiresInSeconds } = await MetaKYCSession.createToken({
+    baseUrl:       'https://api.example.com',
+    clientId:      'your-client-id',           // or tenantId: 1
+    apiKey:        process.env.METAKYC_API_KEY!,
+    secretKey:     process.env.METAKYC_SECRET_KEY!,
+    externalRefId: 'USER-12345',               // optional — scopes the token to this user
+  });
+  return Response.json({ accessToken, expiresInSeconds });
+}
+```
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `baseUrl` | `string` | Yes | MetaKYC API base URL |
+| `apiKey` | `string` | Yes | Your tenant API key |
+| `secretKey` | `string` | Yes | Your tenant secret key |
+| `tenantId` | `number` | One of | Numeric tenant ID (provide this **or** `clientId`) |
+| `clientId` | `string` | One of | String client ID (provide this **or** `tenantId`) |
+| `externalRefId` | `string` | No | When set, the returned token is **scoped**: all API calls made with it can only create or access applicants matching this `externalRefId`. Tokens created without it remain unrestricted (backward-compatible). |
+
+### Step 2 — Client: initialize the SDK
+
+Pass the token to the frontend SDK via `getAccessToken`:
 
 ```tsx
-import { MetaKYCProvider } from '@metakyc/sdk';
-import '@metakyc/sdk/styles';
+import { MetaKYCProvider } from '@vpdev2/metakyc';
 
 function App() {
   return (
     <MetaKYCProvider
       config={{
-        apiKey: process.env.METAKYC_API_KEY,
-        tenantId: parseInt(process.env.TENANT_ID),
-        baseUrl: process.env.METAKYC_BASE_URL,
+        getAccessToken: () => fetchSessionToken(), // returns the accessToken string
+        clientId: 'your-client-id',
+        baseUrl: 'https://api.example.com',
         endpoints: { pattern: 'host-controller' },
+        applicantForm: {
+          externalRefId: 'USER-12345',
+        },
         // Optional: Configure identity providers (e.g., SardinAI)
         identityProviders: {
           sardinai: process.env.SARDINAI_CLIENT_ID ? {
@@ -59,7 +93,9 @@ function App() {
 }
 ```
 
-### 2. Use the complete workflow component
+> **Tip:** You can also pass `apiKey` directly instead of `getAccessToken` for quick testing, but session tokens are recommended for production since they keep your secret key on the server.
+
+### Step 3 — Use the workflow component
 
 ```tsx
 import { KycWorkflow } from '@metakyc/sdk';
@@ -75,7 +111,7 @@ function KYCPage() {
 }
 ```
 
-### 3. Or build custom UI with hooks
+### Step 4 — Or build custom UI with hooks
 
 ```tsx
 import { useKycWorkflow, useQuestionnaire } from '@metakyc/sdk';

package/dist/client/config.d.ts

@@ -133,6 +133,12 @@ export interface MetaKYCClientConfig {
     locale?: string;
     /** Identity provider configurations */
     identityProviders?: IdentityProviderConfigs;
+    /**
+     * Existing applicant ID to continue a previous KYC session.
+     * When provided, the SDK skips applicant creation and goes straight to the workflow.
+     * When omitted or null, the SDK starts with the applicant creation form.
+     */
+    applicantId?: number;
     /** Applicant form configuration */
     applicantForm?: ApplicantFormConfig;
     /** Theme configuration (optional - will fetch from backend if not provided) */

package/dist/client/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/client/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/client/config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,iBAAiB,GAAG,qBAAqB,GAAG,QAAQ,CAAC;AAEnF;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,eAAe,CAAC;IACzB,WAAW,CAAC,EAAE,mBAAmB,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,SAAS,GAAG,YAAY,CAAC;IACtC,MAAM,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IACnC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,+EAA+E;IAC/E,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACzB,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE,sBAAsB,CAAC;IAClC,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAC1B,WAAW,GACX,UAAU,GACV,OAAO,GACP,OAAO,GACP,aAAa,GACb,aAAa,GACb,mBAAmB,GACnB,QAAQ,GACR,cAAc,GACd,KAAK,GACL,MAAM,GACN,SAAS,GACT,aAAa,GACb,kBAAkB,GAClB,iBAAiB,GACjB,YAAY,GACZ,cAAc,GACd,gBAAgB,GAChB,YAAY,GACZ,gBAAgB,GAChB,YAAY,GACZ,WAAW,GACX,eAAe,CAAC;AAEpB;;GAEG;AACH,MAAM,MAAM,yBAAyB,GACjC,aAAa,GACb,oBAAoB,GACpB,OAAO,GACP,OAAO,GACP,kBAAkB,GAClB,cAAc,GACd,gBAAgB,GAChB,eAAe,GACf,OAAO,GACP,sBAAsB,GACtB,SAAS,GACT,eAAe,GACf,QAAQ,GACR,MAAM,GACN,OAAO,GACP,YAAY,GACZ,gBAAgB,GAChB,KAAK,GACL,cAAc,GACd,eAAe,CAAC;AAEpB;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,aAAa,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;IAEzC,iFAAiF;IACjF,aAAa,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAErC,4FAA4F;IAC5F,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,8EAA8E;IAC9E,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,sFAAsF;IACtF,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEtC;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,GAAG,aAAa,CAAC;IAEzC;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACxC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,sFAAsF;IACtF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;IAEhB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAEjD,6BAA6B;IAC7B,SAAS,CAAC,EAAE,cAAc,CAAC;IAE3B,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,2CAA2C;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,uCAAuC;IACvC,iBAAiB,CAAC,EAAE,uBAAuB,CAAC;IAE5C;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,mCAAmC;IACnC,aAAa,CAAC,EAAE,mBAAmB,CAAC;IAEpC,+EAA+E;IAC/E,KAAK,CAAC,EAAE,GAAG,CAAC;IAEZ,4EAA4E;IAC5E,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,OAAO,CAAC,mBAAmB,CAOtD,CAAC"}

package/dist/client/session.d.ts

@@ -6,6 +6,12 @@ export interface CreateSessionTokenParams {
     tenantId?: number;
     /** String client ID (non-ABP projects). Provide this OR tenantId. */
     clientId?: string;
+    /**
+     * Optional external reference ID to bind the session token to a specific user.
+     * When set, the server enforces that all API calls made with this token
+     * can only create/access applicants matching this externalRefId.
+     */
+    externalRefId?: string;
 }
 export interface SessionTokenResult {
     accessToken: string;

package/dist/client/session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/client/session.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,qBAAa,cAAc;WACZ,WAAW,CAAC,MAAM,EAAE,wBAAwB,GAAG,OAAO,CAAC,kBAAkB,CAAC;CA4BxF"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/client/session.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,qBAAa,cAAc;WACZ,WAAW,CAAC,MAAM,EAAE,wBAAwB,GAAG,OAAO,CAAC,kBAAkB,CAAC;CA+BxF"}

package/dist/hooks/useKycWorkflow.d.ts

@@ -2,11 +2,11 @@ import { ProgressApplicantResult, ApplicantProgressStatus } from '../types';
 import { WorkflowOrchestrator } from '../state';
 
 /**
- * Hook to manage KYC workflow state and progression with automatic persistence
+ * Hook to manage KYC workflow state and progression
  */
 export declare function useKycWorkflow(applicantId?: number): {
     progress: ProgressApplicantResult | null;
-    applicantId: number | null;
+    applicantId: number | undefined;
     currentStep: import('..').FlowStep | null;
     steps: import('..').StepInfo[];
     status: ApplicantProgressStatus;

package/dist/hooks/useKycWorkflow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useKycWorkflow.d.ts","sourceRoot":"","sources":["../../src/hooks/useKycWorkflow.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACxB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAGhD;;GAEG;AACH,wBAAgB,cAAc,CAAC,WAAW,CAAC,EAAE,MAAM;;;;;;;;;;;;;;;;;8BAiIE,GAAG;;EAkDvD"}
+{"version":3,"file":"useKycWorkflow.d.ts","sourceRoot":"","sources":["../../src/hooks/useKycWorkflow.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACxB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAGhD;;GAEG;AACH,wBAAgB,cAAc,CAAC,WAAW,CAAC,EAAE,MAAM;;;;;;;;;;;;;;;;;8BA+HE,GAAG;;EAkDvD"}