@dossier-wiki/cloud-sdk 0.1.0 → 0.2.0-staging.568b313

package/README.md

@@ -1,88 +1,739 @@
 # @dossier-wiki/cloud-sdk
 
-TypeScript SDK for the [Dossiers Cloud API](https://api.dossiers.wiki) — sanctions search, high-risk dossier search, screening requests, KYC sessions, document processing, and webhook handling.
+The official TypeScript SDK for the Dossiers API.
 
-## Install
+Covers AML screening, KYC session management, AI-powered document processing,
+form templates, and webhook verification — all with full TypeScript types and
+optional Zod runtime validation.
 
-```sh
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Migrating from the flat API (v0.1)](#migrating-from-the-flat-api-v01)
+- [Authentication](#authentication)
+- [Error Handling](#error-handling)
+- [AML Screening](#aml-screening)
+  - [Sanctions Search](#sanctions-search)
+  - [PEP & Adverse Media (Dossiers)](#pep--adverse-media-dossiers)
+  - [Ongoing Screening Requests](#ongoing-screening-requests)
+- [KYC Sessions](#kyc-sessions)
+- [KYC Workflows](#kyc-workflows)
+  - [Building a Workflow](#building-a-workflow)
+  - [Zod Validation](#zod-validation)
+- [Document Processing](#document-processing)
+  - [Initiate a Job](#initiate-a-job)
+  - [Poll for Results](#poll-for-results)
+  - [Real-Time Progress (SSE)](#real-time-progress-sse)
+  - [Typed Extraction Schemas](#typed-extraction-schemas)
+- [Form Templates](#form-templates)
+- [Media](#media)
+- [Webhooks](#webhooks)
+- [TypeScript](#typescript)
+
+---
+
+## Installation
+
+```bash
 npm install @dossier-wiki/cloud-sdk
 # or
-bun add @dossier-wiki/cloud-sdk
+pnpm add @dossier-wiki/cloud-sdk
 ```
 
-## Quick start
+Requires Node.js 18+ (or any runtime with a global `fetch` and `crypto.subtle`).
+
+---
+
+## Quick Start
 
 ```ts
 import { DossiersAPIService } from '@dossier-wiki/cloud-sdk';
 
-const dossiers = new DossiersAPIService({
-    apiKey: process.env.DOSSIERS_API_KEY!,
+const service = new DossiersAPIService({
+  apiKey: process.env.DOSSIERS_API_KEY!,
 });
 
-const hits = await dossiers.searchSanctions({
-    name: 'Acme Holdings',
-    threshold: 0.8,
+// AML — search sanctions
+const { totalHits, documents } = await service.aml.searchSanctions({
+  fullName: 'John Doe',
+});
+
+// KYC — create a session
+const { sessionUrl } = await service.kyc.sessions.create({
+  customer: { name: 'Alice Brown', email: 'alice@example.com' },
+  workflowId: 'wf_abc123',
+});
+
+// Document processing
+const instance = await service.documents.initiate({
+  processorId: 'INVOICE',
+  files: [{ url: 'https://example.com/invoice.pdf', mimeType: 'application/pdf' }],
 });
 ```
 
-### Webhooks
+---
+
+## Migrating from the flat API (v0.1)
+
+Version 0.1 exposed every operation as a method directly on the service
+(`service.searchSanctions()`, `service.createKycSession()`, ...). That top-level
+surface grew too large to navigate, so operations are now grouped into resource
+namespaces.
+
+**The old flat methods still work** — they are thin, deprecated wrappers that
+forward to the new resource methods, so existing code keeps running unchanged.
+Your editor will show them struck through; migrate at your own pace. They will
+be removed in a future major version.
+
+| Deprecated flat method | Use instead |
+|------------------------|-------------|
+| `service.searchSanctions(input)` | `service.aml.searchSanctions(input)` |
+| `service.searchDossiers(input)` | `service.aml.searchDossiers(input)` |
+| `service.createScreeningRequest(input)` | `service.aml.createScreeningRequest(input)` |
+| `service.createKycSession(input)` | `service.kyc.sessions.create(input)` |
+| `service.listKycSessions(filters?)` | `service.kyc.sessions.list(filters?)` |
+| `service.getKycSession(id)` | `service.kyc.sessions.get(id)` |
+| `service.deleteKycSession(id)` | `service.kyc.sessions.delete(id)` |
+| `service.initiateDocumentProcessing(input)` | `service.documents.initiate(input)` |
+| `service.listDocumentProcessingInstances(query?)` | `service.documents.list(query?)` |
+| `service.listDocumentProcessors()` | `service.documents.listProcessors()` |
+| `service.getDocumentProcessingInstance(id)` | `service.documents.get(id)` |
+| `service.getDocumentProcessingStage(id, stageId)` | `service.documents.getStage(id, stageId)` |
+| `service.deleteDocumentProcessingInstance(id)` | `service.documents.delete(id)` |
+| `service.streamDocumentProcessingEvents(id, init?)` | `service.documents.stream(id, init?)` |
+
+New capabilities added since v0.1 — KYC workflows (`service.kyc.workflows`),
+form templates (`service.formTemplates`), media access (`service.media`), and
+KYC session webhook events — are only available on the resource API.
+
+---
+
+## Authentication
+
+All requests are authenticated with your API key as a Bearer token. Set it
+once on the service instance — never include it in client-side code.
 
 ```ts
-import {
-    DossiersWebhookRouter,
-    DossiersWebhookEventTypes,
-} from '@dossier-wiki/cloud-sdk';
+const service = new DossiersAPIService({
+  apiKey: process.env.DOSSIERS_API_KEY!,
 
-const router = new DossiersWebhookRouter(process.env.DOSSIERS_WEBHOOK_SECRET!);
+  // Optional: override the base URL (e.g. for local development)
+  baseUrl: 'http://localhost:4000',
+
+  // Optional: inject a custom fetch (useful for testing or proxying)
+  fetch: myCustomFetch,
+});
+```
+
+---
+
+## Error Handling
 
-router.on(
-    DossiersWebhookEventTypes.DOCUMENT_VERIFICATION_INSTANCE_UPDATED,
-    async ({ data }) => {
-        if (data.status === 'completed') {
-            // ... handle completion
-        }
+All SDK methods throw a `DossiersAPIError` on non-2xx responses.
+
+```ts
+import { DossiersAPIService, DossiersAPIError } from '@dossier-wiki/cloud-sdk';
+
+try {
+  const session = await service.kyc.sessions.get('ses_nonexistent');
+} catch (err) {
+  if (err instanceof DossiersAPIError) {
+    console.error(err.status);  // e.g. 404
+    console.error(err.message); // human-readable message from the API
+    console.error(err.body);    // raw parsed response body
+  }
+}
+```
+
+---
+
+## AML Screening
+
+### Sanctions Search
+
+Search global sanctions lists (OFAC, UN, FCDO, DFAT, CASL, INTERPOL) for
+individuals or entities.
+
+```ts
+const results = await service.aml.searchSanctions({
+  fullName: 'Jane Smith',
+
+  // Optional: narrow to specific lists
+  sources: ['ofac', 'un'],
+
+  // Optional: filter by country
+  countries: ['US', 'GB'],
+
+  // Optional: match against document numbers
+  idNumbers: ['P123456789'],
+});
+
+console.log(results.totalHits);
+for (const sanction of results.documents) {
+  console.log(sanction.name, sanction.source, sanction.sanctionsProgramme);
+}
+```
+
+### PEP & Adverse Media (Dossiers)
+
+Search PEP registries and adverse media databases. Returns individual dossiers
+with risk scores, positions held, and associates.
+
+```ts
+const dossiers = await service.aml.searchDossiers({
+  fullName: 'Robert Jones',
+  onlyShowHighRiskProfiles: true,
+  noCache: false, // use cached results (default)
+});
+
+for (const dossier of dossiers) {
+  const score = dossier.riskScorecard?.overallRiskScore ?? 0;
+  console.log(dossier.fullName, score, dossier.riskScorecard?.riskCategory);
+}
+```
+
+### Ongoing Screening Requests
+
+Submit individuals for continuous monitoring. Webhook events fire when
+screening completes or when new alerts are triggered.
+
+```ts
+const { requestId } = await service.aml.createScreeningRequest({
+  fullName: 'Alice Brown',
+  externalId: 'cust_123',        // your internal reference ID
+  dateOfBirth: '1985-06-15',
+  country: 'GB',
+  identificationDocument: {
+    type: 'passport',
+    number: 'AB123456',
+    country: 'GB',
+  },
+});
+```
+
+---
+
+## KYC Sessions
+
+A KYC session is a single customer verification journey. The customer receives
+a link (`sessionUrl`) they visit to complete the configured workflow steps.
+
+```ts
+// Create a session
+const { session, sessionUrl, token } = await service.kyc.sessions.create({
+  customer: {
+    name: 'Nimal Perera',
+    email: 'nimal@example.com',
+    externalId: 'cust_001',  // your internal reference
+  },
+  workflowId: 'wf_standard_kyc',
+  expiresInMs: 86_400_000,   // 24 hours (default: 1 hour)
+});
+
+// Send the sessionUrl to your customer
+await sendInvitationEmail(session.customer.email, sessionUrl);
+
+// List sessions
+const { sessions, totalCount } = await service.kyc.sessions.list({
+  isComplete: true,
+  sortBy: 'completedAt',
+  sortOrder: 'desc',
+  limit: 50,
+  offset: 0,
+});
+
+// Get a specific session (includes full step history & media)
+const fullSession = await service.kyc.sessions.get(session.id);
+console.log(fullSession.status); // 'complete' | 'in-progress' | 'approved' | ...
+
+// Delete a session
+await service.kyc.sessions.delete(session.id);
+```
+
+---
+
+## KYC Workflows
+
+A workflow defines the ordered steps a customer goes through during a session
+(e.g. identity verification → liveness → form collection).
+
+### Building a Workflow
+
+Use `stepDefaults()` to get pre-built configurations for each step type, then
+assemble them into a workflow.
+
+```ts
+import type { WorkflowRules } from '@dossier-wiki/cloud-sdk';
+
+// Fetch defaults for all step types
+const defaults = await service.kyc.workflows.stepDefaults();
+const idStep = defaults.find(d => d.type === 'id_verification')!;
+const livenessStep = defaults.find(d => d.type === 'liveness')!;
+
+// Create the workflow
+const workflow = await service.kyc.workflows.create({
+  name: 'Standard KYC',
+  description: 'Identity check + liveness verification',
+  steps: [
+    {
+      stepId: idStep.defaultStepId,
+      type: 'id_verification',
+      input: idStep.defaultInput as { config?: Record<string, unknown> },
+      output: { schema: idStep.schema },
+      rules: idStep.defaultRules as WorkflowRules,
+      locales: idStep.defaultLocales,
+      skippable: idStep.skippable,
+    },
+    {
+      stepId: livenessStep.defaultStepId,
+      type: 'liveness',
+      input: livenessStep.defaultInput as { config?: Record<string, unknown> },
+      output: { schema: livenessStep.schema },
+      rules: livenessStep.defaultRules as WorkflowRules,
+      locales: livenessStep.defaultLocales,
+      skippable: livenessStep.skippable,
     },
-);
+  ],
+});
+
+// Use the workflow when creating sessions
+const { sessionUrl } = await service.kyc.sessions.create({
+  customer: { name: 'Bob Lee' },
+  workflowId: workflow.id,
+});
+```
+
+### Zod Validation
+
+The SDK exports Zod schemas for the step discriminated union, so you can
+validate workflow input at runtime before sending it to the API.
+
+```ts
+import { schemas } from '@dossier-wiki/cloud-sdk';
+
+// Validates the full workflow creation input including per-step type constraints
+const validated = schemas.CreateWorkflowSchema.parse(rawInput);
+const workflow = await service.kyc.workflows.create(validated);
+
+// Validate a single step
+const step = schemas.WorkflowStepSchema.parse({
+  stepId: 'step_liveness',
+  type: 'liveness',
+  input: { config: { challengeType: 'selfie', timeLimitSeconds: 30 } },
+  output: {},
+  rules: { onSuccess: 'COMPLETE_SESSION', onFailure: 'FAIL_SESSION' },
+});
+```
+
+Available step types and their config constraints:
+
+| Type | Config fields |
+|------|--------------|
+| `id_verification` | `strategy`, `allowedDocuments`, `maxSubmissions`, `allowUpload` |
+| `document_collection` | `allowedDocuments`, `allowUpload`, `maxSubmissions` |
+| `liveness` | `challengeType`, `timeLimitSeconds`, `minFaceLuminance`, `minFaceDetectionConfidence` |
+| `form_collection` | `templateId`, `fields` |
+| `esignature` | `signatureTypesAllowed` |
+| `action` | `actionType` |
+
+Other workflow operations:
+
+```ts
+// List all workflows
+const workflows = await service.kyc.workflows.list();
+
+// Get a specific workflow
+const wf = await service.kyc.workflows.get('wf_abc123');
 
-// In any Fetch-API server (Hono, Bun.serve, Cloudflare Workers, etc.):
-export default {
-    fetch: (req: Request) => router.handle(req),
+// Update (creates a new version; existing sessions are unaffected)
+const updated = await service.kyc.workflows.update('wf_abc123', {
+  name: 'Standard KYC v2',
+});
+
+// Delete
+await service.kyc.workflows.delete('wf_old123');
+```
+
+---
+
+## Document Processing
+
+Initiate AI extraction jobs on uploaded documents. The pipeline validates the
+document, extracts structured data, and runs post-processing checks.
+
+Available processor IDs:
+
+| `processorId` | Document |
+|---------------|---------|
+| `INVOICE` | Invoice / bill |
+| `SRI_LANKA_ID` | Sri Lanka National Identity Card |
+| `SRI_LANKA_FORM1_COMPANY_REGISTRATION` | Company Registration Form 1 |
+| `SRI_LANKA_FORM15_ANNUAL_RETURN` | Annual Return Form 15 |
+
+### Initiate a Job
+
+```ts
+const instance = await service.documents.initiate({
+  processorId: 'INVOICE',
+  files: [
+    { url: 'https://example.com/invoice.pdf', mimeType: 'application/pdf' },
+  ],
+
+  // Optional: cross-check context for the AI
+  inputData: {
+    expectedVendor: 'ACME Corp',
+    expectedAmount: '1500.00',
+  },
+
+  // Optional: arbitrary metadata stored on the instance
+  metadata: { orderId: 'ord_456' },
+
+  // Default: true — runs asynchronously; false waits for completion
+  backgroundProcessing: true,
+});
+
+console.log(instance.instanceId); // use this to poll or stream
+```
+
+### Poll for Results
+
+```ts
+let instance = await service.documents.get(instanceId);
+
+while (instance.status === 'pending' || instance.status === 'running') {
+  await new Promise(r => setTimeout(r, 2000));
+  instance = await service.documents.get(instanceId);
+}
+
+if (instance.status === 'completed') {
+  console.log(instance.result?.validation.passed);
+  console.log(instance.result?.normalizedData);
+}
+```
+
+### Real-Time Progress (SSE)
+
+```ts
+const res = await service.documents.stream(instanceId);
+const reader = res.body!.getReader();
+const decoder = new TextDecoder();
+
+while (true) {
+  const { done, value } = await reader.read();
+  if (done) break;
+  const text = decoder.decode(value, { stream: true });
+  // Each SSE line is a DocumentProcessingEvent JSON payload
+  console.log(text);
+}
+```
+
+### Typed Extraction Schemas
+
+Use the generic parameter to type the `result.schema` field for a specific processor:
+
+```ts
+import type {
+  DocumentProcessingExtractedField,
+  DocumentProcessingTransliteratedField,
+} from '@dossier-wiki/cloud-sdk';
+
+type SriLankaIdSchema = {
+  name: DocumentProcessingTransliteratedField;
+  idNumber: DocumentProcessingExtractedField<string>;
+  dateOfBirth: DocumentProcessingExtractedField<string>;
+  address: DocumentProcessingTransliteratedField;
+  gender: DocumentProcessingExtractedField<string>;
 };
+
+const instance = await service.documents.initiate<SriLankaIdSchema>({
+  processorId: 'SRI_LANKA_ID',
+  files: [{ base64Data: '...', mimeType: 'image/jpeg' }],
+});
+
+// result.schema is now typed as SriLankaIdSchema
+const name = instance.result?.schema.name.enTransliterations[0].transliteratedText;
+```
+
+Other document processing operations:
+
+```ts
+// List instances
+const { instances, count } = await service.documents.list({
+  processorId: 'INVOICE',
+  status: 'completed',
+  limit: 20,
+});
+
+// Get a specific stage result
+const stage = await service.documents.getStage(instanceId, 'post_validation');
+console.log(stage.data.validation.passed);
+
+// List available processors
+const processors = await service.documents.listProcessors();
+
+// Delete an instance
+await service.documents.delete(instanceId);
 ```
 
-The router verifies the `x-webhook-signature` header (HMAC-SHA256 of the raw body) using the secret you pass to the constructor. Invalid signatures get a `401`; unhandled event types return `200 ok` so Dossiers does not retry.
+---
+
+## Form Templates
 
-## Configuration
+Form templates define reusable sets of fields for the `form_collection` KYC
+workflow step.
 
 ```ts
-new DossiersAPIService({
-    apiKey: '...',           // required — issued in the Dossiers dashboard
-    baseUrl: '...',          // optional — defaults to https://api.dossiers.wiki
-    fetch: customFetch,      // optional — inject a fetch implementation (e.g. for testing)
+// Create a template
+const template = await service.formTemplates.create({
+  name: 'Employment Details',
+  fields: [
+    {
+      id: 'employer',
+      type: 'text',
+      label: 'Employer Name',
+      required: true,
+    },
+    {
+      id: 'salary',
+      type: 'currency',
+      label: 'Annual Salary (LKR)',
+      required: true,
+      validation: { min: 0 },
+    },
+    {
+      id: 'employment_type',
+      type: 'select',
+      label: 'Employment Type',
+      required: true,
+      options: [
+        { value: 'full_time', label: 'Full Time' },
+        { value: 'part_time', label: 'Part Time' },
+        { value: 'self_employed', label: 'Self Employed' },
+      ],
+    },
+  ],
 });
+
+// Reference the template in a form_collection step config
+const workflowStep = {
+  type: 'form_collection' as const,
+  input: { config: { templateId: template.id } },
+  // ...
+};
+
+// List, get, update, delete
+const { templates } = await service.formTemplates.list({ searchQuery: 'employment' });
+const full = await service.formTemplates.get(template.id);
+await service.formTemplates.update(template.id, { name: 'Employment Details v2' });
+await service.formTemplates.delete(template.id);
 ```
 
-## Error handling
+Available field types: `text`, `long_text`, `number`, `currency`, `country`,
+`language`, `email`, `phone`, `date`, `select`, `multi_select`, `dropdown`,
+`toggle`, `boolean`, `file`, `heading`, `paragraph`, `description`, `divider`.
+
+---
+
+## Media
 
-All non-2xx responses throw `DossiersAPIError`:
+Fetch binary files (images, videos, PDF signatures) from session results and
+document processing instances using signed storage tokens.
 
 ```ts
-import { DossiersAPIError } from '@dossier-wiki/cloud-sdk';
+// Tokens appear in session result media arrays and processing instance files
+const token = session.result.steps[0].summary?.media[0]?.key;
 
-try {
-    await dossiers.getKycSession('missing-id');
-} catch (err) {
-    if (err instanceof DossiersAPIError) {
-        console.log(err.status); // HTTP status
-        console.log(err.body);   // parsed JSON or raw text
-    }
+if (token) {
+  const res = await service.media.get(token);
+
+  // Browser — convert to object URL for display
+  const blob = await res.blob();
+  const objectUrl = URL.createObjectURL(blob);
+  imageElement.src = objectUrl;
+
+  // Node.js — pipe to disk
+  const { createWriteStream } = await import('fs');
+  const { Readable } = await import('stream');
+  Readable.fromWeb(res.body!).pipe(createWriteStream('./capture.jpg'));
 }
 ```
 
-## API reference
+---
+
+## Webhooks
 
-See [docs/REFERENCE.md](./docs/REFERENCE.md) for the full method list.
+Use `DossiersWebhookRouter` to handle incoming webhook events with HMAC-SHA256
+signature verification.
 
-## License
+```ts
+import { DossiersWebhookRouter, DossiersWebhookEventTypes } from '@dossier-wiki/cloud-sdk';
 
-MIT
+const router = new DossiersWebhookRouter(process.env.DOSSIERS_WEBHOOK_SECRET!);
+
+router
+  .on(DossiersWebhookEventTypes.DOCUMENT_VERIFICATION_INSTANCE_COMPLETED, async (event, ctx) => {
+    const { documentProcessorInstanceId } = event.data;
+    const instance = await service.documents.get(documentProcessorInstanceId);
+    await saveResult(instance);
+  })
+  .on(DossiersWebhookEventTypes.KYC_SESSION_COMPLETED, async (event, ctx) => {
+    // Payloads carry no PII — fetch the full session on demand.
+    const { kycSessionId, outcome } = event.data;
+    const session = await service.kyc.sessions.get(kycSessionId);
+    await recordVerification(session, outcome); // outcome: 'complete' | 'failed'
+  })
+  .on(DossiersWebhookEventTypes.AML_SCREENING_ALERT_TRIGGERED, async (event, ctx) => {
+    console.log('Alert triggered for screening request', event.data);
+  });
+
+// Express
+app.post('/webhooks/dossiers', async (req, res) => {
+  // Reconstruct a Web API Request from the Express request
+  const body = await getRawBody(req);
+  const webReq = new Request('https://your-server/webhooks/dossiers', {
+    method: 'POST',
+    headers: req.headers as HeadersInit,
+    body,
+  });
+  const response = await router.handle(webReq);
+  res.status(response.status).send(await response.text());
+});
+
+// Next.js App Router
+export async function POST(req: Request) {
+  return router.handle(req, { waitUntil: (p) => context.waitUntil(p) });
+}
+```
+
+Webhook events are acknowledged immediately (200 OK) before the handler runs —
+a slow handler will not cause the platform to retry. If your handler throws,
+the error is logged but no retry occurs. Implement your own retry logic inside
+the handler if needed.
+
+Every event delivered to a handler has the shape:
+
+```ts
+{
+  id: string;              // e.g. "evt_1712345678_ab12cd34"
+  type: DossiersWebhookEventTypes;
+  organizationId: string;
+  eventTriggeredAt: string; // ISO 8601
+  data: /* typed per event — see below */;
+}
+```
+
+The `data` field is fully typed by the event `type` you pass to `.on()`. Import
+`DossiersWebhookPayload` for the discriminated union of all event shapes.
+
+### Available Event Types
+
+**Document processing**
+
+| Enum value | Event string | `data` type |
+|------------|-------------|-------------|
+| `DOCUMENT_VERIFICATION_INSTANCE_CREATED` | `documentVerification.instance.created` | `DocumentVerificationInstanceCreatedData` |
+| `DOCUMENT_VERIFICATION_INSTANCE_UPDATED` | `documentVerification.instance.updated` | `DocumentVerificationInstanceUpdatedData` |
+| `DOCUMENT_VERIFICATION_INSTANCE_COMPLETED` | `documentVerification.instance.completed` | `DocumentVerificationInstanceCompletedData` |
+| `DOCUMENT_VERIFICATION_INSTANCE_DELETED` | `documentVerification.instance.deleted` | `DocumentVerificationInstanceDeletedData` |
+
+**KYC sessions**
+
+| Enum value | Event string | `data` type |
+|------------|-------------|-------------|
+| `KYC_SESSION_CREATED` | `kycSessions.session.created` | `KycSessionEventData` |
+| `KYC_SESSION_UPDATED` | `kycSessions.session.updated` | `KycSessionEventData` |
+| `KYC_SESSION_COMPLETED` | `kycSessions.session.completed` | `KycSessionEventData` (with `outcome`) |
+| `KYC_SESSION_REVIEWED` | `kycSessions.session.reviewed` | `KycSessionEventData` (with `review`) |
+| `KYC_SESSION_DELETED` | `kycSessions.session.deleted` | `KycSessionDeletedData` |
+| `KYC_STEP_COMPLETED` | `kycSessions.step.completed` | `KycStepEventData` |
+| `KYC_STEP_FAILED` | `kycSessions.step.failed` | `KycStepEventData` |
+| `KYC_SESSION_COMMENT_ADDED` | `kycSessions.session.commentAdded` | `KycSessionCommentAddedData` |
+| `KYC_SESSION_COMMENT_UPDATED` | `kycSessions.session.commentUpdated` | `KycSessionCommentUpdatedData` |
+| `KYC_SESSION_COMMENT_DELETED` | `kycSessions.session.commentDeleted` | `KycSessionCommentDeletedData` |
+
+> KYC payloads carry **no PII** (no customer name/email, no step outputs). They
+> reference a `kycSessionId` — fetch the detail you need with
+> `service.kyc.sessions.get(kycSessionId)`.
+
+**AML screening**
+
+| Enum value | Event string |
+|------------|-------------|
+| `AML_SCREENING_REQUEST_CREATED` | `amlScreening.screeningRequest.created` |
+| `AML_SCREENING_REQUEST_COMPLETED` | `amlScreening.screeningRequest.completed` |
+| `AML_SCREENING_ALERT_TRIGGERED` | `amlScreening.screeningAlert.triggered` |
+| `AML_SCREENING_ALERT_STATUS_CHANGED` | `amlScreening.screeningAlert.statusChanged` |
+| `AML_SCREENING_ALERT_COMMENT_ADDED` | `amlScreening.screeningAlert.commentAdded` |
+| `AML_SCREENING_ALERT_COMMENT_UPDATED` | `amlScreening.screeningAlert.commentUpdated` |
+| `AML_SCREENING_ALERT_COMMENT_DELETED` | `amlScreening.screeningAlert.commentDeleted` |
+| `AML_SCREENING_ALERT_DELETED` | `amlScreening.screeningAlert.deleted` |
+
+**System**
+
+| Enum value | Event string |
+|------------|-------------|
+| `SYSTEM_TEST_EVENT` | `system.testEvent` |
+| `SYSTEM_PRODUCT_ACCESS_GRANTED` | `system.product.accessGranted` |
+| `SYSTEM_PRODUCT_ACCESS_REVOKED` | `system.product.accessRevoked` |
+| `SYSTEM_API_KEY_CREATED` | `system.apiKey.created` |
+| `SYSTEM_API_KEY_INVALIDATED` | `system.apiKey.invalidated` |
+| `SYSTEM_USAGE_LIMIT_REACHED` | `system.usage.limitReached` |
+| `SYSTEM_USAGE_LIMIT_WARNING` | `system.usage.limitWarning` |
+
+---
+
+## TypeScript
+
+All API request and response shapes are exported as TypeScript interfaces.
+Import them as needed:
+
+```ts
+import type {
+  // AML
+  SanctionSearchInput,
+  SanctionSearchResponse,
+  Sanction,
+  DossierSearchInput,
+  IndividualDossier,
+  CreateScreeningRequestDto,
+
+  // KYC Sessions
+  CreateKycSessionDTO,
+  KycSessionOutputDTO,
+  KycSessionFiltersDTO,
+  PaginatedKycSessionsDTO,
+
+  // KYC Workflows
+  CreateKycWorkflowInput,
+  KycWorkflow,
+  KycWorkflowStep,
+  KycWorkflowStepType,
+  WorkflowRules,
+  WorkflowStepDefault,
+
+  // Document Processing
+  InitiateDocumentProcessingInput,
+  DocumentProcessingInstance,
+  DocumentProcessingResult,
+  DocumentProcessingExtractedField,
+  DocumentProcessingTransliteratedField,
+  DocumentProcessorId,
+
+  // Form Templates
+  CreateFormTemplateInput,
+  FormTemplate,
+  FormField,
+  FormFieldType,
+
+  // Webhooks
+  DossiersWebhookPayload,
+  DossiersWebhookEvent,
+  KycSessionEventData,
+  KycSessionDeletedData,
+  KycStepEventData,
+  KycSessionCommentAddedData,
+  KycSessionCommentUpdatedData,
+  KycSessionCommentDeletedData,
+} from '@dossier-wiki/cloud-sdk';
+```