@artu-ai/compliance-sdk 0.0.5 → 0.2.0

package/src/sdk/base.ts

@@ -0,0 +1,43 @@
+/**
+ * Base SDK Types & Registration
+ *
+ * Unscoped/default SDK types and resource factory registration.
+ */
+
+import type { ComplianceSDKOptionsBase } from "./types";
+import {
+  ClientsResource,
+  TransactionsResource,
+  ReportsResource,
+  BankAccountsResource,
+  AddressesResource,
+} from "../resources";
+import { registerScope } from "./resource-registry";
+
+// ===========================
+// SDK Options
+// ===========================
+
+/**
+ * Options for creating an unscoped SDK
+ */
+export type UnscopedSDKOptions = ComplianceSDKOptionsBase & {
+  jurisdiction?: undefined;
+};
+
+// ===========================
+// Registration
+// ===========================
+
+/**
+ * Registers the base (unscoped) resource factories
+ */
+export function registerBaseScope(): void {
+  registerScope("base", {
+    clients: (config) => new ClientsResource(config),
+    transactions: (config) => new TransactionsResource(config),
+    reports: (config) => new ReportsResource(config),
+    bankAccounts: (config) => new BankAccountsResource(config),
+    addresses: (config) => new AddressesResource(config),
+  });
+}

package/src/sdk/index.ts

@@ -0,0 +1,98 @@
+/**
+ * SDK Core Module
+ *
+ * Core SDK infrastructure including types, registry, and scope registrations.
+ * Organized by jurisdiction with barrel exports.
+ */
+
+// ===========================
+// Core Types
+// ===========================
+
+export {
+  type Environment,
+  type ComplianceSDKOptionsBase,
+  type ComplianceAuthOptions,
+  type ComplianceAuthMode,
+  type FetchCredentials,
+  type ComplianceAPIKeyAuth,
+  type ComplianceCookieAuth,
+  type SDKScope,
+  type SDKScopeBase,
+  type SDKScopeMexico,
+  isMexicoScope,
+  buildScope,
+} from "./types";
+
+export type { SessionInfo } from "../utils/session";
+
+// ===========================
+// Registry
+// ===========================
+
+export {
+  type ResourceFactory,
+  type ScopeResourceFactories,
+  registerScope,
+  getResourceFactories,
+  getScopeKey,
+  hasScope,
+  getRegisteredScopes,
+  clearRegistry,
+} from "./resource-registry";
+
+// ===========================
+// Base (Unscoped)
+// ===========================
+
+export { type UnscopedSDKOptions, registerBaseScope } from "./base";
+
+// ===========================
+// Mexico
+// ===========================
+
+export {
+  // Types
+  type ComplianceSDKOptionsMexico,
+  type MexicoSDKOptions,
+  type MexicoComplianceSDK,
+  type AVISDKOptions,
+  type AVIComplianceSDK,
+  type JYSSDKOptions,
+  type JYSComplianceSDK,
+  type TSCSDKOptions,
+  type TSCComplianceSDK,
+  // Registration
+  registerMexicoScopes,
+} from "./mex";
+
+// ===========================
+// Initialize All Scopes
+// ===========================
+
+import { registerBaseScope } from "./base";
+import { registerMexicoScopes } from "./mex";
+
+/**
+ * Registers all SDK scopes.
+ * Called automatically when the SDK module is imported.
+ */
+export function initializeRegistry(): void {
+  registerBaseScope();
+  registerMexicoScopes();
+}
+
+// Auto-initialize on import
+initializeRegistry();
+
+// ===========================
+// ComplianceSDK
+// ===========================
+
+export {
+  ComplianceSDK,
+  ComplianceSDKImpl,
+  type ComplianceSDKOptions,
+  type ComplianceSDKConstructor,
+  type UnscopedComplianceSDK,
+} from "./ComplianceSDK";

package/src/sdk/mex/ComplianceSDK.ts

