@artu-ai/compliance-sdk 0.0.6 → 0.3.0

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

@@ -0,0 +1,609 @@
+/**
+ * AVI (Activos Virtuales) Reports Resource
+ *
+ * Extends MexReportsResource with AVI-specific behavior:
+ * - Accepts flattened CreateAVIReportInput (AVI fields at root level)
+ * - Returns MexAVIReport models
+ */
+
+import { z } from "zod";
+import type {
+  CreateReportInput,
+  UpdateReportInput,
+  CreateReportItemInput,
+  UpdateReportItemInput,
+  CreateAVIReportInput,
+  UpdateAVIReportInput,
+  CreateAVIReportItemInput,
+  UpdateAVIReportItemInput,
+  ListOptions,
+  PaginatedResponse,
+  AtomicBatchResult,
+  PartialBatchResult,
+  ValidationResult,
+  GenerateResult,
+  SubmissionResult,
+  AviReportDefaultsInput,
+  SubmitAVIReportInput,
+} from "@artu-ai/shared";
+import {
+  CodigoActividad,
+  createAVIReportInputSchema,
+  updateAVIReportInputSchema,
+  createAVIReportItemInputSchema,
+  updateAVIReportItemInputSchema,
+  aviDefaultsInputSchema,
+  submitAVIReportInputSchema,
+  transformSort,
+  aviReportFieldMapping,
+} from "@artu-ai/shared";
+import type {
+  AVIReportFilter,
+  AVIReportSort,
+  AVIReportItemFilter,
+  ReportSort,
+  ReportItemFilter,
+  ReportItemSort,
+} from "@artu-ai/shared";
+import { MexReportsResource } from "../../reports";
+import { type BatchOptions } from "../../../clients";
+import {
+  MexAVIReport,
+  MexAVIReportItem,
+  type ReportData,
+  type ReportItemData,
+} from "../../../../models";
+
+// ===========================
+// AVIReportsResource
+// ===========================
+
+/**
+ * AVI (Activos Virtuales) scoped reports resource.
+ *
+ * @example
+ * ```typescript
+ * const aviSdk = new ComplianceSDK({
+ *   apiKey,
+ *   jurisdiction: Jurisdiction.Mexico,
+ *   actividadVulnerable: CodigoActividad.AVI,
+ * });
+ *
+ * // Create with fully flattened input
+ * const report = await aviSdk.reports.create({
+ *   mesReportado: "202401",
+ * });
+ *
+ * // Returns MexAVIReport
+ * console.log(report.mesReportado);
+ * ```
+ */
+export class AVIReportsResource extends MexReportsResource<AVIReportSort, AviReportDefaultsInput> {
+  // ─────────────────────────────────────────────────────────────────
+  // Report CRUD
+  // ─────────────────────────────────────────────────────────────────
+
+  async create(data: CreateAVIReportInput): Promise<MexAVIReport> {
+    const validated = this.validate(createAVIReportInputSchema, data);
+    const nestedData = this.transformToNested(validated);
+
+    const response = await this.execute(() =>
+      this.trpc.reports.create.mutate(nestedData)
+    );
+
+    return this.instantiate(response);
+  }
+
+  async retrieve(id: string): Promise<MexAVIReport> {
+    const response = await this.execute(() =>
+      this.trpc.reports.retrieve.query({ id })
+    );
+    return this.instantiate(response);
+  }
+
+  async retrieveByMetadata(key: string, value: string): Promise<MexAVIReport> {
+    const response = await this.execute(() =>
+      this.trpc.reports.retrieveByMetadata.query({ key, value })
+    );
+    return this.instantiate(response);
+  }
+
+  async retrieveByExternalId(externalId: string): Promise<MexAVIReport> {
+    const response = await this.execute(() =>
+      this.trpc.reports.retrieveByExternalId.query({ externalId })
+    );
+    return this.instantiate(response);
+  }
+
+  async update(id: string, data: UpdateAVIReportInput): Promise<MexAVIReport> {
+    const validated = this.validate(updateAVIReportInputSchema, data);
+    const nestedData = this.transformUpdateToNested(validated);
+
+    const response = await this.execute(() =>
+      this.trpc.reports.update.mutate({ id, data: nestedData })
+    );
+    return this.instantiate(response);
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // List & Pagination
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Lists AVI reports with optional filtering.
+   *
+   * Accepts flattened AVI filter (future AVI-specific report fields at root level).
+   */
+  async list(
+    options?: ListOptions<AVIReportFilter, AVIReportSort>
+  ): Promise<PaginatedResponse<MexAVIReport>> {
+    const scopedFilter = this.applyScopeToFilter(options?.filter);
+    const scopedSort = this.applyScopeToSort(options?.sort);
+
+    const response = await this.execute(() =>
+      this.trpc.reports.list.query({
+        ...options,
+        filter: scopedFilter,
+        sort: scopedSort,
+      })
+    );
+
+    return {
+      data: response.data.map((r) => this.instantiate(r)),
+      pagination: response.pagination,
+    };
+  }
+
+  /**
+   * Iterates over AVI reports.
+   *
+   * Accepts flattened AVI filter (future AVI-specific report fields at root level).
+   */
+  iterate(
+    filter?: AVIReportFilter
+  ): AsyncGenerator<MexAVIReport, void, undefined> {
+    const scopedFilter = this.applyScopeToFilter(filter);
+    return this.createIterator<MexAVIReport>({ filter: scopedFilter });
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Batch Operations
+  // ─────────────────────────────────────────────────────────────────
+
+  async createMany(
+    reports: CreateAVIReportInput[],
+    options?: { atomic?: true }
+  ): Promise<AtomicBatchResult<MexAVIReport>>;
+  async createMany(
+    reports: CreateAVIReportInput[],
+    options: { atomic: false }
+  ): Promise<PartialBatchResult<MexAVIReport>>;
+  async createMany(
+    reports: CreateAVIReportInput[],
+    options: BatchOptions = {}
+  ): Promise<
+    AtomicBatchResult<MexAVIReport> | PartialBatchResult<MexAVIReport>
+  > {
+    const atomic = options.atomic ?? true;
+    const validated = this.validate(
+      z.array(createAVIReportInputSchema),
+      reports
+    );
+    const nestedItems = validated.map((r) => this.transformToNested(r));
+
+    const response = await this.execute(() =>
+      this.trpc.reports.createMany.mutate({ items: nestedItems, atomic })
+    );
+
+    if (response.atomic) {
+      return {
+        atomic: true,
+        data: response.data.map((r) => this.instantiate(r)),
+      };
+    } 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: UpdateAVIReportInput }[],
+    options?: { atomic?: true }
+  ): Promise<AtomicBatchResult<MexAVIReport>>;
+  async updateMany(
+    updates: { id: string; data: UpdateAVIReportInput }[],
+    options: { atomic: false }
+  ): Promise<PartialBatchResult<MexAVIReport>>;
+  async updateMany(
+    updates: { id: string; data: UpdateAVIReportInput }[],
+    options: BatchOptions = {}
+  ): Promise<
+    AtomicBatchResult<MexAVIReport> | PartialBatchResult<MexAVIReport>
+  > {
+    const atomic = options.atomic ?? true;
+    const updateItemSchema = z.object({
+      id: z.uuid(),
+      data: updateAVIReportInputSchema,
+    });
+
+    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.reports.updateMany.mutate({ items: nestedUpdates, atomic })
+    );
+
+    if (response.atomic) {
+      return {
+        atomic: true,
+        data: response.data.map((r) => this.instantiate(r)),
+      };
+    } else {
+      return {
+        atomic: false,
+        succeeded: response.succeeded.map((item) => ({
+          index: item.index,
+          data: this.instantiate(item.data),
+        })),
+        failed: response.failed,
+      };
+    }
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Report Items
+  // ─────────────────────────────────────────────────────────────────
+
+  async addItem(
+    reportId: string,
+    data: CreateAVIReportItemInput
+  ): Promise<MexAVIReportItem> {
+    const validated = this.validate(createAVIReportItemInputSchema, data);
+    const nestedData = this.transformItemToNested(validated);
+
+    const response = await this.execute(() =>
+      this.trpc.reports.addItem.mutate({ reportId, data: nestedData })
+    );
+
+    return this.instantiateItem(response);
+  }
+
+  async getItem(reportId: string, itemId: string): Promise<MexAVIReportItem> {
+    const response = await this.execute(() =>
+      this.trpc.reports.getItem.query({ reportId, itemId })
+    );
+    return this.instantiateItem(response);
+  }
+
+  async updateItem(
+    reportId: string,
+    itemId: string,
+    data: UpdateAVIReportItemInput
+  ): Promise<MexAVIReportItem> {
+    const validated = this.validate(updateAVIReportItemInputSchema, data);
+    const nestedData = this.transformItemUpdateToNested(validated);
+
+    const response = await this.execute(() =>
+      this.trpc.reports.updateItem.mutate({
+        reportId,
+        itemId,
+        data: nestedData,
+      })
+    );
+    return this.instantiateItem(response);
+  }
+
+  async listItems(
+    reportId: string,
+    options?: ListOptions<AVIReportItemFilter, ReportItemSort>
+  ): Promise<PaginatedResponse<MexAVIReportItem>> {
+    // Transform flattened AVI filter to nested format
+    const scopedFilter = this.applyScopeToItemFilter(options?.filter);
+
+    const response = await this.execute(() =>
+      this.trpc.reports.listItems.query({
+        reportId,
+        ...options,
+        filter: scopedFilter,
+      })
+    );
+
+    return {
+      data: response.data.map((i) => this.instantiateItem(i)),
+      pagination: response.pagination,
+    };
+  }
+
+  /**
+   * Transforms a flattened AVIReportItemFilter to nested ReportItemFilter format.
+   */
+  protected applyScopeToItemFilter(
+    filter?: AVIReportItemFilter
+  ): ReportItemFilter | undefined {
+    if (!filter) return undefined;
+
+    const { alertType, alertDescription, ...baseFields } = filter;
+
+    // If no AVI-specific fields, return base filter as-is
+    if (alertType === undefined && alertDescription === undefined) {
+      return baseFields as ReportItemFilter;
+    }
+
+    // Build nested filter structure
+    const aviFilter: Record<string, unknown> = {};
+    if (alertType !== undefined) aviFilter.alertType = alertType;
+    if (alertDescription !== undefined) aviFilter.alertDescription = alertDescription;
+
+    return {
+      ...baseFields,
+      jurisdictions: {
+        MX: {
+          actividadVulnerable: {
+            AVI: aviFilter,
+          },
+        },
+      },
+    } as ReportItemFilter;
+  }
+
+  async addItems(
+    reportId: string,
+    items: CreateAVIReportItemInput[]
+  ): Promise<{ added: number; items: MexAVIReportItem[] }> {
+    const validated = this.validate(
+      z.array(createAVIReportItemInputSchema),
+      items
+    );
+    const nestedItems = validated.map((i) => this.transformItemToNested(i));
+
+    const response = await this.execute(() =>
+      this.trpc.reports.addItems.mutate({ reportId, items: nestedItems })
+    );
+
+    return {
+      added: response.added,
+      items: response.items.map((i) => this.instantiateItem(i)),
+    };
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Validation
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Validates an AVI report.
+   *
+   * Uses AVI-scoped validation input (jurisdiction and activity are implicit).
+   *
+   * @param reportId - The report ID to validate
+   * @param defaults - AVI report defaults including rfc, platformDomain, alertType, etc.
+   *
+   * @example
+   * ```typescript
+   * const result = await aviSdk.reports.validateReport(report.id, {
+   *   rfc: "ABC200101XXX",
+   *   platformDomain: "https://example.com",
+   *   alertType: "100",
+   * });
+   * ```
+   */
+  override async validateReport(
+    reportId: string,
+    defaults: AviReportDefaultsInput
+  ): Promise<ValidationResult> {
+    const validated = this.validate(aviDefaultsInputSchema, defaults);
+    const nestedInput = this.transformAviDefaultsToNested(reportId, validated);
+    return this.execute(() =>
+      this.trpc.reports.validate.mutate(nestedInput as Parameters<typeof this.trpc.reports.validate.mutate>[0])
+    );
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Generation
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Generates XML for an AVI report.
+   *
+   * Uses the same input as validateReport.
+   *
+   * @param reportId - The report ID to generate XML for
+   * @param defaults - AVI report defaults including rfc, platformDomain, alertType, etc.
+   *
+   * @example
+   * ```typescript
+   * const result = await aviSdk.reports.generateReport(report.id, {
+   *   rfc: "ABC200101XXX",
+   *   platformDomain: "https://example.com",
+   *   alertType: "100",
+   * });
+   * console.log(result.xml);
+   * ```
+   */
+  override async generateReport(
+    reportId: string,
+    defaults: AviReportDefaultsInput
+  ): Promise<GenerateResult> {
+    const validated = this.validate(aviDefaultsInputSchema, defaults);
+    const nestedInput = this.transformAviDefaultsToNested(reportId, validated);
+    return this.execute(() =>
+      this.trpc.reports.generate.mutate(
+        nestedInput as Parameters<typeof this.trpc.reports.generate.mutate>[0]
+      )
+    );
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Submission
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Submits a validated AVI report.
+   *
+   * Uses AVI-scoped submission input (activity is implicit).
+   *
+   * @example
+   * ```typescript
+   * const result = await aviSdk.reports.submit({
+   *   reportId: report.id,
+   *   acuseRecibo: "SAT-12345",
+   *   notes: "Submitted via portal",
+   * });
+   * ```
+   */
+  override async submit(
+    input: SubmitAVIReportInput
+  ): Promise<SubmissionResult> {
+    const validated = this.validate(submitAVIReportInputSchema, input);
+
+    const jurisdictions = {
+      MX: {
+        actividadVulnerable: {
+          [CodigoActividad.AVI]: {
+            acuseRecibo: validated.acuseRecibo,
+            notes: validated.notes,
+          },
+        },
+      },
+    };
+
+    return this.execute(() =>
+      this.trpc.reports.submit.mutate({
+        reportId: validated.reportId,
+        jurisdictions,
+      })
+    );
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Protected Helpers
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Transforms a flattened AVIReportSort to nested ReportSort format.
+   *
+   * Maps flattened field names to their full API paths.
+   */
+  protected override applyScopeToSort(sort?: AVIReportSort): ReportSort | undefined {
+    if (!sort || sort.length === 0) {
+      return undefined;
+    }
+    return transformSort(sort, aviReportFieldMapping);
+  }
+
+  protected override transformToNested(
+    data: CreateAVIReportInput
+  ): CreateReportInput {
+    const { mesReportado, ...baseFields } = data;
+
+    return {
+      ...baseFields,
+      jurisdictions: {
+        MX: {
+          actividadVulnerable: {
+            [CodigoActividad.AVI]: { mesReportado },
+          },
+        },
+      },
+    } as CreateReportInput;
+  }
+
+  protected override transformUpdateToNested(
+    data: UpdateAVIReportInput
+  ): UpdateReportInput {
+    return data as UpdateReportInput;
+  }
+
+  protected override instantiate(data: ReportData): MexAVIReport {
+    return new MexAVIReport(data);
+  }
+
+  protected override instantiateItem(data: ReportItemData): MexAVIReportItem {
+    return new MexAVIReportItem(data);
+  }
+
+  protected transformItemToNested(
+    data: CreateAVIReportItemInput
+  ): CreateReportItemInput {
+    const { alertType, alertDescription, amendment, ...baseFields } = data;
+
+    const aviData: Record<string, unknown> = {};
+    if (alertType !== undefined) aviData.alertType = alertType;
+    if (alertDescription !== undefined)
+      aviData.alertDescription = alertDescription;
+    if (amendment !== undefined) aviData.amendment = amendment;
+
+    return {
+      ...baseFields,
+      jurisdictions: {
+        MX: {
+          actividadVulnerable: {
+            [CodigoActividad.AVI]: aviData,
+          },
+        },
+      },
+    } as CreateReportItemInput;
+  }
+
+  protected transformItemUpdateToNested(
+    data: UpdateAVIReportItemInput
+  ): UpdateReportItemInput {
+    const { alertType, alertDescription, amendment, ...baseFields } = data;
+
+    const aviData: Record<string, unknown> = {};
+    if (alertType !== undefined) aviData.alertType = alertType;
+    if (alertDescription !== undefined)
+      aviData.alertDescription = alertDescription;
+    if (amendment !== undefined) aviData.amendment = amendment;
+
+    if (Object.keys(aviData).length === 0) {
+      return baseFields as UpdateReportItemInput;
+    }
+
+    return {
+      ...baseFields,
+      jurisdictions: {
+        MX: {
+          actividadVulnerable: {
+            [CodigoActividad.AVI]: aviData,
+          },
+        },
+      },
+    } as UpdateReportItemInput;
+  }
+
+  /**
+   * Transforms AVI defaults to nested API format for validate/generate.
+   */
+  protected transformAviDefaultsToNested(
+    reportId: string,
+    defaults: AviReportDefaultsInput
+  ): { reportId: string; jurisdictions: unknown } {
+    const { rfc, collegiateEntityCode, exempt, priority, ...aviFields } =
+      defaults;
+
+    return {
+      reportId,
+      jurisdictions: {
+        MX: {
+          actividadVulnerable: {
+            rfc,
+            collegiateEntityCode,
+            exempt,
+            priority,
+            [CodigoActividad.AVI]: aviFields,
+          },
+        },
+      },
+    };
+  }
+}