@inkress/admin-sdk 1.1.42 → 1.1.44

package/dist/index.js

@@ -1917,7 +1917,7 @@ const ORDER_FIELD_TYPES = {
     status_on: 'number',
     uid: 'string',
     cart_id: 'number',
-    currency_id: 'number',
+    currency_code: 'string',
     customer_id: 'number',
     payment_link_id: 'number',
     billing_plan_id: 'number',
@@ -1945,7 +1945,7 @@ const PRODUCT_FIELD_TYPES = {
     tag_ids: 'array',
     uid: 'string',
     category_id: 'number',
-    currency_id: 'number',
+    currency_code: 'string',
     user_id: 'number',
     inserted_at: 'date',
     updated_at: 'date',
@@ -2037,7 +2037,7 @@ const BILLING_PLAN_FIELD_TYPES = {
     payout_value_limit: 'number',
     payout_percentage_limit: 'number',
     uid: 'string',
-    currency_id: 'number',
+    currency_code: 'string',
     payment_provider_id: 'number',
     inserted_at: 'date',
     updated_at: 'date',
@@ -2078,7 +2078,7 @@ const PAYMENT_LINK_FIELD_TYPES = {
     status: 'number',
     kind: 'number',
     customer_id: 'number',
-    currency_id: 'number',
+    currency_code: 'string',
     order_id: 'number',
     inserted_at: 'date',
     updated_at: 'date',
@@ -2122,7 +2122,7 @@ const FINANCIAL_REQUEST_FIELD_TYPES = {
     merchant_id: 'number',
     requester_id: 'number',
     reviewer_id: 'number',
-    currency_id: 'number',
+    currency_code: 'string',
     evidence_file_id: 'number',
     inserted_at: 'date',
     updated_at: 'date',
@@ -2216,7 +2216,6 @@ const FEE_FIELD_TYPES = {
     currency_code: 'string',
     hash: 'string',
     fee_set_id: 'number',
-    currency_id: 'number',
     user_id: 'number',
     inserted_at: 'date',
     updated_at: 'date',
@@ -3474,6 +3473,62 @@ class PublicResource {
     }
 }
 
+/**
+ * KYC document requirements by entity type
+ * These are the standard documents required for each type of business entity
+ */
+const KYC_DOCUMENT_REQUIREMENTS = {
+    personal: [
+        'Proof of Identity',
+        'Proof of Address',
+        'Proof of Bank Account Ownership',
+    ],
+    'sole-trader': [
+        'Proof of Identity',
+        'Proof of Address',
+        'Proof of Bank Account Ownership',
+        'Business Certificate',
+        'Articles of Incorporation',
+    ],
+    llc: [
+        'Proof of Identity',
+        'Proof of Address',
+        'Proof of Bank Account Ownership',
+        'Business Certificate',
+        'Articles of Incorporation',
+        'Annual Return',
+        'Notice of Directors',
+        'Notice of Secretary',
+        'Tax Compliance Certificate',
+    ],
+    'non-profit': [
+        'Proof of Identity',
+        'Proof of Address',
+        'Proof of Bank Account Ownership',
+        'Business Certificate',
+        'Articles of Incorporation',
+        'Annual Return',
+    ],
+    alumni: [
+        'Proof of Identity',
+        'Proof of Address',
+        'Proof of Bank Account Ownership',
+        'Business Certificate',
+        'Articles of Incorporation',
+        'Annual Return',
+    ],
+    other: [
+        'Proof of Identity',
+        'Proof of Address',
+        'Proof of Bank Account Ownership',
+        'Business Certificate',
+        'Articles of Incorporation',
+        'Annual Return',
+        'Notice of Directors',
+        'Notice of Secretary',
+        'Tax Compliance Certificate',
+    ],
+};
 // Field type definitions for query validation
 const KYC_FIELD_TYPES = {
     id: 'number',
@@ -3554,6 +3609,185 @@ class KycResource {
     async updateBankInfo(data) {
         return this.client.post('/legal_requests', data);
     }
+    // ============================================================================
+    // KYC DOCUMENT REQUIREMENTS & STATUS
+    // ============================================================================
+    /**
+     * Get required KYC documents for a specific entity type
+     * This is a client-side method that doesn't make an API call
+     *
+     * @param entityType - The type of business entity
+     * @returns Array of required document types
+     *
+     * @example
+     * const docs = kyc.getRequiredDocuments('llc');
+     * // Returns: ['Proof of Identity', 'Proof of Address', ...]
+     */
+    getRequiredDocuments(entityType) {
+        return [...KYC_DOCUMENT_REQUIREMENTS[entityType]];
+    }
+    /**
+     * Get all KYC document requirements (without making an API call)
+     * Useful for displaying the full list in your application
+     *
+     * @returns Complete mapping of entity types to required documents
+     *
+     * @example
+     * const allRequirements = kyc.getAllRequirements();
+     * console.log(allRequirements.llc); // ['Proof of Identity', ...]
+     */
+    getAllRequirements() {
+        return { ...KYC_DOCUMENT_REQUIREMENTS };
+    }
+    /**
+     * Get KYC requirements and submission status for the authenticated merchant
+     * Fetches all KYC requests and maps them to required documents
+     *
+     * @param entityType - The merchant's business entity type
+     * @returns Complete KYC requirements with submission status
+     *
+     * @example
+     * const status = await kyc.getRequirementsStatus('llc');
+     * console.log(`Completion: ${status.completion_percentage}%`);
+     * console.log(`Approved: ${status.total_approved}/${status.total_required}`);
+     *
+     * // Check individual document status
+     * status.document_statuses.forEach(doc => {
+     *   console.log(`${doc.document_type}: ${doc.status || 'not submitted'}`);
+     * });
+     */
+    async getRequirementsStatus(entityType) {
+        // Get required documents for this entity type
+        const requiredDocuments = this.getRequiredDocuments(entityType);
+        // Fetch all KYC requests for the authenticated merchant
+        const params = {
+            kind: 'document_submission',
+        };
+        const response = await this.list(params);
+        if (response.state === 'error' || !response.result) {
+            return {
+                state: 'error',
+            };
+        }
+        const kycRequests = response.result.entries || [];
+        // Map submitted documents
+        const submittedDocs = new Map();
+        kycRequests.forEach(request => {
+            var _a;
+            const docType = (_a = request.data) === null || _a === void 0 ? void 0 : _a.document_type;
+            if (docType && requiredDocuments.includes(docType)) {
+                // Keep the most recent submission for each document type
+                const existing = submittedDocs.get(docType);
+                if (!existing || new Date(request.inserted_at) > new Date(existing.inserted_at)) {
+                    submittedDocs.set(docType, request);
+                }
+            }
+        });
+        // Build document statuses
+        const documentStatuses = requiredDocuments.map(docType => {
+            var _a;
+            const submission = submittedDocs.get(docType);
+            if (!submission) {
+                return {
+                    document_type: docType,
+                    required: true,
+                    submitted: false,
+                };
+            }
+            // Convert integer status to string using translator
+            // The API returns status as a number, but the type says it's a string
+            const statusString = StatusTranslator.toStringWithoutContext(submission.status, 'legal_request');
+            // Map to our simplified status types
+            let status;
+            if (statusString) {
+                if (statusString === 'pending' || statusString === 'in_review') {
+                    status = 'pending';
+                }
+                else if (statusString === 'approved') {
+                    status = 'approved';
+                }
+                else if (statusString === 'rejected') {
+                    status = 'rejected';
+                }
+            }
+            const reviewedAt = submission.updated_at !== submission.inserted_at
+                ? submission.updated_at
+                : undefined;
+            return {
+                document_type: docType,
+                required: true,
+                submitted: true,
+                status,
+                submitted_at: submission.inserted_at,
+                reviewed_at: reviewedAt,
+                rejection_reason: (_a = submission.data) === null || _a === void 0 ? void 0 : _a.rejection_reason,
+            };
+        });
+        // Calculate statistics
+        const totalRequired = requiredDocuments.length;
+        const totalSubmitted = documentStatuses.filter(d => d.submitted).length;
+        const totalApproved = documentStatuses.filter(d => d.status === 'approved').length;
+        const totalRejected = documentStatuses.filter(d => d.status === 'rejected').length;
+        const totalPending = documentStatuses.filter(d => d.status === 'pending').length;
+        const completionPercentage = totalRequired > 0
+            ? Math.round((totalApproved / totalRequired) * 100)
+            : 0;
+        const isComplete = totalApproved === totalRequired;
+        const requirements = {
+            entity_type: entityType,
+            required_documents: requiredDocuments,
+            document_statuses: documentStatuses,
+            total_required: totalRequired,
+            total_submitted: totalSubmitted,
+            total_approved: totalApproved,
+            total_rejected: totalRejected,
+            total_pending: totalPending,
+            completion_percentage: completionPercentage,
+            is_complete: isComplete,
+        };
+        return {
+            state: 'ok',
+            result: requirements,
+        };
+    }
+    /**
+     * Check if all required documents have been approved for the authenticated merchant
+     *
+     * @param entityType - The merchant's business entity type
+     * @returns True if all required documents are approved
+     *
+     * @example
+     * const isComplete = await kyc.isKycComplete('llc');
+     * if (isComplete) {
+     *   console.log('Merchant is fully verified!');
+     * }
+     */
+    async isKycComplete(entityType) {
+        var _a;
+        const response = await this.getRequirementsStatus(entityType);
+        return ((_a = response.result) === null || _a === void 0 ? void 0 : _a.is_complete) || false;
+    }
+    /**
+     * Get list of missing (not submitted or rejected) documents for the authenticated merchant
+     *
+     * @param entityType - The merchant's business entity type
+     * @returns Array of document types that need to be submitted or resubmitted
+     *
+     * @example
+     * const missing = await kyc.getMissingDocuments('llc');
+     * if (missing.length > 0) {
+     *   console.log('Please submit:', missing.join(', '));
+     * }
+     */
+    async getMissingDocuments(entityType) {
+        const response = await this.getRequirementsStatus(entityType);
+        if (response.state === 'error' || !response.result) {
+            return [];
+        }
+        return response.result.document_statuses
+            .filter(doc => !doc.submitted || doc.status === 'rejected')
+            .map(doc => doc.document_type);
+    }
 }
 
 class PaymentLinksResource {
@@ -3842,6 +4076,15 @@ class FinancialRequestsResource {
     }
 }
 
+let crypto;
+try {
+    if (typeof require !== 'undefined') {
+        crypto = require('crypto');
+    }
+}
+catch (_a) {
+    // Fallback for environments without Node.js crypto
+}
 class WebhookUrlsResource {
     constructor(client) {
         this.client = client;
@@ -3901,6 +4144,160 @@ class WebhookUrlsResource {
     createQueryBuilder() {
         return new WebhookUrlQueryBuilder(this);
     }
+    // ============================================================================
+    // WEBHOOK VERIFICATION METHODS
+    // ============================================================================
+    /**
+     * Verify webhook signature using HMAC SHA256
+     * Inkress webhooks use the format: crypto.mac(:hmac, :sha256, secret, body) |> Base.encode64()
+     */
+    verifySignature(body, signature, secret) {
+        if (!crypto) {
+            throw new Error('Node.js crypto module not available. Cannot verify webhook signature.');
+        }
+        try {
+            // Generate expected signature using HMAC SHA256
+            const expectedSignature = crypto
+                .createHmac('sha256', secret)
+                .update(body, 'utf8')
+                .digest('base64');
+            // Use constant-time comparison to prevent timing attacks
+            return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature));
+        }
+        catch (error) {
+            return false;
+        }
+    }
+    /**
+     * Parse webhook payload from a string
+     */
+    parsePayload(payload) {
+        try {
+            const parsed = JSON.parse(payload);
+            if (!parsed.id || !parsed.timestamp || !parsed.event) {
+                throw new Error('Invalid webhook payload structure: missing required fields (id, timestamp, or event)');
+            }
+            return parsed;
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                throw new Error(`Failed to parse webhook payload: ${error.message}`);
+            }
+            throw new Error('Failed to parse webhook payload');
+        }
+    }
+    /**
+     * Verify and parse an incoming webhook request
+     * This method clones the request body, validates the signature, and returns the parsed payload
+     *
+     * @param request - The incoming HTTP request object with headers and body
+     * @param secret - Your webhook secret for signature verification
+     * @param options - Optional verification options (e.g., timestamp tolerance)
+     * @returns Promise that resolves to the parsed webhook payload
+     * @throws Error if signature verification fails or payload is invalid
+     *
+     * @example
+     * ```typescript
+     * // Express.js example
+     * app.post('/webhooks', async (req, res) => {
+     *   try {
+     *     const payload = await sdk.webhookUrls.verifyRequest(
+     *       { headers: req.headers, body: req.body },
+     *       'your-webhook-secret'
+     *     );
+     *
+     *     // Process the webhook
+     *     console.log('Received webhook:', payload.event.type);
+     *
+     *     res.status(200).json({ received: true });
+     *   } catch (error) {
+     *     console.error('Webhook verification failed:', error);
+     *     res.status(400).json({ error: error.message });
+     *   }
+     * });
+     * ```
+     */
+    async verifyRequest(request, secret, options) {
+        // Extract signature from headers (case-insensitive)
+        const signature = request.headers['x-inkress-webhook-signature'] ||
+            request.headers['X-Inkress-Webhook-Signature'];
+        if (!signature || typeof signature !== 'string') {
+            throw new Error('Missing X-Inkress-Webhook-Signature header');
+        }
+        // Clone and ensure body is a string
+        let body;
+        if (typeof request.body === 'string') {
+            body = request.body;
+        }
+        else if (request.body && typeof request.body === 'object') {
+            body = JSON.stringify(request.body);
+        }
+        else {
+            throw new Error('Invalid request body format: body must be a string or object');
+        }
+        // Verify signature
+        const isValid = this.verifySignature(body, signature, secret);
+        if (!isValid) {
+            throw new Error('Webhook signature verification failed: signature does not match');
+        }
+        // Parse the payload
+        const payload = this.parsePayload(body);
+        // Optional: Verify timestamp tolerance
+        if (options === null || options === void 0 ? void 0 : options.tolerance) {
+            const currentTimestamp = Math.floor(Date.now() / 1000);
+            const timeDifference = Math.abs(currentTimestamp - payload.timestamp);
+            if (timeDifference > options.tolerance) {
+                throw new Error(`Webhook timestamp outside tolerance window: ${timeDifference}s (max: ${options.tolerance}s)`);
+            }
+        }
+        return payload;
+    }
+    /**
+     * Verify webhook signature only (without parsing)
+     * Useful for custom verification flows
+     *
+     * @param body - The raw webhook request body as a string
+     * @param signature - The signature from X-Inkress-Webhook-Signature header
+     * @param secret - Your webhook secret
+     * @returns Promise that resolves to true if valid, rejects with error if invalid
+     */
+    async verify(body, signature, secret) {
+        if (!this.verifySignature(body, signature, secret)) {
+            throw new Error('Webhook signature verification failed');
+        }
+        return true;
+    }
+    /**
+     * Generate webhook signature for testing
+     * Matches Inkress signature generation: crypto.mac(:hmac, :sha256, secret, body) |> Base.encode64()
+     *
+     * @example
+     * ```typescript
+     * const testBody = JSON.stringify({ id: '123', timestamp: Date.now(), event: {...} });
+     * const signature = sdk.webhookUrls.generateSignature(testBody, 'your-secret');
+     * ```
+     */
+    generateSignature(body, secret) {
+        if (!crypto) {
+            throw new Error('Node.js crypto module not available. Cannot generate signature.');
+        }
+        return crypto
+            .createHmac('sha256', secret)
+            .update(body, 'utf8')
+            .digest('base64');
+    }
+    /**
+     * Extract event data from webhook payload with type safety
+     *
+     * @example
+     * ```typescript
+     * const payload = await sdk.webhookUrls.verifyRequest(request, secret);
+     * const orderData = sdk.webhookUrls.extractEventData<Order>(payload);
+     * ```
+     */
+    extractEventData(payload) {
+        return payload.event.data;
+    }
 }
 
 /**
@@ -4561,6 +4958,7 @@ exports.FinancialRequestQueryBuilder = FinancialRequestQueryBuilder;
 exports.HttpClient = HttpClient;
 exports.InkressApiError = InkressApiError;
 exports.InkressSDK = InkressSDK;
+exports.KYC_DOCUMENT_REQUIREMENTS = KYC_DOCUMENT_REQUIREMENTS;
 exports.MERCHANT_FIELD_TYPES = MERCHANT_FIELD_TYPES;
 exports.MerchantQueryBuilder = MerchantQueryBuilder;
 exports.ORDER_FIELD_TYPES = ORDER_FIELD_TYPES;