@@ -0,0 +1,140 @@
+/**
+ * Mexico-scoped ComplianceSDK
+ *
+ * Provides Mexico-specific resources like EBR (Expediente de Beneficiario Real).
+ */
+
+import { ComplianceSDKImpl } from "../ComplianceSDK";
+import type {
+  MexicoScopedSDKOptions,
+  ComplianceSDKOptionsMexico,
+} from "./types";
+import { EBRResource } from "../../resources/mex/ebr";
+import type { MexClientsResource } from "../../resources/mex/clients";
+import type { MexTransactionsResource } from "../../resources/mex/transactions";
+import type { MexReportsResource } from "../../resources/mex/reports";
+import type { MexBankAccountsResource } from "../../resources/mex/bank-accounts";
+import type { MexAddressesResource } from "../../resources/mex/addresses";
+
+/**
+ * Mexico ComplianceSDK Implementation.
+ *
+ * Extends the base SDK with Mexico-specific resources.
+ * This class is used when you create a ComplianceSDK with `jurisdiction: "MX"`.
+ *
+ * Registration is handled by `registerMexicoScopes()` in `./index.ts`.
+ *
+ * @example
+ * ```typescript
+ * const sdk = new ComplianceSDK({
+ *   apiKey: process.env.API_KEY!,
+ *   environment: "test",
+ *   jurisdiction: "MX",
+ * });
+ *
+ * // Mexico-specific EBR resource is available
+ * console.log(sdk.ebr); // EbrResource instance
+ * ```
+ */
+export class MexicoComplianceSDKImpl extends ComplianceSDKImpl {
+  // ─────────────────────────────────────────────────────────────────
+  // Override resource types with Mexico-specific types
+  // The registry creates these at runtime, we just need correct types
+  // ─────────────────────────────────────────────────────────────────
+
+  declare public readonly clients: MexClientsResource;
+  declare public readonly transactions: MexTransactionsResource;
+  declare public readonly reports: MexReportsResource;
+  declare public readonly bankAccounts: MexBankAccountsResource;
+  declare public readonly addresses: MexAddressesResource;
+
+  /**
+   * EBR (Expediente de Beneficiario Real) resource.
+   *
+   * Mexico-only resource for managing beneficial owner records.
+   */
+  public readonly ebr: EBRResource;
+
+  constructor(options: ComplianceSDKOptionsMexico) {
+    super(options);
+
+    // Add Mexico-specific resources
+    this.ebr = new EBRResource({
+      trpc: this.trpc,
+      scope: this._scope,
+      environment: this.environment,
+    });
+  }
+}
+
+/**
+ * Mexico-scoped ComplianceSDK (convenience class).
+ * Pre-configured for Mexico jurisdiction - no need to specify jurisdiction in options.
+ *
+ * Includes Mexico-specific resources:
+ * - `ebr` - EBR (Evaluación Basada en Riesgos) for AML/KYC risk evaluation
+ *
+ * @example
+ * ```typescript
+ * import { ComplianceSDK } from "@artu/compliance-sdk/mexico";
+ *
+ * const sdk = new ComplianceSDK({
+ *   apiKey: process.env.API_KEY!,
+ *   environment: "test",
+ * });
+ *
+ * // Already scoped to Mexico - no need to specify jurisdiction
+ * const client = await sdk.clients.create({
+ *   type: ClientType.Person,
+ *   name: "Juan García",
+ * });
+ *
+ * // Access Mexico-specific EBR resource
+ * const weights = sdk.ebr.presets.suggested();
+ * ```
+ */
+export class MexicoComplianceSDKScoped extends MexicoComplianceSDKImpl {
+  // Resource types inherited from MexicoComplianceSDKImpl (already Mexico-typed)
+
+  /**
+   * EBR (Evaluación Basada en Riesgos) resource manager.
+   *
+   * Provides risk-based evaluation methodology for AML/KYC compliance
+   * as required by Mexican LFPIORPI regulations.
+   *
+   * Key features:
+   * - Immutable configurations (append-only for audit trail)
+   * - Scope-aware (global or activity-specific)
+   * - Weight presets for all 15 Actividades Vulnerables
+   * - Risk level mapping (5 internal → 3 regulatory)
+   *
+   * @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 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"
+   * ```
+   */
+  public readonly ebr: EBRResource;
+
+  constructor(options: MexicoScopedSDKOptions) {
+    const { actividadVulnerable, ...baseOptions } = options;
+    super({ ...baseOptions, jurisdiction: "MX", actividadVulnerable });
+
+    // Initialize Mexico-specific resources
+    this.ebr = new EBRResource({
+      trpc: this.trpc,
+      scope: this.scope,
+      environment: this.environment,
+    });
+  }
+}

