@artu-ai/compliance-sdk 0.0.6 → 0.3.0

package/src/resources/mex/clients.ts

@@ -0,0 +1,758 @@
+/**
+ * Mexico Clients Resource
+ *
+ * Extends ClientsResource with Mexico-specific behavior:
+ * - Accepts flattened CreateMexClientInput (MX fields at root level)
+ * - Automatically sets primaryJurisdiction to Mexico
+ * - Filters list/iterate to Mexico clients only
+ * - Returns MexClient models
+ */
+
+import { z } from "zod";
+import type {
+  CreateClientInput,
+  UpdateClientInput,
+  ClientFilter,
+  ClientSort,
+  ListOptions,
+  PaginatedResponse,
+  CreateMexClientInput,
+  UpdateMexClientInput,
+  AtomicBatchResult,
+  PartialBatchResult,
+  ClientRelationshipType,
+  LinkedClient as LinkedClientInput,
+  CreateAddressInput,
+  UpdateAddressInput,
+  CreateMexAddressInput,
+  UpdateMexAddressInput,
+  CreateContactMethodInput,
+  UpdateContactMethodInput,
+  CreateBankAccountInput,
+  UpdateBankAccountInput,
+  SyncItem,
+  SyncResult,
+  MexClientFilter,
+  MexClientSort,
+} from "@artu-ai/shared";
+import {
+  Jurisdiction,
+  createMexClientInputSchema,
+  updateMexClientInputSchema,
+  linkedClientSchema,
+  createMexAddressInputSchema,
+  updateMexAddressInputSchema,
+  createContactMethodInputSchema,
+  updateContactMethodInputSchema,
+  createBankAccountInputSchema,
+  updateBankAccountInputSchema,
+  replaceSyncItemSchema,
+  transformSort,
+  mexClientFieldMapping,
+} from "@artu-ai/shared";
+import {
+  ClientsResource,
+  type BatchOptions,
+  type ClientIncludeMap,
+} from "../clients";
+import {
+  MexClient,
+  MexAddress,
+  MexBankAccount,
+  ContactMethod,
+  LinkedClient,
+  type ClientData,
+} from "../../models";
+
+// ===========================
+// MexClientsResource
+// ===========================
+
+/**
+ * Mexico-scoped clients resource.
+ *
+ * Provides the same operations as ClientsResource but with:
+ * - Flattened input types (MX fields at root level)
+ * - Automatic jurisdiction scoping
+ * - MexClient model return type
+ *
+ * @example
+ * ```typescript
+ * const mexSdk = new ComplianceSDK({
+ *   apiKey,
+ *   environment: "test",
+ *   jurisdiction: Jurisdiction.Mexico,
+ * });
+ *
+ * // Create with flattened input
+ * const client = await mexSdk.clients.create({
+ *   type: ClientType.Person,
+ *   name: "Juan García",
+ *   rfc: "GAJL850101ABC",      // MX field at root
+ *   curp: "GAJL850101HDFRRL09", // MX field at root
+ *   actividadVulnerable: {      // Activity data keyed by code
+ *     AVI: { username: "JGARCIA" },
+ *   },
+ * });
+ *
+ * // List returns only Mexico clients
+ * const { data } = await mexSdk.clients.list();
+ * // data is MexClient[]
+ * ```
+ */
+export class MexClientsResource<
+  TSort = MexClientSort,
+> extends ClientsResource<TSort> {
+  // ─────────────────────────────────────────────────────────────────
+  // CRUD Operations (override with flattened input types)
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Creates a new Mexico client with flattened input.
+   *
+   * @param data - Client creation data with MX fields at root level
+   * @returns The created MexClient model
+   */
+  async create(data: CreateMexClientInput): Promise<MexClient> {
+    const validated = this.validate(createMexClientInputSchema, data);
+    const nestedData = this.transformToNested(validated);
+
+    const response = await this.execute(() =>
+      this.trpc.clients.create.mutate(nestedData)
+    );
+
+    return this.instantiate(response);
+  }
+
+  /**
+   * Retrieves a client by ID.
+   */
+  async retrieve(id: string, include?: ClientIncludeMap): Promise<MexClient> {
+    const response = await this.execute(() =>
+      this.trpc.clients.retrieve.query({ id, include })
+    );
+    return this.instantiate(response);
+  }
+
+  /**
+   * Retrieves a Mexico client by externalId.
+   */
+  async retrieveByExternalId(externalId: string): Promise<MexClient> {
+    const response = await this.execute(() =>
+      this.trpc.clients.retrieveByExternalId.query({ externalId })
+    );
+    return this.instantiate(response);
+  }
+
+  /**
+   * Updates a Mexico client with flattened input.
+   */
+  async update(id: string, data: UpdateMexClientInput): Promise<MexClient> {
+    const validated = this.validate(updateMexClientInputSchema, data);
+    const nestedData = this.transformUpdateToNested(validated);
+
+    const response = await this.execute(() =>
+      this.trpc.clients.update.mutate({ id, data: nestedData })
+    );
+    return this.instantiate(response);
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // List & Pagination (scoped to Mexico)
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Lists Mexico clients with optional filtering.
+   *
+   * Accepts flattened Mexico filter (MX fields at root level) and automatically
+   * transforms to nested format before calling the API.
+   *
+   * @example
+   * ```typescript
+   * // Filter with flattened MX fields
+   * const { data } = await mexSdk.clients.list({
+   *   filter: {
+   *     name: { contains: "García" },
+   *     rfc: { startsWith: "GAJL" },  // MX field at root!
+   *   },
+   * });
+   * ```
+   */
+  async list(
+    options?: ListOptions<MexClientFilter, TSort> & { includePrimaryContacts?: boolean }
+  ): Promise<PaginatedResponse<MexClient>> {
+    const scopedFilter = this.applyScopeToFilter(options?.filter);
+    const scopedSort = this.applyScopeToSort(options?.sort);
+
+    const response = await this.execute(() =>
+      this.trpc.clients.list.query({
+        ...options,
+        filter: scopedFilter,
+        sort: scopedSort,
+      })
+    );
+
+    return {
+      data: response.data.map((c) => this.instantiate(c)),
+      pagination: response.pagination,
+    };
+  }
+
+  /**
+   * Iterates over Mexico clients.
+   *
+   * Accepts flattened Mexico filter (MX fields at root level) and automatically
+   * transforms to nested format before calling the API.
+   */
+  iterate(filter?: MexClientFilter): AsyncGenerator<MexClient, void, undefined> {
+    const scopedFilter = this.applyScopeToFilter(filter);
+    return this.createIterator<MexClient>({ filter: scopedFilter });
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Batch Operations
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Creates multiple Mexico clients with flattened input.
+   */
+  async createMany(
+    clients: CreateMexClientInput[],
+    options?: { atomic?: true }
+  ): Promise<AtomicBatchResult<MexClient>>;
+  async createMany(
+    clients: CreateMexClientInput[],
+    options: { atomic: false }
+  ): Promise<PartialBatchResult<MexClient>>;
+  async createMany(
+    clients: CreateMexClientInput[],
+    options: BatchOptions = {}
+  ): Promise<AtomicBatchResult<MexClient> | PartialBatchResult<MexClient>> {
+    const atomic = options.atomic ?? true;
+    const validated = this.validate(
+      z.array(createMexClientInputSchema),
+      clients
+    );
+    const nestedClients = validated.map((c) => this.transformToNested(c));
+
+    const response = await this.execute(() =>
+      this.trpc.clients.createMany.mutate({ items: nestedClients, atomic })
+    );
+
+    if (response.atomic) {
+      return {
+        atomic: true,
+        data: response.data.map((c) => this.instantiate(c)),
+      };
+    } else {
+      return {
+        atomic: false,
+        succeeded: response.succeeded.map((item) => ({
+          index: item.index,
+          data: this.instantiate(item.data),
+        })),
+        failed: response.failed,
+      };
+    }
+  }
+
+  /**
+   * Updates multiple Mexico clients.
+   */
+  async updateMany(
+    updates: { id: string; data: UpdateMexClientInput }[],
+    options?: { atomic?: true }
+  ): Promise<AtomicBatchResult<MexClient>>;
+  async updateMany(
+    updates: { id: string; data: UpdateMexClientInput }[],
+    options: { atomic: false }
+  ): Promise<PartialBatchResult<MexClient>>;
+  async updateMany(
+    updates: { id: string; data: UpdateMexClientInput }[],
+    options: BatchOptions = {}
+  ): Promise<AtomicBatchResult<MexClient> | PartialBatchResult<MexClient>> {
+    const atomic = options.atomic ?? true;
+    const updateItemSchema = z.object({
+      id: z.uuid(),
+      data: updateMexClientInputSchema,
+    });
+
+    const validated = this.validate(z.array(updateItemSchema), updates);
+    const nestedUpdates = validated.map((u) => ({
+      id: u.id,
+      data: this.transformUpdateToNested(u.data),
+    }));
+
+    const response = await this.execute(() =>
+      this.trpc.clients.updateMany.mutate({ items: nestedUpdates, atomic })
+    );
+
+    if (response.atomic) {
+      return {
+        atomic: true,
+        data: response.data.map((c) => this.instantiate(c)),
+      };
+    } else {
+      return {
+        atomic: false,
+        succeeded: response.succeeded.map((item) => ({
+          index: item.index,
+          data: this.instantiate(item.data),
+        })),
+        failed: response.failed,
+      };
+    }
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Client-to-Client Relationship Management (scoped returns)
+  // ─────────────────────────────────────────────────────────────────
+
+  async linkClient(
+    parentClientId: string,
+    childClientId: string,
+    relationshipType: ClientRelationshipType,
+    metadata?: Record<string, unknown>
+  ): Promise<MexClient> {
+    const response = await this.execute(() =>
+      this.trpc.clients.linkClient.mutate({
+        parentClientId,
+        childClientId,
+        relationshipType,
+        metadata,
+      })
+    );
+    return this.instantiate(response);
+  }
+
+  async unlinkClient(
+    parentClientId: string,
+    childClientId: string,
+    relationshipType: ClientRelationshipType
+  ): Promise<MexClient> {
+    const response = await this.execute(() =>
+      this.trpc.clients.unlinkClient.mutate({
+        parentClientId,
+        childClientId,
+        relationshipType,
+      })
+    );
+    return this.instantiate(response);
+  }
+
+  async listLinkedClients(
+    parentClientId: string,
+    relationshipType?: ClientRelationshipType
+  ): Promise<LinkedClient[]> {
+    return super.listLinkedClients(parentClientId, relationshipType);
+  }
+
+  async setLinkedClients(
+    parentClientId: string,
+    linkedClients: LinkedClientInput[]
+  ): Promise<MexClient> {
+    const validated = this.validate(z.array(linkedClientSchema), linkedClients);
+
+    const response = await this.execute(() =>
+      this.trpc.clients.setLinkedClients.mutate({
+        parentClientId,
+        linkedClients: validated,
+      })
+    );
+    return this.instantiate(response);
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Sync All (Atomic)
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Atomically updates a Mexico client and all related resources in a single transaction.
+   *
+   * Accepts flattened Mexico address input types for convenience.
+   */
+  async syncAll(
+    clientId: string,
+    data: {
+      client?: UpdateMexClientInput;
+      addresses?: SyncItem<CreateMexAddressInput>[];
+      contactMethods?: SyncItem<CreateContactMethodInput>[];
+      bankAccounts?: SyncItem<CreateBankAccountInput>[];
+      linkedClients?: LinkedClientInput[];
+    },
+    options: { replaceMode: true }
+  ): Promise<{
+    client: MexClient;
+    addresses: SyncResult<MexAddress>;
+    contactMethods: SyncResult<ContactMethod>;
+    bankAccounts: SyncResult<MexBankAccount>;
+  }>;
+  async syncAll(
+    clientId: string,
+    data: {
+      client?: UpdateMexClientInput;
+      addresses?: SyncItem<UpdateMexAddressInput>[];
+      contactMethods?: SyncItem<UpdateContactMethodInput>[];
+      bankAccounts?: SyncItem<UpdateBankAccountInput>[];
+      linkedClients?: LinkedClientInput[];
+    },
+    options?: { replaceMode?: boolean }
+  ): Promise<{
+    client: MexClient;
+    addresses: SyncResult<MexAddress>;
+    contactMethods: SyncResult<ContactMethod>;
+    bankAccounts: SyncResult<MexBankAccount>;
+  }>;
+  async syncAll(
+    clientId: string,
+    data: {
+      client?: UpdateMexClientInput;
+      addresses?: SyncItem<UpdateMexAddressInput | CreateMexAddressInput>[];
+      contactMethods?: SyncItem<UpdateContactMethodInput | CreateContactMethodInput>[];
+      bankAccounts?: SyncItem<UpdateBankAccountInput | CreateBankAccountInput>[];
+      linkedClients?: LinkedClientInput[];
+    },
+    options?: { replaceMode?: boolean }
+  ): Promise<{
+    client: MexClient;
+    addresses: SyncResult<MexAddress>;
+    contactMethods: SyncResult<ContactMethod>;
+    bankAccounts: SyncResult<MexBankAccount>;
+  }> {
+    // Validate and transform client input
+    const validatedClient = data.client
+      ? this.transformUpdateToNested(
+          this.validate(updateMexClientInputSchema, data.client)
+        )
+      : undefined;
+
+    // Validate and transform addresses (flattened MX → nested)
+    let validatedAddresses: SyncItem<UpdateAddressInput | CreateAddressInput>[] | undefined;
+    if (data.addresses) {
+      const validated = this.validate(
+        z.array(
+          replaceSyncItemSchema(
+            createMexAddressInputSchema,
+            updateMexAddressInputSchema
+          )
+        ),
+        data.addresses
+      );
+      validatedAddresses = validated.map((item) =>
+        this.transformAddressSyncItem(item)
+      );
+    }
+
+    // Validate contact methods (base types, no transform)
+    const validatedContactMethods = data.contactMethods
+      ? this.validate(
+          z.array(
+            replaceSyncItemSchema(
+              createContactMethodInputSchema,
+              updateContactMethodInputSchema
+            )
+          ),
+          data.contactMethods
+        )
+      : undefined;
+
+    // Validate bank accounts (base types, no transform)
+    const validatedBankAccounts = data.bankAccounts
+      ? this.validate(
+          z.array(
+            replaceSyncItemSchema(
+              createBankAccountInputSchema,
+              updateBankAccountInputSchema
+            )
+          ),
+          data.bankAccounts
+        )
+      : undefined;
+
+    const validatedLinkedClients = data.linkedClients
+      ? this.validate(z.array(linkedClientSchema), data.linkedClients)
+      : undefined;
+
+    // Use type from trpc mutation to avoid type mismatch between imported types
+    // and trpc's inferred types
+    type SyncAllInput = Parameters<typeof this.trpc.clients.syncAll.mutate>[0];
+
+    const response = await this.execute(() =>
+      this.trpc.clients.syncAll.mutate({
+        clientId,
+        client: validatedClient,
+        addresses: validatedAddresses as SyncAllInput["addresses"],
+        contactMethods: validatedContactMethods,
+        bankAccounts: validatedBankAccounts,
+        linkedClients: validatedLinkedClients,
+        replaceMode: options?.replaceMode,
+      })
+    );
+
+    return {
+      client: this.instantiate(response.client),
+      addresses: {
+        created: response.addresses.created.map((a) => new MexAddress(a)),
+        updated: response.addresses.updated.map((a) => new MexAddress(a)),
+        deleted: response.addresses.deleted,
+      },
+      contactMethods: {
+        created: response.contactMethods.created.map((c) => new ContactMethod(c)),
+        updated: response.contactMethods.updated.map((c) => new ContactMethod(c)),
+        deleted: response.contactMethods.deleted,
+      },
+      bankAccounts: {
+        created: response.bankAccounts.created.map((b) => new MexBankAccount(b)),
+        updated: response.bankAccounts.updated.map((b) => new MexBankAccount(b)),
+        deleted: response.bankAccounts.deleted,
+      },
+    };
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Protected Helpers
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Transforms a flattened MexClientFilter to nested ClientFilter format
+   * and applies Mexico jurisdiction scoping.
+   *
+   * Extracts MX-specific fields (rfc, curp, actividadEconomica, giroMercantil,
+   * actividadVulnerable) from root level and nests them under jurisdictions.MX.
+   */
+  protected applyScopeToFilter(filter?: MexClientFilter): ClientFilter {
+    if (!filter) {
+      return {
+        availableJurisdictions: Jurisdiction.Mexico,
+      };
+    }
+
+    // Extract MX-specific filter fields
+    const {
+      rfc,
+      curp,
+      actividadEconomica,
+      giroMercantil,
+      actividadVulnerable,
+      ...baseFields
+    } = filter;
+
+    // Build MX jurisdiction filter if any MX fields are present
+    const hasMexFields =
+      rfc !== undefined ||
+      curp !== undefined ||
+      actividadEconomica !== undefined ||
+      giroMercantil !== undefined ||
+      actividadVulnerable !== undefined;
+
+    const mexFilter: Record<string, unknown> = {};
+    if (rfc !== undefined) mexFilter.rfc = rfc;
+    if (curp !== undefined) mexFilter.curp = curp;
+    if (actividadEconomica !== undefined)
+      mexFilter.actividadEconomica = actividadEconomica;
+    if (giroMercantil !== undefined) mexFilter.giroMercantil = giroMercantil;
+    if (actividadVulnerable !== undefined)
+      mexFilter.actividadVulnerable = actividadVulnerable;
+
+    return {
+      ...baseFields,
+      availableJurisdictions: Jurisdiction.Mexico,
+      ...(hasMexFields && { jurisdictions: { MX: mexFilter } }),
+    } as ClientFilter;
+  }
+
+  /**
+   * Transforms a flattened MexClientSort to nested ClientSort format.
+   *
+   * Maps flattened field names (rfc, curp, actividadVulnerable.AVI.username)
+   * to their full API paths (jurisdictions.MX.rfc, etc.).
+   *
+   * Note: Uses unknown parameter to allow derived classes to override with their own sort types.
+   */
+  protected applyScopeToSort(sort?: TSort): ClientSort | undefined {
+    if (!sort || !Array.isArray(sort) || sort.length === 0) {
+      return undefined;
+    }
+    return transformSort(sort as MexClientSort, mexClientFieldMapping);
+  }
+
+  /**
+   * Transforms flattened MX input to nested API format.
+   */
+  protected transformToNested(data: CreateMexClientInput): CreateClientInput {
+    const {
+      rfc,
+      curp,
+      actividadEconomica,
+      giroMercantil,
+      actividadVulnerable,
+      ...baseFields
+    } = data as Record<string, unknown>;
+
+    // Build MX jurisdiction data
+    const mexData: Record<string, unknown> = {};
+    if (rfc !== undefined) mexData.rfc = rfc;
+    if (curp !== undefined) mexData.curp = curp;
+    if (actividadEconomica !== undefined)
+      mexData.actividadEconomica = actividadEconomica;
+    if (giroMercantil !== undefined) mexData.giroMercantil = giroMercantil;
+    if (actividadVulnerable !== undefined)
+      mexData.actividadVulnerable = actividadVulnerable;
+
+    return {
+      ...baseFields,
+      primaryJurisdiction: Jurisdiction.Mexico,
+      jurisdictions: {
+        MX: mexData,
+      },
+    } as CreateClientInput;
+  }
+
+  /**
+   * Transforms flattened MX update input to nested API format.
+   */
+  protected transformUpdateToNested(
+    data: UpdateMexClientInput
+  ): UpdateClientInput {
+    const {
+      rfc,
+      curp,
+      actividadEconomica,
+      giroMercantil,
+      actividadVulnerable,
+      ...baseFields
+    } = data;
+
+    // Only include MX data if any MX fields are present
+    const hasMexFields =
+      rfc !== undefined ||
+      curp !== undefined ||
+      actividadEconomica !== undefined ||
+      giroMercantil !== undefined ||
+      actividadVulnerable !== undefined;
+
+    if (!hasMexFields) {
+      return baseFields as UpdateClientInput;
+    }
+
+    const mexData: Record<string, unknown> = {};
+    if (rfc !== undefined) mexData.rfc = rfc;
+    if (curp !== undefined) mexData.curp = curp;
+    if (actividadEconomica !== undefined)
+      mexData.actividadEconomica = actividadEconomica;
+    if (giroMercantil !== undefined) mexData.giroMercantil = giroMercantil;
+    if (actividadVulnerable !== undefined)
+      mexData.actividadVulnerable = actividadVulnerable;
+
+    return {
+      ...baseFields,
+      jurisdictions: {
+        MX: mexData,
+      },
+    } as UpdateClientInput;
+  }
+
+  /**
+   * Transforms a flattened MX address sync item to nested API format.
+   */
+  protected transformAddressSyncItem(
+    item: SyncItem<UpdateMexAddressInput | CreateMexAddressInput>
+  ): SyncItem<UpdateAddressInput | CreateAddressInput> {
+    if ("_delete" in item && item._delete) {
+      // Delete items pass through unchanged
+      return item as SyncItem<UpdateAddressInput>;
+    }
+    if ("id" in item && item.id) {
+      // Update items - transform the data fields
+      const { id, ...data } = item;
+      return {
+        id,
+        ...this.transformAddressUpdateToNested(data as UpdateMexAddressInput),
+      } as SyncItem<UpdateAddressInput>;
+    }
+    // Create items - transform full item
+    return this.transformAddressToNested(
+      item as CreateMexAddressInput
+    ) as SyncItem<CreateAddressInput>;
+  }
+
+  /**
+   * Transforms flattened MX address input to nested API format.
+   */
+  protected transformAddressToNested(
+    data: CreateMexAddressInput
+  ): CreateAddressInput {
+    const {
+      exteriorNumber,
+      interiorNumber,
+      neighborhood,
+      municipality,
+      betweenStreets,
+      reference,
+      ...baseFields
+    } = data;
+
+    const mexData: Record<string, unknown> = {
+      exteriorNumber,
+      neighborhood,
+    };
+    if (interiorNumber !== undefined) mexData.interiorNumber = interiorNumber;
+    if (municipality !== undefined) mexData.municipality = municipality;
+    if (betweenStreets !== undefined) mexData.betweenStreets = betweenStreets;
+    if (reference !== undefined) mexData.reference = reference;
+
+    return {
+      ...baseFields,
+      jurisdictions: { MX: mexData },
+    } as CreateAddressInput;
+  }
+
+  /**
+   * Transforms flattened MX address update input to nested API format.
+   */
+  protected transformAddressUpdateToNested(
+    data: UpdateMexAddressInput
+  ): UpdateAddressInput {
+    const {
+      exteriorNumber,
+      interiorNumber,
+      neighborhood,
+      municipality,
+      betweenStreets,
+      reference,
+      ...baseFields
+    } = data;
+
+    const hasMexFields =
+      exteriorNumber !== undefined ||
+      interiorNumber !== undefined ||
+      neighborhood !== undefined ||
+      municipality !== undefined ||
+      betweenStreets !== undefined ||
+      reference !== undefined;
+
+    if (!hasMexFields) {
+      return baseFields as UpdateAddressInput;
+    }
+
+    const mexData: Record<string, unknown> = {};
+    if (exteriorNumber !== undefined) mexData.exteriorNumber = exteriorNumber;
+    if (interiorNumber !== undefined) mexData.interiorNumber = interiorNumber;
+    if (neighborhood !== undefined) mexData.neighborhood = neighborhood;
+    if (municipality !== undefined) mexData.municipality = municipality;
+    if (betweenStreets !== undefined) mexData.betweenStreets = betweenStreets;
+    if (reference !== undefined) mexData.reference = reference;
+
+    return {
+      ...baseFields,
+      jurisdictions: { MX: mexData },
+    } as UpdateAddressInput;
+  }
+
+  /**
+   * Instantiates a MexClient model.
+   */
+  protected override instantiate(data: ClientData): MexClient {
+    return new MexClient(data);
+  }
+}