cgs-compliance-sdk 2.0.4 → 2.0.5

package/dist/client-BIRcQF2C.d.ts

@@ -0,0 +1,619 @@
+import { P as PaginationParams } from './types-mQdu71xf.js';
+
+/**
+ * TypeScript type definitions for CGS Geolocation Service API
+ *
+ * These types match the Go API structures in:
+ * - services/geolocation-service/internal/domain/
+ * - services/geolocation-service/internal/service/
+ * - services/geolocation-service/internal/handler/
+ */
+
+interface DeviceFingerprintRequest {
+    device_id: string;
+    user_agent: string;
+    platform: string;
+    browser?: string;
+    browser_version?: string;
+    os?: string;
+    os_version?: string;
+    screen_resolution?: string;
+    language?: string;
+    timezone?: string;
+}
+interface VerifyIPRequest {
+    ip_address: string;
+    user_id: string;
+    event_type: string;
+    device_fingerprint?: DeviceFingerprintRequest;
+}
+interface GeoIPResult {
+    country: string;
+    country_iso: string;
+    city: string;
+    region: string;
+    postal_code: string;
+    latitude: number;
+    longitude: number;
+    timezone: string;
+    is_vpn: boolean;
+    is_proxy: boolean;
+    is_tor: boolean;
+    is_hosting: boolean;
+    is_anonymizer: boolean;
+}
+interface JurisdictionConfig {
+    id: string;
+    tenant_id: string;
+    country_iso: string;
+    country_name: string;
+    status: 'allowed' | 'restricted' | 'blocked' | 'sanctioned';
+    risk_level: 'low' | 'medium' | 'high';
+    allow_login: boolean;
+    allow_registration: boolean;
+    allow_transactions: boolean;
+    max_transaction_amount?: number;
+    require_kyc: boolean;
+    require_enhanced_verification: boolean;
+    compliance_notes?: string;
+    created_at: string;
+    updated_at: string;
+}
+interface GeofenceEvaluation {
+    matched_rules: string[];
+    blocked: boolean;
+    should_alert: boolean;
+    reasons: string[];
+}
+interface DeviceFingerprint {
+    id: string;
+    tenant_id: string;
+    user_id: string;
+    device_id: string;
+    user_agent: string;
+    platform: string;
+    browser?: string;
+    browser_version?: string;
+    os?: string;
+    os_version?: string;
+    screen_resolution?: string;
+    language?: string;
+    timezone?: string;
+    ip_address?: string;
+    last_ip_address?: string;
+    last_location?: string;
+    is_trusted: boolean;
+    trust_score: number;
+    risk_flags?: string;
+    first_seen_at: string;
+    last_seen_at: string;
+    login_count: number;
+    location_changes: number;
+}
+interface DeviceTrustResult {
+    device: DeviceFingerprint;
+    is_new_device: boolean;
+    is_trusted: boolean;
+    trust_score: number;
+    risk_factors: string[];
+    recommendations: string[];
+}
+interface LocationVerification {
+    ip_address: string;
+    location: GeoIPResult;
+    is_compliant: boolean;
+    is_blocked: boolean;
+    risk_level: 'low' | 'medium' | 'high' | 'critical';
+    risk_score: number;
+    risk_reasons: string[];
+    jurisdiction?: JurisdictionConfig;
+    geofence_evaluation?: GeofenceEvaluation;
+    device_trust?: DeviceTrustResult;
+    record_id: string;
+}
+interface ComplianceCheckResponse {
+    jurisdiction?: JurisdictionConfig;
+    is_compliant: boolean;
+    message: string;
+}
+type AlertStatus = 'active' | 'under_review' | 'resolved' | 'false_positive' | 'blocked';
+type AlertSeverity = 'low' | 'medium' | 'high' | 'critical';
+type AlertType = 'high_risk_login' | 'sanctioned_region' | 'geofence_violation' | 'tor_detected' | 'vpn_detected' | 'proxy_detected' | 'anonymization_detected' | 'anonymization_tool_detected' | 'high_risk_country' | 'impossible_travel' | 'device_fingerprint_mismatch';
+interface GeolocationAlert {
+    id: string;
+    tenant_id: string;
+    user_id: string;
+    alert_type: AlertType;
+    severity: AlertSeverity;
+    status: AlertStatus;
+    ip_address?: string;
+    location?: string;
+    risk_score?: number;
+    risk_factors?: string;
+    geolocation_record_id?: string;
+    assigned_to?: string;
+    resolution?: string;
+    notes?: string;
+    resolved_by?: string;
+    resolved_at?: string;
+    created_at: string;
+    updated_at: string;
+}
+interface AlertFilters {
+    status?: AlertStatus;
+    severity?: AlertSeverity;
+    alert_type?: AlertType;
+    user_id?: string;
+    assigned_to?: string;
+    start_date?: string;
+    end_date?: string;
+}
+interface AlertListResponse {
+    alerts: GeolocationAlert[];
+    total: number;
+    page: number;
+    page_size: number;
+}
+interface DashboardMetrics {
+    total_alerts: number;
+    active_alerts: number;
+    critical_alerts: number;
+    high_alerts: number;
+    alerts_by_status: Record<AlertStatus, number>;
+    alerts_by_severity: Record<AlertSeverity, number>;
+    alerts_by_type: Record<string, number>;
+    top_risk_users: Array<{
+        user_id: string;
+        alert_count: number;
+        max_risk_score: number;
+    }>;
+    top_risk_countries: Array<{
+        country: string;
+        alert_count: number;
+    }>;
+}
+interface CreateJurisdictionRequest {
+    country_iso: string;
+    country_name: string;
+    status: 'allowed' | 'restricted' | 'blocked' | 'sanctioned';
+    risk_level: 'low' | 'medium' | 'high';
+    allow_login: boolean;
+    allow_registration: boolean;
+    allow_transactions: boolean;
+    max_transaction_amount?: number;
+    require_kyc: boolean;
+    require_enhanced_verification: boolean;
+    compliance_notes?: string;
+}
+interface UpdateJurisdictionRequest extends Partial<CreateJurisdictionRequest> {
+}
+type GeofenceRuleType = 'block_list' | 'allow_list' | 'risk_threshold';
+type GeofenceAction = 'block' | 'alert' | 'allow_with_warning';
+interface GeofenceRule {
+    id: string;
+    tenant_id: string;
+    name: string;
+    description?: string;
+    rule_type: GeofenceRuleType;
+    action: GeofenceAction;
+    priority: number;
+    countries?: string;
+    cities?: string;
+    latitude?: number;
+    longitude?: number;
+    radius_km?: number;
+    risk_threshold?: number;
+    event_types?: string;
+    is_active: boolean;
+    created_by: string;
+    created_at: string;
+    updated_at: string;
+}
+interface CreateGeofenceRuleRequest {
+    name: string;
+    description?: string;
+    rule_type: GeofenceRuleType;
+    action: GeofenceAction;
+    priority?: number;
+    countries?: string[];
+    cities?: string[];
+    latitude?: number;
+    longitude?: number;
+    radius_km?: number;
+    risk_threshold?: number;
+    event_types?: string[];
+    is_active?: boolean;
+}
+interface UpdateGeofenceRuleRequest extends Partial<CreateGeofenceRuleRequest> {
+}
+interface UpdateDeviceTrustRequest {
+    device_id: string;
+    action: 'trust' | 'untrust';
+}
+interface GeolocationRecord {
+    id: string;
+    tenant_id: string;
+    user_id: string;
+    ip_address: string;
+    event_type: string;
+    country: string;
+    country_iso: string;
+    city: string;
+    region: string;
+    postal_code?: string;
+    latitude: number;
+    longitude: number;
+    timezone?: string;
+    is_vpn: boolean;
+    is_proxy: boolean;
+    is_tor: boolean;
+    is_hosting: boolean;
+    is_anonymizer: boolean;
+    risk_score: number;
+    risk_level: string;
+    provider: string;
+    provider_response?: string;
+    created_at: string;
+}
+interface APIError {
+    error: string;
+    message?: string;
+    details?: Record<string, unknown>;
+}
+interface GeolocationClientConfig {
+    /** Base URL of the API Gateway (e.g., "https://api.example.com") */
+    baseURL: string;
+    /** Tenant ID for multi-tenancy */
+    tenantId: string;
+    /** API key or JWT token for authentication */
+    apiKey?: string;
+    /** Custom headers to include in every request */
+    headers?: Record<string, string>;
+    /** Request timeout in milliseconds (default: 10000) */
+    timeout?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+interface UseGeolocationOptions {
+    /** Auto-detect and verify user's IP on mount */
+    autoVerify?: boolean;
+    /** Event type for verification */
+    eventType?: string;
+    /** Include device fingerprint in verification */
+    includeDeviceFingerprint?: boolean;
+}
+interface UseGeolocationResult {
+    /** Current verification result */
+    verification: LocationVerification | null;
+    /** Loading state */
+    loading: boolean;
+    /** Error state */
+    error: Error | null;
+    /** Verify an IP address */
+    verifyIP: (request: VerifyIPRequest) => Promise<LocationVerification>;
+    /** Check compliance for a country */
+    checkCompliance: (countryISO: string) => Promise<ComplianceCheckResponse>;
+    /** Refresh verification */
+    refresh: () => Promise<void>;
+}
+interface UseAlertsOptions {
+    /** Auto-fetch alerts on mount */
+    autoFetch?: boolean;
+    /** Initial filters */
+    filters?: AlertFilters;
+    /** Pagination settings */
+    pagination?: PaginationParams;
+    /** Poll interval in milliseconds (0 = no polling) */
+    pollInterval?: number;
+}
+interface UseAlertsResult {
+    /** List of alerts */
+    alerts: GeolocationAlert[];
+    /** Total count */
+    total: number;
+    /** Loading state */
+    loading: boolean;
+    /** Error state */
+    error: Error | null;
+    /** Fetch alerts with filters */
+    fetchAlerts: (filters?: AlertFilters, pagination?: PaginationParams) => Promise<void>;
+    /** Update alert status */
+    updateStatus: (alertId: string, status: AlertStatus) => Promise<void>;
+    /** Assign alert */
+    assignAlert: (alertId: string, assignedTo: string) => Promise<void>;
+    /** Resolve alert */
+    resolveAlert: (alertId: string, resolution: string, notes?: string) => Promise<void>;
+    /** Dismiss alert as false positive */
+    dismissAlert: (alertId: string, notes?: string) => Promise<void>;
+    /** Refresh alerts */
+    refresh: () => Promise<void>;
+}
+
+/**
+ * GeolocationClient - TypeScript SDK for CGS Geolocation & Compliance Service
+ *
+ * Provides type-safe methods to interact with the geolocation service API.
+ */
+
+declare class GeolocationClient {
+    private config;
+    constructor(config: GeolocationClientConfig);
+    private request;
+    private buildQueryString;
+    /**
+     * Verify an IP address and check compliance
+     *
+     * @param request - Verification request with IP, user ID, event type, and optional device fingerprint
+     * @returns Location verification result with risk assessment
+     *
+     * @example
+     * ```typescript
+     * const result = await client.verifyIP({
+     *   ip_address: "8.8.8.8",
+     *   user_id: "user_123",
+     *   event_type: "login",
+     *   device_fingerprint: {
+     *     device_id: "device_abc",
+     *     user_agent: navigator.userAgent,
+     *     platform: "web"
+     *   }
+     * });
+     *
+     * if (result.is_blocked) {
+     *   console.log("Access blocked:", result.risk_reasons);
+     * }
+     * ```
+     */
+    verifyIP(request: VerifyIPRequest): Promise<LocationVerification>;
+    /**
+     * Check compliance for a specific country
+     *
+     * @param countryISO - ISO 3166-1 alpha-2 country code (e.g., "US", "GB")
+     * @returns Jurisdiction configuration and compliance status
+     *
+     * @example
+     * ```typescript
+     * const compliance = await client.checkCompliance("KP"); // North Korea
+     * if (!compliance.is_compliant) {
+     *   console.log("Country is not allowed:", compliance.jurisdiction?.status);
+     * }
+     * ```
+     */
+    checkCompliance(countryISO: string): Promise<ComplianceCheckResponse>;
+    /**
+     * Get location history for a user
+     *
+     * @param userId - User ID to retrieve history for
+     * @param limit - Maximum number of records to return (default: 100)
+     * @returns Array of geolocation records
+     */
+    getUserLocationHistory(userId: string, limit?: number): Promise<GeolocationRecord[]>;
+    /**
+     * Get a specific alert by ID
+     *
+     * @param alertId - Alert ID
+     * @returns Alert details
+     */
+    getAlert(alertId: string): Promise<GeolocationAlert>;
+    /**
+     * List alerts with filters and pagination
+     *
+     * @param filters - Optional filters (status, severity, type, user, dates)
+     * @param pagination - Optional pagination (page, page_size)
+     * @returns Paginated list of alerts
+     *
+     * @example
+     * ```typescript
+     * const alerts = await client.listAlerts(
+     *   { status: "active", severity: "critical" },
+     *   { page: 1, page_size: 20 }
+     * );
+     * console.log(`Found ${alerts.total} critical alerts`);
+     * ```
+     */
+    listAlerts(filters?: AlertFilters, pagination?: PaginationParams): Promise<AlertListResponse>;
+    /**
+     * Update alert status
+     *
+     * @param alertId - Alert ID
+     * @param status - New status
+     */
+    updateAlertStatus(alertId: string, status: AlertStatus): Promise<void>;
+    /**
+     * Assign an alert to an analyst
+     *
+     * @param alertId - Alert ID
+     * @param assignedTo - User ID to assign to
+     */
+    assignAlert(alertId: string, assignedTo: string): Promise<void>;
+    /**
+     * Resolve an alert
+     *
+     * @param alertId - Alert ID
+     * @param resolution - Resolution type
+     * @param notes - Optional notes
+     */
+    resolveAlert(alertId: string, resolution: string, notes?: string): Promise<void>;
+    /**
+     * Dismiss an alert as false positive
+     *
+     * @param alertId - Alert ID
+     * @param notes - Optional notes explaining why it's a false positive
+     */
+    dismissAlert(alertId: string, notes?: string): Promise<void>;
+    /**
+     * Escalate an alert to higher severity or different assignee
+     *
+     * @param alertId - Alert ID
+     * @param assignedTo - New assignee user ID
+     * @param severity - New severity level
+     * @param notes - Escalation notes
+     */
+    escalateAlert(alertId: string, assignedTo: string, severity: string, notes: string): Promise<void>;
+    /**
+     * Block an alert (mark as blocked)
+     *
+     * @param alertId - Alert ID
+     * @param notes - Optional notes
+     */
+    blockAlert(alertId: string, notes?: string): Promise<void>;
+    /**
+     * Get dashboard metrics
+     *
+     * @param timeRangeHours - Time range in hours (default: 24)
+     * @returns Dashboard metrics and statistics
+     *
+     * @example
+     * ```typescript
+     * const metrics = await client.getDashboardMetrics(168); // Last 7 days
+     * console.log(`${metrics.critical_alerts} critical alerts in last week`);
+     * ```
+     */
+    getDashboardMetrics(timeRangeHours?: number): Promise<DashboardMetrics>;
+    /**
+     * List all jurisdiction configurations
+     *
+     * @returns Array of jurisdiction configurations
+     */
+    listJurisdictions(): Promise<JurisdictionConfig[]>;
+    /**
+     * Get a jurisdiction configuration by ID
+     *
+     * @param jurisdictionId - Jurisdiction ID
+     * @returns Jurisdiction configuration
+     */
+    getJurisdiction(jurisdictionId: string): Promise<JurisdictionConfig>;
+    /**
+     * Create a new jurisdiction configuration
+     *
+     * @param request - Jurisdiction configuration data
+     * @returns Created jurisdiction
+     *
+     * @example
+     * ```typescript
+     * const jurisdiction = await client.createJurisdiction({
+     *   country_iso: "US",
+     *   country_name: "United States",
+     *   status: "allowed",
+     *   risk_level: "low",
+     *   allow_login: true,
+     *   allow_registration: true,
+     *   allow_transactions: true,
+     *   require_kyc: false,
+     *   require_enhanced_verification: false
+     * });
+     * ```
+     */
+    createJurisdiction(request: CreateJurisdictionRequest): Promise<JurisdictionConfig>;
+    /**
+     * Update a jurisdiction configuration
+     *
+     * @param jurisdictionId - Jurisdiction ID
+     * @param request - Updated fields
+     * @returns Updated jurisdiction
+     */
+    updateJurisdiction(jurisdictionId: string, request: UpdateJurisdictionRequest): Promise<JurisdictionConfig>;
+    /**
+     * Delete a jurisdiction configuration
+     *
+     * @param jurisdictionId - Jurisdiction ID
+     */
+    deleteJurisdiction(jurisdictionId: string): Promise<void>;
+    /**
+     * List all geofence rules
+     *
+     * @returns Array of geofence rules
+     */
+    listGeofenceRules(): Promise<GeofenceRule[]>;
+    /**
+     * Get a geofence rule by ID
+     *
+     * @param ruleId - Geofence rule ID
+     * @returns Geofence rule
+     */
+    getGeofenceRule(ruleId: string): Promise<GeofenceRule>;
+    /**
+     * Create a new geofence rule
+     *
+     * @param request - Geofence rule data
+     * @returns Created geofence rule
+     *
+     * @example
+     * ```typescript
+     * const rule = await client.createGeofenceRule({
+     *   name: "Block High Risk Countries",
+     *   rule_type: "block_list",
+     *   action: "block",
+     *   countries: ["KP", "IR", "SY"],
+     *   event_types: ["login", "transaction"],
+     *   priority: 100
+     * });
+     * ```
+     */
+    createGeofenceRule(request: CreateGeofenceRuleRequest): Promise<GeofenceRule>;
+    /**
+     * Update a geofence rule
+     *
+     * @param ruleId - Geofence rule ID
+     * @param request - Updated fields
+     * @returns Updated geofence rule
+     */
+    updateGeofenceRule(ruleId: string, request: UpdateGeofenceRuleRequest): Promise<GeofenceRule>;
+    /**
+     * Delete a geofence rule
+     *
+     * @param ruleId - Geofence rule ID
+     */
+    deleteGeofenceRule(ruleId: string): Promise<void>;
+    /**
+     * Get all devices for a user
+     *
+     * @param userId - User ID
+     * @returns Array of device fingerprints
+     */
+    getUserDevices(userId: string): Promise<DeviceFingerprint[]>;
+    /**
+     * Get a specific device by device ID
+     *
+     * @param deviceId - Device ID
+     * @returns Device fingerprint
+     */
+    getDevice(deviceId: string): Promise<DeviceFingerprint>;
+    /**
+     * Update device trust status
+     *
+     * @param deviceId - Device ID
+     * @param action - "trust" or "untrust"
+     *
+     * @example
+     * ```typescript
+     * // Mark a device as trusted
+     * await client.updateDeviceTrust("device_abc", "trust");
+     *
+     * // Mark a device as untrusted
+     * await client.updateDeviceTrust("device_xyz", "untrust");
+     * ```
+     */
+    updateDeviceTrust(deviceId: string, action: 'trust' | 'untrust'): Promise<void>;
+    /**
+     * Check service health
+     *
+     * @returns Health status object
+     */
+    healthCheck(): Promise<{
+        status: string;
+        timestamp: string;
+    }>;
+    /**
+     * Update client configuration
+     *
+     * @param config - Partial configuration to update
+     */
+    updateConfig(config: Partial<GeolocationClientConfig>): void;
+    /**
+     * Get current configuration (readonly)
+     */
+    getConfig(): Readonly<GeolocationClientConfig>;
+}
+
+export { type AlertStatus as A, type ComplianceCheckResponse as C, type DeviceFingerprintRequest as D, GeolocationClient as G, type JurisdictionConfig as J, type LocationVerification as L, type UpdateJurisdictionRequest as U, type VerifyIPRequest as V, type GeoIPResult as a, type GeofenceEvaluation as b, type DeviceFingerprint as c, type DeviceTrustResult as d, type AlertSeverity as e, type AlertType as f, type GeolocationAlert as g, type AlertFilters as h, type AlertListResponse as i, type DashboardMetrics as j, type CreateJurisdictionRequest as k, type GeofenceRuleType as l, type GeofenceAction as m, type GeofenceRule as n, type CreateGeofenceRuleRequest as o, type UpdateGeofenceRuleRequest as p, type UpdateDeviceTrustRequest as q, type GeolocationRecord as r, type APIError as s, type GeolocationClientConfig as t, type UseGeolocationOptions as u, type UseGeolocationResult as v, type UseAlertsOptions as w, type UseAlertsResult as x };