@artu-ai/compliance-sdk 0.4.0 → 0.4.2

package/src/resources/mex/clients.ts

@@ -1,758 +0,0 @@
-/**
- * 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);
-  }
-}