@artu-ai/compliance-sdk 0.0.6 → 0.2.0

package/src/resources/clients.ts

@@ -0,0 +1,802 @@
+/**
+ * Clients Resource
+ *
+ * CRUD operations, filtering, pagination, and batch operations for clients.
+ *
+ * This is the base (unscoped) resource. For jurisdiction-scoped SDKs, use:
+ * - MexClientsResource - Mexico-scoped with flattened MX fields
+ * - AVIClientsResource - Mexico AVI-scoped with flattened AVI fields
+ * - JYSClientsResource - Mexico JYS-scoped with flattened JYS fields
+ * - TSCClientsResource - Mexico TSC-scoped with flattened TSC fields
+ */
+
+import { z } from "zod";
+import type {
+  CreateClientInput,
+  UpdateClientInput,
+  CreateAddressInput,
+  UpdateAddressInput,
+  CreateContactMethodInput,
+  UpdateContactMethodInput,
+  CreateBankAccountInput,
+  UpdateBankAccountInput,
+  ClientFilter,
+  ListOptions,
+  PaginatedResponse,
+  AtomicBatchResult,
+  PartialBatchResult,
+  ClientRelationshipType,
+  LinkedClient as LinkedClientInput,
+  SyncItem,
+  SyncResult,
+} from "@artu-ai/shared";
+import {
+  createClientInputSchema,
+  updateClientInputSchema,
+  createAddressInputSchema,
+  updateAddressInputSchema,
+  createContactMethodInputSchema,
+  updateContactMethodInputSchema,
+  createBankAccountInputSchema,
+  updateBankAccountInputSchema,
+  linkedClientSchema,
+  replaceSyncItemSchema,
+} from "@artu-ai/shared";
+import { BaseResource } from "./base";
+import {
+  Client,
+  type ClientData,
+  Address,
+  ContactMethod,
+  BankAccount,
+  LinkedClient,
+} from "../models";
+
+// ===========================
+// Types
+// ===========================
+
+/**
+ * Options for batch operations
+ */
+export interface BatchOptions {
+  /**
+   * If true (default), all items must succeed or entire operation fails.
+   * If false, partial success is allowed with succeeded/failed arrays.
+   */
+  atomic?: boolean;
+}
+
+export interface ClientIncludeMap {
+  primaryContacts?: boolean;
+  addresses?: boolean;
+  contactMethods?: boolean;
+  bankAccounts?: boolean;
+  documents?: boolean;
+  linkedClients?: boolean;
+}
+
+// ===========================
+// ClientsResource
+// ===========================
+
+/**
+ * Base resource manager for client operations.
+ *
+ * Provides:
+ * - CRUD operations (create, retrieve, update, delete)
+ * - Filtering and pagination
+ * - Batch operations (createMany, updateMany)
+ *
+ * @example
+ * ```typescript
+ * // Create a client with full nested format
+ * const client = await sdk.clients.create({
+ *   type: "individual",
+ *   name: "Juan García",
+ *   primaryJurisdiction: "MX",
+ *   jurisdictions: {
+ *     MX: { rfc: "GAJL850101ABC" },
+ *   },
+ * });
+ *
+ * // List with filtering
+ * const { data, pagination } = await sdk.clients.list({
+ *   filter: { type: "individual", primaryJurisdiction: "MX" },
+ *   limit: 20,
+ * });
+ *
+ * // Iterate all clients
+ * for await (const client of sdk.clients.iterate()) {
+ *   console.log(client.name);
+ * }
+ * ```
+ */
+export class ClientsResource extends BaseResource<
+  Client,
+  CreateClientInput,
+  UpdateClientInput,
+  ClientFilter
+> {
+  // ─────────────────────────────────────────────────────────────────
+  // CRUD Operations
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Creates a new client.
+   *
+   * @param data - Client creation data in nested format
+   * @returns The created client model
+   *
+   * @example
+   * ```typescript
+   * const client = await sdk.clients.create({
+   *   type: ClientType.Person,
+   *   name: "Juan García",
+   *   primaryJurisdiction: Jurisdiction.Mexico,
+   *   jurisdictions: {
+   *     MX: { rfc: "GAJL850101ABC" },
+   *   },
+   * });
+   * ```
+   */
+  async create(data: CreateClientInput): Promise<Client> {
+    const validated = this.validate(createClientInputSchema, data);
+
+    const response = await this.execute(() =>
+      this.trpc.clients.create.mutate(validated)
+    );
+
+    return this.instantiate(response);
+  }
+
+  /**
+   * Retrieves a client by ID.
+   *
+   * @param id - Client ID
+   * @param include - Optional includes (relations, primary contacts)
+   * @returns The client model (with optional fields populated if included)
+   */
+  async retrieve(id: string, include?: ClientIncludeMap): Promise<Client> {
+    const response = await this.execute(() =>
+      this.trpc.clients.retrieve.query({ id, include })
+    );
+    return this.instantiate(response);
+  }
+
+  /**
+   * Retrieves a client by metadata key/value.
+   */
+  async retrieveByMetadata(key: string, value: string): Promise<Client> {
+    const response = await this.execute(() =>
+      this.trpc.clients.retrieveByMetadata.query({ key, value })
+    );
+    return this.instantiate(response);
+  }
+
+  /**
+   * Retrieves a client by externalId.
+   *
+   * @param externalId - External identifier assigned by your system
+   * @returns The client model
+   *
+   * @example
+   * ```typescript
+   * const client = await sdk.clients.retrieveByExternalId("external-123");
+   * console.log(client.name);
+   * ```
+   */
+  async retrieveByExternalId(externalId: string): Promise<Client> {
+    const response = await this.execute(() =>
+      this.trpc.clients.retrieveByExternalId.query({ externalId })
+    );
+    return this.instantiate(response);
+  }
+
+  /**
+   * Updates a client.
+   *
+   * @param id - Client ID
+   * @param data - Update data (partial)
+   * @returns The updated client model
+   *
+   * @example
+   * ```typescript
+   * const client = await sdk.clients.update("client_123", {
+   *   email: "new@example.com",
+   * });
+   * ```
+   */
+  async update(id: string, data: UpdateClientInput): Promise<Client> {
+    const validated = this.validate(updateClientInputSchema, data);
+
+    const response = await this.execute(() =>
+      this.trpc.clients.update.mutate({ id, data: validated })
+    );
+    return this.instantiate(response);
+  }
+
+  /**
+   * Deletes a client (soft delete).
+   *
+   * @param id - Client ID
+   *
+   * @example
+   * ```typescript
+   * await sdk.clients.delete("client_123");
+   * ```
+   */
+  async delete(id: string): Promise<void> {
+    await this.execute(() => this.trpc.clients.delete.mutate({ id }));
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // List & Pagination
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Lists clients with optional filtering and pagination.
+   *
+   * @param options - List options (filter, cursor, limit)
+   * @param options.includePrimaryContacts - Include primary email/phone
+   * @returns Paginated response with client models
+   *
+   * @example
+   * ```typescript
+   * const { data, pagination } = await sdk.clients.list({
+   *   filter: { type: "individual" },
+   *   limit: 20,
+   * });
+   *
+   * if (pagination.hasMore) {
+   *   const nextPage = await sdk.clients.list({
+   *     cursor: pagination.nextCursor,
+   *   });
+   * }
+   * ```
+   */
+  async list(
+    options?: ListOptions<ClientFilter> & { includePrimaryContacts?: boolean }
+  ): Promise<PaginatedResponse<Client>> {
+    const response = await this.execute(() =>
+      this.trpc.clients.list.query(options)
+    );
+
+    return {
+      data: response.data.map((c) => this.instantiate(c)),
+      pagination: response.pagination,
+    };
+  }
+
+  /**
+   * Returns an async iterator over all clients matching the filter.
+   * Automatically fetches subsequent pages as you iterate.
+   *
+   * @param filter - Optional filter criteria
+   * @returns Async generator yielding client models
+   *
+   * @example
+   * ```typescript
+   * for await (const client of sdk.clients.iterate({ type: "individual" })) {
+   *   console.log(client.name);
+   * }
+   * ```
+   */
+  iterate(filter?: ClientFilter): AsyncGenerator<Client, void, undefined> {
+    return this.createIterator({ filter });
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Batch Operations
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Creates multiple clients in a single request.
+   *
+   * @param clients - Array of client creation data
+   * @param options - Batch options (atomic: true by default)
+   * @returns Atomic result with data array, or partial result with succeeded/failed
+   *
+   * @example
+   * ```typescript
+   * // Atomic mode (default) - all or nothing
+   * const result = await sdk.clients.createMany([...]);
+   * if (result.atomic) {
+   *   console.log("All created:", result.data);
+   * }
+   *
+   * // Non-atomic mode - partial success allowed
+   * const result = await sdk.clients.createMany([...], { atomic: false });
+   * if (!result.atomic) {
+   *   console.log("Succeeded:", result.succeeded.length);
+   *   console.log("Failed:", result.failed.length);
+   * }
+   * ```
+   */
+  async createMany(
+    clients: CreateClientInput[],
+    options?: { atomic?: true }
+  ): Promise<AtomicBatchResult<Client>>;
+  async createMany(
+    clients: CreateClientInput[],
+    options: { atomic: false }
+  ): Promise<PartialBatchResult<Client>>;
+  async createMany(
+    clients: CreateClientInput[],
+    options: BatchOptions = {}
+  ): Promise<AtomicBatchResult<Client> | PartialBatchResult<Client>> {
+    const atomic = options.atomic ?? true;
+    const validated = this.validate(z.array(createClientInputSchema), clients);
+
+    const response = await this.execute(() =>
+      this.trpc.clients.createMany.mutate({ items: validated, 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 clients 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
+   *
+   * @example
+   * ```typescript
+   * // Atomic mode (default) - all or nothing
+   * const result = await sdk.clients.updateMany([...]);
+   * if (result.atomic) {
+   *   console.log("All updated:", result.data);
+   * }
+   *
+   * // Non-atomic mode - partial success allowed
+   * const result = await sdk.clients.updateMany([...], { atomic: false });
+   * if (!result.atomic) {
+   *   console.log("Succeeded:", result.succeeded.length);
+   *   console.log("Failed:", result.failed.length);
+   * }
+   * ```
+   */
+  async updateMany(
+    updates: { id: string; data: UpdateClientInput }[],
+    options?: { atomic?: true }
+  ): Promise<AtomicBatchResult<Client>>;
+  async updateMany(
+    updates: { id: string; data: UpdateClientInput }[],
+    options: { atomic: false }
+  ): Promise<PartialBatchResult<Client>>;
+  async updateMany(
+    updates: { id: string; data: UpdateClientInput }[],
+    options: BatchOptions = {}
+  ): Promise<AtomicBatchResult<Client> | PartialBatchResult<Client>> {
+    const atomic = options.atomic ?? true;
+    const updateItemSchema = z.object({
+      id: z.uuid(),
+      data: updateClientInputSchema,
+    });
+
+    const validated = this.validate(z.array(updateItemSchema), updates);
+
+    const response = await this.execute(() =>
+      this.trpc.clients.updateMany.mutate({ items: validated, 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
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Links a client to another client with a relationship type.
+   *
+   * @param parentClientId - The ID of the parent client (e.g., a company)
+   * @param childClientId - The ID of the child client (e.g., a legal rep)
+   * @param relationshipType - The type of relationship
+   * @param metadata - Optional metadata for the relationship
+   * @returns The updated parent client
+   *
+   * @example
+   * ```typescript
+   * // Link a legal representative to a company
+   * await sdk.clients.linkClient(
+   *   companyId,
+   *   legalRepId,
+   *   ClientRelationshipType.LegalRepresentative
+   * );
+   *
+   * // Link a controlling beneficiary with metadata
+   * await sdk.clients.linkClient(
+   *   companyId,
+   *   beneficiaryId,
+   *   ClientRelationshipType.ControllingBeneficiary,
+   *   { ownershipPercentage: 51 }
+   * );
+   * ```
+   */
+  async linkClient(
+    parentClientId: string,
+    childClientId: string,
+    relationshipType: ClientRelationshipType,
+    metadata?: Record<string, unknown>
+  ): Promise<Client> {
+    const response = await this.execute(() =>
+      this.trpc.clients.linkClient.mutate({
+        parentClientId,
+        childClientId,
+        relationshipType,
+        metadata,
+      })
+    );
+    return this.instantiate(response);
+  }
+
+  /**
+   * Unlinks a client from another client.
+   *
+   * @param parentClientId - The ID of the parent client
+   * @param childClientId - The ID of the child client to unlink
+   * @param relationshipType - The type of relationship to remove
+   * @returns The updated parent client
+   *
+   * @example
+   * ```typescript
+   * // Remove a legal representative
+   * await sdk.clients.unlinkClient(
+   *   companyId,
+   *   legalRepId,
+   *   ClientRelationshipType.LegalRepresentative
+   * );
+   * ```
+   */
+  async unlinkClient(
+    parentClientId: string,
+    childClientId: string,
+    relationshipType: ClientRelationshipType
+  ): Promise<Client> {
+    const response = await this.execute(() =>
+      this.trpc.clients.unlinkClient.mutate({
+        parentClientId,
+        childClientId,
+        relationshipType,
+      })
+    );
+    return this.instantiate(response);
+  }
+
+  /**
+   * Lists all clients linked to a parent client.
+   *
+   * @param parentClientId - The ID of the parent client
+   * @param relationshipType - Optional filter by relationship type
+   * @returns Array of LinkedClient models
+   *
+   * @example
+   * ```typescript
+   * // List all linked clients
+   * const links = await sdk.clients.listLinkedClients(companyId);
+   *
+   * // List only legal representatives
+   * const legalReps = await sdk.clients.listLinkedClients(
+   *   companyId,
+   *   ClientRelationshipType.LegalRepresentative
+   * );
+   *
+   * // Access relationship metadata
+   * for (const link of links) {
+   *   console.log(link.id, link.relationshipType, link.metadata);
+   * }
+   * ```
+   */
+  async listLinkedClients(
+    parentClientId: string,
+    relationshipType?: ClientRelationshipType
+  ): Promise<LinkedClient[]> {
+    const response = await this.execute(() =>
+      this.trpc.clients.listLinkedClients.query({
+        parentClientId,
+        relationshipType,
+      })
+    );
+
+    return response.map((l) => new LinkedClient(l));
+  }
+
+  /**
+   * Retrieves a single linked client relationship by ID.
+   *
+   * @param id - The ID of the relationship
+   * @returns The LinkedClient model
+   *
+   * @example
+   * ```typescript
+   * const relationship = await sdk.clients.retrieveLinkedClient(relationshipId);
+   * console.log(relationship.relationshipType, relationship.metadata);
+   * ```
+   */
+  async retrieveLinkedClient(id: string): Promise<LinkedClient> {
+    const response = await this.execute(() =>
+      this.trpc.clients.retrieveLinkedClient.query({ id })
+    );
+    return new LinkedClient(response);
+  }
+
+  /**
+   * Updates a linked client relationship's metadata.
+   *
+   * @param id - The ID of the relationship
+   * @param metadata - New metadata for the relationship
+   * @returns The updated LinkedClient model
+   *
+   * @example
+   * ```typescript
+   * const updated = await sdk.clients.updateLinkedClient(relationshipId, {
+   *   ownershipPercentage: 51,
+   *   votingRights: true,
+   * });
+   * ```
+   */
+  async updateLinkedClient(
+    id: string,
+    metadata?: Record<string, unknown>
+  ): Promise<LinkedClient> {
+    const response = await this.execute(() =>
+      this.trpc.clients.updateLinkedClient.mutate({ id, metadata })
+    );
+    return new LinkedClient(response);
+  }
+
+  /**
+   * Replaces all linked clients for a parent client.
+   *
+   * @param parentClientId - The ID of the parent client
+   * @param linkedClients - Array of linked client definitions
+   * @returns The updated parent client
+   *
+   * @example
+   * ```typescript
+   * // Replace all linked clients
+   * await sdk.clients.setLinkedClients(companyId, [
+   *   { clientId: legalRepId, relationshipType: "legal_representative" },
+   *   { clientId: beneficiaryId, relationshipType: "controlling_beneficiary" },
+   * ]);
+   * ```
+   */
+  async setLinkedClients(
+    parentClientId: string,
+    linkedClients: LinkedClientInput[]
+  ): Promise<Client> {
+    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 client and all related resources in a single transaction.
+   *
+   * All operations succeed or fail together - if any fails, the entire
+   * transaction is rolled back.
+   *
+   * @param clientId - The client ID to update
+   * @param data - Sync data with optional client, addresses, contactMethods, bankAccounts, linkedClients
+   * @param options - Sync options
+   * @param options.replaceMode - When true, items not in the arrays are deleted (default: false)
+   * @returns Result with updated client and sync results for each resource type
+   *
+   * @example
+   * ```typescript
+   * // Patch mode (default) - only mentioned items are affected
+   * const result = await sdk.clients.syncAll("client_123", {
+   *   // Update client fields
+   *   client: { name: "Updated Name" },
+   *
+   *   // Sync addresses (create, update, delete)
+   *   addresses: [
+   *     { street: "123 New St", city: "Mexico City", country: "MX" },  // create
+   *     { id: "addr_456", street: "Updated St" },  // update
+   *     { id: "addr_789", _delete: true },  // delete
+   *   ],
+   *
+   *   // Sync contact methods
+   *   contactMethods: [
+   *     { type: "email", value: "new@example.com", isPrimary: true },
+   *   ],
+   *
+   *   // Sync bank accounts
+   *   bankAccounts: [
+   *     { accountNumber: "1234567890", bankName: "BBVA" },
+   *   ],
+   *
+   *   // Replace all linked clients
+   *   linkedClients: [
+   *     { clientId: "rep_123", relationshipType: "legal_representative" },
+   *   ],
+   * });
+   *
+   * // Replace mode - provided arrays become the complete set (requires full create input for new items)
+   * const result = await sdk.clients.syncAll("client_123", {
+   *   addresses: currentAddresses,
+   *   contactMethods: currentContacts,
+   *   bankAccounts: currentAccounts,
+   * }, { replaceMode: true });
+   *
+   * console.log(result.client);  // updated client
+   * console.log(result.addresses.created);  // newly created addresses
+   * console.log(result.addresses.updated);  // updated addresses
+   * console.log(result.addresses.deleted);  // deleted address IDs
+   * ```
+   */
+  async syncAll(
+    clientId: string,
+    data: {
+      client?: UpdateClientInput;
+      addresses?: SyncItem<CreateAddressInput>[];
+      contactMethods?: SyncItem<CreateContactMethodInput>[];
+      bankAccounts?: SyncItem<CreateBankAccountInput>[];
+      linkedClients?: LinkedClientInput[];
+    },
+    options: { replaceMode: true }
+  ): Promise<{
+    client: Client;
+    addresses: SyncResult<Address>;
+    contactMethods: SyncResult<ContactMethod>;
+    bankAccounts: SyncResult<BankAccount>;
+  }>;
+  async syncAll(
+    clientId: string,
+    data: {
+      client?: UpdateClientInput;
+      addresses?: SyncItem<UpdateAddressInput>[];
+      contactMethods?: SyncItem<UpdateContactMethodInput>[];
+      bankAccounts?: SyncItem<UpdateBankAccountInput>[];
+      linkedClients?: LinkedClientInput[];
+    },
+    options?: { replaceMode?: boolean }
+  ): Promise<{
+    client: Client;
+    addresses: SyncResult<Address>;
+    contactMethods: SyncResult<ContactMethod>;
+    bankAccounts: SyncResult<BankAccount>;
+  }>;
+  async syncAll(
+    clientId: string,
+    data: {
+      client?: UpdateClientInput;
+      addresses?: SyncItem<UpdateAddressInput | CreateAddressInput>[];
+      contactMethods?: SyncItem<UpdateContactMethodInput | CreateContactMethodInput>[];
+      bankAccounts?: SyncItem<UpdateBankAccountInput | CreateBankAccountInput>[];
+      linkedClients?: LinkedClientInput[];
+    },
+    options?: { replaceMode?: boolean }
+  ): Promise<{
+    client: Client;
+    addresses: SyncResult<Address>;
+    contactMethods: SyncResult<ContactMethod>;
+    bankAccounts: SyncResult<BankAccount>;
+  }> {
+    // Validate inputs - use replaceSyncItemSchema which validates create vs update based on id presence
+    const validatedClient = data.client
+      ? this.validate(updateClientInputSchema, data.client)
+      : undefined;
+    const validatedAddresses = data.addresses
+      ? this.validate(
+          z.array(
+            replaceSyncItemSchema(createAddressInputSchema, updateAddressInputSchema)
+          ),
+          data.addresses
+        )
+      : undefined;
+    const validatedContactMethods = data.contactMethods
+      ? this.validate(
+          z.array(
+            replaceSyncItemSchema(
+              createContactMethodInputSchema,
+              updateContactMethodInputSchema
+            )
+          ),
+          data.contactMethods
+        )
+      : undefined;
+    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;
+
+    const response = await this.execute(() =>
+      this.trpc.clients.syncAll.mutate({
+        clientId,
+        client: validatedClient,
+        addresses: validatedAddresses,
+        contactMethods: validatedContactMethods,
+        bankAccounts: validatedBankAccounts,
+        linkedClients: validatedLinkedClients,
+        replaceMode: options?.replaceMode,
+      })
+    );
+
+    return {
+      client: this.instantiate(response.client),
+      addresses: {
+        created: response.addresses.created.map((a) => new Address(a)),
+        updated: response.addresses.updated.map((a) => new Address(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 BankAccount(b)),
+        updated: response.bankAccounts.updated.map((b) => new BankAccount(b)),
+        deleted: response.bankAccounts.deleted,
+      },
+    };
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Instantiation (protected for subclasses to override)
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Instantiates a Client model from API response data.
+   * Subclasses override this to return their specific model type.
+   */
+  protected instantiate(data: ClientData): Client {
+    return new Client(data);
+  }
+}