@artu-ai/compliance-sdk 0.4.1 → 0.4.3

package/src/sdk/ComplianceSDK.ts

@@ -1,812 +0,0 @@
-/**
- * ComplianceSDK - Main SDK entry point
- *
- * This class provides access to all compliance API resources.
- * It initializes the tRPC client and all resource managers.
- *
- * The SDK can be scoped to a specific jurisdiction and/or actividadVulnerable,
- * which automatically applies to all resource operations.
- *
- * @example
- * ```typescript
- * // Unscoped SDK - works with any jurisdiction
- * const sdk = new ComplianceSDK({
- *   apiKey: process.env.COMPLIANCE_API_KEY!,
- *   environment: "test",
- * });
- *
- * // Mexico-scoped SDK
- * const mexSDK = new ComplianceSDK({
- *   apiKey: process.env.COMPLIANCE_API_KEY!,
- *   environment: "test",
- *   jurisdiction: "MX",
- * });
- *
- * // Mexico AVI-scoped SDK
- * const aviSDK = new ComplianceSDK({
- *   apiKey: process.env.COMPLIANCE_API_KEY!,
- *   environment: "test",
- *   jurisdiction: "MX",
- *   actividadVulnerable: CodigoActividad.AVI,
- * });
- *
- * // When scoped, resources automatically use the jurisdiction/actividadVulnerable
- * const client = await aviSDK.clients.create({
- *   type: ClientType.Person,
- *   name: "Juan García",
- *   // primaryJurisdiction defaults to "MX"
- *   // jurisdictions.MX.actividadVulnerable.AVI is auto-initialized
- * });
- * ```
- */
-
-import { Jurisdiction, CodigoActividad } from "@artu-ai/shared";
-import {
-  createAPIClient,
-  type TRPCClient,
-  type APIVersion,
-  type SDKEnvironment,
-  LATEST_API_VERSION,
-  DEFAULT_TIMEOUT,
-} from "../utils/trpc-client";
-import {
-  resolveEnvironment,
-  resolveBaseUrl,
-  resolveOrganizationId,
-} from "../utils/environment";
-import {
-  type SDKScope,
-  type Environment,
-  type BaseComplianceSDK,
-  type OtherJurisdictionSDKOptions,
-  type ComplianceAuthMode,
-  type FetchCredentials,
-  isMexicoScope,
-  buildScope,
-} from "./types";
-import { getResourceFactories } from "./resource-registry";
-import { getSDKClass } from "./sdk-registry";
-import { type UnscopedSDKOptions } from "./base";
-// Import Mexico types from type files directly to avoid circular dependency through barrel
-import {
-  type ComplianceSDKOptionsMexico,
-  type MexicoSDKOptions,
-  type MexicoComplianceSDK,
-} from "./mex/types";
-import {
-  type AVISDKOptions,
-  type AVIComplianceSDK,
-} from "./mex/actividad-vulnerable/avi/types";
-import {
-  type JYSSDKOptions,
-  type JYSComplianceSDK,
-} from "./mex/actividad-vulnerable/jys/types";
-import {
-  type TSCSDKOptions,
-  type TSCComplianceSDK,
-} from "./mex/actividad-vulnerable/tsc/types";
-import {
-  fetchSession,
-  type SDKSessionOptions,
-  type SDKSessionOptionsWithReturnTo,
-  type SessionResult,
-  type SessionResultWithRedirect,
-  type SessionResultWithoutRedirect,
-} from "../utils/session";
-
-// Re-export base options type for sub-exports
-export type { ComplianceSDKOptionsBase } from "./types";
-
-// Resources
-import {
-  type ClientsResource,
-  type TransactionsResource,
-  type ReportsResource,
-  BankAccountsResource,
-  AddressesResource,
-  ContactMethodsResource,
-  DocumentsResource,
-} from "../resources";
-
-// ===========================
-// Re-exports
-// ===========================
-
-// Re-export SDKScope for external use
-export type { SDKScope };
-
-// Re-export Mexico SDK types for convenience
-export type {
-  ComplianceSDKOptionsMexico,
-  MexicoSDKOptions,
-  AVISDKOptions,
-  JYSSDKOptions,
-  TSCSDKOptions,
-  MexicoComplianceSDK,
-  AVIComplianceSDK,
-  JYSComplianceSDK,
-  TSCComplianceSDK,
-};
-
-// ===========================
-// SDK Options Types
-// ===========================
-
-/**
- * SDK configuration options.
- *
- * Use `actividadVulnerable` only when `jurisdiction` is `Jurisdiction.Mexico`.
- */
-export type ComplianceSDKOptions =
-  | UnscopedSDKOptions
-  | ComplianceSDKOptionsMexico;
-
-// ===========================
-// Typed SDK Interfaces
-// ===========================
-
-/**
- * Unscoped SDK - uses base resource types
- */
-export interface UnscopedComplianceSDK extends BaseComplianceSDK {
-  // Core resources (base types)
-  readonly clients: ClientsResource;
-  readonly transactions: TransactionsResource;
-  readonly reports: ReportsResource;
-  readonly bankAccounts: BankAccountsResource;
-
-  // Supporting resources (base types)
-  readonly addresses: AddressesResource;
-  readonly contactMethods: ContactMethodsResource;
-  readonly documents: DocumentsResource;
-}
-
-// ===========================
-// ComplianceSDK Class
-// ===========================
-
-/**
- * Main entry point for the Compliance SDK.
- *
- * Provides access to all API resources:
- * - `clients` - Client management (individuals, companies, trusts)
- * - `transactions` - Transaction management
- * - `addresses` - Address management
- * - `contactMethods` - Contact method management
- * - `bankAccounts` - Bank account management
- * - `documents` - Document upload and management
- * - `reports` - Regulatory report generation and submission
- *
- * ## Scoping
- *
- * The SDK can be scoped to a specific jurisdiction and/or actividadVulnerable:
- *
- * ```typescript
- * // Unscoped - generic SDK
- * const sdk = new ComplianceSDK({ apiKey, environment: "test" });
- *
- * // Scoped to Mexico
- * const mexSDK = new ComplianceSDK({
- *   apiKey,
- *   environment: "test",
- *   jurisdiction: Jurisdiction.Mexico,
- * });
- *
- * // Scoped to Mexico AVI actividadVulnerable
- * const aviSDK = new ComplianceSDK({
- *   apiKey,
- *   environment: "test",
- *   jurisdiction: Jurisdiction.Mexico,
- *   actividadVulnerable: CodigoActividad.AVI,
- * });
- * ```
- *
- * When scoped:
- * - Create operations default to the specified jurisdiction/actividadVulnerable
- * - List operations filter by the specified jurisdiction/actividadVulnerable
- * - Models returned are the appropriate type for the scope
- *
- * @example
- * ```typescript
- * import { ComplianceSDK, ClientType, Jurisdiction, CodigoActividad } from "@artu/compliance-sdk";
- *
- * const sdk = new ComplianceSDK({
- *   apiKey: process.env.COMPLIANCE_API_KEY!,
- *   environment: "test",
- *   jurisdiction: Jurisdiction.Mexico,
- *   actividadVulnerable: CodigoActividad.AVI,
- * });
- *
- * // Check scope
- * console.log(sdk.jurisdiction);          // "MX"
- * console.log(sdk.actividadVulnerable);   // "AVI"
- * console.log(sdk.isMexico);              // true
- *
- * // Create a client - jurisdiction/actividadVulnerable are auto-applied
- * const client = await sdk.clients.create({
- *   type: ClientType.Person,
- *   name: "Juan García",
- * });
- * ```
- */
-export class ComplianceSDKImpl {
-  // ===========================
-  // Protected Properties (accessible by subclasses)
-  // ===========================
-
-  /** tRPC client for API communication */
-  protected readonly trpc!: TRPCClient;
-
-  /** Current environment */
-  protected readonly _environment!: Environment;
-
-  /** Current API version */
-  protected readonly _apiVersion!: APIVersion;
-
-  /** SDK scope (jurisdiction and actividadVulnerable) */
-  protected readonly _scope!: SDKScope;
-
-  /** Resolved base URL */
-  protected readonly _baseUrl!: string;
-
-  /** Auth mode */
-  protected readonly _authMode!: ComplianceAuthMode;
-
-  /** Credentials policy (cookie mode) */
-  protected readonly _credentials?: FetchCredentials;
-
-  /** Custom headers (cookie mode, for server-side cookie forwarding) */
-  protected readonly _headers?: Record<string, string>;
-
-  /** Organization ID for session login (cookie mode) */
-  protected readonly _organizationId?: string;
-
-  // ===========================
-  // Resource Managers
-  // ===========================
-
-  /**
-   * Clients resource manager.
-   *
-   * Provides CRUD operations for clients (individuals, companies, trusts).
-   * When SDK is scoped, creates and lists are automatically scoped.
-   *
-   * @example
-   * ```typescript
-   * // Create a client (uses SDK scope for jurisdiction/activity)
-   * const client = await sdk.clients.create({
-   *   type: ClientType.Person,
-   *   name: "Juan García",
-   * });
-   *
-   * // List clients (filtered by SDK scope)
-   * const clients = await sdk.clients.list();
-   *
-   * // Iterate through all clients in scope
-   * for await (const client of sdk.clients.iterate()) {
-   *   console.log(client.name);
-   * }
-   * ```
-   */
-  public readonly clients!: ClientsResource;
-
-  /**
-   * Transactions resource manager.
-   *
-   * Provides CRUD operations for transactions and client linking.
-   * When SDK is scoped, creates and lists are automatically scoped.
-   *
-   * @example
-   * ```typescript
-   * // Create a transaction (uses SDK scope)
-   * const txn = await sdk.transactions.create({
-   *   amount: 50000,
-   *   currency: Currency.MXN,
-   * });
-   *
-   * // Link a client to transaction
-   * await sdk.transactions.linkClient(txn.id, clientId, "originator");
-   * ```
-   */
-  public readonly transactions!: TransactionsResource;
-
-  /**
-   * Addresses resource manager.
-   *
-   * Provides CRUD operations for client addresses.
-   *
-   * @example
-   * ```typescript
-   * const address = await sdk.addresses.create({
-   *   clientId,
-   *   type: AddressType.Home,
-   *   street: "Av. Reforma 222",
-   *   city: "México",
-   *   country: Country.Mexico,
-   * });
-   * ```
-   */
-  public readonly addresses!: AddressesResource;
-
-  /**
-   * Contact methods resource manager.
-   *
-   * Provides CRUD operations for client contact methods (email, phone).
-   *
-   * @example
-   * ```typescript
-   * const contact = await sdk.contactMethods.create({
-   *   clientId,
-   *   type: ContactMethodType.Email,
-   *   value: "juan@example.com",
-   * });
-   * ```
-   */
-  public readonly contactMethods!: ContactMethodsResource;
-
-  /**
-   * Bank accounts resource manager.
-   *
-   * Provides CRUD operations for client bank accounts.
-   *
-   * @example
-   * ```typescript
-   * const account = await sdk.bankAccounts.create({
-   *   clientId,
-   *   type: BankAccountType.Checking,
-   *   bankName: "BBVA",
-   * });
-   * ```
-   */
-  public readonly bankAccounts!: BankAccountsResource;
-
-  /**
-   * Documents resource manager.
-   *
-   * Provides upload, download, and management for client documents.
-   *
-   * @example
-   * ```typescript
-   * const doc = await sdk.documents.upload({
-   *   clientId,
-   *   category: DocumentCategory.Identification,
-   *   type: MexDocumentType.INE,
-   *   file: buffer,
-   *   filename: "ine.pdf",
-   * });
-   * ```
-   */
-  public readonly documents!: DocumentsResource;
-
-  /**
-   * Reports resource manager.
-   *
-   * Provides CRUD operations for regulatory reports.
-   * When SDK is scoped, creates and lists are automatically scoped.
-   *
-   * @example
-   * ```typescript
-   * // Create a report (uses SDK scope for jurisdiction/activity)
-   * const report = await sdk.reports.create({
-   *   // mesReportado is required for AVI scope
-   *   jurisdictions: {
-   *     MX: {
-   *       actividadVulnerable: {
-   *         AVI: { mesReportado: "202403" },
-   *       },
-   *     },
-   *   },
-   * });
-   *
-   * // Validate and generate
-   * const validation = await sdk.reports.validateReport(report.id);
-   * if (validation.valid) {
-   *   const result = await sdk.reports.generate(report.id);
-   * }
-   * ```
-   */
-  public readonly reports!: ReportsResource;
-
-  // ===========================
-  // Constructor
-  // ===========================
-
-  constructor(options: ComplianceSDKOptions) {
-    const {
-      environment,
-      baseUrl,
-      organizationId,
-      apiVersion = LATEST_API_VERSION,
-      timeout = DEFAULT_TIMEOUT,
-      jurisdiction,
-      mode,
-      ...authOptions
-    } = options;
-
-    // Extract actividadVulnerable only for Mexico options
-    const actividadVulnerable =
-      "actividadVulnerable" in options
-        ? options.actividadVulnerable
-        : undefined;
-
-    // Build scope early for SDK class dispatch
-    const scope = buildScope(jurisdiction, actividadVulnerable);
-
-    // === SDK Class Dispatch ===
-    // If we're directly constructing ComplianceSDKImpl (not via super() from subclass),
-    // check if a jurisdiction-specific SDK class is registered and return that instead.
-    if (new.target === ComplianceSDKImpl) {
-      const SDKClass = getSDKClass(scope);
-      if (SDKClass) {
-        // Return instance of jurisdiction-specific SDK
-        return new SDKClass(options) as this;
-      }
-    }
-
-    // === Normal base SDK initialization ===
-
-    const authMode: ComplianceAuthMode = mode ?? "apiKey";
-
-    const resolvedApiKey =
-      authMode === "apiKey"
-        ? "apiKey" in authOptions
-          ? authOptions.apiKey
-          : process.env.ARTU_API_KEY
-        : undefined;
-
-    const resolvedCredentials: FetchCredentials | undefined =
-      authMode === "cookie"
-        ? "credentials" in authOptions
-          ? authOptions.credentials
-          : "include"
-        : undefined;
-
-    const resolvedHeaders: Record<string, string> | undefined =
-      authMode === "cookie" && "headers" in authOptions
-        ? authOptions.headers
-        : undefined;
-
-    // Validate API key when using apiKey auth mode
-    if (authMode === "apiKey") {
-      if (!resolvedApiKey || typeof resolvedApiKey !== "string") {
-        throw new Error(
-          "API key is required. Provide it via auth.apiKey, options.apiKey, or set the ARTU_API_KEY environment variable."
-        );
-      }
-    }
-
-    // Resolve environment (from options or env var, defaults to "test")
-    const resolvedEnv = resolveEnvironment(environment);
-    this._environment = resolvedEnv;
-    this._apiVersion = apiVersion;
-
-    // Resolve organization ID (from options or env var)
-    this._organizationId = organizationId ?? resolveOrganizationId();
-
-    // Validate actividadVulnerable requires Mexico jurisdiction
-    if (actividadVulnerable && jurisdiction !== Jurisdiction.Mexico) {
-      throw new Error(
-        `actividadVulnerable can only be specified when jurisdiction is Mexico. ` +
-          `Got jurisdiction: ${jurisdiction}`
-      );
-    }
-
-    // Resolve base URL
-    const resolvedBaseUrl = resolveBaseUrl({
-      environment: resolvedEnv,
-      baseUrl,
-    });
-
-    // Store scope and base config
-    this._scope = scope;
-    this._baseUrl = resolvedBaseUrl;
-    this._authMode = authMode;
-    this._credentials = resolvedCredentials;
-    this._headers = resolvedHeaders;
-
-    // Create tRPC client
-    const trpcConfig =
-      authMode === "apiKey"
-        ? {
-            mode: authMode,
-            apiKey: resolvedApiKey as string,
-            baseUrl: resolvedBaseUrl,
-            environment: resolvedEnv as SDKEnvironment,
-            apiVersion,
-            timeout,
-            organizationId: this._organizationId,
-          }
-        : {
-            mode: authMode,
-            credentials: resolvedCredentials,
-            headers: resolvedHeaders,
-            baseUrl: resolvedBaseUrl,
-            environment: resolvedEnv as SDKEnvironment,
-            apiVersion,
-            timeout,
-            organizationId: this._organizationId,
-          };
-
-    this.trpc = createAPIClient(trpcConfig);
-
-    // Initialize resource managers using registry
-    const resourceConfig = {
-      trpc: this.trpc,
-      scope: this._scope,
-      environment: resolvedEnv,
-    };
-    const factories = getResourceFactories(this._scope);
-
-    // Create scoped resources from registry
-    this.clients = factories.clients(resourceConfig);
-    this.transactions = factories.transactions(resourceConfig);
-    this.reports = factories.reports(resourceConfig);
-
-    // Bank accounts and addresses can be scoped or use base
-    this.bankAccounts = factories.bankAccounts
-      ? factories.bankAccounts(resourceConfig)
-      : new BankAccountsResource(resourceConfig);
-    this.addresses = factories.addresses
-      ? factories.addresses(resourceConfig)
-      : new AddressesResource(resourceConfig);
-
-    // Supporting resources (not scoped by jurisdiction)
-    this.contactMethods = new ContactMethodsResource(resourceConfig);
-    this.documents = new DocumentsResource(resourceConfig);
-  }
-
-  // ===========================
-  // Public Getters - Environment
-  // ===========================
-
-  /**
-   * Current environment ("test" or "live").
-   *
-   * @example
-   * ```typescript
-   * console.log(`Running in ${sdk.environment} mode`);
-   * ```
-   */
-  get environment(): Environment {
-    return this._environment;
-  }
-
-  /**
-   * Current API version.
-   *
-   * @example
-   * ```typescript
-   * console.log(`Using API version ${sdk.apiVersion}`);
-   * ```
-   */
-  get apiVersion(): APIVersion {
-    return this._apiVersion;
-  }
-
-  /**
-   * Whether SDK is running in test environment.
-   *
-   * @example
-   * ```typescript
-   * if (sdk.isTest) {
-   *   console.log("Running in test mode - no real data affected");
-   * }
-   * ```
-   */
-  get isTest(): boolean {
-    return this._environment === "test";
-  }
-
-  /**
-   * Whether SDK is running in live environment.
-   *
-   * @example
-   * ```typescript
-   * if (sdk.isLive) {
-   *   console.log("CAUTION: Live environment - real data will be affected");
-   * }
-   * ```
-   */
-  get isLive(): boolean {
-    return this._environment === "live";
-  }
-
-  // ===========================
-  // Public Getters - Scope
-  // ===========================
-
-  /**
-   * Current jurisdiction scope, or undefined if unscoped.
-   *
-   * @example
-   * ```typescript
-   * if (sdk.jurisdiction === Jurisdiction.Mexico) {
-   *   console.log("SDK is scoped to Mexico");
-   * }
-   * ```
-   */
-  get jurisdiction(): Jurisdiction | undefined {
-    return this._scope.jurisdiction;
-  }
-
-  /**
-   * Current actividadVulnerable scope, or undefined if unscoped.
-   * Only available when jurisdiction is Mexico.
-   *
-   * @example
-   * ```typescript
-   * if (sdk.actividadVulnerable === CodigoActividad.AVI) {
-   *   console.log("SDK is scoped to Activos Virtuales");
-   * }
-   * ```
-   */
-  get actividadVulnerable(): CodigoActividad | undefined {
-    return isMexicoScope(this._scope)
-      ? this._scope.actividadVulnerable
-      : undefined;
-  }
-
-  /**
-   * The complete scope configuration.
-   *
-   * @example
-   * ```typescript
-   * console.log(sdk.scope); // { jurisdiction: "MX", actividadVulnerable: "AVI" }
-   * ```
-   */
-  get scope(): Readonly<SDKScope> {
-    return { ...this._scope };
-  }
-
-  /**
-   * Whether SDK is scoped to any jurisdiction.
-   */
-  get isScoped(): boolean {
-    return this._scope.jurisdiction !== undefined;
-  }
-
-  /**
-   * Whether SDK is scoped to Mexico jurisdiction.
-   */
-  get isMexico(): boolean {
-    return this._scope.jurisdiction === Jurisdiction.Mexico;
-  }
-
-  /**
-   * Whether SDK is scoped to United States jurisdiction.
-   */
-  get isUnitedStates(): boolean {
-    return this._scope.jurisdiction === Jurisdiction.UnitedStates;
-  }
-
-  /**
-   * Whether SDK is scoped to an Actividad Vulnerable activity.
-   */
-  get isActividadVulnerable(): boolean {
-    return (
-      isMexicoScope(this._scope) &&
-      this._scope.actividadVulnerable !== undefined
-    );
-  }
-
-  /**
-   * Fetches current session info from the API (/auth/me).
-   * Only available in cookie auth mode.
-   *
-   * @example Basic usage (session can be null)
-   * ```typescript
-   * const result = await sdk.session();
-   * if (result.isAuthenticated) {
-   *   console.log("User:", result.session.userId);
-   * }
-   * ```
-   *
-   * @example With returnTo (strongly typed - redirectUrl present when not authenticated)
-   * ```typescript
-   * // In Next.js Server Component
-   * import { redirect, headers } from "next/navigation";
-   *
-   * const h = await headers();
-   * const host = h.get("host") ?? "localhost:3000";
-   * const proto = h.get("x-forwarded-proto") ?? "http";
-   * const returnTo = `${proto}://${host}/env/test/dashboard`;
-   *
-   * const result = await sdk.session({ returnTo });
-   *
-   * if (result.redirectUrl) {
-   *   redirect(result.redirectUrl);
-   * }
-   *
-   * // result.session is guaranteed here (TypeScript knows it's not null)
-   * console.log("User:", result.session.userId);
-   * ```
-   */
-  async session(
-    options: SDKSessionOptionsWithReturnTo
-  ): Promise<SessionResultWithRedirect>;
-  async session(
-    options?: SDKSessionOptions
-  ): Promise<SessionResultWithoutRedirect>;
-  async session(options?: SDKSessionOptions): Promise<SessionResult> {
-    if (this._authMode !== "cookie") {
-      throw new Error(
-        "session() is only available when using cookie auth mode."
-      );
-    }
-
-    const baseOptions = {
-      baseUrl: this._baseUrl,
-      environment: this._environment,
-      credentials: this._credentials ?? "include",
-      headers: this._headers,
-      // Use provided organizationId or fall back to SDK-level config
-      organizationId: options?.organizationId ?? this._organizationId,
-    };
-
-    if (options?.returnTo) {
-      return fetchSession({
-        ...baseOptions,
-        returnTo: options.returnTo,
-      });
-    }
-
-    return fetchSession(baseOptions);
-  }
-}
-
-// ===========================
-// Constructor Interface
-// ===========================
-
-/**
- * ComplianceSDK constructor with overloaded signatures.
- *
- * This interface enables `new ComplianceSDK(options)` to return the correct
- * typed SDK interface based on the jurisdiction and actividadVulnerable options.
- *
- * @example
- * ```typescript
- * // Unscoped SDK - base types
- * const sdk = new ComplianceSDK({
- *   apiKey: "...",
- *   environment: "test",
- * });
- * // sdk.clients is ClientsResource
- *
- * // Mexico-scoped SDK
- * const mexSdk = new ComplianceSDK({
- *   apiKey: "...",
- *   environment: "test",
- *   jurisdiction: "MX",
- * });
- * // mexSdk.clients is MexClientsResource
- *
- * // AVI-scoped SDK
- * const aviSdk = new ComplianceSDK({
- *   apiKey: "...",
- *   environment: "test",
- *   jurisdiction: "MX",
- *   actividadVulnerable: "AVI",
- * });
- * // aviSdk.clients is AVIClientsResource
- * // aviSdk.clients.create() accepts CreateAVIClientInput
- * ```
- */
-export interface ComplianceSDKConstructor {
-  new (options: AVISDKOptions): AVIComplianceSDK;
-  new (options: JYSSDKOptions): JYSComplianceSDK;
-  new (options: TSCSDKOptions): TSCComplianceSDK;
-  new (options: MexicoSDKOptions): MexicoComplianceSDK;
-  new (
-    options: OtherJurisdictionSDKOptions | UnscopedSDKOptions
-  ): UnscopedComplianceSDK;
-  new (options: ComplianceSDKOptions): ComplianceSDK;
-}
-
-// Cast the class to use the overloaded constructor interface
-// This enables proper type inference when using `new ComplianceSDK(options)`
-export const ComplianceSDK: ComplianceSDKConstructor =
-  ComplianceSDKImpl as ComplianceSDKConstructor;
-
-// Also export as a type for those who need it
-export type ComplianceSDK = InstanceType<typeof ComplianceSDKImpl>;