@artu-ai/compliance-sdk 0.0.5 → 0.2.0

package/src/sdk/ComplianceSDK.ts

@@ -0,0 +1,797 @@
+/**
+ * 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 { validateEnvironment, resolveBaseUrl } 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>;
+
+  // ===========================
+  // 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,
+      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."
+        );
+      }
+    }
+
+    // Validate environment
+    const validatedEnvironment = validateEnvironment(environment);
+    this._environment = validatedEnvironment;
+    this._apiVersion = apiVersion;
+
+    // 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: validatedEnvironment,
+      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: validatedEnvironment as SDKEnvironment,
+            apiVersion,
+            timeout,
+          }
+        : {
+            mode: authMode,
+            credentials: resolvedCredentials,
+            headers: resolvedHeaders,
+            baseUrl: resolvedBaseUrl,
+            environment: validatedEnvironment as SDKEnvironment,
+            apiVersion,
+            timeout,
+          };
+
+    this.trpc = createAPIClient(trpcConfig);
+
+    // Initialize resource managers using registry
+    const resourceConfig = {
+      trpc: this.trpc,
+      scope: this._scope,
+      environment: validatedEnvironment,
+    };
+    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,
+    };
+
+    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>;