@artu-ai/compliance-sdk 0.0.6 → 0.3.0

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

@@ -0,0 +1,591 @@
+/**
+ * JYS (Juegos y Sorteos) Reports Resource
+ *
+ * Extends MexReportsResource with JYS-specific behavior:
+ * - Accepts flattened CreateJYSReportInput (JYS fields at root level)
+ * - Returns MexJYSReport models
+ */
+
+import { z } from "zod";
+import type {
+  CreateReportInput,
+  UpdateReportInput,
+  CreateReportItemInput,
+  UpdateReportItemInput,
+  CreateJYSReportInput,
+  UpdateJYSReportInput,
+  CreateJYSReportItemInput,
+  UpdateJYSReportItemInput,
+  ListOptions,
+  PaginatedResponse,
+  AtomicBatchResult,
+  PartialBatchResult,
+  JysReportDefaultsInput,
+  ValidationResult,
+  GenerateResult,
+  SubmissionResult,
+  SubmitJYSSubmissionInput,
+} from "@artu-ai/shared";
+import {
+  CodigoActividad,
+  createJYSReportInputSchema,
+  updateJYSReportInputSchema,
+  createJYSReportItemInputSchema,
+  updateJYSReportItemInputSchema,
+  jysDefaultsInputSchema,
+  submitJYSSubmissionInputSchema,
+  transformSort,
+  jysReportFieldMapping,
+} from "@artu-ai/shared";
+import type {
+  JYSReportFilter,
+  JYSReportSort,
+  JYSReportItemFilter,
+  ReportSort,
+  ReportItemFilter,
+  ReportItemSort,
+} from "@artu-ai/shared";
+import { MexReportsResource } from "../../reports";
+import { type BatchOptions } from "../../../clients";
+import {
+  MexJYSReport,
+  MexJYSReportItem,
+  type ReportData,
+  type ReportItemData,
+} from "../../../../models";
+
+// ===========================
+// JYSReportsResource
+// ===========================
+
+/**
+ * JYS (Juegos y Sorteos) scoped reports resource.
+ *
+ * @example
+ * ```typescript
+ * const jysSdk = new ComplianceSDK({
+ *   apiKey,
+ *   jurisdiction: Jurisdiction.Mexico,
+ *   actividadVulnerable: CodigoActividad.JYS,
+ * });
+ *
+ * // Create with fully flattened input
+ * const report = await jysSdk.reports.create({
+ *   mesReportado: "202401",
+ * });
+ *
+ * // Returns MexJYSReport
+ * console.log(report.mesReportado);
+ * ```
+ */
+export class JYSReportsResource extends MexReportsResource<JYSReportSort, JysReportDefaultsInput> {
+  // ─────────────────────────────────────────────────────────────────
+  // Report CRUD
+  // ─────────────────────────────────────────────────────────────────
+
+  async create(data: CreateJYSReportInput): Promise<MexJYSReport> {
+    const validated = this.validate(createJYSReportInputSchema, 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<MexJYSReport> {
+    const response = await this.execute(() =>
+      this.trpc.reports.retrieve.query({ id })
+    );
+    return this.instantiate(response);
+  }
+
+  async retrieveByMetadata(key: string, value: string): Promise<MexJYSReport> {
+    const response = await this.execute(() =>
+      this.trpc.reports.retrieveByMetadata.query({ key, value })
+    );
+    return this.instantiate(response);
+  }
+
+  async retrieveByExternalId(externalId: string): Promise<MexJYSReport> {
+    const response = await this.execute(() =>
+      this.trpc.reports.retrieveByExternalId.query({ externalId })
+    );
+    return this.instantiate(response);
+  }
+
+  async update(id: string, data: UpdateJYSReportInput): Promise<MexJYSReport> {
+    const validated = this.validate(updateJYSReportInputSchema, 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 JYS reports with optional filtering.
+   *
+   * Accepts flattened JYS filter (future JYS-specific report fields at root level).
+   */
+  async list(
+    options?: ListOptions<JYSReportFilter, JYSReportSort>
+  ): Promise<PaginatedResponse<MexJYSReport>> {
+    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 JYS reports.
+   *
+   * Accepts flattened JYS filter (future JYS-specific report fields at root level).
+   */
+  iterate(
+    filter?: JYSReportFilter
+  ): AsyncGenerator<MexJYSReport, void, undefined> {
+    const scopedFilter = this.applyScopeToFilter(filter);
+    return this.createIterator<MexJYSReport>({ filter: scopedFilter });
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Batch Operations
+  // ─────────────────────────────────────────────────────────────────
+
+  async createMany(
+    reports: CreateJYSReportInput[],
+    options?: { atomic?: true }
+  ): Promise<AtomicBatchResult<MexJYSReport>>;
+  async createMany(
+    reports: CreateJYSReportInput[],
+    options: { atomic: false }
+  ): Promise<PartialBatchResult<MexJYSReport>>;
+  async createMany(
+    reports: CreateJYSReportInput[],
+    options: BatchOptions = {}
+  ): Promise<
+    AtomicBatchResult<MexJYSReport> | PartialBatchResult<MexJYSReport>
+  > {
+    const atomic = options.atomic ?? true;
+    const validated = this.validate(
+      z.array(createJYSReportInputSchema),
+      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: UpdateJYSReportInput }[],
+    options?: { atomic?: true }
+  ): Promise<AtomicBatchResult<MexJYSReport>>;
+  async updateMany(
+    updates: { id: string; data: UpdateJYSReportInput }[],
+    options: { atomic: false }
+  ): Promise<PartialBatchResult<MexJYSReport>>;
+  async updateMany(
+    updates: { id: string; data: UpdateJYSReportInput }[],
+    options: BatchOptions = {}
+  ): Promise<
+    AtomicBatchResult<MexJYSReport> | PartialBatchResult<MexJYSReport>
+  > {
+    const atomic = options.atomic ?? true;
+    const updateItemSchema = z.object({
+      id: z.uuid(),
+      data: updateJYSReportInputSchema,
+    });
+
+    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: CreateJYSReportItemInput
+  ): Promise<MexJYSReportItem> {
+    const validated = this.validate(createJYSReportItemInputSchema, 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<MexJYSReportItem> {
+    const response = await this.execute(() =>
+      this.trpc.reports.getItem.query({ reportId, itemId })
+    );
+    return this.instantiateItem(response);
+  }
+
+  async updateItem(
+    reportId: string,
+    itemId: string,
+    data: UpdateJYSReportItemInput
+  ): Promise<MexJYSReportItem> {
+    const validated = this.validate(updateJYSReportItemInputSchema, 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<JYSReportItemFilter, ReportItemSort>
+  ): Promise<PaginatedResponse<MexJYSReportItem>> {
+    // Transform flattened JYS 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 JYSReportItemFilter to nested ReportItemFilter format.
+   */
+  protected applyScopeToItemFilter(
+    filter?: JYSReportItemFilter
+  ): ReportItemFilter | undefined {
+    if (!filter) return undefined;
+
+    const { alertType, alertDescription, ...baseFields } = filter;
+
+    // If no JYS-specific fields, return base filter as-is
+    if (alertType === undefined && alertDescription === undefined) {
+      return baseFields as ReportItemFilter;
+    }
+
+    // Build nested filter structure
+    const jysFilter: Record<string, unknown> = {};
+    if (alertType !== undefined) jysFilter.alertType = alertType;
+    if (alertDescription !== undefined) jysFilter.alertDescription = alertDescription;
+
+    return {
+      ...baseFields,
+      jurisdictions: {
+        MX: {
+          actividadVulnerable: {
+            JYS: jysFilter,
+          },
+        },
+      },
+    } as ReportItemFilter;
+  }
+
+  async addItems(
+    reportId: string,
+    items: CreateJYSReportItemInput[]
+  ): Promise<{ added: number; items: MexJYSReportItem[] }> {
+    const validated = this.validate(
+      z.array(createJYSReportItemInputSchema),
+      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 JYS report.
+   *
+   * Uses JYS-scoped validation input (jurisdiction and activity are implicit).
+   *
+   * @param reportId - The report ID to validate
+   * @param defaults - JYS report defaults including rfc, alertType, etc.
+   *
+   * @example
+   * ```typescript
+   * const result = await jysSdk.reports.validateReport(report.id, {
+   *   rfc: "ABC200101XXX",
+   *   alertType: "100",
+   * });
+   * ```
+   */
+  override async validateReport(
+    reportId: string,
+    defaults: JysReportDefaultsInput
+  ): Promise<ValidationResult> {
+    const validated = this.validate(jysDefaultsInputSchema, defaults);
+    const nestedInput = this.transformJysDefaultsToNested(reportId, validated);
+    return this.execute(() =>
+      this.trpc.reports.validate.mutate(
+        nestedInput as Parameters<typeof this.trpc.reports.validate.mutate>[0]
+      )
+    );
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Generation
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Generates XML for a JYS report.
+   *
+   * Uses the same input as validateReport.
+   *
+   * @param reportId - The report ID to generate XML for
+   * @param defaults - JYS report defaults including rfc, alertType, etc.
+   */
+  override async generateReport(
+    reportId: string,
+    defaults: JysReportDefaultsInput
+  ): Promise<GenerateResult> {
+    const validated = this.validate(jysDefaultsInputSchema, defaults);
+    const nestedInput = this.transformJysDefaultsToNested(reportId, validated);
+    return this.execute(() =>
+      this.trpc.reports.generate.mutate(
+        nestedInput as Parameters<typeof this.trpc.reports.generate.mutate>[0]
+      )
+    );
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Submission
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Submits a validated JYS report.
+   *
+   * Uses JYS-scoped submission input (activity is implicit).
+   */
+  override async submit(
+    input: SubmitJYSSubmissionInput
+  ): Promise<SubmissionResult> {
+    const validated = this.validate(submitJYSSubmissionInputSchema, input);
+
+    const jurisdictions = {
+      MX: {
+        actividadVulnerable: {
+          [CodigoActividad.JYS]: {
+            acuseRecibo: validated.acuseRecibo,
+            notes: validated.notes,
+          },
+        },
+      },
+    };
+
+    return this.execute(() =>
+      this.trpc.reports.submit.mutate({
+        reportId: validated.reportId,
+        jurisdictions,
+      })
+    );
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Protected Helpers
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Transforms a flattened JYSReportSort to nested ReportSort format.
+   *
+   * Maps flattened field names to their full API paths.
+   */
+  protected override applyScopeToSort(sort?: JYSReportSort): ReportSort | undefined {
+    if (!sort || sort.length === 0) {
+      return undefined;
+    }
+    return transformSort(sort, jysReportFieldMapping);
+  }
+
+  protected override transformToNested(
+    data: CreateJYSReportInput
+  ): CreateReportInput {
+    const { mesReportado, ...baseFields } = data;
+
+    return {
+      ...baseFields,
+      jurisdictions: {
+        MX: {
+          actividadVulnerable: {
+            [CodigoActividad.JYS]: { mesReportado },
+          },
+        },
+      },
+    } as CreateReportInput;
+  }
+
+  protected override transformUpdateToNested(
+    data: UpdateJYSReportInput
+  ): UpdateReportInput {
+    return data as UpdateReportInput;
+  }
+
+  protected override instantiate(data: ReportData): MexJYSReport {
+    return new MexJYSReport(data);
+  }
+
+  protected override instantiateItem(data: ReportItemData): MexJYSReportItem {
+    return new MexJYSReportItem(data);
+  }
+
+  protected transformItemToNested(
+    data: CreateJYSReportItemInput
+  ): CreateReportItemInput {
+    const { alertType, alertDescription, amendment, ...baseFields } = data;
+
+    const jysData: Record<string, unknown> = {};
+    if (alertType !== undefined) jysData.alertType = alertType;
+    if (alertDescription !== undefined)
+      jysData.alertDescription = alertDescription;
+    if (amendment !== undefined) jysData.amendment = amendment;
+
+    return {
+      ...baseFields,
+      jurisdictions: {
+        MX: {
+          actividadVulnerable: {
+            [CodigoActividad.JYS]: jysData,
+          },
+        },
+      },
+    } as CreateReportItemInput;
+  }
+
+  protected transformItemUpdateToNested(
+    data: UpdateJYSReportItemInput
+  ): UpdateReportItemInput {
+    const { alertType, alertDescription, amendment, ...baseFields } = data;
+
+    const jysData: Record<string, unknown> = {};
+    if (alertType !== undefined) jysData.alertType = alertType;
+    if (alertDescription !== undefined)
+      jysData.alertDescription = alertDescription;
+    if (amendment !== undefined) jysData.amendment = amendment;
+
+    if (Object.keys(jysData).length === 0) {
+      return baseFields as UpdateReportItemInput;
+    }
+
+    return {
+      ...baseFields,
+      jurisdictions: {
+        MX: {
+          actividadVulnerable: {
+            [CodigoActividad.JYS]: jysData,
+          },
+        },
+      },
+    } as UpdateReportItemInput;
+  }
+
+  /**
+   * Transforms JYS defaults to nested API format for validate/generate.
+   */
+  protected transformJysDefaultsToNested(
+    reportId: string,
+    defaults: JysReportDefaultsInput
+  ): { reportId: string; jurisdictions: unknown } {
+    const { rfc, collegiateEntityCode, exempt, priority, ...jysFields } =
+      defaults;
+
+    return {
+      reportId,
+      jurisdictions: {
+        MX: {
+          actividadVulnerable: {
+            rfc,
+            collegiateEntityCode,
+            exempt,
+            priority,
+            [CodigoActividad.JYS]: jysFields,
+          },
+        },
+      },
+    };
+  }
+}