package/src/sdk/mex/actividad-vulnerable/avi/ComplianceSDK.ts

@@ -0,0 +1,51 @@
+/**
+ * AVI-scoped ComplianceSDK
+ *
+ * Pre-configured SDK for Mexico jurisdiction and Activos Virtuales (AVI) activity.
+ * Extends MexicoComplianceSDKScoped to inherit Mexico-specific resources like EBR.
+ */
+
+import { MexicoComplianceSDKScoped } from "../../ComplianceSDK";
+import type { AVIScopedSDKOptions } from "./types";
+import type { AVIClientsResource } from "../../../../resources/mex/actividad-vulnerable/avi/clients";
+import type { AVITransactionsResource } from "../../../../resources/mex/actividad-vulnerable/avi/transactions";
+import type { AVIReportsResource } from "../../../../resources/mex/actividad-vulnerable/avi/reports";
+
+/**
+ * AVI-scoped ComplianceSDK.
+ * Pre-configured for Mexico jurisdiction and Activos Virtuales (AVI) activity.
+ *
+ * Inherits Mexico-specific resources:
+ * - `ebr` - EBR (Evaluación Basada en Riesgos) for AML/KYC risk evaluation
+ *
+ * @example
+ * ```typescript
+ * import { ComplianceSDK } from "@artu/compliance-sdk/mexico/actividad-vulnerable/avi";
+ *
+ * const sdk = new ComplianceSDK({
+ *   apiKey: process.env.API_KEY!,
+ *   environment: "test",
+ * });
+ *
+ * // Already scoped - no need to specify jurisdiction/activity
+ * const client = await sdk.clients.create({
+ *   type: ClientType.Person,
+ *   name: "Juan García",
+ * });
+ *
+ * // Access inherited EBR resource
+ * const weights = sdk.ebr.presets.suggested();
+ * ```
+ */
+export class AVIComplianceSDKScoped extends MexicoComplianceSDKScoped {
+  // Override resource types with AVI-specific types
+  // The registry creates these at runtime, we just need correct types
+  declare public readonly clients: AVIClientsResource;
+  declare public readonly transactions: AVITransactionsResource;
+  declare public readonly reports: AVIReportsResource;
+  // addresses and bankAccounts inherited from MexicoComplianceSDKImpl (MexAddressesResource, MexBankAccountsResource)
+
+  constructor(options: AVIScopedSDKOptions) {
+    super({ ...options, actividadVulnerable: "AVI" });
+  }
+}

package/src/sdk/mex/actividad-vulnerable/avi/index.ts

@@ -0,0 +1,16 @@
+/**
+ * AVI SDK Module
+ *
+ * Exports types, registration, and scoped SDK for Activos Virtuales.
+ */
+
+// Types and registration
+export {
+  type AVISDKOptions,
+  type AVIScopedSDKOptions,
+  type AVIComplianceSDK,
+  registerAVIScope,
+} from "./types";
+
+// Scoped SDK class
+export { AVIComplianceSDKScoped } from "./ComplianceSDK";

package/src/sdk/mex/actividad-vulnerable/avi/types.ts

