@artu-ai/compliance-sdk 0.0.6 → 0.2.0

package/src/resources/mex/actividad-vulnerable/avi/clients.ts

@@ -0,0 +1,537 @@
+/**
+ * AVI (Activos Virtuales) Clients Resource
+ *
+ * Extends MexClientsResource with AVI-specific behavior:
+ * - Accepts flattened CreateAVIClientInput (AVI fields at root level)
+ * - Returns MexAVIClient models
+ */
+
+import { z } from "zod";
+import type {
+  CreateClientInput,
+  UpdateClientInput,
+  ClientFilter,
+  ListOptions,
+  PaginatedResponse,
+  CreateAVIClientInput,
+  UpdateAVIClientInput,
+  CreateMexClientInput,
+  UpdateMexClientInput,
+  AtomicBatchResult,
+  PartialBatchResult,
+  ClientRelationshipType,
+  LinkedClient as LinkedClientInput,
+  CreateMexAddressInput,
+  UpdateMexAddressInput,
+  CreateContactMethodInput,
+  UpdateContactMethodInput,
+  CreateBankAccountInput,
+  UpdateBankAccountInput,
+  SyncItem,
+  SyncResult,
+  MexClientFilter,
+  AVIClientFilter,
+} from "@artu-ai/shared";
+import {
+  CodigoActividad,
+  createAVIClientInputSchema,
+  updateAVIClientInputSchema,
+  linkedClientSchema,
+} from "@artu-ai/shared";
+import { MexClientsResource } from "../../clients";
+import { type BatchOptions, type ClientIncludeMap } from "../../../clients";
+import {
+  MexAVIClient,
+  MexAddress,
+  MexBankAccount,
+  ContactMethod,
+  LinkedClient,
+  type ClientData,
+} from "../../../../models";
+
+// ===========================
+// AVIClientsResource
+// ===========================
+
+/**
+ * AVI (Activos Virtuales) scoped clients resource.
+ *
+ * Provides the same operations as MexClientsResource but with:
+ * - Flattened input types (AVI fields at root level)
+ * - MexAVIClient model return type
+ *
+ * @example
+ * ```typescript
+ * const aviSdk = new ComplianceSDK({
+ *   apiKey,
+ *   environment: "test",
+ *   jurisdiction: Jurisdiction.Mexico,
+ *   actividadVulnerable: CodigoActividad.AVI,
+ * });
+ *
+ * // Create with fully flattened input
+ * const client = await aviSdk.clients.create({
+ *   type: ClientType.Person,
+ *   name: "Juan García",
+ *   rfc: "GAJL850101ABC",   // MX field
+ *   username: "JGARCIA",     // AVI field at root!
+ * });
+ *
+ * // Returns MexAVIClient
+ * console.log(client.username);
+ * ```
+ */
+export class AVIClientsResource extends MexClientsResource {
+  // ─────────────────────────────────────────────────────────────────
+  // CRUD Operations
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Creates a new AVI client with fully flattened input.
+   */
+  async create(data: CreateAVIClientInput): Promise<MexAVIClient> {
+    const validated = this.validate(createAVIClientInputSchema, 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<MexAVIClient> {
+    const response = await this.execute(() =>
+      this.trpc.clients.retrieve.query({ id, include })
+    );
+    return this.instantiate(response);
+  }
+
+  /**
+   * Retrieves an AVI client by externalId.
+   */
+  async retrieveByExternalId(externalId: string): Promise<MexAVIClient> {
+    const response = await this.execute(() =>
+      this.trpc.clients.retrieveByExternalId.query({ externalId })
+    );
+    return this.instantiate(response);
+  }
+
+  /**
+   * Updates an AVI client with flattened input.
+   */
+  async update(id: string, data: UpdateAVIClientInput): Promise<MexAVIClient> {
+    const validated = this.validate(updateAVIClientInputSchema, 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
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Lists AVI clients with optional filtering.
+   *
+   * Accepts fully flattened AVI filter (MX and AVI fields at root level)
+   * and automatically transforms to nested format before calling the API.
+   *
+   * @example
+   * ```typescript
+   * const { data } = await aviSdk.clients.list({
+   *   filter: {
+   *     name: { contains: "García" },
+   *     rfc: { startsWith: "GAJL" },  // MX field at root
+   *     username: { contains: "jgarcia" },  // AVI field at root!
+   *   },
+   * });
+   * ```
+   */
+  async list(
+    options?: ListOptions<AVIClientFilter>
+  ): Promise<PaginatedResponse<MexAVIClient>> {
+    const scopedFilter = this.applyScopeToFilter(options?.filter);
+
+    const response = await this.execute(() =>
+      this.trpc.clients.list.query({
+        ...options,
+        filter: scopedFilter,
+      })
+    );
+
+    return {
+      data: response.data.map((c) => this.instantiate(c)),
+      pagination: response.pagination,
+    };
+  }
+
+  /**
+   * Iterates over AVI clients.
+   *
+   * Accepts fully flattened AVI filter (MX and AVI fields at root level)
+   * and automatically transforms to nested format before calling the API.
+   */
+  iterate(
+    filter?: AVIClientFilter
+  ): AsyncGenerator<MexAVIClient, void, undefined> {
+    const scopedFilter = this.applyScopeToFilter(filter);
+    return this.createIterator<MexAVIClient>({ filter: scopedFilter });
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Batch Operations
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Creates multiple AVI clients with flattened input.
+   */
+  async createMany(
+    clients: CreateAVIClientInput[],
+    options?: { atomic?: true }
+  ): Promise<AtomicBatchResult<MexAVIClient>>;
+  async createMany(
+    clients: CreateAVIClientInput[],
+    options: { atomic: false }
+  ): Promise<PartialBatchResult<MexAVIClient>>;
+  async createMany(
+    clients: CreateAVIClientInput[],
+    options: BatchOptions = {}
+  ): Promise<
+    AtomicBatchResult<MexAVIClient> | PartialBatchResult<MexAVIClient>
+  > {
+    const atomic = options.atomic ?? true;
+    const validated = this.validate(
+      z.array(createAVIClientInputSchema),
+      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 AVI clients.
+   */
+  async updateMany(
+    updates: { id: string; data: UpdateAVIClientInput }[],
+    options?: { atomic?: true }
+  ): Promise<AtomicBatchResult<MexAVIClient>>;
+  async updateMany(
+    updates: { id: string; data: UpdateAVIClientInput }[],
+    options: { atomic: false }
+  ): Promise<PartialBatchResult<MexAVIClient>>;
+  async updateMany(
+    updates: { id: string; data: UpdateAVIClientInput }[],
+    options: BatchOptions = {}
+  ): Promise<
+    AtomicBatchResult<MexAVIClient> | PartialBatchResult<MexAVIClient>
+  > {
+    const atomic = options.atomic ?? true;
+    const updateItemSchema = z.object({
+      id: z.uuid(),
+      data: updateAVIClientInputSchema,
+    });
+
+    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<MexAVIClient> {
+    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<MexAVIClient> {
+    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<MexAVIClient> {
+    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)
+  // ─────────────────────────────────────────────────────────────────
+
+  async syncAll(
+    clientId: string,
+    data: {
+      client?: UpdateAVIClientInput;
+      addresses?: SyncItem<CreateMexAddressInput>[];
+      contactMethods?: SyncItem<CreateContactMethodInput>[];
+      bankAccounts?: SyncItem<CreateBankAccountInput>[];
+      linkedClients?: LinkedClientInput[];
+    },
+    options: { replaceMode: true }
+  ): Promise<{
+    client: MexAVIClient;
+    addresses: SyncResult<MexAddress>;
+    contactMethods: SyncResult<ContactMethod>;
+    bankAccounts: SyncResult<MexBankAccount>;
+  }>;
+  async syncAll(
+    clientId: string,
+    data: {
+      client?: UpdateAVIClientInput;
+      addresses?: SyncItem<UpdateMexAddressInput>[];
+      contactMethods?: SyncItem<UpdateContactMethodInput>[];
+      bankAccounts?: SyncItem<UpdateBankAccountInput>[];
+      linkedClients?: LinkedClientInput[];
+    },
+    options?: { replaceMode?: boolean }
+  ): Promise<{
+    client: MexAVIClient;
+    addresses: SyncResult<MexAddress>;
+    contactMethods: SyncResult<ContactMethod>;
+    bankAccounts: SyncResult<MexBankAccount>;
+  }>;
+  async syncAll(
+    clientId: string,
+    data: {
+      client?: UpdateAVIClientInput;
+      addresses?: SyncItem<UpdateMexAddressInput | CreateMexAddressInput>[];
+      contactMethods?: SyncItem<UpdateContactMethodInput | CreateContactMethodInput>[];
+      bankAccounts?: SyncItem<UpdateBankAccountInput | CreateBankAccountInput>[];
+      linkedClients?: LinkedClientInput[];
+    },
+    options?: { replaceMode?: boolean }
+  ): Promise<{
+    client: MexAVIClient;
+    addresses: SyncResult<MexAddress>;
+    contactMethods: SyncResult<ContactMethod>;
+    bankAccounts: SyncResult<MexBankAccount>;
+  }> {
+    // Transform client input using AVI-specific transform
+    const transformedClient = data.client
+      ? this.transformUpdateToNested(data.client)
+      : undefined;
+
+    // Call parent syncAll with transformed client data
+    const result = await super.syncAll(
+      clientId,
+      {
+        ...data,
+        client: transformedClient as UpdateMexClientInput,
+      },
+      options as { replaceMode?: boolean }
+    );
+
+    // Re-instantiate client with AVI-specific model
+    return {
+      ...result,
+      client: this.instantiate(result.client as unknown as ClientData),
+    };
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Protected Helpers
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Transforms a flattened AVIClientFilter to nested ClientFilter format
+   * and applies Mexico jurisdiction scoping.
+   *
+   * Extracts AVI-specific fields (username) from root level and nests them
+   * under jurisdictions.MX.actividadVulnerable.AVI.
+   */
+  protected override applyScopeToFilter(filter?: AVIClientFilter): ClientFilter {
+    if (!filter) {
+      return super.applyScopeToFilter(undefined);
+    }
+
+    // Extract AVI-specific filter fields
+    const { username, ...mexFilter } = filter;
+
+    // Let parent handle MX fields
+    const nestedFilter = super.applyScopeToFilter(
+      mexFilter as MexClientFilter
+    );
+
+    // Only add AVI activity filter if username is provided
+    if (username !== undefined) {
+      const mexJurisdiction = (nestedFilter.jurisdictions?.MX ?? {}) as Record<
+        string,
+        unknown
+      >;
+
+      return {
+        ...nestedFilter,
+        jurisdictions: {
+          ...nestedFilter.jurisdictions,
+          MX: {
+            ...mexJurisdiction,
+            actividadVulnerable: {
+              [CodigoActividad.AVI]: { username },
+            },
+          },
+        },
+      } as ClientFilter;
+    }
+
+    return nestedFilter;
+  }
+
+  /**
+   * Transforms flattened AVI input to nested API format.
+   */
+  protected override transformToNested(
+    data: CreateAVIClientInput
+  ): CreateClientInput {
+    // Extract AVI-specific field first
+    const { username, ...restData } = data as Record<string, unknown>;
+
+    // Use parent for base + MX fields
+    const nested = super.transformToNested(
+      restData as unknown as CreateMexClientInput
+    );
+
+    // Add AVI activity data (parent always provides jurisdictions.MX)
+    const mexData = nested.jurisdictions?.MX;
+
+    return {
+      ...nested,
+      jurisdictions: {
+        MX: {
+          ...mexData,
+          actividadVulnerable: {
+            [CodigoActividad.AVI]: { username },
+          },
+        },
+      },
+    } as CreateClientInput;
+  }
+
+  /**
+   * Transforms flattened AVI update input to nested API format.
+   */
+  protected override transformUpdateToNested(
+    data: UpdateAVIClientInput
+  ): UpdateClientInput {
+    // Extract AVI-specific field first
+    const { username, ...restData } = data as Record<string, unknown>;
+
+    // Use parent for base + MX fields
+    const nested = super.transformUpdateToNested(
+      restData as unknown as UpdateMexClientInput
+    );
+
+    // Only add AVI data if username is provided
+    if (username !== undefined) {
+      const mexData = ((nested.jurisdictions?.MX as Record<string, unknown>) ??
+        {}) as Record<string, unknown>;
+      mexData.actividadVulnerable = {
+        [CodigoActividad.AVI]: { username },
+      };
+
+      return {
+        ...nested,
+        jurisdictions: { MX: mexData },
+      } as UpdateClientInput;
+    }
+
+    return nested;
+  }
+
+  /**
+   * Instantiates a MexAVIClient model.
+   */
+  protected override instantiate(data: ClientData): MexAVIClient {
+    return new MexAVIClient(data);
+  }
+}

package/src/resources/mex/actividad-vulnerable/avi/index.ts

@@ -0,0 +1,7 @@
+/**
+ * AVI (Activos Virtuales) Scoped Resources
+ */
+
+export { AVIClientsResource } from "./clients";
+export { AVITransactionsResource } from "./transactions";
+export { AVIReportsResource } from "./reports";