@artu-ai/compliance-sdk 0.4.1 → 0.4.2

package/src/resources/mex/ebr.ts

@@ -1,621 +0,0 @@
-/**
- * EBR Resource
- *
- * Provides the SDK interface for managing EBR (Evaluación Basada en Riesgos)
- * configurations. Supports both global EBR (no AV) and activity-specific EBR.
- *
- * @module resources/mex/ebr
- */
-
-import type { ZodError } from "zod";
-import { TRPCClientError } from "@trpc/client";
-import { ValidationError } from "../../errors/validation";
-import { mapTRPCError } from "../../errors";
-import type { SDKScope, Environment } from "../../sdk/types";
-import { isMexicoScope } from "../../sdk/types";
-import type { TRPCClient } from "../../utils/trpc-client";
-
-// Import from @artu-ai/shared
-import {
-  // Constants
-  WEIGHT_RANGE,
-  DEFAULT_THRESHOLDS,
-  // Schemas
-  CreateEBRConfigInputSchema,
-  type CreateEBRConfigInput,
-  type EBRConfiguration,
-  type EBRConfigListItem,
-  type ScoreThresholds,
-  // Enums
-  RiskLevels,
-  InternalRiskLevel,
-  RegulatoryRiskLevel,
-} from "@artu-ai/shared";
-
-// ===========================
-// Weight Presets (SDK-only)
-// ===========================
-
-/**
- * Confidence level for weight presets.
- */
-export type PresetConfidence = "high" | "medium";
-
-/**
- * A weight preset for a specific Actividad Vulnerable.
- */
-export interface WeightPreset {
-  client: number;
-  geographic: number;
-  product: number;
-  transactional: number;
-  confidence: PresetConfidence;
-}
-
-/**
- * Weight presets for all 15 Actividades Vulnerables.
- *
- * These presets are validated according to:
- * - ENR 2020/2023 (Evaluación Nacional de Riesgos)
- * - GAFI/FATF RBA Guidance
- * - LFPIORPI regulatory requirements
- */
-export const WEIGHT_PRESETS: Record<string, WeightPreset> = {
-  // Inmobiliarias (Real Estate)
-  INM: {
-    client: 0.25,
-    geographic: 0.35,
-    product: 0.2,
-    transactional: 0.2,
-    confidence: "high",
-  },
-
-  // Metales Preciosos y Joyería (Precious Metals & Jewelry - DPMS)
-  MPJ: {
-    client: 0.25,
-    geographic: 0.2,
-    product: 0.2,
-    transactional: 0.35,
-    confidence: "high",
-  },
-
-  // Notarios y Corredores (Notaries & Brokers)
-  NOT: {
-    client: 0.4,
-    geographic: 0.2,
-    product: 0.25,
-    transactional: 0.15,
-    confidence: "high",
-  },
-
-  // Casas de Empeño (Pawn Shops)
-  EMP: {
-    client: 0.25,
-    geographic: 0.2,
-    product: 0.2,
-    transactional: 0.35,
-    confidence: "medium",
-  },
-
-  // Blindaje de Vehículos (Vehicle Armoring)
-  BLI: {
-    client: 0.35,
-    geographic: 0.25,
-    product: 0.3,
-    transactional: 0.1,
-    confidence: "medium",
-  },
-
-  // Venta de Vehículos (Vehicle Sales)
-  VEH: {
-    client: 0.25,
-    geographic: 0.2,
-    product: 0.25,
-    transactional: 0.3,
-    confidence: "high",
-  },
-
-  // Activos Virtuales (Virtual Assets - PSAV)
-  AVI: {
-    client: 0.35,
-    geographic: 0.15,
-    product: 0.3,
-    transactional: 0.2,
-    confidence: "high",
-  },
-
-  // Juegos y Sorteos (Gaming & Lotteries)
-  JYS: {
-    client: 0.25,
-    geographic: 0.25,
-    product: 0.2,
-    transactional: 0.3,
-    confidence: "high",
-  },
-
-  // Obras de Arte (Art Trade)
-  ODA: {
-    client: 0.3,
-    geographic: 0.25,
-    product: 0.3,
-    transactional: 0.15,
-    confidence: "high",
-  },
-
-  // Servicios Profesionales (Professional Services)
-  SPR: {
-    client: 0.4,
-    geographic: 0.15,
-    product: 0.3,
-    transactional: 0.15,
-    confidence: "high",
-  },
-
-  // Arrendamiento de Inmuebles (Real Estate Leasing)
-  ARR: {
-    client: 0.3,
-    geographic: 0.25,
-    product: 0.2,
-    transactional: 0.25,
-    confidence: "medium",
-  },
-
-  // Fideicomisos (Trusts)
-  FID: {
-    client: 0.4,
-    geographic: 0.15,
-    product: 0.3,
-    transactional: 0.15,
-    confidence: "high",
-  },
-
-  // Tarjetas de Servicios y Crédito (Prepaid Cards & Credit Services)
-  TSC: {
-    client: 0.25,
-    geographic: 0.15,
-    product: 0.3,
-    transactional: 0.3,
-    confidence: "medium",
-  },
-
-  // Donatarias / ONG (Charities & NGOs)
-  DON: {
-    client: 0.35,
-    geographic: 0.25,
-    product: 0.25,
-    transactional: 0.15,
-    confidence: "high",
-  },
-
-  // Comercio Exterior (Foreign Trade)
-  CEX: {
-    client: 0.25,
-    geographic: 0.35,
-    product: 0.25,
-    transactional: 0.15,
-    confidence: "medium",
-  },
-} as const;
-
-/**
- * List of all Actividades Vulnerables with available presets.
- */
-const AVAILABLE_PRESET_ACTIVITIES = Object.keys(
-  WEIGHT_PRESETS
-) as readonly string[];
-
-/**
- * All 15 Actividades Vulnerables defined in LFPIORPI.
- */
-export const ACTIVIDADES_VULNERABLES = [
-  "INM",
-  "MPJ",
-  "NOT",
-  "EMP",
-  "BLI",
-  "VEH",
-  "AVI",
-  "JYS",
-  "ODA",
-  "SPR",
-  "ARR",
-  "FID",
-  "TSC",
-  "DON",
-  "CEX",
-] as const;
-
-export type ActividadVulnerable = (typeof ACTIVIDADES_VULNERABLES)[number];
-
-/** @deprecated Use WeightPreset instead */
-export type MERWeightPreset = WeightPreset;
-
-// ===========================
-// Types
-// ===========================
-
-/**
- * Context for EBR resource operations.
- * Passed from the main SDK.
- */
-export interface EBRResourceContext {
-  /** tRPC client for API communication (optional for backward compatibility) */
-  trpc?: TRPCClient;
-  /** SDK scope (jurisdiction and optional actividadVulnerable) */
-  scope: SDKScope;
-  /** Environment (test or live) */
-  environment: Environment;
-}
-
-/**
- * Weights sub-resource for accessing weight configuration.
- */
-export interface EBRWeightsResource {
-  /** Valid weight range (min: 0.10, max: 0.70) */
-  readonly range: typeof WEIGHT_RANGE;
-}
-
-/**
- * Thresholds sub-resource for accessing threshold configuration.
- */
-export interface EBRThresholdsResource {
-  /** Default/suggested thresholds */
-  readonly defaults: ScoreThresholds;
-}
-
-/**
- * Presets sub-resource for accessing weight presets.
- */
-export interface EBRPresetsResource {
-  /**
-   * Lists all available preset activity codes.
-   * @returns Array of activity codes with presets
-   */
-  list(): readonly string[];
-
-  /**
-   * Gets the preset for a specific activity.
-   * @param activity - Activity code (e.g., "AVI", "INM")
-   * @returns The weight preset or null if not found
-   */
-  get(activity: string): WeightPreset | null;
-
-  /**
-   * Gets the suggested preset for the current SDK scope.
-   * Returns null if SDK is not scoped to an activity or no preset exists.
-   * @returns The suggested weight preset or null
-   */
-  suggested(): WeightPreset | null;
-}
-
-/**
- * Risk level sub-resource for risk level utilities.
- */
-export interface EBRRiskLevelResource {
-  /**
-   * Maps an internal risk level (5) to regulatory level (3).
-   * @param internal - Internal risk level
-   * @returns Regulatory risk level
-   */
-  mapToRegulatory(internal: InternalRiskLevel): RegulatoryRiskLevel;
-
-  /**
-   * Gets the recommended KYC update frequency for a risk level.
-   * @param level - Internal risk level
-   * @returns Update frequency in months
-   */
-  getUpdateFrequency(level: InternalRiskLevel): number;
-}
-
-// ===========================
-// EBR Resource Class
-// ===========================
-
-/**
- * EBR Resource
- *
- * Manages EBR (Evaluación Basada en Riesgos) configurations for Mexican
- * AML/KYC compliance under LFPIORPI.
- *
- * Key features:
- * - **Immutable configurations**: No updates - each change creates a new version
- * - **Scope-aware**: Works with global EBR or activity-specific EBR
- * - **Validation**: Full client-side validation before API calls
- * - **Audit trail**: All versions preserved with justifications
- *
- * @example
- * ```typescript
- * // Create EBR configuration
- * const config = await sdk.ebr.create({
- *   weights: { client: 0.25, geographic: 0.35, product: 0.20, transactional: 0.20 },
- *   thresholds: sdk.ebr.thresholds.defaults,
- *   justification: "Initial configuration for Q4 2024",
- * });
- *
- * // Get suggested preset for current activity
- * const suggested = sdk.ebr.presets.suggested();
- *
- * // Map risk level for regulatory reporting
- * const regulatory = sdk.ebr.riskLevel.mapToRegulatory("muy_alto"); // "alto"
- * ```
- */
-export class EBRResource {
-  protected readonly ctx: EBRResourceContext;
-
-  constructor(context: EBRResourceContext) {
-    this.ctx = context;
-  }
-
-  /**
-   * Gets the tRPC client, throwing if not available.
-   */
-  private get trpc(): TRPCClient {
-    if (!this.ctx.trpc) {
-      throw new Error(
-        "EBRResource requires tRPC client for API operations. " +
-        "Make sure the SDK was initialized with API connection."
-      );
-    }
-    return this.ctx.trpc;
-  }
-
-  // ===========================
-  // Main Methods
-  // ===========================
-
-  /**
-   * Creates a new EBR configuration.
-   *
-   * If a configuration already exists, the existing one is marked as "superseded"
-   * and a new version is created. This maintains a complete audit trail.
-   *
-   * @param input - Configuration input (weights, thresholds, justification)
-   * @returns The created EBR configuration
-   * @throws {ValidationError} If input validation fails
-   */
-  async create(input: CreateEBRConfigInput): Promise<EBRConfiguration> {
-    // 1. Validate input using Zod schema
-    const parseResult = CreateEBRConfigInputSchema.safeParse(input);
-
-    if (!parseResult.success) {
-      throw ValidationError.fromZodError(parseResult.error as ZodError);
-    }
-
-    const validated = parseResult.data;
-
-    // 2. Validate activity mismatch if explicitly provided
-    if (validated.actividadVulnerable) {
-      const scopeActivity = this.getCurrentActivity();
-      if (scopeActivity && validated.actividadVulnerable !== scopeActivity) {
-        throw new ValidationError([
-          {
-            path: ["actividadVulnerable"],
-            message: `Activity mismatch - SDK scope is ${scopeActivity} but input specifies ${validated.actividadVulnerable}`,
-            code: "ACTIVITY_MISMATCH",
-          },
-        ]);
-      }
-    }
-
-    // 3. Determine the effective activity (from input or scope)
-    const effectiveActivity =
-      validated.actividadVulnerable ?? this.getCurrentActivity();
-
-    // 4. Call the API
-    const response = await this.execute(() =>
-      this.trpc.ebr.create.mutate({
-        ...validated,
-        actividadVulnerable: effectiveActivity ?? undefined,
-      })
-    );
-
-    return this.transformResponse(response);
-  }
-
-  /**
-   * Gets the currently active EBR configuration.
-   *
-   * @returns The active configuration or null if none exists
-   */
-  async get(): Promise<EBRConfiguration | null> {
-    const activity = this.getCurrentActivity();
-
-    const response = await this.execute(() =>
-      this.trpc.ebr.get.query({
-        actividadVulnerable: activity ?? undefined,
-      })
-    );
-
-    if (!response) {
-      return null;
-    }
-
-    return this.transformResponse(response);
-  }
-
-  /**
-   * Gets an EBR configuration by ID.
-   *
-   * @param id - Configuration ID
-   * @returns The configuration or null if not found
-   */
-  async getById(id: string): Promise<EBRConfiguration | null> {
-    const response = await this.execute(() =>
-      this.trpc.ebr.getById.query({ id })
-    );
-
-    if (!response) {
-      return null;
-    }
-
-    return this.transformResponse(response);
-  }
-
-  /**
-   * Gets the complete history of EBR configurations.
-   *
-   * @param options - Optional options including limit
-   * @returns Array of all EBR configuration versions, newest first
-   */
-  async getHistory(options?: { limit?: number }): Promise<EBRConfigListItem[]> {
-    const activity = this.getCurrentActivity();
-
-    const response = await this.execute(() =>
-      this.trpc.ebr.getHistory.query({
-        actividadVulnerable: activity ?? undefined,
-        limit: options?.limit,
-      })
-    );
-
-    return response;
-  }
-
-  /**
-   * Promotes an EBR configuration from test to live environment.
-   *
-   * Must be called from the test environment.
-   *
-   * @returns The promoted configuration (now in live)
-   */
-  async promote(): Promise<EBRConfiguration> {
-    const activity = this.getCurrentActivity();
-
-    const response = await this.execute(() =>
-      this.trpc.ebr.promote.mutate({
-        actividadVulnerable: activity ?? undefined,
-      })
-    );
-
-    return this.transformResponse(response);
-  }
-
-  // ===========================
-  // Sub-Resources
-  // ===========================
-
-  /**
-   * Weights configuration sub-resource.
-   */
-  get weights(): EBRWeightsResource {
-    return {
-      range: WEIGHT_RANGE,
-    };
-  }
-
-  /**
-   * Thresholds configuration sub-resource.
-   */
-  get thresholds(): EBRThresholdsResource {
-    return {
-      defaults: DEFAULT_THRESHOLDS as unknown as ScoreThresholds,
-    };
-  }
-
-  /**
-   * Presets sub-resource for weight presets.
-   */
-  get presets(): EBRPresetsResource {
-    return {
-      list: () => AVAILABLE_PRESET_ACTIVITIES,
-
-      get: (activity: string): WeightPreset | null => {
-        return WEIGHT_PRESETS[activity] ?? null;
-      },
-
-      suggested: (): WeightPreset | null => {
-        const activity = this.getCurrentActivity();
-        if (!activity) {
-          return null;
-        }
-        return WEIGHT_PRESETS[activity] ?? null;
-      },
-    };
-  }
-
-  /**
-   * Risk level utilities sub-resource.
-   */
-  get riskLevel(): EBRRiskLevelResource {
-    return {
-      mapToRegulatory: RiskLevels.mapToRegulatory,
-      getUpdateFrequency: RiskLevels.getUpdateFrequency,
-    };
-  }
-
-  // ===========================
-  // Private Helpers
-  // ===========================
-
-  /**
-   * Gets the current activity from the SDK scope.
-   */
-  private getCurrentActivity(): string | null {
-    if (isMexicoScope(this.ctx.scope) && this.ctx.scope.actividadVulnerable) {
-      return this.ctx.scope.actividadVulnerable;
-    }
-    return null;
-  }
-
-  /**
-   * Wraps a tRPC operation with error mapping.
-   */
-  private async execute<T>(operation: () => Promise<T>): Promise<T> {
-    try {
-      return await operation();
-    } catch (error) {
-      if (error instanceof TRPCClientError) {
-        throw mapTRPCError(error);
-      }
-      throw error;
-    }
-  }
-
-  /**
-   * Transforms API response to EBRConfiguration type.
-   * Converts ISO date strings from API to Date objects.
-   */
-  private transformResponse(response: {
-    id: string;
-    organizationId: string;
-    actividadVulnerable: string | null;
-    environment: "test" | "live";
-    version: number;
-    weights: {
-      client: number;
-      geographic: number;
-      product: number;
-      transactional: number;
-    };
-    thresholds: ScoreThresholds;
-    justification: string;
-    reviewPeriodMonths: number;
-    validUntil: string; // ISO string from API
-    status: "active" | "superseded";
-    createdAt: string; // ISO string from API
-    createdBy: string;
-    supersededAt?: string; // ISO string from API
-    supersededBy?: string;
-    promotedFromId?: string;
-  }): EBRConfiguration {
-    return {
-      id: response.id,
-      organizationId: response.organizationId,
-      actividadVulnerable: response.actividadVulnerable,
-      environment: response.environment,
-      version: response.version,
-      weights: response.weights,
-      thresholds: response.thresholds,
-      justification: response.justification,
-      reviewPeriodMonths: response.reviewPeriodMonths,
-      validUntil: new Date(response.validUntil),
-      status: response.status,
-      createdAt: new Date(response.createdAt),
-      createdBy: response.createdBy,
-      supersededAt: response.supersededAt
-        ? new Date(response.supersededAt)
-        : undefined,
-      supersededBy: response.supersededBy,
-      promotedFromId: response.promotedFromId,
-    };
-  }
-}

package/src/resources/mex/index.ts

@@ -1,23 +0,0 @@
-/**
- * Mexico Scoped Resources
- */
-
-// Mexico-level resources
-export { MexClientsResource } from "./clients";
-export { MexTransactionsResource } from "./transactions";
-export { MexBankAccountsResource } from "./bank-accounts";
-export { MexAddressesResource } from "./addresses";
-export { MexReportsResource } from "./reports";
-export {
-  EBRResource,
-  type EBRResourceContext,
-  type EBRPresetsResource,
-  type EBRWeightsResource,
-  type EBRThresholdsResource,
-  type EBRRiskLevelResource,
-  type WeightPreset,
-  type PresetConfidence,
-} from "./ebr";
-
-// Activity-specific resources
-export * from "./actividad-vulnerable";