@@ -0,0 +1,72 @@
+/**
+ * AVI SDK Types & Registration
+ *
+ * Activos Virtuales (Virtual Assets) - cryptocurrency exchanges, wallets, etc.
+ */
+
+import { Jurisdiction, CodigoActividad } from "@artu-ai/shared";
+import type { ComplianceSDKOptionsBase } from "../../../types";
+import type { MexicoComplianceSDK } from "../../types";
+import {
+  AVIClientsResource,
+  AVITransactionsResource,
+  AVIReportsResource,
+  MexBankAccountsResource,
+  MexAddressesResource,
+} from "../../../../resources";
+import { registerScope } from "../../../resource-registry";
+import type { ReportsResource } from "../../../../resources/reports";
+import type { EBRResource } from "../../../../resources/mex/ebr";
+
+// ===========================
+// SDK Options
+// ===========================
+
+/**
+ * Options for creating an AVI-scoped SDK
+ */
+export type AVISDKOptions = ComplianceSDKOptionsBase & {
+  jurisdiction: typeof Jurisdiction.Mexico | "MX";
+  actividadVulnerable: typeof CodigoActividad.AVI | "AVI";
+};
+
+/**
+ * Options for AVI-scoped SDK (without jurisdiction/activity - pre-configured)
+ */
+export type AVIScopedSDKOptions = Omit<
+  ComplianceSDKOptionsBase,
+  "jurisdiction" | "actividadVulnerable"
+>;
+
+// ===========================
+// Typed SDK Interface
+// ===========================
+
+/**
+ * Mexico AVI-scoped SDK - uses AVI resource types
+ * Extends MexicoComplianceSDK with AVI-specific overrides
+ */
+export interface AVIComplianceSDK
+  extends Omit<MexicoComplianceSDK, "clients" | "transactions" | "reports"> {
+  readonly clients: AVIClientsResource;
+  readonly transactions: AVITransactionsResource;
+  readonly reports: AVIReportsResource;
+  readonly bankAccounts: MexBankAccountsResource;
+  /** EBR resource for risk-based evaluation */
+  readonly ebr: EBRResource;
+}
+
+// ===========================
+// Registration
+// ===========================
+
+export function registerAVIScope(): void {
+  registerScope("MX:AVI", {
+    clients: (config) => new AVIClientsResource(config),
+    transactions: (config) => new AVITransactionsResource(config),
+    reports: (config) =>
+      new AVIReportsResource(config) as unknown as ReportsResource,
+    bankAccounts: (config) => new MexBankAccountsResource(config),
+    addresses: (config) => new MexAddressesResource(config),
+  });
+}

package/src/sdk/mex/actividad-vulnerable/index.ts

@@ -0,0 +1,58 @@
+/**
+ * Actividad Vulnerable SDK Types & Registrations
+ *
+ * Barrel export for all activity-specific SDK types, registrations, and scoped SDKs.
+ */
+
+// ===========================
+// AVI
+// ===========================
+
+export {
+  type AVISDKOptions,
+  type AVIScopedSDKOptions,
+  type AVIComplianceSDK,
+  registerAVIScope,
+  AVIComplianceSDKScoped,
+} from "./avi";
+
+// ===========================
+// JYS
+// ===========================
+
+export {
+  type JYSSDKOptions,
+  type JYSScopedSDKOptions,
+  type JYSComplianceSDK,
+  registerJYSScope,
+  JYSComplianceSDKScoped,
+} from "./jys";
+
+// ===========================
+// TSC
+// ===========================
+
+export {
+  type TSCSDKOptions,
+  type TSCScopedSDKOptions,
+  type TSCComplianceSDK,
+  registerTSCScope,
+  TSCComplianceSDKScoped,
+} from "./tsc";
+
+// ===========================
+// Register All Activities
+// ===========================
+
+import { registerAVIScope } from "./avi";
+import { registerJYSScope } from "./jys";
+import { registerTSCScope } from "./tsc";
+
+/**
+ * Registers all Actividad Vulnerable activity scopes
+ */
+export function registerActividadVulnerableScopes(): void {
+  registerAVIScope();
+  registerJYSScope();
+  registerTSCScope();
+}

package/src/sdk/mex/actividad-vulnerable/jys/ComplianceSDK.ts

