@artu-ai/compliance-sdk 0.0.5 → 0.2.0

package/src/namespaces/mexico/index.ts

@@ -0,0 +1,325 @@
+/**
+ * Mexico namespace
+ *
+ * All Mexico-specific functionality organized in one place:
+ * - Enums (ActividadEconomica, GiroMercantil, DocumentType)
+ * - Validators (RFC, CURP, CLABE)
+ * - Models (MexClient, MexTransaction, etc.)
+ * - Resources (MexClientsResource, etc.)
+ * - TypeGuards (isMexClient, etc.)
+ * - Types (MexJurisdictionData, etc.)
+ * - ActividadVulnerable (AVI, JYS, TSC subnamespaces)
+ *
+ * @example
+ * ```ts
+ * import { Mexico } from "@artu/compliance-sdk";
+ *
+ * // General enums
+ * Mexico.Enums.ActividadEconomica.Comercio
+ * Mexico.Enums.DocumentType.INE
+ *
+ * // Validators
+ * Mexico.Validators.Rfc.validate("GOAP820528H00")
+ *
+ * // Models
+ * Mexico.Models.Client  // MexClient
+ *
+ * // Actividad Vulnerable (nested)
+ * Mexico.ActividadVulnerable.Enums.CodigoActividad.AVI
+ * Mexico.ActividadVulnerable.AVI.Enums.TipoOperacion.Buy
+ * Mexico.ActividadVulnerable.AVI.Models.Client  // MexAVIClient
+ * ```
+ */
+
+import {
+  ActividadEconomica,
+  ActividadesEconomicas,
+  GiroMercantil,
+  GirosMercantiles,
+  MexDocumentType,
+  MexDocumentTypes,
+  AddressProofServiceType,
+  AddressProofServiceTypes,
+  MexEntityType,
+  MexEntityTypes,
+  PoderType,
+  PoderTypes,
+  Rfc,
+  Curp,
+  Clabe,
+} from "@artu-ai/shared";
+
+import type {
+  MexJurisdictionData,
+  MexPersonJurisdictionData,
+  MexCompanyJurisdictionData,
+  MexTrustJurisdictionData,
+  ActividadVulnerableClientData,
+  MexBankAccountData as MexBankAccountDataType,
+  MexDocument as MexDocumentSchema,
+  CreateMexDocumentInput,
+  UpdateMexDocumentInput,
+  // Document field types
+  IneFrontFields,
+  IneBackFields,
+  CurpDocumentFields,
+  RfcConstanciaFields,
+  AddressProofFields,
+  ActaConstitutivaFields,
+  PoderNotarialFields,
+  // Create input types per document type
+  CreateMexIneFrontInput,
+  CreateMexIneBackInput,
+  CreateMexPassportInput,
+  CreateMexCurpInput,
+  CreateMexRfcConstanciaInput,
+  CreateMexAddressProofInput,
+  CreateMexActaConstitutivaInput,
+  CreateMexPoderNotarialInput,
+  // Update input types per document type
+  UpdateMexIneFrontInput,
+  UpdateMexIneBackInput,
+  UpdateMexPassportInput,
+  UpdateMexCurpInput,
+  UpdateMexRfcConstanciaInput,
+  UpdateMexAddressProofInput,
+  UpdateMexActaConstitutivaInput,
+  UpdateMexPoderNotarialInput,
+} from "@artu-ai/shared";
+
+import {
+  MexClient,
+  MexTransaction,
+  MexBankAccount,
+  MexAddress,
+  MexReport,
+  MexReportItem,
+  // Document models
+  MexDocument,
+  MexIneFrontDocument,
+  MexIneBackDocument,
+  MexPassportDocument,
+  MexCurpDocument,
+  MexRfcConstanciaDocument,
+  MexAddressProofDocument,
+  MexActaConstitutivaDocument,
+  MexPoderNotarialDocument,
+  // Type guards
+  isMexClient,
+  isMexTransaction,
+  isMexBankAccount,
+  isMexAddress,
+  isMexReport,
+  isMexReportItem,
+  isMexDocument,
+  isMexIneFront,
+  isMexIneBack,
+  isMexPassport,
+  isMexCurp,
+  isMexRfcConstancia,
+  isMexAddressProof,
+  isMexActaConstitutiva,
+  isMexPoderNotarial,
+} from "../../models";
+
+import {
+  MexClientsResource,
+  MexTransactionsResource,
+  MexBankAccountsResource,
+  MexReportsResource,
+} from "../../resources";
+
+// Actividad Vulnerable namespace
+import { ActividadVulnerable, AVI, JYS, TSC } from "./actividad-vulnerable";
+
+// Re-export for convenience
+export { ActividadVulnerable, AVI, JYS, TSC } from "./actividad-vulnerable";
+
+// ===========================
+// Enums
+// ===========================
+
+export const Enums = {
+  // Enum values
+  ActividadEconomica,
+  GiroMercantil,
+  DocumentType: MexDocumentType,
+  AddressProofServiceType,
+  EntityType: MexEntityType,
+  PoderType,
+  // Enum utilities (with .enum, .map, .codes, .options, .schema())
+  ActividadesEconomicas,
+  GirosMercantiles,
+  DocumentTypes: MexDocumentTypes,
+  AddressProofServiceTypes,
+  EntityTypes: MexEntityTypes,
+  PoderTypes,
+} as const;
+
+// ===========================
+// Validators
+// ===========================
+
+export const Validators = {
+  Rfc,
+  Curp,
+  Clabe,
+} as const;
+
+// ===========================
+// Models
+// ===========================
+
+export const Models = {
+  Client: MexClient,
+  Transaction: MexTransaction,
+  BankAccount: MexBankAccount,
+  Address: MexAddress,
+  Report: MexReport,
+  ReportItem: MexReportItem,
+  // Document models
+  Document: MexDocument,
+  IneFrontDocument: MexIneFrontDocument,
+  IneBackDocument: MexIneBackDocument,
+  PassportDocument: MexPassportDocument,
+  CurpDocument: MexCurpDocument,
+  RfcConstanciaDocument: MexRfcConstanciaDocument,
+  AddressProofDocument: MexAddressProofDocument,
+  ActaConstitutivaDocument: MexActaConstitutivaDocument,
+  PoderNotarialDocument: MexPoderNotarialDocument,
+} as const;
+
+// ===========================
+// Resources
+// ===========================
+
+export const Resources = {
+  Clients: MexClientsResource,
+  Transactions: MexTransactionsResource,
+  BankAccounts: MexBankAccountsResource,
+  Reports: MexReportsResource,
+} as const;
+
+// ===========================
+// TypeGuards
+// ===========================
+
+export const TypeGuards = {
+  isClient: isMexClient,
+  isTransaction: isMexTransaction,
+  isBankAccount: isMexBankAccount,
+  isAddress: isMexAddress,
+  isReport: isMexReport,
+  isReportItem: isMexReportItem,
+  // Document guards
+  isDocument: isMexDocument,
+  isIneFront: isMexIneFront,
+  isIneBack: isMexIneBack,
+  isPassport: isMexPassport,
+  isCurp: isMexCurp,
+  isRfcConstancia: isMexRfcConstancia,
+  isAddressProof: isMexAddressProof,
+  isActaConstitutiva: isMexActaConstitutiva,
+  isPoderNotarial: isMexPoderNotarial,
+} as const;
+
+// ===========================
+// Types
+// ===========================
+
+export interface Types {
+  JurisdictionData: MexJurisdictionData;
+  PersonJurisdictionData: MexPersonJurisdictionData;
+  CompanyJurisdictionData: MexCompanyJurisdictionData;
+  TrustJurisdictionData: MexTrustJurisdictionData;
+  ActividadVulnerableClientData: ActividadVulnerableClientData;
+  BankAccountData: MexBankAccountDataType;
+  Document: MexDocumentSchema;
+  CreateDocumentInput: CreateMexDocumentInput;
+  UpdateDocumentInput: UpdateMexDocumentInput;
+  // Document field types
+  IneFrontFields: IneFrontFields;
+  IneBackFields: IneBackFields;
+  CurpDocumentFields: CurpDocumentFields;
+  RfcConstanciaFields: RfcConstanciaFields;
+  AddressProofFields: AddressProofFields;
+  ActaConstitutivaFields: ActaConstitutivaFields;
+  PoderNotarialFields: PoderNotarialFields;
+}
+
+// Re-export types for direct usage
+export type {
+  MexJurisdictionData,
+  MexPersonJurisdictionData,
+  MexCompanyJurisdictionData,
+  MexTrustJurisdictionData,
+  ActividadVulnerableClientData,
+  MexBankAccountDataType as MexBankAccountData,
+  MexDocumentSchema as MexDocument,
+  CreateMexDocumentInput,
+  UpdateMexDocumentInput,
+  // Document field types
+  IneFrontFields,
+  IneBackFields,
+  CurpDocumentFields,
+  RfcConstanciaFields,
+  AddressProofFields,
+  ActaConstitutivaFields,
+  PoderNotarialFields,
+  // Create input types per document type
+  CreateMexIneFrontInput,
+  CreateMexIneBackInput,
+  CreateMexPassportInput,
+  CreateMexCurpInput,
+  CreateMexRfcConstanciaInput,
+  CreateMexAddressProofInput,
+  CreateMexActaConstitutivaInput,
+  CreateMexPoderNotarialInput,
+  // Update input types per document type
+  UpdateMexIneFrontInput,
+  UpdateMexIneBackInput,
+  UpdateMexPassportInput,
+  UpdateMexCurpInput,
+  UpdateMexRfcConstanciaInput,
+  UpdateMexAddressProofInput,
+  UpdateMexActaConstitutivaInput,
+  UpdateMexPoderNotarialInput,
+};
+
+// ===========================
+// SDK Types
+// ===========================
+
+export type {
+  ComplianceSDKOptionsMexico,
+  MexicoSDKOptions,
+  MexicoComplianceSDK,
+  AVISDKOptions,
+  AVIComplianceSDK,
+  JYSSDKOptions,
+  JYSComplianceSDK,
+  TSCSDKOptions,
+  TSCComplianceSDK,
+} from "../../sdk/mex";
+
+// ===========================
+// Main Mexico Namespace
+// ===========================
+
+/**
+ * Mexico namespace - all Mexico-specific SDK functionality
+ */
+export const Mexico = {
+  Enums,
+  Validators,
+  Models,
+  Resources,
+  TypeGuards,
+  ActividadVulnerable,
+  // Shortcuts to activity namespaces
+  AVI,
+  JYS,
+  TSC,
+} as const;
+
+export default Mexico;

