@artu-ai/compliance-sdk 0.0.6 → 0.3.0

package/src/resources/mex/reports.ts

@@ -0,0 +1,643 @@
+/**
+ * Mexico Reports Resource
+ *
+ * Extends ReportsResource with Mexico-specific behavior:
+ * - Accepts flattened CreateMexReportInput (MX fields at root level)
+ * - Filters list/iterate to Mexico reports only
+ * - Returns MexReport models
+ */
+
+import { z } from "zod";
+import type {
+  CreateReportInput,
+  UpdateReportInput,
+  CreateReportItemInput,
+  UpdateReportItemInput,
+  CreateMexReportInput,
+  UpdateMexReportInput,
+  CreateMexReportItemInput,
+  UpdateMexReportItemInput,
+  ListOptions,
+  PaginatedResponse,
+  AtomicBatchResult,
+  PartialBatchResult,
+  MexSubmitReportInput,
+  ValidationResult,
+  GenerateResult,
+  SubmissionResult,
+  MexReportDefaultsInput,
+  ReportDefaultsInput,
+} from "@artu-ai/shared";
+import {
+  Jurisdiction,
+  createMexReportInputSchema,
+  updateMexReportInputSchema,
+  createMexReportItemInputSchema,
+  updateMexReportItemInputSchema,
+  mexSubmitReportInputSchema,
+  transformSort,
+  mexReportFieldMapping,
+  mexReportDefaultsInputSchema,
+} from "@artu-ai/shared";
+import type {
+  ReportFilter,
+  ReportSort,
+  MexReportFilter,
+  MexReportSort,
+} from "@artu-ai/shared";
+import {
+  ReportsResource,
+  type ReportItemFilter,
+  type ReportItemSort,
+} from "../reports";
+import { type BatchOptions } from "../clients";
+import { MexReport, type ReportData, type ReportItemData } from "../../models";
+import { MexReportItem } from "../../models/mex";
+
+// ===========================
+// MexReportsResource
+// ===========================
+
+/**
+ * Mexico-scoped reports resource.
+ *
+ * Provides the same operations as ReportsResource but with:
+ * - Flattened input types (MX fields at root level)
+ * - Automatic jurisdiction scoping
+ * - MexReport model return type
+ *
+ * @example
+ * ```typescript
+ * const mexSdk = new ComplianceSDK({
+ *   apiKey,
+ *   environment: "test",
+ *   jurisdiction: Jurisdiction.Mexico,
+ * });
+ *
+ * // Create with flattened input
+ * const report = await mexSdk.reports.create({
+ *   actividadVulnerable: {
+ *     AVI: { mesReportado: "202401" },
+ *   },
+ * });
+ *
+ * // List returns only Mexico reports
+ * const { data } = await mexSdk.reports.list();
+ * // data is MexReport[]
+ * ```
+ */
+export class MexReportsResource<
+  TSort = MexReportSort,
+  TDefaults = MexReportDefaultsInput,
+> extends ReportsResource<TSort, TDefaults> {
+  // ─────────────────────────────────────────────────────────────────
+  // Report CRUD (override with flattened input types)
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Creates a new Mexico report with flattened input.
+   */
+  async create(data: CreateMexReportInput): Promise<MexReport> {
+    const validated = this.validate(createMexReportInputSchema, data);
+    const nestedData = this.transformToNested(validated);
+
+    const response = await this.execute(() =>
+      this.trpc.reports.create.mutate(nestedData)
+    );
+
+    return this.instantiate(response);
+  }
+
+  /**
+   * Retrieves a report by ID.
+   */
+  async retrieve(id: string): Promise<MexReport> {
+    const response = await this.execute(() =>
+      this.trpc.reports.retrieve.query({ id })
+    );
+    return this.instantiate(response);
+  }
+
+  async retrieveByMetadata(key: string, value: string): Promise<MexReport> {
+    const response = await this.execute(() =>
+      this.trpc.reports.retrieveByMetadata.query({ key, value })
+    );
+    return this.instantiate(response);
+  }
+
+  async retrieveByExternalId(externalId: string): Promise<MexReport> {
+    const response = await this.execute(() =>
+      this.trpc.reports.retrieveByExternalId.query({ externalId })
+    );
+    return this.instantiate(response);
+  }
+
+  /**
+   * Updates a Mexico report with flattened input.
+   */
+  async update(id: string, data: UpdateMexReportInput): Promise<MexReport> {
+    const validated = this.validate(updateMexReportInputSchema, 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 (scoped to Mexico)
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Lists Mexico reports with optional filtering.
+   *
+   * Accepts flattened MX filter (future MX-specific report fields at root level).
+   * Automatically filters to reports with Mexico jurisdiction data.
+   */
+  async list(
+    options?: ListOptions<MexReportFilter, TSort>
+  ): Promise<PaginatedResponse<MexReport>> {
+    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 Mexico reports.
+   *
+   * Accepts flattened MX filter (future MX-specific report fields at root level).
+   * Automatically filters to reports with Mexico jurisdiction data.
+   */
+  iterate(
+    filter?: MexReportFilter
+  ): AsyncGenerator<MexReport, void, undefined> {
+    const scopedFilter = this.applyScopeToFilter(filter);
+    return this.createIterator<MexReport>({ filter: scopedFilter });
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Batch Operations
+  // ─────────────────────────────────────────────────────────────────
+
+  async createMany(
+    reports: CreateMexReportInput[],
+    options?: { atomic?: true }
+  ): Promise<AtomicBatchResult<MexReport>>;
+  async createMany(
+    reports: CreateMexReportInput[],
+    options: { atomic: false }
+  ): Promise<PartialBatchResult<MexReport>>;
+  async createMany(
+    reports: CreateMexReportInput[],
+    options: BatchOptions = {}
+  ): Promise<AtomicBatchResult<MexReport> | PartialBatchResult<MexReport>> {
+    const atomic = options.atomic ?? true;
+    const validated = this.validate(
+      z.array(createMexReportInputSchema),
+      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: UpdateMexReportInput }[],
+    options?: { atomic?: true }
+  ): Promise<AtomicBatchResult<MexReport>>;
+  async updateMany(
+    updates: { id: string; data: UpdateMexReportInput }[],
+    options: { atomic: false }
+  ): Promise<PartialBatchResult<MexReport>>;
+  async updateMany(
+    updates: { id: string; data: UpdateMexReportInput }[],
+    options: BatchOptions = {}
+  ): Promise<AtomicBatchResult<MexReport> | PartialBatchResult<MexReport>> {
+    const atomic = options.atomic ?? true;
+    const updateItemSchema = z.object({
+      id: z.uuid(),
+      data: updateMexReportInputSchema,
+    });
+
+    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
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Adds an item to a report with flattened Mexico input.
+   */
+  async addItem(
+    reportId: string,
+    data: CreateMexReportItemInput
+  ): Promise<MexReportItem> {
+    const validated = this.validate(createMexReportItemInputSchema, data);
+    const nestedData = this.transformItemToNested(validated);
+
+    const response = await this.execute(() =>
+      this.trpc.reports.addItem.mutate({ reportId, data: nestedData })
+    );
+
+    return this.instantiateItem(response);
+  }
+
+  /**
+   * Gets a specific report item.
+   */
+  async getItem(reportId: string, itemId: string): Promise<MexReportItem> {
+    const response = await this.execute(() =>
+      this.trpc.reports.getItem.query({ reportId, itemId })
+    );
+    return this.instantiateItem(response);
+  }
+
+  /**
+   * Updates a report item with flattened Mexico input.
+   */
+  async updateItem(
+    reportId: string,
+    itemId: string,
+    data: UpdateMexReportItemInput
+  ): Promise<MexReportItem> {
+    const validated = this.validate(updateMexReportItemInputSchema, data);
+    const nestedData = this.transformItemUpdateToNested(validated);
+
+    const response = await this.execute(() =>
+      this.trpc.reports.updateItem.mutate({
+        reportId,
+        itemId,
+        data: nestedData,
+      })
+    );
+    return this.instantiateItem(response);
+  }
+
+  /**
+   * Lists items in a report with filtering, sorting, and pagination.
+   */
+  async listItems(
+    reportId: string,
+    options?: ListOptions<ReportItemFilter, ReportItemSort>
+  ): Promise<PaginatedResponse<MexReportItem>> {
+    const response = await this.execute(() =>
+      this.trpc.reports.listItems.query({
+        reportId,
+        ...options,
+      })
+    );
+
+    return {
+      data: response.data.map((i) => this.instantiateItem(i)),
+      pagination: response.pagination,
+    };
+  }
+
+  /**
+   * Adds multiple items to a report with flattened Mexico input.
+   */
+  async addItems(
+    reportId: string,
+    items: CreateMexReportItemInput[]
+  ): Promise<{ added: number; items: MexReportItem[] }> {
+    const validated = this.validate(
+      z.array(createMexReportItemInputSchema),
+      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 Mexico report.
+   *
+   * Uses Mexico-scoped validation input (jurisdiction is implicit).
+   *
+   * @param reportId - The report ID to validate
+   * @param defaults - Mexico report defaults including activity-specific settings
+   *
+   * @example
+   * ```typescript
+   * const result = await mexSdk.reports.validateReport(report.id, {
+   *   actividadVulnerable: {
+   *     rfc: "ABC200101XXX",
+   *     AVI: {
+   *       platformDomain: "https://example.com",
+   *       alertType: "100",
+   *     },
+   *   },
+   * });
+   * ```
+   */
+  override async validateReport(
+    reportId: string,
+    defaults: TDefaults
+  ): Promise<ValidationResult> {
+    const validated = this.validate(
+      mexReportDefaultsInputSchema,
+      defaults as MexReportDefaultsInput
+    );
+    const nestedInput = this.transformValidateToNested(reportId, validated);
+    return this.execute(() => this.trpc.reports.validate.mutate(nestedInput));
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Generation
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Generates XML for a Mexico report.
+   *
+   * Uses the same input as validateReport since generation requires
+   * the same transformation and defaults.
+   *
+   * @param reportId - The report ID to generate XML for
+   * @param defaults - Mexico report defaults including activity-specific settings
+   *
+   * @example
+   * ```typescript
+   * const result = await mexSdk.reports.generateReport(report.id, {
+   *   actividadVulnerable: {
+   *     rfc: "ABC200101XXX",
+   *     AVI: {
+   *       platformDomain: "https://example.com",
+   *       alertType: "100",
+   *     },
+   *   },
+   * });
+   * console.log(result.xml);
+   * ```
+   */
+  override async generateReport(
+    reportId: string,
+    defaults: TDefaults
+  ): Promise<GenerateResult> {
+    const validated = this.validate(
+      mexReportDefaultsInputSchema,
+      defaults as MexReportDefaultsInput
+    );
+    const nestedInput = this.transformValidateToNested(reportId, validated);
+    return this.execute(() => this.trpc.reports.generate.mutate(nestedInput));
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Submission
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Submits a validated Mexico report.
+   *
+   * The report must be in "valid" status. After submission, the report
+   * is locked and cannot be edited (except rejected reports which can
+   * be edited and resubmitted).
+   *
+   * @param reportId - The report ID
+   * @param actividadVulnerable - The activity type (AVI, JYS, or TSC)
+   * @param data - Optional submission data (acuseRecibo, notes)
+   *
+   * @example
+   * ```typescript
+   * const result = await mexSdk.reports.submitReport(
+   *   report.id,
+   *   "AVI",
+   *   { acuseRecibo: "SAT-12345", notes: "Submitted via portal" }
+   * );
+   * ```
+   */
+  async submit(input: MexSubmitReportInput): Promise<SubmissionResult> {
+    const validated = this.validate(mexSubmitReportInputSchema, input);
+
+    const jurisdictions = {
+      MX: {
+        actividadVulnerable: validated.actividadVulnerable,
+      },
+    };
+
+    return this.execute(() =>
+      this.trpc.reports.submit.mutate({
+        reportId: validated.reportId,
+        jurisdictions,
+      })
+    );
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Protected Helpers
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Applies Mexico jurisdiction filter.
+   *
+   * Currently MexReportFilter has the same fields as the base filter,
+   * but this method ensures the jurisdiction scope is applied.
+   * Uses `availableJurisdictions` to find any report that includes Mexico.
+   */
+  protected applyScopeToFilter(filter?: MexReportFilter): ReportFilter {
+    if (!filter) {
+      return {
+        availableJurisdictions: Jurisdiction.Mexico,
+      };
+    }
+
+    // Currently no MX-specific report filter fields to nest
+    // Just pass through and add jurisdiction scope
+    return {
+      ...filter,
+      availableJurisdictions: Jurisdiction.Mexico,
+    } as ReportFilter;
+  }
+
+  /**
+   * Transforms a flattened MexReportSort to nested ReportSort format.
+   *
+   * Maps flattened field names to their full API paths.
+   *
+   * Note: Uses unknown parameter to allow derived classes to override with their own sort types.
+   */
+  protected applyScopeToSort(sort?: TSort): ReportSort | undefined {
+    if (!sort || !Array.isArray(sort) || sort.length === 0) {
+      return undefined;
+    }
+    return transformSort(sort as MexReportSort, mexReportFieldMapping);
+  }
+
+  /**
+   * Transforms flattened MX input to nested API format.
+   */
+  protected transformToNested(data: CreateMexReportInput): CreateReportInput {
+    const { actividadVulnerable, ...baseFields } = data;
+
+    // Build MX jurisdiction data
+    const mexData: Record<string, unknown> = {};
+    if (actividadVulnerable !== undefined) {
+      mexData.actividadVulnerable = actividadVulnerable;
+    }
+
+    return {
+      ...baseFields,
+      jurisdictions:
+        Object.keys(mexData).length > 0
+          ? {
+              MX: mexData,
+            }
+          : undefined,
+    } as CreateReportInput;
+  }
+
+  /**
+   * Transforms flattened MX update input to nested API format.
+   */
+  protected transformUpdateToNested(
+    data: UpdateMexReportInput
+  ): UpdateReportInput {
+    const { actividadVulnerable, ...baseFields } = data;
+
+    if (actividadVulnerable === undefined) {
+      return baseFields as UpdateReportInput;
+    }
+
+    return {
+      ...baseFields,
+      jurisdictions: {
+        MX: { actividadVulnerable },
+      },
+    } as UpdateReportInput;
+  }
+
+  /**
+   * Instantiates a MexReport model.
+   */
+  protected override instantiate(data: ReportData): MexReport {
+    return new MexReport(data);
+  }
+
+  /**
+   * Instantiates a MexReportItem model.
+   */
+  protected override instantiateItem(data: ReportItemData): MexReportItem {
+    return new MexReportItem(data);
+  }
+
+  /**
+   * Transforms flattened MX report item input to nested API format.
+   */
+  protected transformItemToNested(
+    data: CreateMexReportItemInput
+  ): CreateReportItemInput {
+    const { actividadVulnerable, ...baseFields } = data;
+
+    if (actividadVulnerable === undefined) {
+      return baseFields as CreateReportItemInput;
+    }
+
+    return {
+      ...baseFields,
+      jurisdictions: {
+        MX: { actividadVulnerable },
+      },
+    } as CreateReportItemInput;
+  }
+
+  /**
+   * Transforms flattened MX report item update input to nested API format.
+   */
+  protected transformItemUpdateToNested(
+    data: UpdateMexReportItemInput
+  ): UpdateReportItemInput {
+    const { actividadVulnerable, ...baseFields } = data;
+
+    if (actividadVulnerable === undefined) {
+      return baseFields as UpdateReportItemInput;
+    }
+
+    return {
+      ...baseFields,
+      jurisdictions: {
+        MX: { actividadVulnerable },
+      },
+    } as UpdateReportItemInput;
+  }
+
+  /**
+   * Transforms flattened MX validate/generate input to nested API format.
+   */
+  protected transformValidateToNested(
+    reportId: string,
+    defaults: MexReportDefaultsInput
+  ): { reportId: string } & ReportDefaultsInput {
+    return {
+      reportId,
+      jurisdictions: {
+        MX: defaults,
+      },
+    };
+  }
+}