cgs-compliance-sdk 2.0.4 → 2.0.5

package/dist/index-BQPX1yNM.d.ts

@@ -0,0 +1,524 @@
+import { c as EntityType, C as CustomerStatus, L as LocationCompliance, U as UUID, T as Timestamp, P as PaginationParams, a as PaginatedResponse } from './types-mQdu71xf.js';
+
+/**
+ * Configuration types for CGS SDK clients
+ */
+interface BaseClientConfig {
+    /** Base URL for the service */
+    baseURL: string;
+    /** Tenant ID for multi-tenancy */
+    tenantId: string;
+    /** Optional API key for authentication */
+    apiKey?: string;
+    /** Custom headers to include in all requests */
+    headers?: Record<string, string>;
+    /** Request timeout in milliseconds (default: 10000) */
+    timeout?: number;
+    /** Number of retry attempts (default: 3) */
+    retries?: number;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+}
+interface CGSConfig {
+    /** API Gateway base URL - All requests go through the gateway */
+    apiGatewayURL: string;
+    /** Tenant ID for multi-tenancy */
+    tenantId: string;
+    /** Optional API key for authentication */
+    apiKey?: string;
+    /** Custom headers to include in all requests */
+    headers?: Record<string, string>;
+    /** Request timeout in milliseconds (default: 10000) */
+    timeout?: number;
+    /** Number of retry attempts for failed requests (default: 3) */
+    retries?: number;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+    /** Automatically create customer profiles on geolocation verification (default: true) */
+    autoCreateProfiles?: boolean;
+    /** Sync mode: 'async' uses events, 'sync' uses direct API calls (default: 'sync') */
+    syncMode?: 'async' | 'sync';
+}
+type RequiredCGSConfig = Required<CGSConfig>;
+type RequiredBaseClientConfig = Required<BaseClientConfig>;
+
+/**
+ * Base HTTP client for all CGS SDK clients
+ *
+ * Provides common functionality:
+ * - Request/response handling
+ * - Error handling
+ * - Retry logic with exponential backoff
+ * - Timeout management
+ * - Debug logging
+ */
+
+declare abstract class BaseClient {
+    protected config: RequiredBaseClientConfig;
+    constructor(config: BaseClientConfig);
+    /**
+     * Make an HTTP request with timeout and error handling
+     */
+    protected request<T>(endpoint: string, options?: RequestInit, serviceURL?: string): Promise<T>;
+    /**
+     * Make an HTTP request with retry logic
+     */
+    protected requestWithRetry<T>(endpoint: string, options?: RequestInit, serviceURL?: string, retries?: number): Promise<T>;
+    /**
+     * Handle error responses from API
+     */
+    protected handleErrorResponse(status: number, data: any): never;
+    /**
+     * Build query string from parameters
+     */
+    protected buildQueryString(params: Record<string, unknown>): string;
+    /**
+     * Update client configuration
+     */
+    updateConfig(config: Partial<BaseClientConfig>): void;
+    /**
+     * Get current configuration (readonly)
+     */
+    getConfig(): Readonly<BaseClientConfig>;
+    /**
+     * Health check endpoint
+     */
+    healthCheck(): Promise<{
+        status: string;
+        timestamp: string;
+    }>;
+}
+
+/**
+ * Type definitions for CGS Risk Profile Service
+ *
+ * These types match the Go structures in:
+ * services/customer-risk-profile-service/internal/domain/customer_profile.go
+ */
+
+interface CustomerProfile {
+    id: UUID;
+    tenant_id: UUID;
+    created_at: Timestamp;
+    updated_at: Timestamp;
+    customer_id: string;
+    account_number?: string;
+    entity_type: EntityType;
+    customer_status: CustomerStatus;
+    customer_tier?: string;
+    date_of_establishment?: Timestamp;
+    last_recorded_activity?: Timestamp;
+    full_name?: string;
+    date_of_birth?: Timestamp;
+    age?: number;
+    gender?: string;
+    business_name?: string;
+    registration_number?: string;
+    country_of_incorporation?: string;
+    date_of_incorporation?: Timestamp;
+    legal_form?: LegalForm;
+    nature_of_business?: string;
+    tax_id?: string;
+    annual_turnover?: number;
+    primary_phone_number?: string;
+    email_address: string;
+    residential_address?: string;
+    country_of_residence?: string;
+    registered_address?: string;
+    operating_address?: string;
+    occupation?: string;
+    employer_name?: string;
+    employment_type?: EmploymentType;
+    business_sector?: string;
+    income_range?: string;
+    source_of_funds?: string;
+    source_of_wealth?: string;
+    total_transactions: number;
+    total_volume: number;
+    flagged_transactions: number;
+    risk_score: number;
+    risk_category: RiskCategory;
+    previous_risk_score?: number;
+    previous_risk_category?: RiskCategory;
+    risk_last_calculated?: Timestamp;
+    watchlist_matches?: string[];
+    screening_status?: ScreeningStatus;
+    is_pep: boolean;
+    has_adverse_media: boolean;
+    has_sanctions: boolean;
+    requires_edd: boolean;
+    edd_notes?: string;
+    kyc_status?: string;
+    identification_type?: string;
+    identification_number?: string;
+    id_issuing_country?: string;
+    id_issue_date?: Timestamp;
+    id_expiry_date?: Timestamp;
+    location?: string;
+    location_compliance?: LocationCompliance;
+    risk_factors?: RiskFactor[];
+    risk_history?: RiskHistory[];
+}
+type RiskCategory = 'low' | 'medium' | 'high' | 'critical';
+type EmploymentType = 'salaried' | 'self_employed' | 'unemployed';
+type LegalForm = 'limited' | 'partnership' | 'ngo' | 'trust' | 'sole_trader';
+type ScreeningStatus = 'clear' | 'potential_match' | 'true_positive' | 'false_positive';
+interface RiskFactor {
+    id: UUID;
+    tenant_id: UUID;
+    profile_id: UUID;
+    factor_type: RiskFactorType;
+    factor_name: string;
+    score: number;
+    weight: number;
+    weighted_score: number;
+    description?: string;
+    evidence?: Record<string, unknown>;
+    source_event?: string;
+    source_service?: string;
+    reference_id?: string;
+    metadata?: Record<string, unknown>;
+    is_active: boolean;
+    expires_at?: Timestamp;
+    created_at: Timestamp;
+    updated_at: Timestamp;
+}
+type RiskFactorType = 'kyc' | 'aml' | 'fraud' | 'geolocation' | 'transaction' | 'watchlist' | 'pep' | 'sanctions' | 'adverse_media';
+interface RiskHistory {
+    id: UUID;
+    tenant_id: UUID;
+    profile_id: UUID;
+    previous_score: number;
+    new_score: number;
+    previous_category: RiskCategory;
+    new_category: RiskCategory;
+    change_reason: string;
+    triggered_by: string;
+    metadata?: Record<string, unknown>;
+    created_at: Timestamp;
+}
+interface CreateProfileRequest {
+    customer_id: string;
+    entity_type: EntityType;
+    customer_status?: CustomerStatus;
+    account_number?: string;
+    customer_tier?: string;
+    full_name?: string;
+    date_of_birth?: string;
+    gender?: string;
+    business_name?: string;
+    registration_number?: string;
+    country_of_incorporation?: string;
+    legal_form?: LegalForm;
+    nature_of_business?: string;
+    primary_phone_number?: string;
+    email_address: string;
+    residential_address?: string;
+    country_of_residence?: string;
+    registered_address?: string;
+    operating_address?: string;
+    occupation?: string;
+    employment_type?: EmploymentType;
+    income_range?: string;
+    source_of_funds?: string;
+    kyc_status?: string;
+    location?: string;
+    location_compliance?: LocationCompliance;
+}
+interface UpdateProfileRequest extends Partial<CreateProfileRequest> {
+    last_recorded_activity?: Timestamp;
+}
+interface ProfileDetailsResponse {
+    profile: CustomerProfile;
+    risk_factors: RiskFactor[];
+    risk_history: RiskHistory[];
+    watchlist_alert_count: number;
+    fraud_alert_count: number;
+    geolocation_alert_count: number;
+    kyc_alert_count: number;
+}
+interface ProfileFilters extends PaginationParams {
+    risk_category?: RiskCategory[];
+    min_risk_score?: number;
+    max_risk_score?: number;
+    entity_type?: EntityType[];
+    status?: CustomerStatus[];
+    location?: string[];
+    country_of_residence?: string[];
+    location_compliance?: LocationCompliance[];
+    is_pep?: boolean;
+    has_sanctions?: boolean;
+    has_adverse_media?: boolean;
+    requires_edd?: boolean;
+    kyc_status?: string[];
+    search?: string;
+    sort_by?: 'risk_score' | 'created_at' | 'updated_at' | 'customer_id' | 'full_name';
+    sort_order?: 'asc' | 'desc';
+}
+type ProfileListResponse = PaginatedResponse<CustomerProfile>;
+interface RiskDashboardMetrics {
+    total_risky_profiles: number;
+    total_critical_profiles: number;
+    total_high_profiles: number;
+    total_medium_profiles: number;
+    total_low_profiles: number;
+    total_pep_profiles: number;
+    total_sanctioned_profiles: number;
+    total_edd_required: number;
+    average_risk_score: number;
+    risk_distribution: Array<{
+        category: RiskCategory;
+        count: number;
+        percentage: number;
+    }>;
+    trend_indicators: {
+        critical_trend: 'up' | 'down' | 'stable';
+        critical_change: number;
+        high_trend: 'up' | 'down' | 'stable';
+        high_change: number;
+    };
+    recent_high_risk_profiles?: CustomerProfile[];
+}
+interface RiskConfiguration {
+    id: UUID;
+    tenant_id: UUID;
+    kyc_weight: number;
+    aml_weight: number;
+    fraud_weight: number;
+    geolocation_weight: number;
+    transaction_weight: number;
+    watchlist_weight: number;
+    critical_threshold: number;
+    high_threshold: number;
+    medium_threshold: number;
+    auto_escalate_critical: boolean;
+    create_case_on_critical: boolean;
+    auto_block_sanctioned: boolean;
+    require_review_on_pep: boolean;
+    created_at: Timestamp;
+    updated_at: Timestamp;
+}
+
+/**
+ * RiskProfileClient - Customer Risk Profile Management
+ *
+ * Provides methods to create, retrieve, and manage customer risk profiles
+ * in the CGS Compliance Platform.
+ */
+
+declare class RiskProfileClient extends BaseClient {
+    constructor(config: BaseClientConfig);
+    /**
+     * Create a new customer risk profile
+     *
+     * @param request - Profile creation data
+     * @returns Created customer profile
+     *
+     * @example
+     * ```typescript
+     * const profile = await client.createProfile({
+     *   customer_id: 'CUST-12345',
+     *   entity_type: 'individual',
+     *   customer_status: 'active',
+     *   full_name: 'John Doe',
+     *   email_address: 'john@example.com',
+     *   date_of_birth: '1990-01-15',
+     *   country_of_residence: 'US'
+     * });
+     * ```
+     */
+    createProfile(request: CreateProfileRequest): Promise<CustomerProfile>;
+    /**
+     * Get customer profile by customer ID
+     *
+     * Note: This searches for the profile using the customer_id field.
+     * Returns the first matching profile for the tenant.
+     *
+     * @param customerId - Customer ID to search for
+     * @returns Customer profile
+     *
+     * @example
+     * ```typescript
+     * const profile = await client.getProfile('CUST-12345');
+     * console.log('Risk score:', profile.risk_score);
+     * ```
+     */
+    getProfile(customerId: string): Promise<CustomerProfile>;
+    /**
+     * Get profile by UUID
+     *
+     * @param profileId - Profile UUID
+     * @returns Customer profile
+     */
+    getProfileById(profileId: string): Promise<CustomerProfile>;
+    /**
+     * Get detailed profile information including risk factors and history
+     *
+     * @param profileId - Profile UUID
+     * @returns Detailed profile response with risk factors and history
+     *
+     * @example
+     * ```typescript
+     * const details = await client.getProfileDetails(profileId);
+     * console.log('Risk factors:', details.risk_factors);
+     * console.log('Risk history:', details.risk_history);
+     * console.log('Alert counts:', {
+     *   watchlist: details.watchlist_alert_count,
+     *   fraud: details.fraud_alert_count,
+     *   geo: details.geolocation_alert_count
+     * });
+     * ```
+     */
+    getProfileDetails(profileId: string): Promise<ProfileDetailsResponse>;
+    /**
+     * Update customer profile
+     *
+     * @param profileId - Profile UUID
+     * @param updates - Fields to update
+     * @returns Updated customer profile
+     *
+     * @example
+     * ```typescript
+     * const updated = await client.updateProfile(profileId, {
+     *   location: 'New York, USA',
+     *   location_compliance: 'compliant',
+     *   last_recorded_activity: new Date().toISOString()
+     * });
+     * ```
+     */
+    updateProfile(profileId: string, updates: UpdateProfileRequest): Promise<CustomerProfile>;
+    /**
+     * Manually recalculate risk score for a profile
+     *
+     * Triggers immediate risk score recalculation based on current risk factors.
+     *
+     * @param profileId - Profile UUID
+     * @param reason - Optional reason for recalculation
+     *
+     * @example
+     * ```typescript
+     * await client.recalculateRiskScore(profileId, 'Manual review completed');
+     * ```
+     */
+    recalculateRiskScore(profileId: string, reason?: string): Promise<void>;
+    /**
+     * Query profiles with advanced filters
+     *
+     * @param filters - Filter criteria and pagination
+     * @returns Paginated list of profiles
+     *
+     * @example
+     * ```typescript
+     * const results = await client.queryProfiles({
+     *   risk_category: ['high', 'critical'],
+     *   kyc_status: ['pending'],
+     *   is_pep: true,
+     *   page: 1,
+     *   page_size: 20,
+     *   sort_by: 'risk_score',
+     *   sort_order: 'desc'
+     * });
+     *
+     * console.log(`Found ${results.total} high-risk profiles`);
+     * results.data.forEach(profile => {
+     *   console.log(`${profile.full_name}: ${profile.risk_score}`);
+     * });
+     * ```
+     */
+    queryProfiles(filters?: ProfileFilters): Promise<ProfileListResponse>;
+    /**
+     * Search profiles by text (searches name, email, customer_id, account_number)
+     *
+     * @param searchText - Text to search for
+     * @param limit - Maximum results to return (default: 10)
+     * @returns Array of matching profiles
+     */
+    searchProfiles(searchText: string, limit?: number): Promise<CustomerProfile[]>;
+    /**
+     * Get all high-risk profiles (high + critical)
+     *
+     * @param limit - Maximum results to return (default: 50)
+     * @returns Array of high-risk profiles
+     */
+    getHighRiskProfiles(limit?: number): Promise<CustomerProfile[]>;
+    /**
+     * Get profiles requiring PEP review
+     *
+     * @param limit - Maximum results to return (default: 50)
+     * @returns Array of PEP profiles
+     */
+    getPEPProfiles(limit?: number): Promise<CustomerProfile[]>;
+    /**
+     * Get profiles with sanctions matches
+     *
+     * @param limit - Maximum results to return (default: 50)
+     * @returns Array of sanctioned profiles
+     */
+    getSanctionedProfiles(limit?: number): Promise<CustomerProfile[]>;
+    /**
+     * Get risk dashboard metrics and statistics
+     *
+     * @param startDate - Optional start date for metrics (ISO format)
+     * @param endDate - Optional end date for metrics (ISO format)
+     * @returns Dashboard metrics
+     *
+     * @example
+     * ```typescript
+     * const metrics = await client.getDashboardMetrics();
+     * console.log('Total risky profiles:', metrics.total_risky_profiles);
+     * console.log('Critical profiles:', metrics.total_critical_profiles);
+     * console.log('Average risk score:', metrics.average_risk_score);
+     *
+     * metrics.risk_distribution.forEach(item => {
+     *   console.log(`${item.category}: ${item.count} (${item.percentage}%)`);
+     * });
+     * ```
+     */
+    getDashboardMetrics(startDate?: string, endDate?: string): Promise<RiskDashboardMetrics>;
+    /**
+     * Get or create profile (idempotent operation)
+     *
+     * Attempts to get existing profile by customer_id, creates if not found.
+     *
+     * @param customerId - Customer ID
+     * @param createRequest - Profile data to use if creating new profile
+     * @returns Existing or newly created profile
+     *
+     * @example
+     * ```typescript
+     * const profile = await client.getOrCreateProfile('CUST-123', {
+     *   customer_id: 'CUST-123',
+     *   entity_type: 'individual',
+     *   full_name: 'John Doe',
+     *   email_address: 'john@example.com'
+     * });
+     * ```
+     */
+    getOrCreateProfile(customerId: string, createRequest: CreateProfileRequest): Promise<CustomerProfile>;
+    /**
+     * Batch get profiles by customer IDs
+     *
+     * @param customerIds - Array of customer IDs
+     * @returns Array of profiles (may be less than input if some not found)
+     */
+    batchGetProfiles(customerIds: string[]): Promise<CustomerProfile[]>;
+    /**
+     * Get risk configuration for tenant
+     *
+     * Returns the risk scoring weights and thresholds configured for the tenant.
+     *
+     * @returns Risk configuration
+     */
+    getRiskConfiguration(): Promise<RiskConfiguration>;
+    /**
+     * Update risk configuration for tenant
+     *
+     * Updates risk scoring weights and/or thresholds.
+     *
+     * @param config - Configuration updates
+     * @returns Updated risk configuration
+     */
+    updateRiskConfiguration(config: Partial<RiskConfiguration>): Promise<RiskConfiguration>;
+}
+
+export { BaseClient as B, type CGSConfig as C, type EmploymentType as E, type LegalForm as L, type ProfileDetailsResponse as P, RiskProfileClient as R, type ScreeningStatus as S, type UpdateProfileRequest as U, type BaseClientConfig as a, type RequiredCGSConfig as b, type RequiredBaseClientConfig as c, type CustomerProfile as d, type RiskCategory as e, type RiskFactor as f, type RiskFactorType as g, type RiskHistory as h, type CreateProfileRequest as i, type ProfileFilters as j, type ProfileListResponse as k, type RiskDashboardMetrics as l, type RiskConfiguration as m };