@artu-ai/compliance-sdk 0.0.6 → 0.3.0

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

@@ -0,0 +1,404 @@
+/**
+ * AVI (Activos Virtuales) Transactions Resource
+ *
+ * Extends MexTransactionsResource with AVI-specific behavior:
+ * - Accepts flattened CreateAVITransactionInput (AVI fields at root level)
+ * - Returns MexAVITransaction models
+ */
+
+import { z } from "zod";
+import type {
+  CreateTransactionInput,
+  UpdateTransactionInput,
+  TransactionSort,
+  ListOptions,
+  PaginatedResponse,
+  CreateAVITransactionInput,
+  UpdateAVITransactionInput,
+  AtomicBatchResult,
+  PartialBatchResult,
+  RelatedClient,
+  AVITransactionFilter,
+  AVITransactionSort,
+} from "@artu-ai/shared";
+import {
+  Jurisdiction,
+  CodigoActividad,
+  createAVITransactionInputSchema,
+  updateAVITransactionInputSchema,
+  ClientRole,
+  transformSort,
+  aviTransactionFieldMapping,
+} from "@artu-ai/shared";
+import { MexTransactionsResource } from "../../transactions";
+import { type BatchOptions } from "../../../clients";
+import { MexAVITransaction, type TransactionData } from "../../../../models";
+
+// ===========================
+// AVITransactionsResource
+// ===========================
+
+/**
+ * AVI (Activos Virtuales) scoped transactions resource.
+ *
+ * @example
+ * ```typescript
+ * const aviSdk = new ComplianceSDK({
+ *   apiKey,
+ *   jurisdiction: Jurisdiction.Mexico,
+ *   actividadVulnerable: CodigoActividad.AVI,
+ * });
+ *
+ * // Create with fully flattened input
+ * const txn = await aviSdk.transactions.create({
+ *   amount: 50000,
+ *   currency: "MXN",
+ *   timestamp: new Date(),
+ *   operationType: "buy",
+ *   crypto: "BTC",
+ *   hash: "ABC123DEF456",
+ * });
+ *
+ * // Returns MexAVITransaction
+ * console.log(txn.operationType);
+ * ```
+ */
+export class AVITransactionsResource extends MexTransactionsResource<AVITransactionSort> {
+  // ─────────────────────────────────────────────────────────────────
+  // CRUD Operations
+  // ─────────────────────────────────────────────────────────────────
+
+  async create(data: CreateAVITransactionInput): Promise<MexAVITransaction> {
+    const validated = this.validate(createAVITransactionInputSchema, data);
+    const nestedData = this.transformToNested(validated);
+
+    const response = await this.execute(() =>
+      this.trpc.transactions.create.mutate(nestedData)
+    );
+
+    return this.instantiate(response);
+  }
+
+  async retrieve(id: string): Promise<MexAVITransaction> {
+    const response = await this.execute(() =>
+      this.trpc.transactions.retrieve.query({ id })
+    );
+    return this.instantiate(response);
+  }
+
+  async retrieveByMetadata(
+    key: string,
+    value: string
+  ): Promise<MexAVITransaction> {
+    const response = await this.execute(() =>
+      this.trpc.transactions.retrieveByMetadata.query({ key, value })
+    );
+    return this.instantiate(response);
+  }
+
+  async update(
+    id: string,
+    data: UpdateAVITransactionInput
+  ): Promise<MexAVITransaction> {
+    const validated = this.validate(updateAVITransactionInputSchema, data);
+    const nestedData = this.transformUpdateToNested(validated);
+
+    const response = await this.execute(() =>
+      this.trpc.transactions.update.mutate({ id, data: nestedData })
+    );
+    return this.instantiate(response);
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // List & Pagination
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Lists AVI transactions with optional filtering.
+   *
+   * Accepts flattened AVI filter (future AVI-specific transaction fields at root level).
+   */
+  async list(
+    options?: ListOptions<AVITransactionFilter, AVITransactionSort>
+  ): Promise<PaginatedResponse<MexAVITransaction>> {
+    const scopedFilter = this.applyScopeToFilter(options?.filter);
+    const scopedSort = this.applyScopeToSort(options?.sort);
+
+    const response = await this.execute(() =>
+      this.trpc.transactions.list.query({
+        ...options,
+        filter: scopedFilter,
+        sort: scopedSort,
+      })
+    );
+
+    return {
+      data: response.data.map((t) => this.instantiate(t)),
+      pagination: response.pagination,
+    };
+  }
+
+  /**
+   * Iterates over AVI transactions.
+   *
+   * Accepts flattened AVI filter (future AVI-specific transaction fields at root level).
+   */
+  iterate(
+    filter?: AVITransactionFilter
+  ): AsyncGenerator<MexAVITransaction, void, undefined> {
+    const scopedFilter = this.applyScopeToFilter(filter);
+    return this.createIterator<MexAVITransaction>({ filter: scopedFilter });
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Client Relationship Management (scoped returns)
+  // ─────────────────────────────────────────────────────────────────
+
+  async listByClient(
+    clientId: string,
+    options?: { cursor?: string; limit?: number }
+  ): Promise<PaginatedResponse<MexAVITransaction>> {
+    const response = await this.execute(() =>
+      this.trpc.transactions.listByClient.query({ clientId, ...options })
+    );
+
+    return {
+      data: response.data.map((t) => this.instantiate(t)),
+      pagination: response.pagination,
+    };
+  }
+
+  async linkClient(
+    transactionId: string,
+    clientId: string,
+    role?: ClientRole
+  ): Promise<MexAVITransaction> {
+    const response = await this.execute(() =>
+      this.trpc.transactions.linkClient.mutate({
+        transactionId,
+        clientId,
+        role,
+      })
+    );
+    return this.instantiate(response);
+  }
+
+  async unlinkClient(
+    transactionId: string,
+    clientId: string
+  ): Promise<MexAVITransaction> {
+    const response = await this.execute(() =>
+      this.trpc.transactions.unlinkClient.mutate({
+        transactionId,
+        clientId,
+      })
+    );
+    return this.instantiate(response);
+  }
+
+  async setClients(
+    transactionId: string,
+    clients: RelatedClient[]
+  ): Promise<MexAVITransaction> {
+    const response = await this.execute(() =>
+      this.trpc.transactions.setClients.mutate({
+        transactionId,
+        clients,
+      })
+    );
+    return this.instantiate(response);
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Batch Operations
+  // ─────────────────────────────────────────────────────────────────
+
+  async createMany(
+    transactions: CreateAVITransactionInput[],
+    options?: { atomic?: true }
+  ): Promise<AtomicBatchResult<MexAVITransaction>>;
+  async createMany(
+    transactions: CreateAVITransactionInput[],
+    options: { atomic: false }
+  ): Promise<PartialBatchResult<MexAVITransaction>>;
+  async createMany(
+    transactions: CreateAVITransactionInput[],
+    options: BatchOptions = {}
+  ): Promise<
+    AtomicBatchResult<MexAVITransaction> | PartialBatchResult<MexAVITransaction>
+  > {
+    const atomic = options.atomic ?? true;
+    const validated = this.validate(
+      z.array(createAVITransactionInputSchema),
+      transactions
+    );
+    const nestedItems = validated.map((t) => this.transformToNested(t));
+
+    const response = await this.execute(() =>
+      this.trpc.transactions.createMany.mutate({ items: nestedItems, atomic })
+    );
+
+    if (response.atomic) {
+      return {
+        atomic: true,
+        data: response.data.map((t) => this.instantiate(t)),
+      };
+    } else {
+      return {
+        atomic: false,
+        succeeded: response.succeeded.map((item) => ({
+          index: item.index,
+          data: this.instantiate(item.data),
+        })),
+        failed: response.failed,
+      };
+    }
+  }
+
+  async updateMany(
+    updates: { id: string; data: UpdateAVITransactionInput }[],
+    options?: { atomic?: true }
+  ): Promise<AtomicBatchResult<MexAVITransaction>>;
+  async updateMany(
+    updates: { id: string; data: UpdateAVITransactionInput }[],
+    options: { atomic: false }
+  ): Promise<PartialBatchResult<MexAVITransaction>>;
+  async updateMany(
+    updates: { id: string; data: UpdateAVITransactionInput }[],
+    options: BatchOptions = {}
+  ): Promise<
+    AtomicBatchResult<MexAVITransaction> | PartialBatchResult<MexAVITransaction>
+  > {
+    const atomic = options.atomic ?? true;
+    const updateItemSchema = z.object({
+      id: z.uuid(),
+      data: updateAVITransactionInputSchema,
+    });
+
+    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.transactions.updateMany.mutate({ items: nestedUpdates, atomic })
+    );
+
+    if (response.atomic) {
+      return {
+        atomic: true,
+        data: response.data.map((t) => this.instantiate(t)),
+      };
+    } else {
+      return {
+        atomic: false,
+        succeeded: response.succeeded.map((item) => ({
+          index: item.index,
+          data: this.instantiate(item.data),
+        })),
+        failed: response.failed,
+      };
+    }
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Protected Helpers
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Transforms a flattened AVITransactionSort to nested TransactionSort format.
+   *
+   * Maps flattened field names to their full API paths.
+   */
+  protected override applyScopeToSort(sort?: AVITransactionSort): TransactionSort | undefined {
+    if (!sort || sort.length === 0) {
+      return undefined;
+    }
+    return transformSort(sort, aviTransactionFieldMapping);
+  }
+
+  protected override transformToNested(
+    data: CreateAVITransactionInput
+  ): CreateTransactionInput {
+    // Extract AVI-specific fields based on operation type
+    const {
+      amount,
+      currency,
+      timestamp,
+      relatedClientIds,
+      description,
+      externalId,
+      metadata,
+      ...aviFields
+    } = data as Record<string, unknown>;
+
+    // Build base fields (relatedClientIds is required)
+    const baseFields: Record<string, unknown> = {
+      amount,
+      currency,
+      timestamp,
+      relatedClientIds,
+    };
+    if (description !== undefined) baseFields.description = description;
+    if (externalId !== undefined) baseFields.externalId = externalId;
+    if (metadata !== undefined) baseFields.metadata = metadata;
+
+    return {
+      ...baseFields,
+      primaryJurisdiction: Jurisdiction.Mexico,
+      jurisdictions: {
+        MX: {
+          actividadVulnerable: {
+            [CodigoActividad.AVI]: aviFields,
+          },
+        },
+      },
+    } as CreateTransactionInput;
+  }
+
+  protected override transformUpdateToNested(
+    data: UpdateAVITransactionInput
+  ): UpdateTransactionInput {
+    // Cast to access fields - Zod validation ensures correctness
+    const input = data as Record<string, unknown>;
+    const {
+      status,
+      description,
+      externalId,
+      metadata,
+      primaryJurisdiction,
+      ...aviFields
+    } = input;
+
+    // Build base update fields
+    const result: UpdateTransactionInput = {};
+    if (status !== undefined)
+      result.status = status as UpdateTransactionInput["status"];
+    if (description !== undefined) result.description = description as string;
+    if (externalId !== undefined) result.externalId = externalId as string;
+    if (metadata !== undefined)
+      result.metadata = metadata as Record<string, unknown>;
+    if (primaryJurisdiction !== undefined)
+      result.primaryJurisdiction =
+        primaryJurisdiction as UpdateTransactionInput["primaryJurisdiction"];
+
+    // If AVI fields are present (all-or-nothing), nest them in jurisdictions
+    // Check for operationType as the indicator that AVI data is being updated
+    if (aviFields.operationType !== undefined) {
+      (result as Record<string, unknown>).jurisdictions = {
+        MX: {
+          actividadVulnerable: {
+            [CodigoActividad.AVI]: aviFields,
+          },
+        },
+      };
+    }
+
+    return result;
+  }
+
+  protected override instantiate(data: TransactionData): MexAVITransaction {
+    return new MexAVITransaction(data);
+  }
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Actividad Vulnerable Scoped Resources
+ */
+
+// AVI (Activos Virtuales)
+export * from "./avi";
+
+// JYS (Juegos y Sorteos)
+export * from "./jys";
+
+// TSC (Tarjetas de Servicio y Crédito)
+export * from "./tsc";