@@ -0,0 +1,51 @@
+/**
+ * JYS-scoped ComplianceSDK
+ *
+ * Pre-configured SDK for Mexico jurisdiction and Joyas y Relojes (JYS) activity.
+ * Extends MexicoComplianceSDKScoped to inherit Mexico-specific resources like EBR.
+ */
+
+import { MexicoComplianceSDKScoped } from "../../ComplianceSDK";
+import type { JYSScopedSDKOptions } from "./types";
+import type { JYSClientsResource } from "../../../../resources/mex/actividad-vulnerable/jys/clients";
+import type { JYSTransactionsResource } from "../../../../resources/mex/actividad-vulnerable/jys/transactions";
+import type { JYSReportsResource } from "../../../../resources/mex/actividad-vulnerable/jys/reports";
+
+/**
+ * JYS-scoped ComplianceSDK.
+ * Pre-configured for Mexico jurisdiction and Joyas y Relojes (JYS) activity.
+ *
+ * Inherits Mexico-specific resources:
+ * - `ebr` - EBR (Evaluación Basada en Riesgos) for AML/KYC risk evaluation
+ *
+ * @example
+ * ```typescript
+ * import { ComplianceSDK } from "@artu/compliance-sdk/mexico/actividad-vulnerable/jys";
+ *
+ * const sdk = new ComplianceSDK({
+ *   apiKey: process.env.API_KEY!,
+ *   environment: "test",
+ * });
+ *
+ * // Already scoped - no need to specify jurisdiction/activity
+ * const client = await sdk.clients.create({
+ *   type: ClientType.Person,
+ *   name: "Juan García",
+ * });
+ *
+ * // Access inherited EBR resource
+ * const weights = sdk.ebr.presets.suggested();
+ * ```
+ */
+export class JYSComplianceSDKScoped extends MexicoComplianceSDKScoped {
+  // Override resource types with JYS-specific types
+  // The registry creates these at runtime, we just need correct types
+  declare public readonly clients: JYSClientsResource;
+  declare public readonly transactions: JYSTransactionsResource;
+  declare public readonly reports: JYSReportsResource;
+  // addresses and bankAccounts inherited from MexicoComplianceSDKImpl (MexAddressesResource, MexBankAccountsResource)
+
+  constructor(options: JYSScopedSDKOptions) {
+    super({ ...options, actividadVulnerable: "JYS" });
+  }
+}

package/src/sdk/mex/actividad-vulnerable/jys/index.ts

@@ -0,0 +1,16 @@
+/**
+ * JYS SDK Module
+ *
+ * Exports types, registration, and scoped SDK for Joyas y Sorteos.
+ */
+
+// Types and registration
+export {
+  type JYSSDKOptions,
+  type JYSScopedSDKOptions,
+  type JYSComplianceSDK,
+  registerJYSScope,
+} from "./types";
+
+// Scoped SDK class
+export { JYSComplianceSDKScoped } from "./ComplianceSDK";

package/src/sdk/mex/actividad-vulnerable/jys/types.ts

@@ -0,0 +1,72 @@
+/**
+ * JYS SDK Types & Registration
+ *
+ * Joyas y Relojes (Jewelry and Watches) - high-value goods dealers.
+ */
+
+import { Jurisdiction, CodigoActividad } from "@artu-ai/shared";
+import type { ComplianceSDKOptionsBase } from "../../../types";
+import type { MexicoComplianceSDK } from "../../types";
+import {
+  JYSClientsResource,
+  JYSTransactionsResource,
+  JYSReportsResource,
+  MexBankAccountsResource,
+  MexAddressesResource,
+} from "../../../../resources";
+import { registerScope } from "../../../resource-registry";
+import type { ReportsResource } from "../../../../resources/reports";
+import type { EBRResource } from "../../../../resources/mex/ebr";
+
+// ===========================
+// SDK Options
+// ===========================
+
+/**
+ * Options for creating a JYS-scoped SDK
+ */
+export type JYSSDKOptions = ComplianceSDKOptionsBase & {
+  jurisdiction: typeof Jurisdiction.Mexico | "MX";
+  actividadVulnerable: typeof CodigoActividad.JYS | "JYS";
+};
+
+/**
+ * Options for JYS-scoped SDK (without jurisdiction/activity - pre-configured)
+ */
+export type JYSScopedSDKOptions = Omit<
+  ComplianceSDKOptionsBase,
+  "jurisdiction" | "actividadVulnerable"
+>;
+
+// ===========================
+// Typed SDK Interface
+// ===========================
+
+/**
+ * Mexico JYS-scoped SDK - uses JYS resource types
+ * Extends MexicoComplianceSDK with JYS-specific overrides
+ */
+export interface JYSComplianceSDK
+  extends Omit<MexicoComplianceSDK, "clients" | "transactions" | "reports"> {
+  readonly clients: JYSClientsResource;
+  readonly transactions: JYSTransactionsResource;
+  readonly reports: JYSReportsResource;
+  readonly bankAccounts: MexBankAccountsResource;
+  /** EBR resource for risk-based evaluation */
+  readonly ebr: EBRResource;
+}
+
+// ===========================
+// Registration
+// ===========================
+
+export function registerJYSScope(): void {
+  registerScope("MX:JYS", {
+    clients: (config) => new JYSClientsResource(config),
+    transactions: (config) => new JYSTransactionsResource(config),
+    reports: (config) =>
+      new JYSReportsResource(config) as unknown as ReportsResource,
+    bankAccounts: (config) => new MexBankAccountsResource(config),
+    addresses: (config) => new MexAddressesResource(config),
+  });
+}

