@flonkid/kyc 1.8.2 → 1.9.1

package/dist/server.d.cts

@@ -1,3 +1,865 @@
+interface components {
+    schemas: {
+        CreateSessionRequestDto: {
+            /**
+             * @description Client identifier for session association (optional)
+             * @example client-12345
+             */
+            clientId?: string;
+            /**
+             * @description Client metadata for identification (optional) - arbitrary object with client identifiers
+             * @example {
+             *       "email": "user@example.com",
+             *       "userId": "12345",
+             *       "customId": "internal-id"
+             *     }
+             */
+            clientMetadata?: Record<string, never>;
+            /**
+             * @description Document type for verification (required)
+             * @example id_card
+             * @enum {string}
+             */
+            documentType: "passport" | "id_card" | "driver_license";
+            /**
+             * @description Session lifetime in seconds (optional, default: 300)
+             * @default 300
+             * @example 300
+             */
+            expiresIn: number;
+        };
+        SessionResponseDto: {
+            /**
+             * @description Unique session identifier
+             * @example clx1234567890abcdef
+             */
+            id: string;
+            /**
+             * @description Session status
+             * @example pending
+             * @enum {string}
+             */
+            status: "pending" | "in_progress" | "completed" | "failed" | "expired";
+            /**
+             * Format: date-time
+             * @description Session expiration timestamp
+             * @example 2024-10-25T14:30:00.000Z
+             */
+            expiresAt: string;
+            /**
+             * @description Client metadata
+             * @example {
+             *       "userId": "user_12345",
+             *       "email": "john.doe@example.com"
+             *     }
+             */
+            clientMetadata?: Record<string, never>;
+            /**
+             * @description Widget URL for embedding
+             * @example https://widget.flonk.id/?sessionId=clx1234567890abcdef&mode=embedded
+             */
+            widgetUrl: string;
+            /**
+             * @description QR code data for mobile verification
+             * @example https://widget.flonk.id/verify/clx1234567890abcdef?token=kyc_1234567890_abc123
+             */
+            qrCodeUrl: string;
+            /**
+             * Format: date-time
+             * @description Session creation timestamp
+             * @example 2024-10-25T14:25:00.000Z
+             */
+            createdAt: string;
+            /**
+             * @description Project identifier
+             * @example clxproject123
+             */
+            projectId: string;
+            /**
+             * @description Whether manual upload is allowed for this session
+             * @example true
+             */
+            allowManualUpload: boolean;
+            /**
+             * @description Embed token for widget authentication (like Stripe client_secret)
+             * @example eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+             */
+            embedToken?: string;
+            /**
+             * @description Indicates if an existing session was reused instead of creating a new one
+             * @example false
+             */
+            reused?: boolean;
+            /**
+             * @description Test mode flag - true if created with test keys (sk_test_*)
+             * @example false
+             */
+            testMode?: boolean;
+        };
+        UploadDocumentImageDto: {
+            /**
+             * @description KYC Session ID
+             * @example cm5abc123def456
+             */
+            sessionId: string;
+            /**
+             * @description Image side/type
+             * @example front
+             * @enum {string}
+             */
+            imageType: "front" | "back" | "main";
+            /**
+             * @description Whether this is a retake photo (replaces existing photo)
+             * @default false
+             * @example false
+             */
+            isRetake: boolean;
+            /**
+             * Format: binary
+             * @description Single document image
+             */
+            images: string;
+        };
+        DocumentUploadResponseDto: {
+            /** @example true */
+            success: boolean;
+            /**
+             * @description Processing status: queued, processing, completed
+             * @example queued
+             */
+            status: string;
+            /**
+             * @description Job ID for tracking
+             * @example doc:session123:front:1234567890
+             */
+            jobId?: string;
+            /** @example passport */
+            detectedDocumentType: string;
+            /** @example 0.9 */
+            detectionConfidence: number;
+            /** @example front */
+            uploadedImageType: string;
+            /** @example front */
+            detectedSide?: string;
+            /** @example German ID Card */
+            documentName?: string;
+            /** @example true */
+            isValidDocument: boolean;
+            /** @example false */
+            requiresBackSide: boolean;
+            /** @example Please upload the back side of your ID card */
+            nextStepMessage: string;
+            /**
+             * @example {
+             *       "front": true,
+             *       "back": false
+             *     }
+             */
+            uploadedSides: Record<string, never>;
+            /** @example false */
+            readyForVerification: boolean;
+            /** @example Image uploaded successfully. Processing in background. */
+            message?: string;
+            /**
+             * @description Estimated processing time in milliseconds
+             * @example 3000
+             */
+            estimatedProcessingTime?: number;
+        };
+        UploadFaceImageDto: {
+            /**
+             * @description KYC Session ID
+             * @example cm5abc123def456
+             */
+            sessionId: string;
+            /**
+             * Format: binary
+             * @description Face image for biometric verification
+             */
+            images: string;
+        };
+        FaceUploadResponseDto: {
+            /** @example true */
+            success: boolean;
+            /**
+             * @description Processing status: queued, processing, completed
+             * @example queued
+             */
+            status: string;
+            /**
+             * @description Job ID for tracking
+             * @example face:session123:1234567890
+             */
+            jobId?: string;
+            /** @example 0.85 */
+            confidence: number;
+            /** @example Face image uploaded. Processing liveness in background. */
+            message: string;
+            /** @example true */
+            readyForFinalVerification: boolean;
+            /**
+             * @description Estimated processing time in milliseconds
+             * @example 2000
+             */
+            estimatedProcessingTime?: number;
+        };
+        UploadPoaImageDto: {
+            /**
+             * @description KYC Session ID
+             * @example cm5abc123def456
+             */
+            sessionId: string;
+            /**
+             * Format: binary
+             * @description Proof of Address document (utility bill, bank statement, etc.). Supports JPEG, PNG, WebP, and PDF.
+             */
+            images: string;
+            /** @description Custom extraction prompt (overrides default) */
+            prompt?: string;
+        };
+        PoaExtractedDataDto: {
+            /** @example John Doe */
+            fullName?: string;
+            /** @example 123 Main Street */
+            address?: string;
+            /** @example Berlin */
+            city?: string;
+            /** @example 10115 */
+            postalCode?: string;
+            /** @example Germany */
+            country?: string;
+            /** @example utility_bill */
+            documentType?: string;
+            /** @example 2025-01-15 */
+            issueDate?: string;
+            /** @example Berlin Electricity GmbH */
+            issuer?: string;
+        };
+        PoaConfidenceBreakdownDto: {
+            /**
+             * @example {
+             *       "full_name": 1,
+             *       "address": 1,
+             *       "city": 0
+             *     }
+             */
+            fieldScores: Record<string, never>;
+            /** @example 1 */
+            totalWeight: number;
+            /** @example 0.75 */
+            achievedWeight: number;
+            /** @example 0.75 */
+            confidenceScore: number;
+        };
+        PoaUploadResponseDto: {
+            /** @example true */
+            success: boolean;
+            /** @example Proof of address uploaded and processed successfully */
+            message: string;
+            data?: components["schemas"]["PoaExtractedDataDto"];
+            /**
+             * @description Processing time in milliseconds
+             * @example 5000
+             */
+            processingTimeMs?: number;
+            /**
+             * @description Whether session is ready for final verification
+             * @example true
+             */
+            readyForVerification: boolean;
+            /**
+             * @description Confidence score from 0.0 to 1.0
+             * @example 0.85
+             */
+            confidenceScore?: number;
+            confidenceBreakdown?: components["schemas"]["PoaConfidenceBreakdownDto"];
+            /**
+             * @description PoA verification status based on confidence thresholds
+             * @example auto_approved
+             * @enum {string}
+             */
+            poaStatus?: "pending" | "auto_approved" | "manual_review" | "approved" | "rejected";
+        };
+        PoaAsyncResponseDto: {
+            /** @example true */
+            success: boolean;
+            /** @example f47ac10b-58cc-4372-a567-0e02b2c3d479 */
+            jobId: string;
+            /**
+             * @example processing
+             * @enum {string}
+             */
+            status: "processing";
+            /** @example PoA extraction started. Poll /kyc/poa-status/:jobId for results. */
+            message: string;
+        };
+        PoaStatusResponseDto: {
+            /** @example f47ac10b-58cc-4372-a567-0e02b2c3d479 */
+            jobId: string;
+            /**
+             * @example completed
+             * @enum {string}
+             */
+            status: "processing" | "completed" | "failed" | "not_found";
+            /** @example PoA extraction completed */
+            message: string;
+            data?: components["schemas"]["PoaExtractedDataDto"];
+            /**
+             * @description Confidence score from 0.0 to 1.0
+             * @example 0.85
+             */
+            confidenceScore?: number;
+            /**
+             * @example auto_approved
+             * @enum {string}
+             */
+            poaStatus?: "pending" | "auto_approved" | "manual_review" | "approved" | "rejected";
+        };
+        ExtractedDataDto: {
+            /** @example John Doe */
+            fullName: string;
+            /** @example John */
+            firstName: string;
+            /** @example Doe */
+            lastName: string;
+            /** @example 1990-01-01 */
+            dateOfBirth: string;
+            /** @example German */
+            nationality: string;
+            /** @example M */
+            sex: string;
+        };
+        VerificationDataDto: {
+            /** @example id_card */
+            documentType: string;
+            extractedData: components["schemas"]["ExtractedDataDto"];
+            /** @example atm_1a2b3c4d5e */
+            verificationAttemptId: string;
+        };
+        VerificationResponseDto: {
+            /** @example true */
+            success: boolean;
+            /**
+             * @description Processing status: queued, processing, completed, failed
+             * @example queued
+             */
+            status?: string;
+            /**
+             * @description Job ID for tracking
+             * @example verify:session123:1234567890
+             */
+            jobId?: string;
+            /** @example Verification started. You will receive results shortly. */
+            message?: string;
+            /** @example client123 */
+            clientId?: string;
+            /** @example 2024-01-15T10:30:00Z */
+            timestamp?: string;
+            /** @example 0.95 */
+            confidence?: number;
+            data?: components["schemas"]["VerificationDataDto"];
+            /**
+             * @description PoA verification status: auto_approved, manual_review, rejected, pending
+             * @example auto_approved
+             */
+            poaStatus?: string;
+        };
+        GrantVaultConsentDto: {
+            /** @description KYC session id whose primary verification just completed. */
+            sessionId: string;
+            /** @description Version of consent text the user agreed to. */
+            consentVersion?: string;
+        };
+        GrantVaultConsentResponseDto: {
+            verifiedIdentityId: string;
+            vaultPrefix: string;
+            consentVersion: string;
+            /** Format: date-time */
+            consentAt: string;
+        };
+        CheckVaultDto: {
+            /** @description KYC session id (current new session). */
+            sessionId: string;
+        };
+        CheckVaultResponseDto: {
+            available: boolean;
+            /** @enum {string} */
+            mode?: "full_reuse" | "partial_reuse_poa";
+            /** Format: date-time */
+            completedAt?: string;
+            sourceProjectName?: string;
+            documentType?: Record<string, never>;
+            vaultHasPoa?: boolean;
+            projectRequiresPoa?: boolean;
+            /**
+             * @description Identity proof method the widget must show before applying reuse.
+             * @enum {string}
+             */
+            challengeMethod?: "otp" | "liveness";
+        };
+        RequestVaultOtpDto: {
+            /** @description Current widget session id. */
+            sessionId: string;
+        };
+        RequestVaultOtpResponseDto: {
+            /** @description Always true — the endpoint does not reveal whether the email actually matches a vault entry. */
+            sent: boolean;
+        };
+        VerifyVaultOtpDto: {
+            sessionId: string;
+            /** @description 6-digit numeric code received by email. */
+            code: string;
+        };
+        VerifyVaultOtpResponseDto: {
+            verified: boolean;
+        };
+        VaultIdentityChallengeDto: {
+            sessionId: string;
+            /** @description Burst of selfie frames (Beta auto-capture). 1-6 frames. */
+            selfiesBase64?: string[];
+            /** @description Legacy single-selfie path. Prefer `selfiesBase64` for Beta burst. May include a "data:image/jpeg;base64," prefix or be raw base64. */
+            selfieBase64?: string;
+        };
+        VaultIdentityChallengeResponseDto: {
+            verified: boolean;
+            /** @description Face-match similarity score (0..1) when computed. */
+            similarity?: number;
+            liveness?: Record<string, never>;
+            /** @enum {string} */
+            reason?: "no_email" | "no_vault" | "no_portrait" | "liveness_failed" | "face_mismatch";
+        };
+        ApplyVaultReuseDto: {
+            sessionId: string;
+            /** @enum {string} */
+            mode: "full_reuse" | "partial_reuse_poa";
+        };
+        ApplyVaultReuseResponseDto: {
+            attemptId: string;
+            verifiedIdentityId: string;
+            /** @enum {string} */
+            mode: "full_reuse" | "partial_reuse_poa";
+        };
+        RevokeIdentityDto: {
+            /** @description Email whose vault entry should be revoked. Must match a session-verified email. */
+            email: string;
+            /** @description Optional human-readable reason. */
+            reason?: string;
+        };
+        RevokeIdentityResponseDto: {
+            revoked: boolean;
+            /** Format: date-time */
+            revokedAt: string;
+        };
+        MarkAllReadDto: Record<string, never>;
+        SendOtpDto: Record<string, never>;
+        VerifyOtpDto: Record<string, never>;
+        ResendOtpDto: Record<string, never>;
+        CreateBillingProfileDto: {
+            /** @description Company name (required for B2B invoicing) */
+            companyName?: string;
+            /** @description VAT/Tax ID number (EU format: XX followed by numbers) */
+            vatNumber?: string;
+            /** @description Alternative tax identification */
+            taxId?: string;
+            /** @description Address line 1 */
+            addressLine1?: string;
+            /** @description Address line 2 */
+            addressLine2?: string;
+            /** @description City */
+            city?: string;
+            /** @description State/Province */
+            state?: string;
+            /** @description Postal/ZIP code */
+            postalCode?: string;
+            /** @description Country code (2-letter ISO) */
+            country?: string;
+            /** @description Contact person name */
+            contactName?: string;
+            /** @description Email for receiving invoices */
+            contactEmail?: string;
+            /** @description Contact phone number */
+            contactPhone?: string;
+            /** @description Customer reference number for invoices */
+            invoiceRecipientNumber?: string;
+            /** @description Custom notes to include on invoices */
+            invoiceNotes?: string;
+            /**
+             * @description Preferred currency (EUR, USD, etc.)
+             * @default EUR
+             */
+            preferredCurrency: string;
+            /**
+             * @description Auto-generate monthly invoices
+             * @default true
+             */
+            autoInvoice: boolean;
+        };
+        UpdateBillingProfileDto: {
+            /** @description Company name (required for B2B invoicing) */
+            companyName?: string;
+            /** @description VAT/Tax ID number (EU format: XX followed by numbers) */
+            vatNumber?: string;
+            /** @description Alternative tax identification */
+            taxId?: string;
+            /** @description Address line 1 */
+            addressLine1?: string;
+            /** @description Address line 2 */
+            addressLine2?: string;
+            /** @description City */
+            city?: string;
+            /** @description State/Province */
+            state?: string;
+            /** @description Postal/ZIP code */
+            postalCode?: string;
+            /** @description Country code (2-letter ISO) */
+            country?: string;
+            /** @description Contact person name */
+            contactName?: string;
+            /** @description Email for receiving invoices */
+            contactEmail?: string;
+            /** @description Contact phone number */
+            contactPhone?: string;
+            /** @description Customer reference number for invoices */
+            invoiceRecipientNumber?: string;
+            /** @description Custom notes to include on invoices */
+            invoiceNotes?: string;
+            /**
+             * @description Preferred currency (EUR, USD, etc.)
+             * @default EUR
+             */
+            preferredCurrency: string;
+            /**
+             * @description Auto-generate monthly invoices
+             * @default true
+             */
+            autoInvoice: boolean;
+        };
+        ValidateVatDto: {
+            /** @description VAT number to validate (EU format) */
+            vatNumber: string;
+        };
+        TopUpBalanceDto: {
+            /**
+             * @description Amount to add to balance
+             * @example 50
+             */
+            amount: number;
+            /** @description Payment method reference (e.g., Stripe payment intent ID) */
+            paymentReference?: string;
+            /** @description Type of payment reference (e.g., stripe_payment, manual_topup) */
+            referenceType?: string;
+            /** @description Description for the top-up */
+            description?: string;
+        };
+        BalanceSettingsDto: {
+            /** @description Low balance alert threshold */
+            lowBalanceThreshold?: number;
+            /** @description Enable automatic top-up */
+            autoTopUpEnabled?: boolean;
+            /** @description Amount to auto top-up when balance is low */
+            autoTopUpAmount?: number;
+            /** @description Balance threshold to trigger auto top-up */
+            autoTopUpThreshold?: number;
+            /** @description Credit limit for negative balance */
+            creditLimit?: number;
+        };
+        PaylinqWebhookResponse: {
+            success: boolean;
+            message: string;
+        };
+        AddPaymentMethodDto: Record<string, never>;
+        CreateProjectDto: Record<string, never>;
+        UpdateProjectDto: Record<string, never>;
+        UpdatePoaSettingsDto: {
+            /**
+             * @description Enable PoA verification for this environment
+             * @example true
+             */
+            poaEnabled?: boolean;
+            /**
+             * @description Threshold for auto-approval (0.0-1.0). Documents above this confidence are auto-approved.
+             * @example 0.7
+             */
+            poaAutoApproveThreshold?: number;
+            /**
+             * @description Threshold for manual review (0.0-1.0). Documents between this and auto-approve threshold require manual review.
+             * @example 0.5
+             */
+            poaManualReviewThreshold?: number;
+            /**
+             * @description Block final verification until PoA is approved
+             * @example false
+             */
+            poaRequiredForVerification?: boolean;
+            /**
+             * @description Force all PoA to go through manual review (disable auto-approve)
+             * @example false
+             */
+            poaForceManualReview?: boolean;
+        };
+        RetryWebhookDeliveryDto: Record<string, never>;
+        InviteTeamMemberDto: Record<string, never>;
+        UpdateMemberRoleDto: Record<string, never>;
+        AcceptInvitationDto: Record<string, never>;
+        RegisterDto: Record<string, never>;
+        UpdateProfileDto: Record<string, never>;
+        ChangePasswordDto: Record<string, never>;
+        SetPasswordDto: Record<string, never>;
+        ResetPasswordDto: Record<string, never>;
+        CreateContactRequestDto: {
+            /**
+             * @description Full name of the person making contact
+             * @example John Doe
+             */
+            name: string;
+            /**
+             * @description Email address for contact
+             * @example john.doe@example.com
+             */
+            email: string;
+        };
+        ContactRequestResponseDto: {
+            /** @description Unique identifier for the contact request */
+            id: string;
+            /** @description Contact person name */
+            name: string;
+            /** @description Contact email address */
+            email: string;
+            /**
+             * @description Source of the contact request
+             * @example landing
+             */
+            source: string;
+            /**
+             * @description Status of the contact request
+             * @example new
+             */
+            status: string;
+            /**
+             * Format: date-time
+             * @description Timestamp when the request was created
+             */
+            createdAt: string;
+        };
+        CreateSessionDto: {
+            /**
+             * @description Custom client metadata for identification and tracking
+             * @example {
+             *       "userId": "user_12345",
+             *       "email": "john.doe@example.com",
+             *       "name": "John Doe",
+             *       "accountType": "premium"
+             *     }
+             */
+            clientMetadata?: Record<string, never>;
+            /**
+             * @description Session expiry time in minutes (default: 5, max: 60)
+             * @example 30
+             */
+            expiryMinutes?: number;
+            /**
+             * @description Language for widget UI
+             * @example de
+             * @enum {string}
+             */
+            language?: "en" | "de" | "uk";
+            /**
+             * @description Server-side metadata for internal tracking
+             * @example {
+             *       "requestId": "req_123",
+             *       "sourceIp": "192.168.1.1",
+             *       "userAgent": "MyApp/1.0"
+             *     }
+             */
+            serverMetadata?: Record<string, never>;
+        };
+        SessionDetailsDto: {
+            /**
+             * @description Unique session identifier
+             * @example clx1234567890abcdef
+             */
+            id: string;
+            /**
+             * @description Session status
+             * @example pending
+             * @enum {string}
+             */
+            status: "pending" | "in_progress" | "completed" | "failed" | "expired";
+            /**
+             * Format: date-time
+             * @description Session expiration timestamp
+             * @example 2024-10-25T14:30:00.000Z
+             */
+            expiresAt: string;
+            /**
+             * @description Client metadata
+             * @example {
+             *       "userId": "user_12345",
+             *       "email": "john.doe@example.com"
+             *     }
+             */
+            clientMetadata?: Record<string, never>;
+            /**
+             * @description Widget URL for embedding
+             * @example https://widget.flonk.id/?sessionId=clx1234567890abcdef&mode=embedded
+             */
+            widgetUrl: string;
+            /**
+             * @description QR code data for mobile verification
+             * @example https://widget.flonk.id/verify/clx1234567890abcdef?token=kyc_1234567890_abc123
+             */
+            qrCodeUrl: string;
+            /**
+             * Format: date-time
+             * @description Session creation timestamp
+             * @example 2024-10-25T14:25:00.000Z
+             */
+            createdAt: string;
+            /**
+             * @description Project identifier
+             * @example clxproject123
+             */
+            projectId: string;
+            /**
+             * @description Whether manual upload is allowed for this session
+             * @example true
+             */
+            allowManualUpload: boolean;
+            /**
+             * @description Embed token for widget authentication (like Stripe client_secret)
+             * @example eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+             */
+            embedToken?: string;
+            /**
+             * @description Indicates if an existing session was reused instead of creating a new one
+             * @example false
+             */
+            reused?: boolean;
+            /**
+             * @description Test mode flag - true if created with test keys (sk_test_*)
+             * @example false
+             */
+            testMode?: boolean;
+            /**
+             * Format: date-time
+             * @description Last activity timestamp
+             * @example 2024-10-25T14:28:00.000Z
+             */
+            lastActivity?: string;
+            /**
+             * @description Server metadata
+             * @example {
+             *       "requestId": "req_123",
+             *       "sourceIp": "192.168.1.1"
+             *     }
+             */
+            serverMetadata?: Record<string, never>;
+            /**
+             * Format: date-time
+             * @description Last update timestamp
+             * @example 2024-10-25T14:28:00.000Z
+             */
+            updatedAt: string;
+        };
+        UpdateStatusDto: Record<string, never>;
+        AddNoteDto: Record<string, never>;
+        UploadDocumentDto: {
+            /** @enum {string} */
+            documentType: "main" | "back" | "face" | "passport" | "id_card" | "driver_license" | "utility_bill" | "bank_statement" | "selfie";
+        };
+        UpdateSystemRoleDto: Record<string, never>;
+        SuspendUserDto: Record<string, never>;
+        UnsuspendUserDto: Record<string, never>;
+        ChangeMembershipRoleDto: Record<string, never>;
+        AddMembershipDto: Record<string, never>;
+        SuspendProjectDto: Record<string, never>;
+        UnsuspendProjectDto: Record<string, never>;
+        UpdateBrandingDto: Record<string, never>;
+        UpdateWebhookDto: Record<string, never>;
+        UpdateFaceAutoCaptureDto: Record<string, never>;
+        AddDomainDto: Record<string, never>;
+        CreditBalanceDto: Record<string, never>;
+        DebitBalanceDto: Record<string, never>;
+        ApproveProjectDto: Record<string, never>;
+        RejectProjectDto: Record<string, never>;
+        CreateInviteDto: Record<string, never>;
+        AcceptInviteDto: Record<string, never>;
+        UpdatePlatformFaceAutoCaptureDto: Record<string, never>;
+        WebhookExtractedDataDto: {
+            full_name?: string | null;
+            first_name?: string | null;
+            last_name?: string | null;
+            date_of_birth?: string | null;
+            nationality?: string | null;
+            sex?: string | null;
+            issue_date?: string | null;
+            expiry_date?: string | null;
+            place_of_birth?: string | null;
+        };
+        WebhookPoaVerificationDto: {
+            status: string;
+            confidence_score: number | null;
+            verified_address?: string | null;
+            address_match?: boolean;
+        };
+        WebhookDuplicateVerificationDto: {
+            is_duplicate: boolean;
+            previous_verification_id: string;
+            previous_verified_at: string;
+            /** @enum {string} */
+            match_type: "document_number" | "personal_data";
+            similarity_score: number;
+        };
+        WebhookReuseSourceDto: {
+            /** @enum {number} */
+            is_reused: true;
+            verified_identity_id: string;
+            original_project_id: string | null;
+            original_attempt_id: string;
+            original_completed_at: string;
+            consent_at: string;
+            mode: string;
+        };
+        WebhookEventObjectDto: {
+            id: string;
+            client_id?: string;
+            client_metadata?: {
+                [key: string]: unknown;
+            };
+            status: string;
+            confidence?: number;
+            document_type: string;
+            extracted_data: components["schemas"]["WebhookExtractedDataDto"];
+            created_at: string;
+            updated_at?: string;
+            updated_by?: string;
+            test_mode?: boolean;
+            poa_verification?: components["schemas"]["WebhookPoaVerificationDto"];
+            duplicate_verification?: components["schemas"]["WebhookDuplicateVerificationDto"];
+            reuse_source?: components["schemas"]["WebhookReuseSourceDto"];
+            previous_status?: string;
+            rejection_reason?: string;
+            reviewed_by?: string;
+        };
+        WebhookEventDataDto: {
+            object: components["schemas"]["WebhookEventObjectDto"];
+        };
+        WebhookEventDto: {
+            id: string;
+            /** @enum {string} */
+            type: "verification.completed" | "verification.status_changed" | "verification.updated";
+            created: number;
+            livemode: boolean;
+            data: components["schemas"]["WebhookEventDataDto"];
+        };
+    };
+    responses: never;
+    parameters: never;
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+
 type SessionStatus = 'pending' | 'connected' | 'processing' | 'completed' | 'failed' | 'expired';
 type DocumentType = 'passport' | 'id_card' | 'driver_license';
 type WidgetLanguage = 'en' | 'de' | 'uk';
@@ -5,6 +867,12 @@ interface FlonkKYCServerOptions {
     secretKey: string;
     apiBase?: string;
     timeout?: number;
+    /** Max retry attempts for transient failures (429/5xx/network). Default 2. */
+    maxRetries?: number;
+    /** Base backoff in ms (full-jittered exponential). Default 250. */
+    retryBaseMs?: number;
+    /** Pin the REST API version (`Flonk-Version` header). Default: the SDK's build version. */
+    apiVersion?: string;
 }
 interface CreateSessionParams {
     clientMetadata?: Record<string, unknown>;
@@ -12,6 +880,13 @@ interface CreateSessionParams {
     expiryMinutes?: number;
     language?: WidgetLanguage;
     serverMetadata?: Record<string, unknown>;
+    /**
+     * Idempotency key for this create. A retry with the same key returns the
+     * original session instead of creating a new one. Auto-generated (UUID) per
+     * call if omitted; supply your own to make a specific create idempotent
+     * across process restarts.
+     */
+    idempotencyKey?: string;
 }
 interface Session {
     id: string;
@@ -36,42 +911,48 @@ interface UpdateSessionParams {
     clientMetadata?: Record<string, unknown>;
     serverMetadata?: Record<string, unknown>;
 }
-interface WebhookEvent {
+type WebhookSchemas = components['schemas'];
+type WebhookObjectFull = WebhookSchemas['WebhookEventObjectDto'];
+/** Fields common to every verification webhook's `data.object` (generated). */
+type WebhookObjectBase = Omit<WebhookObjectFull, 'duplicate_verification' | 'reuse_source' | 'previous_status' | 'rejection_reason' | 'reviewed_by' | 'updated_at' | 'updated_by'>;
+interface WebhookEventBase {
     id: string;
-    type: 'verification.completed' | 'verification.status_changed' | 'verification.updated';
     created: number;
     livemode: boolean;
+}
+/** Automated AI verification finished. */
+interface VerificationCompletedEvent extends WebhookEventBase {
+    type: 'verification.completed';
     data: {
-        object: {
-            id: string;
-            client_id?: string;
-            client_metadata?: Record<string, unknown>;
-            status: string;
-            confidence?: number;
-            document_type: string;
-            extracted_data: {
-                full_name?: string;
-                first_name?: string;
-                last_name?: string;
-                date_of_birth?: string;
-                nationality?: string;
-                sex?: string;
-                [key: string]: unknown;
-            };
-            created_at: string;
-            updated_at?: string;
-            updated_by?: string;
-            test_mode?: boolean;
-            poa_verification?: {
-                status: string;
-                confidence_score: number | null;
-            };
-            previous_status?: string;
-            rejection_reason?: string;
-            reviewed_by?: string;
-        };
+        object: WebhookObjectBase & Pick<WebhookObjectFull, 'duplicate_verification' | 'reuse_source'>;
+    };
+}
+/** An admin manually approved/rejected the verification. */
+interface VerificationStatusChangedEvent extends WebhookEventBase {
+    type: 'verification.status_changed';
+    data: {
+        object: WebhookObjectBase & Pick<WebhookObjectFull, 'previous_status' | 'rejection_reason' | 'reviewed_by'>;
+    };
+}
+/** An admin edited verification data, or async PoA review finished. */
+interface VerificationUpdatedEvent extends WebhookEventBase {
+    type: 'verification.updated';
+    data: {
+        object: WebhookObjectBase & Pick<WebhookObjectFull, 'updated_at' | 'updated_by'>;
     };
 }
+/**
+ * Closed discriminated union — the Stripe approach. `event.type` narrows
+ * `event.data.object`, so a `switch (event.type)` is type-safe and exhaustive,
+ * and per-event fields live only on the events that carry them. Kept current by
+ * the OpenAPI codegen pipeline (TYPES.md): a new platform event type is picked
+ * up on the next generation. A brand-new type still arrives at runtime
+ * (`constructEvent` never rejects it) — handle it in the `default` branch, and
+ * cast if you must reference it before regenerating.
+ */
+type WebhookEvent = VerificationCompletedEvent | VerificationStatusChangedEvent | VerificationUpdatedEvent;
+/** Union of every event `type` literal this SDK knows. */
+type WebhookEventType = WebhookEvent['type'];
 interface WebhookVerifyOptions {
     /** Max clock skew in seconds. Default: 300 */
     maxSkewSeconds?: number;
@@ -79,7 +960,13 @@ interface WebhookVerifyOptions {
 
 declare class Webhooks {
     /**
-     * Verify X-Signature-256 header: "sha256=<hex>"
+     * Verify X-Signature-256 header: "sha256=<hex>".
+     *
+     * NOTE: this format carries no timestamp, so it has **no replay protection** —
+     * a captured request stays valid forever. Prefer {@link verifyTimestampSignature}
+     * (the `t=,v1=` header, sent as `X-Signature`), and dedupe by `event.id` in
+     * your own store (a unique index, or Redis `SET id 1 NX EX <ttl>`) so retries
+     * are processed once.
      */
     verifySignature(payload: string, signature: string, secret: string): WebhookEvent;
     /**
@@ -92,11 +979,18 @@ declare class Webhooks {
     constructEvent(payload: string, signature: string, secret: string): WebhookEvent;
     private parsePayload;
     private parseHeader;
+    /**
+     * Constant-time string compare with no length-dependent branch: HMAC both
+     * sides with a per-call random key so the compared buffers are always 32
+     * bytes regardless of input length, then timingSafeEqual. Equal digests imply
+     * equal inputs (HMAC collision resistance), so this leaks neither the result
+     * nor the length via timing.
+     */
     private safeEqual;
 }
 
 declare class FlonkKYCServer {
-    static readonly version = "1.8.2";
+    static readonly version = "1.9.1";
     private readonly http;
     readonly webhooks: Webhooks;
     constructor(options: FlonkKYCServerOptions);
@@ -105,14 +999,22 @@ declare class FlonkKYCServer {
     updateSession(sessionId: string, params: UpdateSessionParams): Promise<SessionDetails>;
 }
 
+/**
+ * Stable, machine-branchable error codes returned by the API in the `code`
+ * field of an error body. Open union (`| (string & {})`) so new codes don't
+ * break consumers — branch on the ones you handle, fall through on the rest.
+ */
+type FlonkErrorCode = 'authentication_error' | 'invalid_publishable_key' | 'session_not_found' | 'session_expired' | 'session_invalid_state' | 'rate_limited' | 'validation_error' | 'api_error' | (string & {});
 declare class FlonkError extends Error {
-    readonly code: string;
+    readonly code: FlonkErrorCode;
     readonly statusCode?: number | undefined;
-    constructor(message: string, code: string, statusCode?: number | undefined);
+    constructor(message: string, code: FlonkErrorCode, statusCode?: number | undefined);
 }
 declare class FlonkAPIError extends FlonkError {
     readonly body?: unknown | undefined;
-    constructor(message: string, statusCode: number, body?: unknown | undefined);
+    constructor(message: string, statusCode: number, body?: unknown | undefined, 
+    /** The API's stable error code (from the response body), if it sent one. */
+    code?: FlonkErrorCode);
 }
 declare class FlonkAuthenticationError extends FlonkError {
     constructor(message?: string);
@@ -124,4 +1026,4 @@ declare class FlonkWebhookSignatureError extends FlonkError {
     constructor(message?: string);
 }
 
-export { type CreateSessionParams, type DocumentType, FlonkAPIError, FlonkAuthenticationError, FlonkError, FlonkKYCServer, type FlonkKYCServerOptions, FlonkValidationError, FlonkWebhookSignatureError, type Session, type SessionDetails, type SessionStatus, type UpdateSessionParams, type WebhookEvent, type WebhookVerifyOptions, Webhooks, type WidgetLanguage };
+export { type CreateSessionParams, type DocumentType, FlonkAPIError, FlonkAuthenticationError, FlonkError, type FlonkErrorCode, FlonkKYCServer, type FlonkKYCServerOptions, FlonkValidationError, FlonkWebhookSignatureError, type Session, type SessionDetails, type SessionStatus, type UpdateSessionParams, type VerificationCompletedEvent, type VerificationStatusChangedEvent, type VerificationUpdatedEvent, type WebhookEvent, type WebhookEventType, type WebhookVerifyOptions, Webhooks, type WidgetLanguage };