@artu-ai/compliance-sdk 0.0.5 → 0.2.0

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

@@ -0,0 +1,489 @@
+/**
+ * TSC (Tarjetas de Servicio y Crédito) Reports Resource
+ *
+ * Extends MexReportsResource with TSC-specific behavior:
+ * - Accepts flattened CreateTSCReportInput (TSC fields at root level)
+ * - Returns MexTSCReport models
+ */
+
+import { z } from "zod";
+import type {
+  CreateReportInput,
+  UpdateReportInput,
+  CreateReportItemInput,
+  UpdateReportItemInput,
+  CreateTSCReportInput,
+  UpdateTSCReportInput,
+  CreateTSCReportItemInput,
+  UpdateTSCReportItemInput,
+  ListOptions,
+  PaginatedResponse,
+  AtomicBatchResult,
+  PartialBatchResult,
+  MexTSCValidateInput,
+  ValidationResult,
+  GenerateResult,
+  SubmissionResult,
+  SubmitTSCSubmissionInput,
+} from "@artu-ai/shared";
+import {
+  CodigoActividad,
+  createTSCReportInputSchema,
+  updateTSCReportInputSchema,
+  createTSCReportItemInputSchema,
+  updateTSCReportItemInputSchema,
+  mexTscValidateInputSchema,
+  submitTSCSubmissionInputSchema,
+} from "@artu-ai/shared";
+import type { TSCReportFilter } from "@artu-ai/shared";
+import { MexReportsResource } from "../../reports";
+import { type ReportItemFilter } from "../../../reports";
+import { type BatchOptions } from "../../../clients";
+import {
+  MexTSCReport,
+  MexTSCReportItem,
+  type ReportData,
+  type ReportItemData,
+} from "../../../../models";
+
+// ===========================
+// TSCReportsResource
+// ===========================
+
+/**
+ * TSC (Tarjetas de Servicio y Crédito) scoped reports resource.
+ *
+ * @example
+ * ```typescript
+ * const tscSdk = new ComplianceSDK({
+ *   apiKey,
+ *   jurisdiction: Jurisdiction.Mexico,
+ *   actividadVulnerable: CodigoActividad.TSC,
+ * });
+ *
+ * // Create with fully flattened input
+ * const report = await tscSdk.reports.create({
+ *   mesReportado: "202401",
+ * });
+ *
+ * // Returns MexTSCReport
+ * console.log(report.mesReportado);
+ * ```
+ */
+export class TSCReportsResource extends MexReportsResource {
+  // ─────────────────────────────────────────────────────────────────
+  // Report CRUD
+  // ─────────────────────────────────────────────────────────────────
+
+  async create(data: CreateTSCReportInput): Promise<MexTSCReport> {
+    const validated = this.validate(createTSCReportInputSchema, 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<MexTSCReport> {
+    const response = await this.execute(() =>
+      this.trpc.reports.retrieve.query({ id })
+    );
+    return this.instantiate(response);
+  }
+
+  async retrieveByMetadata(key: string, value: string): Promise<MexTSCReport> {
+    const response = await this.execute(() =>
+      this.trpc.reports.retrieveByMetadata.query({ key, value })
+    );
+    return this.instantiate(response);
+  }
+
+  async retrieveByExternalId(externalId: string): Promise<MexTSCReport> {
+    const response = await this.execute(() =>
+      this.trpc.reports.retrieveByExternalId.query({ externalId })
+    );
+    return this.instantiate(response);
+  }
+
+  async update(id: string, data: UpdateTSCReportInput): Promise<MexTSCReport> {
+    const validated = this.validate(updateTSCReportInputSchema, 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 TSC reports with optional filtering.
+   *
+   * Accepts flattened TSC filter (future TSC-specific report fields at root level).
+   */
+  async list(
+    options?: ListOptions<TSCReportFilter>
+  ): Promise<PaginatedResponse<MexTSCReport>> {
+    const scopedFilter = this.applyScopeToFilter(options?.filter);
+
+    const response = await this.execute(() =>
+      this.trpc.reports.list.query({
+        ...options,
+        filter: scopedFilter,
+      })
+    );
+
+    return {
+      data: response.data.map((r) => this.instantiate(r)),
+      pagination: response.pagination,
+    };
+  }
+
+  /**
+   * Iterates over TSC reports.
+   *
+   * Accepts flattened TSC filter (future TSC-specific report fields at root level).
+   */
+  iterate(
+    filter?: TSCReportFilter
+  ): AsyncGenerator<MexTSCReport, void, undefined> {
+    const scopedFilter = this.applyScopeToFilter(filter);
+    return this.createIterator<MexTSCReport>({ filter: scopedFilter });
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Batch Operations
+  // ─────────────────────────────────────────────────────────────────
+
+  async createMany(
+    reports: CreateTSCReportInput[],
+    options?: { atomic?: true }
+  ): Promise<AtomicBatchResult<MexTSCReport>>;
+  async createMany(
+    reports: CreateTSCReportInput[],
+    options: { atomic: false }
+  ): Promise<PartialBatchResult<MexTSCReport>>;
+  async createMany(
+    reports: CreateTSCReportInput[],
+    options: BatchOptions = {}
+  ): Promise<
+    AtomicBatchResult<MexTSCReport> | PartialBatchResult<MexTSCReport>
+  > {
+    const atomic = options.atomic ?? true;
+    const validated = this.validate(
+      z.array(createTSCReportInputSchema),
+      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: UpdateTSCReportInput }[],
+    options?: { atomic?: true }
+  ): Promise<AtomicBatchResult<MexTSCReport>>;
+  async updateMany(
+    updates: { id: string; data: UpdateTSCReportInput }[],
+    options: { atomic: false }
+  ): Promise<PartialBatchResult<MexTSCReport>>;
+  async updateMany(
+    updates: { id: string; data: UpdateTSCReportInput }[],
+    options: BatchOptions = {}
+  ): Promise<
+    AtomicBatchResult<MexTSCReport> | PartialBatchResult<MexTSCReport>
+  > {
+    const atomic = options.atomic ?? true;
+    const updateItemSchema = z.object({
+      id: z.uuid(),
+      data: updateTSCReportInputSchema,
+    });
+
+    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: CreateTSCReportItemInput
+  ): Promise<MexTSCReportItem> {
+    const validated = this.validate(createTSCReportItemInputSchema, 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<MexTSCReportItem> {
+    const response = await this.execute(() =>
+      this.trpc.reports.getItem.query({ reportId, itemId })
+    );
+    return this.instantiateItem(response);
+  }
+
+  async updateItem(
+    reportId: string,
+    itemId: string,
+    data: UpdateTSCReportItemInput
+  ): Promise<MexTSCReportItem> {
+    const validated = this.validate(updateTSCReportItemInputSchema, 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<ReportItemFilter>
+  ): Promise<PaginatedResponse<MexTSCReportItem>> {
+    const response = await this.execute(() =>
+      this.trpc.reports.listItems.query({
+        reportId,
+        ...options,
+      })
+    );
+
+    return {
+      data: response.data.map((i) => this.instantiateItem(i)),
+      pagination: response.pagination,
+    };
+  }
+
+  async addItems(
+    reportId: string,
+    items: CreateTSCReportItemInput[]
+  ): Promise<{ added: number; items: MexTSCReportItem[] }> {
+    const validated = this.validate(
+      z.array(createTSCReportItemInputSchema),
+      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 a TSC report.
+   *
+   * Uses TSC-scoped validation input (jurisdiction and activity are implicit).
+   *
+   * @example
+   * ```typescript
+   * const result = await tscSdk.reports.validateReport({
+   *   reportId: report.id,
+   *   defaults: { rfc: "ABC200101XXX" },
+   * });
+   * ```
+   */
+  override async validateReport(
+    input: MexTSCValidateInput
+  ): Promise<ValidationResult> {
+    const validated = this.validate(mexTscValidateInputSchema, input);
+    return this.execute(() => this.trpc.reports.validate.mutate(validated));
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Generation
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Generates XML for a TSC report.
+   *
+   * Uses the same input as validateReport.
+   */
+  override async generateReport(
+    input: MexTSCValidateInput
+  ): Promise<GenerateResult> {
+    const validated = this.validate(mexTscValidateInputSchema, input);
+    return this.execute(() => this.trpc.reports.generate.mutate(validated));
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Submission
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Submits a validated TSC report.
+   *
+   * Uses TSC-scoped submission input (activity is implicit).
+   */
+  override async submit(
+    input: SubmitTSCSubmissionInput
+  ): Promise<SubmissionResult> {
+    const validated = this.validate(submitTSCSubmissionInputSchema, input);
+
+    const jurisdictions = {
+      MX: {
+        actividadVulnerable: {
+          [CodigoActividad.TSC]: {
+            acuseRecibo: validated.acuseRecibo,
+            notes: validated.notes,
+          },
+        },
+      },
+    };
+
+    return this.execute(() =>
+      this.trpc.reports.submit.mutate({
+        reportId: validated.reportId,
+        jurisdictions,
+      })
+    );
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Protected Helpers
+  // ─────────────────────────────────────────────────────────────────
+
+  protected override transformToNested(
+    data: CreateTSCReportInput
+  ): CreateReportInput {
+    const { mesReportado, ...baseFields } = data;
+
+    return {
+      ...baseFields,
+      jurisdictions: {
+        MX: {
+          actividadVulnerable: {
+            [CodigoActividad.TSC]: { mesReportado },
+          },
+        },
+      },
+    } as CreateReportInput;
+  }
+
+  protected override transformUpdateToNested(
+    data: UpdateTSCReportInput
+  ): UpdateReportInput {
+    return data as UpdateReportInput;
+  }
+
+  protected override instantiate(data: ReportData): MexTSCReport {
+    return new MexTSCReport(data);
+  }
+
+  protected override instantiateItem(data: ReportItemData): MexTSCReportItem {
+    return new MexTSCReportItem(data);
+  }
+
+  protected transformItemToNested(
+    data: CreateTSCReportItemInput
+  ): CreateReportItemInput {
+    const { alertType, alertDescription, amendment, ...baseFields } = data;
+
+    const tscData: Record<string, unknown> = {};
+    if (alertType !== undefined) tscData.alertType = alertType;
+    if (alertDescription !== undefined)
+      tscData.alertDescription = alertDescription;
+    if (amendment !== undefined) tscData.amendment = amendment;
+
+    return {
+      ...baseFields,
+      jurisdictions: {
+        MX: {
+          actividadVulnerable: {
+            [CodigoActividad.TSC]: tscData,
+          },
+        },
+      },
+    } as CreateReportItemInput;
+  }
+
+  protected transformItemUpdateToNested(
+    data: UpdateTSCReportItemInput
+  ): UpdateReportItemInput {
+    const { alertType, alertDescription, amendment, ...baseFields } = data;
+
+    const tscData: Record<string, unknown> = {};
+    if (alertType !== undefined) tscData.alertType = alertType;
+    if (alertDescription !== undefined)
+      tscData.alertDescription = alertDescription;
+    if (amendment !== undefined) tscData.amendment = amendment;
+
+    if (Object.keys(tscData).length === 0) {
+      return baseFields as UpdateReportItemInput;
+    }
+
+    return {
+      ...baseFields,
+      jurisdictions: {
+        MX: {
+          actividadVulnerable: {
+            [CodigoActividad.TSC]: tscData,
+          },
+        },
+      },
+    } as UpdateReportItemInput;
+  }
+}