package/src/sdk/mex/actividad-vulnerable/tsc/ComplianceSDK.ts

@@ -0,0 +1,51 @@
+/**
+ * TSC-scoped ComplianceSDK
+ *
+ * Pre-configured SDK for Mexico jurisdiction and Tarjetas de Servicio y Crédito (TSC) activity.
+ * Extends MexicoComplianceSDKScoped to inherit Mexico-specific resources like EBR.
+ */
+
+import { MexicoComplianceSDKScoped } from "../../ComplianceSDK";
+import type { TSCScopedSDKOptions } from "./types";
+import type { TSCClientsResource } from "../../../../resources/mex/actividad-vulnerable/tsc/clients";
+import type { TSCTransactionsResource } from "../../../../resources/mex/actividad-vulnerable/tsc/transactions";
+import type { TSCReportsResource } from "../../../../resources/mex/actividad-vulnerable/tsc/reports";
+
+/**
+ * TSC-scoped ComplianceSDK.
+ * Pre-configured for Mexico jurisdiction and Tarjetas de Servicio y Crédito (TSC) activity.
+ *
+ * Inherits Mexico-specific resources:
+ * - `ebr` - EBR (Evaluación Basada en Riesgos) for AML/KYC risk evaluation
+ *
+ * @example
+ * ```typescript
+ * import { ComplianceSDK } from "@artu/compliance-sdk/mexico/actividad-vulnerable/tsc";
+ *
+ * const sdk = new ComplianceSDK({
+ *   apiKey: process.env.API_KEY!,
+ *   environment: "test",
+ * });
+ *
+ * // Already scoped - no need to specify jurisdiction/activity
+ * const client = await sdk.clients.create({
+ *   type: ClientType.Person,
+ *   name: "Juan García",
+ * });
+ *
+ * // Access inherited EBR resource
+ * const weights = sdk.ebr.presets.suggested();
+ * ```
+ */
+export class TSCComplianceSDKScoped extends MexicoComplianceSDKScoped {
+  // Override resource types with TSC-specific types
+  // The registry creates these at runtime, we just need correct types
+  declare public readonly clients: TSCClientsResource;
+  declare public readonly transactions: TSCTransactionsResource;
+  declare public readonly reports: TSCReportsResource;
+  // addresses and bankAccounts inherited from MexicoComplianceSDKImpl (MexAddressesResource, MexBankAccountsResource)
+
+  constructor(options: TSCScopedSDKOptions) {
+    super({ ...options, actividadVulnerable: "TSC" });
+  }
+}

package/src/sdk/mex/actividad-vulnerable/tsc/index.ts

@@ -0,0 +1,16 @@
+/**
+ * TSC SDK Module
+ *
+ * Exports types, registration, and scoped SDK for Tarjetas de Servicio y Crédito.
+ */
+
+// Types and registration
+export {
+  type TSCSDKOptions,
+  type TSCScopedSDKOptions,
+  type TSCComplianceSDK,
+  registerTSCScope,
+} from "./types";
+
+// Scoped SDK class
+export { TSCComplianceSDKScoped } from "./ComplianceSDK";