@artu-ai/compliance-sdk 0.0.6 → 0.3.0

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

@@ -0,0 +1,54 @@
+/**
+ * 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
+  // Note: @ts-expect-error is needed for some overrides due to sort type parameter variance
+  declare public readonly clients: TSCClientsResource;
+  // @ts-expect-error - Runtime type is correct, variance issue with sort types
+  declare public readonly transactions: TSCTransactionsResource;
+  // @ts-expect-error - Runtime type is correct, variance issue with sort types
+  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";

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

@@ -0,0 +1,86 @@
+/**
+ * TSC SDK Types & Registration
+ *
+ * Tarjetas de Servicios y Crédito (Service and Credit Cards) - prepaid cards, etc.
+ */
+
+import { Jurisdiction, CodigoActividad } from "@artu-ai/shared";
+import type {
+  ComplianceSDKOptionsBase,
+  DistributiveOmit,
+} from "../../../types";
+import type { MexicoComplianceSDK } from "../../types";
+import {
+  TSCClientsResource,
+  TSCTransactionsResource,
+  TSCReportsResource,
+  MexBankAccountsResource,
+  MexAddressesResource,
+} from "../../../../resources";
+import { registerScope } from "../../../resource-registry";
+import type { ClientsResource } from "../../../../resources/clients";
+import type { TransactionsResource } from "../../../../resources/transactions";
+import type { ReportsResource } from "../../../../resources/reports";
+import type { BankAccountsResource } from "../../../../resources/bank-accounts";
+import type { AddressesResource } from "../../../../resources/addresses";
+import type { EBRResource } from "../../../../resources/mex/ebr";
+
+// ===========================
+// SDK Options
+// ===========================
+
+/**
+ * Options for creating a TSC-scoped SDK
+ */
+export type TSCSDKOptions = ComplianceSDKOptionsBase & {
+  jurisdiction: typeof Jurisdiction.Mexico | "MX";
+  actividadVulnerable: typeof CodigoActividad.TSC | "TSC";
+};
+
+/**
+ * Options for TSC-scoped SDK (without jurisdiction/activity - pre-configured)
+ */
+export type TSCScopedSDKOptions = DistributiveOmit<
+  ComplianceSDKOptionsBase,
+  "jurisdiction" | "actividadVulnerable"
+>;
+
+// ===========================
+// Typed SDK Interface
+// ===========================
+
+/**
+ * Mexico TSC-scoped SDK - uses TSC resource types
+ * Extends MexicoComplianceSDK with TSC-specific overrides
+ */
+export interface TSCComplianceSDK extends Omit<
+  MexicoComplianceSDK,
+  "clients" | "transactions" | "reports"
+> {
+  readonly clients: TSCClientsResource;
+  readonly transactions: TSCTransactionsResource;
+  readonly reports: TSCReportsResource;
+  readonly bankAccounts: MexBankAccountsResource;
+  /** EBR resource for risk-based evaluation */
+  readonly ebr: EBRResource;
+}
+
+// ===========================
+// Registration
+// ===========================
+
+export function registerTSCScope(): void {
+  // Note: Casts needed due to sort type parameter variance between scoped and base resources
+  registerScope("MX:TSC", {
+    clients: (config) =>
+      new TSCClientsResource(config) as unknown as ClientsResource,
+    transactions: (config) =>
+      new TSCTransactionsResource(config) as unknown as TransactionsResource,
+    reports: (config) =>
+      new TSCReportsResource(config) as unknown as ReportsResource,
+    bankAccounts: (config) =>
+      new MexBankAccountsResource(config) as unknown as BankAccountsResource,
+    addresses: (config) =>
+      new MexAddressesResource(config) as unknown as AddressesResource,
+  });
+}

package/src/sdk/mex/index.ts