package/src/resources/addresses.ts

@@ -0,0 +1,387 @@
+/**
+ * Addresses Resource
+ *
+ * Manages physical and mailing addresses for clients.
+ */
+
+import { z } from "zod";
+import type {
+  CreateAddressInput,
+  UpdateAddressInput,
+  AddressFilter,
+  AddressType,
+  ListOptions,
+  PaginatedResponse,
+  AtomicBatchResult,
+  PartialBatchResult,
+  SyncItem,
+  SyncResult,
+} from "@artu-ai/shared";
+import {
+  createAddressInputSchema,
+  updateAddressInputSchema,
+  replaceSyncItemSchema,
+} from "@artu-ai/shared";
+import { BaseResource } from "./base";
+import { Address, type AddressData } from "../models/Address";
+import type { BatchOptions } from "./clients";
+
+// ===========================
+// AddressesResource
+// ===========================
+
+/**
+ * Resource for managing client addresses.
+ *
+ * @example
+ * ```typescript
+ * // Create an address for a client
+ * const address = await sdk.addresses.create({
+ *   clientId: "client_123",
+ *   type: "home",
+ *   street1: "Avenida Reforma 123",
+ *   city: "Ciudad de México",
+ *   state: "CDMX",
+ *   postalCode: "06600",
+ *   country: "MX",
+ *   isPrimary: true,
+ * });
+ *
+ * // List all addresses for a client
+ * const addresses = await sdk.addresses.listByClient("client_123");
+ * ```
+ */
+export class AddressesResource extends BaseResource<
+  Address,
+  CreateAddressInput,
+  UpdateAddressInput,
+  AddressFilter
+> {
+  // ─────────────────────────────────────────────────────────────────
+  // CRUD Operations
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Creates an address for a client
+   *
+   * @param data - Address data including clientId
+   * @returns The created Address
+   */
+  async create(data: CreateAddressInput): Promise<Address> {
+    const validated = this.validate(createAddressInputSchema, data);
+
+    const response = await this.execute(() =>
+      this.trpc.addresses.create.mutate(validated)
+    );
+    return this.instantiate(response);
+  }
+
+  /**
+   * Retrieves an address by ID
+   *
+   * @param id - The address ID
+   * @returns The Address
+   */
+  async retrieve(id: string): Promise<Address> {
+    const response = await this.execute(() =>
+      this.trpc.addresses.retrieve.query({ id })
+    );
+    return this.instantiate(response);
+  }
+
+  /**
+   * Retrieves an address by metadata key/value.
+   */
+  async retrieveByMetadata(key: string, value: string): Promise<Address> {
+    const response = await this.execute(() =>
+      this.trpc.addresses.retrieveByMetadata.query({ key, value })
+    );
+    return this.instantiate(response);
+  }
+
+  /**
+   * Retrieves an address by externalId
+   */
+  async retrieveByExternalId(externalId: string): Promise<Address> {
+    const response = await this.execute(() =>
+      this.trpc.addresses.retrieveByExternalId.query({ externalId })
+    );
+    return this.instantiate(response);
+  }
+
+  /**
+   * Updates an address
+   *
+   * @param id - The address ID
+   * @param data - Fields to update
+   * @returns The updated Address
+   */
+  async update(id: string, data: UpdateAddressInput): Promise<Address> {
+    const validated = this.validate(updateAddressInputSchema, data);
+
+    const response = await this.execute(() =>
+      this.trpc.addresses.update.mutate({ id, data: validated })
+    );
+    return this.instantiate(response);
+  }
+
+  /**
+   * Deletes an address
+   *
+   * @param id - The address ID
+   */
+  async delete(id: string): Promise<void> {
+    await this.execute(() => this.trpc.addresses.delete.mutate({ id }));
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // List Operations
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Lists addresses with optional filtering
+   *
+   * @param options - Filtering and pagination options
+   * @returns Paginated list of Addresses
+   */
+  async list(
+    options?: ListOptions<AddressFilter>
+  ): Promise<PaginatedResponse<Address>> {
+    const response = await this.execute(() =>
+      this.trpc.addresses.list.query(options)
+    );
+    return {
+      data: response.data.map((a) => this.instantiate(a)),
+      pagination: response.pagination,
+    };
+  }
+
+  /**
+   * Lists all addresses for a specific client
+   *
+   * @param clientId - The client ID
+   * @param options - Optional pagination options
+   * @returns Paginated list of Addresses
+   */
+  async listByClient(
+    clientId: string,
+    options?: { cursor?: string; limit?: number }
+  ): Promise<PaginatedResponse<Address>> {
+    const response = await this.execute(() =>
+      this.trpc.addresses.listByClient.query({ clientId, ...options })
+    );
+    return {
+      data: response.data.map((a) => this.instantiate(a)),
+      pagination: response.pagination,
+    };
+  }
+
+  /**
+   * Returns an async iterator over all addresses matching the filter.
+   */
+  iterate(filter?: AddressFilter): AsyncGenerator<Address, void, undefined> {
+    return this.createIterator({ filter });
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Batch Operations
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Creates multiple addresses in a single request.
+   *
+   * @param addresses - Array of address creation data (each includes clientId)
+   * @param options - Batch options (atomic: true by default)
+   * @returns Atomic result with data array, or partial result with succeeded/failed
+   */
+  async createMany(
+    addresses: CreateAddressInput[],
+    options?: { atomic?: true }
+  ): Promise<AtomicBatchResult<Address>>;
+  async createMany(
+    addresses: CreateAddressInput[],
+    options: { atomic: false }
+  ): Promise<PartialBatchResult<Address>>;
+  async createMany(
+    addresses: CreateAddressInput[],
+    options: BatchOptions = {}
+  ): Promise<AtomicBatchResult<Address> | PartialBatchResult<Address>> {
+    const atomic = options.atomic ?? true;
+    const validated = this.validate(
+      z.array(createAddressInputSchema),
+      addresses
+    );
+
+    const response = await this.execute(() =>
+      this.trpc.addresses.createMany.mutate({ items: validated, atomic })
+    );
+
+    if (response.atomic) {
+      return {
+        atomic: true,
+        data: response.data.map((a) => this.instantiate(a)),
+      };
+    } else {
+      return {
+        atomic: false,
+        succeeded: response.succeeded.map((item) => ({
+          index: item.index,
+          data: this.instantiate(item.data),
+        })),
+        failed: response.failed,
+      };
+    }
+  }
+
+  /**
+   * Updates multiple addresses in a single request.
+   *
+   * @param updates - Array of { id, data } updates
+   * @param options - Batch options (atomic: true by default)
+   * @returns Atomic result with data array, or partial result with succeeded/failed
+   */
+  async updateMany(
+    updates: { id: string; data: UpdateAddressInput }[],
+    options?: { atomic?: true }
+  ): Promise<AtomicBatchResult<Address>>;
+  async updateMany(
+    updates: { id: string; data: UpdateAddressInput }[],
+    options: { atomic: false }
+  ): Promise<PartialBatchResult<Address>>;
+  async updateMany(
+    updates: { id: string; data: UpdateAddressInput }[],
+    options: BatchOptions = {}
+  ): Promise<AtomicBatchResult<Address> | PartialBatchResult<Address>> {
+    const atomic = options.atomic ?? true;
+    const updateItemSchema = z.object({
+      id: z.uuid(),
+      data: updateAddressInputSchema,
+    });
+
+    const validated = this.validate(z.array(updateItemSchema), updates);
+
+    const response = await this.execute(() =>
+      this.trpc.addresses.updateMany.mutate({ items: validated, atomic })
+    );
+
+    if (response.atomic) {
+      return {
+        atomic: true,
+        data: response.data.map((a) => this.instantiate(a)),
+      };
+    } else {
+      return {
+        atomic: false,
+        succeeded: response.succeeded.map((item) => ({
+          index: item.index,
+          data: this.instantiate(item.data),
+        })),
+        failed: response.failed,
+      };
+    }
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Sync Operations
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Syncs addresses for a client - handles create, update, and delete in bulk.
+   *
+   * This is the most efficient way to reconcile a set of addresses for a client.
+   *
+   * @param clientId - The client ID
+   * @param items - Array of sync items:
+   *   - Without `id`: create new address
+   *   - With `id` and `_delete: true`: delete existing address
+   *   - With `id` (no `_delete`): update existing address
+   * @param options - Sync options
+   * @param options.replaceMode - When true, items not in the array are deleted (default: false)
+   * @returns Sync result with created, updated, and deleted arrays
+   *
+   * @example
+   * ```typescript
+   * // Patch mode (default) - only mentioned items are affected
+   * const result = await sdk.addresses.sync("client_123", [
+   *   // Create new address (no id)
+   *   { street: "123 New St", city: "Mexico City", country: "MX" },
+   *   // Update existing address (has id)
+   *   { id: "addr_456", street: "456 Updated Ave" },
+   *   // Delete address (has id and _delete: true)
+   *   { id: "addr_789", _delete: true },
+   * ]);
+   *
+   * // Replace mode - provided array becomes the complete set
+   * const result = await sdk.addresses.sync("client_123", addresses, { replaceMode: true });
+   *
+   * console.log(result.created);  // newly created addresses
+   * console.log(result.updated);  // updated addresses
+   * console.log(result.deleted);  // array of deleted address IDs
+   * ```
+   */
+  async sync(
+    clientId: string,
+    items: SyncItem<CreateAddressInput>[],
+    options?: { replaceMode: true }
+  ): Promise<SyncResult<Address>>;
+  async sync(
+    clientId: string,
+    items: SyncItem<UpdateAddressInput>[],
+    options?: { replaceMode?: boolean }
+  ): Promise<SyncResult<Address>>;
+  async sync(
+    clientId: string,
+    items: SyncItem<UpdateAddressInput | CreateAddressInput>[],
+    options?: { replaceMode?: boolean }
+  ): Promise<SyncResult<Address>> {
+    const validated = this.validate(
+      z.array(
+        replaceSyncItemSchema(createAddressInputSchema, updateAddressInputSchema)
+      ),
+      items
+    );
+
+    const response = await this.execute(() =>
+      this.trpc.addresses.sync.mutate({
+        clientId,
+        items: validated,
+        replaceMode: options?.replaceMode,
+      })
+    );
+
+    return {
+      created: response.created.map((a) => this.instantiate(a)),
+      updated: response.updated.map((a) => this.instantiate(a)),
+      deleted: response.deleted,
+    };
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Helper Methods
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Gets the primary address for a client
+   *
+   * @param clientId - The client ID
+   * @param type - Optional address type filter
+   * @returns The primary Address or null
+   */
+  async getPrimary(
+    clientId: string,
+    type?: AddressType
+  ): Promise<Address | null> {
+    const response = await this.execute(() =>
+      this.trpc.addresses.getPrimary.query({ clientId, type })
+    );
+    return response ? this.instantiate(response) : null;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Instantiation
+  // ─────────────────────────────────────────────────────────────────
+
+  protected instantiate(data: AddressData): Address {
+    return new Address(data);
+  }
+}