vesant-sdk 1.0.4

package/dist/kyc/core.mjs

@@ -0,0 +1,771 @@
+// src/core/errors.ts
+var CGSError = class _CGSError extends Error {
+  constructor(message, code, statusCode, details) {
+    super(message);
+    this.code = code;
+    this.statusCode = statusCode;
+    this.details = details;
+    this.name = "CGSError";
+    Object.setPrototypeOf(this, _CGSError.prototype);
+  }
+};
+var NetworkError = class _NetworkError extends CGSError {
+  constructor(message, originalError) {
+    super(message, "NETWORK_ERROR", void 0, { originalError });
+    this.originalError = originalError;
+    this.name = "NetworkError";
+    Object.setPrototypeOf(this, _NetworkError.prototype);
+  }
+};
+var ServiceUnavailableError = class _ServiceUnavailableError extends CGSError {
+  constructor(service) {
+    super(`${service} is unavailable`, "SERVICE_UNAVAILABLE", 503, { service });
+    this.name = "ServiceUnavailableError";
+    Object.setPrototypeOf(this, _ServiceUnavailableError.prototype);
+  }
+};
+var AuthenticationError = class _AuthenticationError extends CGSError {
+  constructor(message = "Authentication failed") {
+    super(message, "AUTHENTICATION_ERROR", 401);
+    this.name = "AuthenticationError";
+    Object.setPrototypeOf(this, _AuthenticationError.prototype);
+  }
+};
+var RateLimitError = class _RateLimitError extends CGSError {
+  constructor(retryAfter) {
+    super("Rate limit exceeded", "RATE_LIMIT_EXCEEDED", 429, { retryAfter });
+    this.retryAfter = retryAfter;
+    this.name = "RateLimitError";
+    Object.setPrototypeOf(this, _RateLimitError.prototype);
+  }
+};
+var TimeoutError = class _TimeoutError extends CGSError {
+  constructor(timeout) {
+    super(`Request timeout after ${timeout}ms`, "TIMEOUT", 408, { timeout });
+    this.timeout = timeout;
+    this.name = "TimeoutError";
+    Object.setPrototypeOf(this, _TimeoutError.prototype);
+  }
+};
+
+// src/core/client.ts
+var BaseClient = class {
+  constructor(config) {
+    this.config = {
+      baseURL: config.baseURL,
+      tenantId: config.tenantId,
+      apiKey: config.apiKey || "",
+      headers: config.headers || {},
+      timeout: config.timeout || 1e4,
+      retries: config.retries || 3,
+      debug: config.debug || false
+    };
+  }
+  /**
+   * Make an HTTP request with timeout and error handling
+   */
+  async request(endpoint, options = {}, serviceURL) {
+    const url = `${serviceURL || this.config.baseURL}${endpoint}`;
+    const headers = {
+      "Content-Type": "application/json",
+      "X-Tenant-ID": this.config.tenantId,
+      ...this.config.headers,
+      ...options.headers || {}
+    };
+    if (this.config.apiKey) {
+      headers["Authorization"] = `Bearer ${this.config.apiKey}`;
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+    try {
+      if (this.config.debug) {
+        console.log(`[CGS SDK] ${options.method || "GET"} ${url}`, {
+          headers,
+          body: options.body
+        });
+      }
+      const response = await fetch(url, {
+        ...options,
+        headers,
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      const data = await response.json();
+      if (!response.ok) {
+        this.handleErrorResponse(response.status, data);
+      }
+      if (this.config.debug) {
+        console.log(`[CGS SDK] Response:`, data);
+      }
+      return data;
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof Error) {
+        if (error.name === "AbortError") {
+          throw new TimeoutError(this.config.timeout);
+        }
+        if (error instanceof CGSError) {
+          throw error;
+        }
+      }
+      throw new NetworkError("Network request failed", error);
+    }
+  }
+  /**
+   * Make an HTTP request with retry logic
+   */
+  async requestWithRetry(endpoint, options = {}, serviceURL, retries = this.config.retries) {
+    let lastError;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+      try {
+        return await this.request(endpoint, options, serviceURL);
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error("Unknown error");
+        if (lastError instanceof CGSError && lastError.statusCode && lastError.statusCode >= 400 && lastError.statusCode < 500) {
+          throw lastError;
+        }
+        if (attempt === retries) {
+          break;
+        }
+        const delay = Math.min(1e3 * Math.pow(2, attempt) + Math.random() * 1e3, 1e4);
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        if (this.config.debug) {
+          console.log(`[CGS SDK] Retry attempt ${attempt + 1}/${retries} after ${delay.toFixed(0)}ms`);
+        }
+      }
+    }
+    throw new NetworkError(`Request failed after ${retries} retries`, lastError);
+  }
+  /**
+   * Handle error responses from API
+   */
+  handleErrorResponse(status, data) {
+    const message = data.error || data.message || `HTTP ${status}`;
+    switch (status) {
+      case 400:
+        throw new CGSError(message, "BAD_REQUEST", 400, data);
+      case 401:
+        throw new AuthenticationError(message);
+      case 403:
+        throw new CGSError(message, "FORBIDDEN", 403, data);
+      case 404:
+        throw new CGSError(message, "NOT_FOUND", 404, data);
+      case 429:
+        const retryAfter = data.retry_after || data.retryAfter;
+        throw new RateLimitError(retryAfter);
+      case 500:
+      case 502:
+      case 503:
+      case 504:
+        throw new ServiceUnavailableError(message);
+      default:
+        throw new CGSError(message, "UNKNOWN_ERROR", status, data);
+    }
+  }
+  /**
+   * Build query string from parameters
+   */
+  buildQueryString(params) {
+    const query = new URLSearchParams();
+    Object.entries(params).forEach(([key, value]) => {
+      if (value !== void 0 && value !== null) {
+        if (Array.isArray(value)) {
+          value.forEach((item) => query.append(key, String(item)));
+        } else {
+          query.append(key, String(value));
+        }
+      }
+    });
+    const queryString = query.toString();
+    return queryString ? `?${queryString}` : "";
+  }
+  /**
+   * Update client configuration
+   */
+  updateConfig(config) {
+    this.config = {
+      ...this.config,
+      ...config,
+      headers: {
+        ...this.config.headers,
+        ...config.headers || {}
+      }
+    };
+  }
+  /**
+   * Get current configuration (readonly)
+   */
+  getConfig() {
+    return { ...this.config };
+  }
+  /**
+   * Health check endpoint
+   */
+  async healthCheck() {
+    return this.request("/api/v1/health");
+  }
+};
+
+// src/kyc/client.ts
+function addFilterParam(params, key, value) {
+  if (value !== void 0) {
+    params[key] = Array.isArray(value) ? value.join(",") : value;
+  }
+}
+function addSimpleParams(params, source, keys) {
+  for (const key of keys) {
+    if (source[key] !== void 0) {
+      params[key] = source[key];
+    }
+  }
+}
+var KycClient = class extends BaseClient {
+  constructor(config) {
+    const baseConfig = {
+      baseURL: config.baseURL,
+      tenantId: config.tenantId,
+      apiKey: config.apiKey,
+      headers: config.headers,
+      timeout: config.timeout,
+      retries: 3,
+      // Default retry count for KYC calls
+      debug: config.debug
+    };
+    super(baseConfig);
+    this.userId = config.userId;
+    this.riskProfileBaseURL = config.riskProfileBaseURL;
+  }
+  /**
+   * Set the user ID for operations requiring user context
+   */
+  setUserId(userId) {
+    this.userId = userId;
+  }
+  /**
+   * Get current user ID
+   */
+  getUserId() {
+    return this.userId;
+  }
+  /**
+   * Build headers including user ID if available
+   */
+  getUserHeaders() {
+    const headers = {};
+    if (this.userId) {
+      headers["X-User-ID"] = this.userId;
+    }
+    return headers;
+  }
+  // ============================================================================
+  // Document Verification
+  // ============================================================================
+  /**
+   * Request a KYC submission redirect URL for a user
+   *
+   * Generates a link that the user can visit to submit their KYC documents.
+   *
+   * @param request - Request containing the user ID
+   * @returns Response containing the redirect link
+   *
+   * @example
+   * ```typescript
+   * const result = await client.requestKycSubmitLink({
+   *   user_id: "user_123"
+   * });
+   *
+   * console.log(`Redirect user to: ${result.link}`);
+   * ```
+   */
+  async requestKycSubmitLink(request) {
+    return this.requestWithRetry("/api/v1/kyc/request", {
+      method: "POST",
+      body: JSON.stringify(request),
+      headers: this.getUserHeaders()
+    });
+  }
+  /**
+   * Check KYC status for a user
+   *
+   * Returns the current KYC status:
+   * - "complete" → KYC verified, show "Continue to Login"
+   * - "processing" → Under review, show "Continue to Login"
+   * - "failed" / "declined" → Show error + retry option
+   * - "pending" / "in_progress" → Keep polling
+   *
+   * @param request - Request containing user_id and token
+   * @returns Response with kyc_status and message (reason)
+   *
+   * @example
+   * ```typescript
+   * const result = await client.checkKycStatus({
+   *   user_id: "user_123",
+   *   token: "auth_token_xyz"
+   * });
+   *
+   * if (result.kyc_status === 'complete') {
+   *   // Show "Continue to Login"
+   * } else if (result.kyc_status === 'failed' || result.kyc_status === 'declined') {
+   *   // Show error + retry option
+   * } else {
+   *   // Keep polling
+   * }
+   * ```
+   */
+  async checkKycStatus(request) {
+    const params = {
+      user_id: request.user_id,
+      kyc_id: request.kyc_id
+    };
+    return this.requestWithRetry(
+      `/api/v1/kyc/request/status${this.buildQueryString(params)}`,
+      {
+        method: "GET",
+        headers: this.getUserHeaders()
+      }
+    );
+  }
+  /**
+   * Submit a document verification request with OCR
+   *
+   * Uses requestWithRetry() for automatic retry on transient failures.
+   *
+   * @param request - Document verification request with documents and customer info
+   * @returns Verification response with status and reference
+   *
+   * @example
+   * ```typescript
+   * const result = await client.submitVerification({
+   *   reference: "customer_123",
+   *   email: "customer@example.com",
+   *   country: "US",
+   *   document: {
+   *     proof: base64EncodedImage,
+   *     selected_type: ["id_card", "passport"],
+   *     name: { first_name: "John", last_name: "Doe" },
+   *     dob: "1990-01-15"
+   *   },
+   *   face: {
+   *     proof: base64EncodedSelfie
+   *   }
+   * });
+   *
+   * console.log(`Verification submitted: ${result.reference}`);
+   * ```
+   */
+  async submitVerification(request) {
+    return this.requestWithRetry("/api/v1/kyc/submit", {
+      method: "POST",
+      body: JSON.stringify(request),
+      headers: this.getUserHeaders()
+    });
+  }
+  /**
+   * Get a KYC request by ID
+   *
+   * @param id - KYC request ID
+   * @returns KYC request details including proofs and alerts
+   *
+   * @example
+   * ```typescript
+   * const kyc = await client.getKycRequest("kyc_abc123");
+   * console.log(`Status: ${kyc.status}, ID Verified: ${kyc.id_verified}`);
+   * ```
+   */
+  async getKycRequest(id) {
+    return this.request(`/api/v1/kyc/requests/${id}`);
+  }
+  /**
+   * List KYC requests with filters and pagination
+   *
+   * @param filters - Optional filters (status, search, date range)
+   * @param pagination - Optional pagination (page, page_size)
+   * @returns Paginated list of KYC requests
+   *
+   * @example
+   * ```typescript
+   * const requests = await client.listKycRequests(
+   *   { status: "pending", search: "john" },
+   *   { page: 1, page_size: 20 }
+   * );
+   * console.log(`Found ${requests.total} pending requests`);
+   * ```
+   */
+  async listKycRequests(filters, pagination) {
+    const params = {};
+    if (filters) {
+      addFilterParam(params, "status", filters.status);
+      addSimpleParams(params, filters, ["search", "fromDate", "toDate", "sortBy", "order"]);
+    }
+    if (pagination) {
+      if (pagination.page) params.page = pagination.page;
+      if (pagination.page_size) params.limit = pagination.page_size;
+    }
+    return this.request(
+      `/api/v1/kyc/requests${this.buildQueryString(params)}`,
+      { headers: this.getUserHeaders() }
+    );
+  }
+  /**
+   * Update KYC request status (accept/decline)
+   *
+   * @param request - Status update request with reference, status, and reason
+   *
+   * @example
+   * ```typescript
+   * // Accept a KYC request
+   * await client.updateKycStatus({
+   *   reference: "shufti_ref_123",
+   *   status: "accepted",
+   *   reason: "All documents verified successfully"
+   * });
+   *
+   * // Decline a KYC request
+   * await client.updateKycStatus({
+   *   reference: "shufti_ref_456",
+   *   status: "declined",
+   *   reason: "Document expired"
+   * });
+   * ```
+   */
+  async updateKycStatus(request) {
+    await this.request("/api/v1/kyc/status", {
+      method: "PUT",
+      body: JSON.stringify(request),
+      headers: this.getUserHeaders()
+    });
+  }
+  /**
+   * Request additional documents from customer
+   *
+   * @param request - Request with KYC ID and document types needed
+   *
+   * @example
+   * ```typescript
+   * await client.requestAdditionalDocuments({
+   *   id: "kyc_abc123",
+   *   document_types: ["address", "document_two"],
+   *   message: "Please provide proof of address and secondary ID"
+   * });
+   * ```
+   */
+  async requestAdditionalDocuments(request) {
+    await this.request("/api/v1/kyc/requests", {
+      method: "PUT",
+      body: JSON.stringify(request),
+      headers: this.getUserHeaders()
+    });
+  }
+  /**
+   * Get downloadable URLs for KYC proofs/documents
+   *
+   * @param kycId - KYC request ID
+   * @returns Array of proof download URLs with expiration
+   *
+   * @example
+   * ```typescript
+   * const proofs = await client.getProofDownloadURLs("kyc_abc123");
+   * proofs.forEach(proof => {
+   *   console.log(`${proof.type}: ${proof.url} (expires: ${proof.expires_at})`);
+   * });
+   * ```
+   */
+  async getProofDownloadURLs(kycId) {
+    return this.request(
+      `/api/v1/kyc/proofs/${kycId}`,
+      { headers: this.getUserHeaders() }
+    );
+  }
+  // ============================================================================
+  // KYC Overview & Statistics
+  // ============================================================================
+  /**
+   * Get KYC overview statistics
+   *
+   * @param fromDate - Optional start date (ISO 8601)
+   * @param toDate - Optional end date (ISO 8601)
+   * @returns KYC statistics including counts by status
+   *
+   * @example
+   * ```typescript
+   * const overview = await client.getOverview(
+   *   "2024-01-01T00:00:00Z",
+   *   "2024-12-31T23:59:59Z"
+   * );
+   * console.log(`Total: ${overview.total}, Pending: ${overview.pending}`);
+   * console.log(`Approved: ${overview.approved}, Rejected: ${overview.rejected}`);
+   * ```
+   */
+  async getOverview(fromDate, toDate) {
+    const params = {};
+    if (fromDate) params.fromDate = fromDate;
+    if (toDate) params.toDate = toDate;
+    return this.request(
+      `/api/v1/kyc/overview${this.buildQueryString(params)}`
+    );
+  }
+  // ============================================================================
+  // Alert Management
+  // ============================================================================
+  /**
+   * Get a KYC alert by ID
+   *
+   * @param alertId - Alert ID
+   * @returns Alert details
+   */
+  async getAlert(alertId) {
+    return this.request(`/api/v1/kyc/alerts/${alertId}`);
+  }
+  /**
+   * List KYC alerts with filters and pagination
+   *
+   * @param filters - Optional filters (status, risk, alert_type, assigned_for, etc.)
+   * @param pagination - Optional pagination (page, page_size)
+   * @returns Paginated list of alerts
+   *
+   * @example
+   * ```typescript
+   * const alerts = await client.listAlerts(
+   *   {
+   *     status: ["pending", "in_progress"],
+   *     risk: "critical",
+   *     alert_type: "kyc"
+   *   },
+   *   { page: 1, page_size: 20 }
+   * );
+   * console.log(`Found ${alerts.total} alerts`);
+   * ```
+   */
+  async listAlerts(filters, pagination) {
+    const params = {};
+    if (filters) {
+      addFilterParam(params, "kyc_id", filters.kyc_id);
+      addFilterParam(params, "alert_type", filters.alert_type);
+      addFilterParam(params, "assigned_for", filters.assigned_for);
+      addFilterParam(params, "status", filters.status);
+      addFilterParam(params, "risk", filters.risk);
+      addSimpleParams(params, filters, ["search", "fromDate", "toDate", "sort_by", "order"]);
+    }
+    if (pagination) {
+      if (pagination.page) params.page = pagination.page;
+      if (pagination.page_size) params.limit = pagination.page_size;
+    }
+    return this.request(
+      `/api/v1/kyc/alerts${this.buildQueryString(params)}`
+    );
+  }
+  /**
+   * Update a KYC alert
+   *
+   * @param alertId - Alert ID
+   * @param update - Fields to update (status, assigned_for, reason, alert_type)
+   *
+   * @example
+   * ```typescript
+   * // Assign an alert
+   * await client.updateAlert("alert_123", {
+   *   assigned_for: "analyst_user_id",
+   *   status: "in_progress"
+   * });
+   *
+   * // Resolve an alert
+   * await client.updateAlert("alert_123", {
+   *   status: "resolved",
+   *   reason: "Customer verified via phone call"
+   * });
+   *
+   * // Escalate an alert
+   * await client.updateAlert("alert_123", {
+   *   status: "escalated",
+   *   assigned_for: "manager_user_id",
+   *   reason: "Requires senior review - suspicious documents"
+   * });
+   * ```
+   */
+  async updateAlert(alertId, update) {
+    await this.request(`/api/v1/kyc/alerts/${alertId}`, {
+      method: "PUT",
+      body: JSON.stringify(update),
+      headers: this.getUserHeaders()
+    });
+  }
+  // ============================================================================
+  // KYC Preferences
+  // ============================================================================
+  /**
+   * Get KYC preferences for the tenant
+   *
+   * @returns KYC preferences configuration
+   *
+   * @example
+   * ```typescript
+   * const prefs = await client.getPreferences();
+   * console.log(`Face verification required: ${prefs.is_face_verification_required}`);
+   * console.log(`Required documents: ${prefs.required_document_count}`);
+   * ```
+   */
+  async getPreferences() {
+    return this.request("/api/v1/kyc/preferences");
+  }
+  /**
+   * Update KYC preferences for the tenant
+   *
+   * @param update - Fields to update
+   * @returns Updated preferences
+   *
+   * @example
+   * ```typescript
+   * await client.updatePreferences({
+   *   is_face_verification_required: true,
+   *   is_address_verification_required: true,
+   *   required_document_count: 2,
+   *   reasons: [
+   *     "Documents verified",
+   *     "Identity confirmed",
+   *     "Address matched"
+   *   ]
+   * });
+   * ```
+   */
+  async updatePreferences(update) {
+    return this.request("/api/v1/kyc/preferences", {
+      method: "PUT",
+      body: JSON.stringify(update)
+    });
+  }
+  // ============================================================================
+  // Customer Profile Management (Risk Profile Service)
+  // ============================================================================
+  /**
+   * Make a request to the Risk Profile Service
+   * Uses riskProfileBaseURL if configured, otherwise falls back to baseURL
+   */
+  async riskProfileRequest(path, options = {}) {
+    if (!this.riskProfileBaseURL) {
+      throw new Error(
+        "Risk Profile Service URL not configured. Please provide riskProfileBaseURL in KycClientConfig."
+      );
+    }
+    const url = `${this.riskProfileBaseURL}${path}`;
+    const config = this.getConfig();
+    const headers = {
+      "Content-Type": "application/json",
+      "X-Tenant-ID": config.tenantId,
+      ...config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {},
+      ...this.getUserHeaders(),
+      ...options.headers
+    };
+    const response = await fetch(url, {
+      ...options,
+      headers
+    });
+    if (!response.ok) {
+      const errorData = await response.json().catch(() => ({}));
+      return this.handleErrorResponse(response.status, errorData);
+    }
+    return response.json();
+  }
+  /**
+   * List customer profiles for the tenant
+   *
+   * @param filters - Optional filters (risk_category, entity_type, status, search, etc.)
+   * @param pagination - Optional pagination (limit, offset)
+   * @returns Paginated list of customer profiles
+   *
+   * @example
+   * ```typescript
+   * const profiles = await client.listCustomerProfiles(
+   *   { risk_category: 'high', entity_type: 'individual' },
+   *   { limit: 20, offset: 0 }
+   * );
+   * console.log(`Found ${profiles.total} profiles`);
+   * profiles.profiles.forEach(p => console.log(p.customer_id, p.full_name));
+   * ```
+   */
+  async listCustomerProfiles(filters, pagination) {
+    const params = {};
+    if (filters) {
+      if (filters.risk_category) {
+        params.risk_category = Array.isArray(filters.risk_category) ? filters.risk_category : [filters.risk_category];
+      }
+      if (filters.entity_type) {
+        params.entity_type = Array.isArray(filters.entity_type) ? filters.entity_type : [filters.entity_type];
+      }
+      if (filters.status) {
+        params.status = Array.isArray(filters.status) ? filters.status : [filters.status];
+      }
+      addSimpleParams(params, filters, [
+        "search",
+        "is_pep",
+        "has_sanctions",
+        "requires_edd",
+        "sort_by",
+        "sort_order"
+      ]);
+    }
+    if (pagination) {
+      addSimpleParams(params, pagination, ["limit", "offset"]);
+    }
+    return this.riskProfileRequest(
+      `/api/v1/risk-dashboard/profiles${this.buildQueryString(params)}`
+    );
+  }
+  /**
+   * Get a customer profile by ID
+   *
+   * @param profileId - The profile UUID
+   * @returns Customer profile details
+   *
+   * @example
+   * ```typescript
+   * const profile = await client.getCustomerProfile('uuid-here');
+   * console.log(`Customer: ${profile.full_name}, Risk: ${profile.risk_category}`);
+   * ```
+   */
+  async getCustomerProfile(profileId) {
+    return this.riskProfileRequest(
+      `/api/v1/risk-dashboard/profiles/${profileId}`
+    );
+  }
+  /**
+   * Create a new customer profile
+   *
+   * A customer profile must exist before submitting KYC verification.
+   * The customer_id field will be used as the 'reference' in KYC submissions.
+   *
+   * @param profile - Customer profile data
+   * @returns Created customer profile
+   *
+   * @example
+   * ```typescript
+   * const profile = await client.createCustomerProfile({
+   *   customer_id: 'cust_123',
+   *   entity_type: 'individual',
+   *   full_name: 'John Doe',
+   *   email_address: 'john@example.com',
+   *   country_of_residence: 'US'
+   * });
+   * console.log(`Created profile: ${profile.id}`);
+   *
+   * // Now you can submit KYC using the customer_id as reference
+   * await client.submitVerification({
+   *   reference: profile.customer_id, // 'cust_123'
+   *   email: 'john@example.com',
+   *   // ... other fields
+   * });
+   * ```
+   */
+  async createCustomerProfile(profile) {
+    return this.riskProfileRequest("/api/v1/profiles", {
+      method: "POST",
+      body: JSON.stringify(profile)
+    });
+  }
+  // ============================================================================
+  // Utility Methods (inherited from BaseClient: healthCheck, updateConfig, getConfig, buildQueryString)
+  // ============================================================================
+};
+
+export { KycClient };
+//# sourceMappingURL=core.mjs.map
+//# sourceMappingURL=core.mjs.map