@@ -0,0 +1,66 @@
+/**
+ * Mexico SDK Module
+ *
+ * Barrel export for Mexico SDK types and registrations.
+ */
+
+// Base Mexico types
+export {
+  type ComplianceSDKOptionsMexico,
+  type MexicoSDKOptions,
+  type MexicoScopedSDKOptions,
+  type MexicoComplianceSDK,
+} from "./types";
+
+// Scoped SDK class
+export {
+  MexicoComplianceSDKScoped,
+  MexicoComplianceSDKImpl,
+} from "./ComplianceSDK";
+
+// Actividad Vulnerable types and registrations
+export {
+  type AVISDKOptions,
+  type AVIComplianceSDK,
+  type JYSSDKOptions,
+  type JYSComplianceSDK,
+  type TSCSDKOptions,
+  type TSCComplianceSDK,
+  registerActividadVulnerableScopes,
+} from "./actividad-vulnerable";
+
+// ===========================
+// Registration
+// ===========================
+
+import { registerScope } from "../resource-registry";
+import { registerSDKClass } from "../sdk-registry";
+import { MexClientsResource } from "../../resources/mex/clients";
+import { MexTransactionsResource } from "../../resources/mex/transactions";
+import { MexReportsResource } from "../../resources/mex/reports";
+import { MexBankAccountsResource } from "../../resources/mex/bank-accounts";
+import { MexAddressesResource } from "../../resources/mex/addresses";
+import { registerActividadVulnerableScopes } from "./actividad-vulnerable";
+import { MexicoComplianceSDKImpl } from "./ComplianceSDK";
+import type { ReportsResource } from "../../resources/reports";
+
+/**
+ * Registers all Mexico scopes (base + activities)
+ */
+export function registerMexicoScopes(): void {
+  // Register Mexico base scope resources
+  registerScope("MX", {
+    clients: (config) => new MexClientsResource(config),
+    transactions: (config) => new MexTransactionsResource(config),
+    reports: (config) =>
+      new MexReportsResource(config) as unknown as ReportsResource,
+    bankAccounts: (config) => new MexBankAccountsResource(config),
+    addresses: (config) => new MexAddressesResource(config),
+  });
+
+  // Register Mexico SDK class (for SDK class dispatch)
+  registerSDKClass("MX", MexicoComplianceSDKImpl);
+
+  // Register all activity scopes
+  registerActividadVulnerableScopes();
+}

package/src/sdk/mex/types.ts

@@ -0,0 +1,88 @@
+/**
+ * Mexico SDK Types
+ *
+ * Typed SDK interfaces and options for Mexico jurisdiction (base level).
+ * Activity-specific types are in actividad-vulnerable/ subfolder.
+ */
+
+import { Jurisdiction, type CodigoActividad } from "@artu-ai/shared";
+import type {
+  ComplianceSDKOptionsBase,
+  BaseComplianceSDK,
+  DistributiveOmit,
+} from "../types";
+import type {
+  MexClientsResource,
+  MexTransactionsResource,
+  MexBankAccountsResource,
+  MexReportsResource,
+  MexAddressesResource,
+  EBRResource,
+} from "../../resources";
+import type { ContactMethodsResource } from "../../resources/contact-methods";
+import type { DocumentsResource } from "../../resources/documents";
+
+// ===========================
+// SDK Options Types
+// ===========================
+
+/**
+ * SDK options - Mexico jurisdiction (supports actividadVulnerable)
+ */
+export type ComplianceSDKOptionsMexico = ComplianceSDKOptionsBase & {
+  /**
+   * Target jurisdiction - Mexico
+   */
+  jurisdiction: typeof Jurisdiction.Mexico | "MX";
+
+  /**
+   * Target Actividad Vulnerable activity code.
+   * Only available when jurisdiction is Mexico.
+   */
+  actividadVulnerable?: CodigoActividad | "AVI" | "JYS" | "TSC";
+};
+
+/**
+ * Options for creating a Mexico-scoped SDK (no specific activity)
+ */
+export type MexicoSDKOptions = ComplianceSDKOptionsBase & {
+  jurisdiction: typeof Jurisdiction.Mexico | "MX";
+  actividadVulnerable?: undefined;
+};
+
+/**
+ * Options for Mexico-scoped SDK (without jurisdiction - pre-configured)
+ */
+export type MexicoScopedSDKOptions = DistributiveOmit<
+  ComplianceSDKOptionsBase,
+  "jurisdiction"
+> & {
+  /** Activity code - used by activity-scoped subclasses */
+  actividadVulnerable?: CodigoActividad | "AVI" | "JYS" | "TSC";
+};
+
+// ===========================
+// Typed SDK Interface
+// ===========================
+
+/**
+ * Mexico-scoped SDK - uses Mexico resource types
+ */
+export interface MexicoComplianceSDK extends BaseComplianceSDK {
+  // Core resources (Mexico-scoped)
+  readonly clients: MexClientsResource;
+  readonly transactions: MexTransactionsResource;
+  readonly reports: MexReportsResource;
+  readonly bankAccounts: MexBankAccountsResource;
+
+  // Supporting resources (Mexico-scoped)
+  readonly addresses: MexAddressesResource;
+  readonly contactMethods: ContactMethodsResource;
+  readonly documents: DocumentsResource;
+
+  /**
+   * EBR (Evaluación Basada en Riesgos) resource.
+   * Mexico-only resource for risk-based evaluation methodology.
+   */
+  readonly ebr: EBRResource;
+}

package/src/sdk/resource-registry.ts

