@artu-ai/compliance-sdk 0.0.6 → 0.3.0

package/src/resources/mex/ebr.ts

@@ -0,0 +1,621 @@
+/**
+ * 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

@@ -0,0 +1,23 @@
+/**
+ * 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";