@artu-ai/compliance-sdk 0.4.1 → 0.4.3

package/src/resources/mex/reports.ts

@@ -1,643 +0,0 @@
-/**
- * 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,
-      },
-    };
-  }
-}