@@ -0,0 +1,204 @@
+/**
+ * SDK Resource Registry
+ *
+ * Provides a registry pattern for jurisdiction/activity-specific resource factories.
+ * Each jurisdiction module registers its own factories, eliminating switch statements
+ * in the main SDK class.
+ *
+ * @example
+ * ```typescript
+ * // In resources/mex/registry.ts
+ * import { registerScope } from '../../sdk/registry';
+ * import { MexClientsResource } from './clients';
+ *
+ * registerScope('MX', {
+ *   clients: (config) => new MexClientsResource(config),
+ *   // ...
+ * });
+ *
+ * // In ComplianceSDK.ts
+ * const factories = getResourceFactories(scope);
+ * this.clients = factories.clients(config);
+ * ```
+ */
+
+import type { SDKScope } from "./types";
+import type { ResourceConfig } from "../resources/base";
+import type { ClientsResource } from "../resources/clients";
+import type { TransactionsResource } from "../resources/transactions";
+import type { ReportsResource } from "../resources/reports";
+import type { BankAccountsResource } from "../resources/bank-accounts";
+import type { AddressesResource } from "../resources/addresses";
+
+// ===========================
+// Factory Types
+// ===========================
+
+/**
+ * Factory function that creates a resource instance
+ */
+export type ResourceFactory<T> = (config: ResourceConfig) => T;
+
+/**
+ * Resource factories for a specific scope (jurisdiction/activity)
+ *
+ * Each jurisdiction/activity registers factories that create the appropriate
+ * resource class instances.
+ */
+export interface ScopeResourceFactories {
+  /** Factory for creating clients resource */
+  clients: ResourceFactory<ClientsResource>;
+  /** Factory for creating transactions resource */
+  transactions: ResourceFactory<TransactionsResource>;
+  /** Factory for creating reports resource */
+  reports: ResourceFactory<ReportsResource>;
+  /** Factory for creating bank accounts resource (optional - falls back to base) */
+  bankAccounts?: ResourceFactory<BankAccountsResource>;
+  /** Factory for creating addresses resource (optional for backwards compat) */
+  addresses?: ResourceFactory<AddressesResource>;
+}
+
+// ===========================
+// Registry
+// ===========================
+
+/**
+ * Registry of scope-specific resource factories.
+ * Keys are scope identifiers:
+ * - "base" - unscoped/default
+ * - "MX" - Mexico jurisdiction
+ * - "MX:AVI" - Mexico AVI activity
+ * - "MX:JYS" - Mexico JYS activity
+ * - etc.
+ */
+const scopeRegistry = new Map<string, ScopeResourceFactories>();
+
+/**
+ * Generates a scope key from SDKScope
+ *
+ * @param scope - SDK scope configuration
+ * @returns Scope key string (e.g., "base", "MX", "MX:AVI")
+ */
+export function getScopeKey(scope: SDKScope): string {
+  if (!scope.jurisdiction) {
+    return "base";
+  }
+
+  // Check for Mexico with activity
+  if (
+    scope.jurisdiction === "MX" &&
+    "actividadVulnerable" in scope &&
+    scope.actividadVulnerable
+  ) {
+    return `MX:${scope.actividadVulnerable}`;
+  }
+
+  return scope.jurisdiction;
+}
+
+/**
+ * Registers resource factories for a specific scope.
+ *
+ * Called by jurisdiction modules during initialization.
+ * Each jurisdiction/activity registers its own factories.
+ *
+ * @param scopeKey - Scope identifier (e.g., "base", "MX", "MX:AVI")
+ * @param factories - Resource factory functions
+ *
+ * @example
+ * ```typescript
+ * // Register Mexico AVI factories
+ * 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),
+ * });
+ * ```
+ */
+export function registerScope(
+  scopeKey: string,
+  factories: ScopeResourceFactories
+): void {
+  if (scopeRegistry.has(scopeKey)) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[SDK Registry] Overwriting existing factories for scope: ${scopeKey}`
+    );
+  }
+  scopeRegistry.set(scopeKey, factories);
+}
+
+/**
+ * Gets resource factories for a specific scope.
+ *
+ * Looks up factories with fallback:
+ * 1. Exact scope match (e.g., "MX:AVI")
+ * 2. Jurisdiction-only match (e.g., "MX")
+ * 3. Base/default factories
+ *
+ * @param scope - SDK scope configuration
+ * @returns Resource factories for the scope
+ * @throws Error if no factories are registered (not even base)
+ *
+ * @example
+ * ```typescript
+ * const factories = getResourceFactories({ jurisdiction: "MX", actividadVulnerable: "AVI" });
+ * const clientsResource = factories.clients(config);
+ * ```
+ */
+export function getResourceFactories(scope: SDKScope): ScopeResourceFactories {
+  const scopeKey = getScopeKey(scope);
+
+  // Try exact match first
+  let factories = scopeRegistry.get(scopeKey);
+  if (factories) {
+    return factories;
+  }
+
+  // If scope has activity, try jurisdiction-only
+  if (scope.jurisdiction && scopeKey.includes(":")) {
+    factories = scopeRegistry.get(scope.jurisdiction);
+    if (factories) {
+      return factories;
+    }
+  }
+
+  // Fall back to base
+  factories = scopeRegistry.get("base");
+  if (factories) {
+    return factories;
+  }
+
+  throw new Error(
+    `[SDK Registry] No factories registered for scope: ${scopeKey}. ` +
+      `Ensure registry modules are imported before creating SDK instance.`
+  );
+}
+
+/**
+ * Checks if factories are registered for a scope
+ *
+ * @param scopeKey - Scope identifier to check
+ * @returns true if factories are registered
+ */
+export function hasScope(scopeKey: string): boolean {
+  return scopeRegistry.has(scopeKey);
+}
+
+/**
+ * Gets all registered scope keys (for debugging/testing)
+ *
+ * @returns Array of registered scope keys
+ */
+export function getRegisteredScopes(): string[] {
+  return Array.from(scopeRegistry.keys());
+}
+
+/**
+ * Clears all registered scopes (for testing only)
+ * @internal
+ */
+export function clearRegistry(): void {
+  scopeRegistry.clear();
+}

package/src/sdk/sdk-registry.ts

@@ -0,0 +1,99 @@
+/**
+ * SDK Class Registry
+ *
+ * Provides a registry pattern for jurisdiction-specific SDK classes.
+ * Each jurisdiction can register its own SDK class that extends ComplianceSDKImpl
+ * and adds jurisdiction-specific resources.
+ *
+ * @example
+ * ```typescript
+ * // In sdk/mex/index.ts
+ * import { registerSDKClass } from '../sdk-registry';
+ * import { MexicoComplianceSDKImpl } from './ComplianceSDK';
+ *
+ * registerSDKClass('MX', MexicoComplianceSDKImpl);
+ *
+ * // Now `new ComplianceSDK({ jurisdiction: "MX" })` returns MexicoComplianceSDKImpl
+ * ```
+ */
+
+import type { SDKScope } from "./types";
+import { getScopeKey } from "./resource-registry";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type SDKClassConstructor = new (options: any) => any;
+
+const sdkClassRegistry = new Map<string, SDKClassConstructor>();
+
+/**
+ * Registers an SDK class for a specific scope.
+ *
+ * @param scopeKey - Scope identifier (e.g., "MX", "MX:AVI", "US")
+ * @param SDKClass - SDK class constructor
+ */
+export function registerSDKClass(
+  scopeKey: string,
+  SDKClass: SDKClassConstructor
+): void {
+  if (sdkClassRegistry.has(scopeKey)) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[SDK Registry] Overwriting existing SDK class for scope: ${scopeKey}`
+    );
+  }
+  sdkClassRegistry.set(scopeKey, SDKClass);
+}
+
+/**
+ * Gets the SDK class for a specific scope.
+ *
+ * Looks up with fallback:
+ * 1. Exact scope match (e.g., "MX:AVI")
+ * 2. Jurisdiction-only match (e.g., "MX")
+ * 3. Returns undefined (use base ComplianceSDKImpl)
+ *
+ * @param scope - SDK scope configuration
+ * @returns SDK class constructor or undefined if no specific class registered
+ */
+export function getSDKClass(scope: SDKScope): SDKClassConstructor | undefined {
+  const scopeKey = getScopeKey(scope);
+
+  // Try exact match first (e.g., "MX:AVI")
+  let cls = sdkClassRegistry.get(scopeKey);
+  if (cls) return cls;
+
+  // Try jurisdiction only (e.g., "MX") if scope has activity
+  if (scope.jurisdiction && scopeKey.includes(":")) {
+    cls = sdkClassRegistry.get(scope.jurisdiction);
+    if (cls) return cls;
+  }
+
+  return undefined;
+}
+
+/**
+ * Checks if an SDK class is registered for a scope
+ *
+ * @param scopeKey - Scope identifier to check
+ * @returns true if an SDK class is registered
+ */
+export function hasSDKClass(scopeKey: string): boolean {
+  return sdkClassRegistry.has(scopeKey);
+}
+
+/**
+ * Gets all registered SDK class scope keys (for debugging/testing)
+ *
+ * @returns Array of registered scope keys
+ */
+export function getRegisteredSDKClasses(): string[] {
+  return Array.from(sdkClassRegistry.keys());
+}
+
+/**
+ * Clears all registered SDK classes (for testing only)
+ * @internal
+ */
+export function clearSDKRegistry(): void {
+  sdkClassRegistry.clear();
+}