@artu-ai/compliance-sdk 0.0.6 → 0.3.0

package/src/resources/reports.ts

@@ -0,0 +1,515 @@
+/**
+ * Reports Resource
+ *
+ * CRUD operations, report items management, validation, and generation.
+ *
+ * This is the base (unscoped) resource. For jurisdiction-scoped SDKs, use:
+ * - MexReportsResource - Mexico-scoped with flattened MX fields
+ * - AVIReportsResource - Mexico AVI-scoped with flattened AVI fields
+ * - JYSReportsResource - Mexico JYS-scoped with flattened JYS fields
+ * - TSCReportsResource - Mexico TSC-scoped with flattened TSC fields
+ */
+
+import { z } from "zod";
+import type {
+  CreateReportInput,
+  UpdateReportInput,
+  UpdateReportStatusInput,
+  CreateReportItemInput,
+  UpdateReportItemInput,
+  ReportFilter,
+  ReportSort,
+  ReportItemFilter,
+  ReportItemSort,
+  ValidationResult,
+  GenerateResult,
+  SubmitReportInput,
+  SubmissionResult,
+  ListOptions,
+  PaginatedResponse,
+  AtomicBatchResult,
+  PartialBatchResult,
+  ReportDefaultsInput,
+} from "@artu-ai/shared";
+import {
+  createReportInputSchema,
+  updateReportInputSchema,
+  updateReportStatusInputSchema,
+  createReportItemInputSchema,
+  updateReportItemInputSchema,
+  reportDefaultsInputSchema,
+  submitReportInputSchema,
+} from "@artu-ai/shared";
+import type { BatchOptions } from "./clients";
+import { BaseResource } from "./base";
+import {
+  Report,
+  ReportItem,
+  type ReportData,
+  type ReportItemData,
+} from "../models";
+
+// ===========================
+// Types
+// ===========================
+
+// Re-export filter types for backwards compatibility
+export type { ReportFilter, ReportItemFilter, ReportItemSort };
+
+/**
+ * Add items result
+ */
+export interface AddItemsResult {
+  added: number;
+  items: ReportItem[];
+}
+
+// ===========================
+// ReportsResource
+// ===========================
+
+/**
+ * Base resource manager for report operations.
+ *
+ * Provides:
+ * - CRUD operations (create, retrieve, update, delete)
+ * - Report items management (add, update, remove items)
+ * - Validation and generation
+ *
+ * @example
+ * ```typescript
+ * // Create a report with full nested format
+ * const report = await sdk.reports.create({
+ *   jurisdictions: {
+ *     MX: {
+ *       actividadVulnerable: {
+ *         AVI: { mesReportado: "202401" }
+ *       }
+ *     }
+ *   }
+ * });
+ *
+ * // Add items to the report
+ * await sdk.reports.addItem(report.id, {
+ *   transactionId: "txn_123",
+ * });
+ *
+ * // Validate the report
+ * const result = await sdk.reports.validate(report.id);
+ * if (result.valid) {
+ *   // Generate XML
+ *   const xml = await sdk.reports.generate(report.id);
+ * }
+ * ```
+ */
+export class ReportsResource<
+  TSort = ReportSort,
+  TDefaults = ReportDefaultsInput,
+> extends BaseResource<
+  Report,
+  CreateReportInput,
+  UpdateReportInput,
+  ReportFilter,
+  TSort
+> {
+  // ─────────────────────────────────────────────────────────────────
+  // Report CRUD
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Creates a new report.
+   *
+   * @param data - Report creation data in nested format
+   * @returns The created report model
+   */
+  async create(data: CreateReportInput): Promise<Report> {
+    const validated = this.validate(createReportInputSchema, data);
+
+    const response = await this.execute(() =>
+      this.trpc.reports.create.mutate(validated)
+    );
+
+    return this.instantiate(response);
+  }
+
+  /**
+   * Retrieves a report by ID.
+   */
+  async retrieve(id: string): Promise<Report> {
+    const response = await this.execute(() =>
+      this.trpc.reports.retrieve.query({ id })
+    );
+    return this.instantiate(response);
+  }
+
+  /**
+   * Retrieves a report by metadata key/value.
+   */
+  async retrieveByMetadata(key: string, value: string): Promise<Report> {
+    const response = await this.execute(() =>
+      this.trpc.reports.retrieveByMetadata.query({ key, value })
+    );
+    return this.instantiate(response);
+  }
+
+  /**
+   * Retrieves a report by externalId.
+   */
+  async retrieveByExternalId(externalId: string): Promise<Report> {
+    const response = await this.execute(() =>
+      this.trpc.reports.retrieveByExternalId.query({ externalId })
+    );
+    return this.instantiate(response);
+  }
+
+  /**
+   * Updates a report.
+   */
+  async update(id: string, data: UpdateReportInput): Promise<Report> {
+    const validated = this.validate(updateReportInputSchema, data);
+
+    const response = await this.execute(() =>
+      this.trpc.reports.update.mutate({ id, data: validated })
+    );
+    return this.instantiate(response);
+  }
+
+  /**
+   * Updates a report's status.
+   *
+   * Restrictions:
+   * - Can only manually set to: Draft
+   * - Cannot change from: Accepted (terminal), Submitted (awaiting response)
+   *
+   * Use this to reset a report back to Draft status for re-editing.
+   */
+  async updateStatus(id: string, data: UpdateReportStatusInput): Promise<Report> {
+    const validated = this.validate(updateReportStatusInputSchema, data);
+
+    const response = await this.execute(() =>
+      this.trpc.reports.updateStatus.mutate({ id, data: validated })
+    );
+    return this.instantiate(response);
+  }
+
+  /**
+   * Deletes a report.
+   */
+  async delete(id: string): Promise<void> {
+    await this.execute(() => this.trpc.reports.delete.mutate({ id }));
+  }
+
+  /**
+   * Lists reports with optional filtering and pagination.
+   */
+  async list(
+    options?: ListOptions<ReportFilter, TSort>
+  ): Promise<PaginatedResponse<Report>> {
+    const response = await this.execute(() =>
+      this.trpc.reports.list.query(
+        options as ListOptions<ReportFilter, ReportSort>
+      )
+    );
+
+    return {
+      data: response.data.map((r) => this.instantiate(r)),
+      pagination: response.pagination,
+    };
+  }
+
+  /**
+   * Returns an async iterator over all reports matching the filter.
+   */
+  iterate(filter?: ReportFilter): AsyncGenerator<Report, void, undefined> {
+    return this.createIterator({ filter });
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Report Items
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Adds an item to a report.
+   */
+  async addItem(
+    reportId: string,
+    data: CreateReportItemInput
+  ): Promise<ReportItem> {
+    const validated = this.validate(createReportItemInputSchema, data);
+
+    const response = await this.execute(() =>
+      this.trpc.reports.addItem.mutate({ reportId, data: validated })
+    );
+
+    return this.instantiateItem(response);
+  }
+
+  /**
+   * Gets a specific report item.
+   */
+  async getItem(reportId: string, itemId: string): Promise<ReportItem> {
+    const response = await this.execute(() =>
+      this.trpc.reports.getItem.query({ reportId, itemId })
+    );
+    return this.instantiateItem(response);
+  }
+
+  /**
+   * Updates a report item.
+   */
+  async updateItem(
+    reportId: string,
+    itemId: string,
+    data: UpdateReportItemInput
+  ): Promise<ReportItem> {
+    const validated = this.validate(updateReportItemInputSchema, data);
+
+    const response = await this.execute(() =>
+      this.trpc.reports.updateItem.mutate({ reportId, itemId, data: validated })
+    );
+    return this.instantiateItem(response);
+  }
+
+  /**
+   * Removes an item from a report.
+   */
+  async removeItem(reportId: string, itemId: string): Promise<void> {
+    await this.execute(() =>
+      this.trpc.reports.removeItem.mutate({ reportId, itemId })
+    );
+  }
+
+  /**
+   * Lists items in a report with filtering, sorting, and pagination.
+   */
+  async listItems(
+    reportId: string,
+    options?: ListOptions<ReportItemFilter, ReportItemSort>
+  ): Promise<PaginatedResponse<ReportItem>> {
+    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.
+   * Validates all items upfront - fails fast if any item is invalid.
+   */
+  async addItems(
+    reportId: string,
+    items: CreateReportItemInput[]
+  ): Promise<AddItemsResult> {
+    const validated = this.validate(
+      z.array(createReportItemInputSchema),
+      items
+    );
+
+    const response = await this.execute(() =>
+      this.trpc.reports.addItems.mutate({ reportId, items: validated })
+    );
+
+    return {
+      added: response.added,
+      items: response.items.map((i) => this.instantiateItem(i)),
+    };
+  }
+
+  /**
+   * Removes multiple items from a report.
+   */
+  async removeItems(
+    reportId: string,
+    itemIds: string[]
+  ): Promise<{ removed: number }> {
+    return this.execute(() =>
+      this.trpc.reports.removeItems.mutate({ reportId, itemIds })
+    );
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Validation & Generation
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Validates a report and its items.
+   *
+   * Requires jurisdiction-specific defaults.
+   * For scoped SDKs, use the scoped resource which provides a simpler API.
+   *
+   * @param reportId - The report ID to validate
+   * @param defaults - Jurisdiction-specific defaults for validation
+   */
+  async validateReport(
+    reportId: string,
+    defaults: TDefaults
+  ): Promise<ValidationResult> {
+    const validated = this.validate(reportDefaultsInputSchema, defaults);
+    return this.execute(() =>
+      this.trpc.reports.validate.mutate({ reportId, ...validated })
+    );
+  }
+
+  /**
+   * Validates and generates the report output (e.g., XML for Mexico reports).
+   *
+   * Performs validation first:
+   * - If validation fails, returns `{ status: "validation_failed", validation: {...} }`
+   * - If validation passes, returns `{ status: "success", xml: "...", ... }`
+   *
+   * Use `validateReport` for dry-run/preview validation without generating XML.
+   *
+   * @param reportId - The report ID to generate
+   * @param defaults - Jurisdiction-specific defaults for generation
+   * @returns GenerateResult with status "success" or "validation_failed"
+   */
+  async generateReport(
+    reportId: string,
+    defaults: TDefaults
+  ): Promise<GenerateResult> {
+    const validated = this.validate(reportDefaultsInputSchema, defaults);
+    return this.execute(() =>
+      this.trpc.reports.generate.mutate({ reportId, ...validated })
+    );
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Submission
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Submits a validated report.
+   *
+   * The report must be in "valid" status. After submission, the report
+   * is locked and cannot be edited.
+   *
+   * @param reportId - The report ID
+   * @param input - Submission data with jurisdiction-specific structure
+   */
+  async submit(input: SubmitReportInput): Promise<SubmissionResult> {
+    const validated = this.validate(submitReportInputSchema, input);
+    return this.execute(() => this.trpc.reports.submit.mutate(validated));
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Batch Operations
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Creates multiple reports in a single request.
+   *
+   * @param reports - Array of report creation data
+   * @param options - Batch options (atomic: true by default)
+   * @returns Atomic result with data array, or partial result with succeeded/failed
+   */
+  async createMany(
+    reports: CreateReportInput[],
+    options?: { atomic?: true }
+  ): Promise<AtomicBatchResult<Report>>;
+  async createMany(
+    reports: CreateReportInput[],
+    options: { atomic: false }
+  ): Promise<PartialBatchResult<Report>>;
+  async createMany(
+    reports: CreateReportInput[],
+    options: BatchOptions = {}
+  ): Promise<AtomicBatchResult<Report> | PartialBatchResult<Report>> {
+    const atomic = options.atomic ?? true;
+    const validated = this.validate(z.array(createReportInputSchema), reports);
+
+    const response = await this.execute(() =>
+      this.trpc.reports.createMany.mutate({ items: validated, 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,
+      };
+    }
+  }
+
+  /**
+   * Updates multiple reports in a single request.
+   *
+   * @param updates - Array of { id, data } updates
+   * @param options - Batch options (atomic: true by default)
+   * @returns Atomic result with data array, or partial result with succeeded/failed
+   */
+  async updateMany(
+    updates: { id: string; data: UpdateReportInput }[],
+    options?: { atomic?: true }
+  ): Promise<AtomicBatchResult<Report>>;
+  async updateMany(
+    updates: { id: string; data: UpdateReportInput }[],
+    options: { atomic: false }
+  ): Promise<PartialBatchResult<Report>>;
+  async updateMany(
+    updates: { id: string; data: UpdateReportInput }[],
+    options: BatchOptions = {}
+  ): Promise<AtomicBatchResult<Report> | PartialBatchResult<Report>> {
+    const atomic = options.atomic ?? true;
+    const updateItemSchema = z.object({
+      id: z.uuid(),
+      data: updateReportInputSchema,
+    });
+
+    const validated = this.validate(z.array(updateItemSchema), updates);
+
+    const response = await this.execute(() =>
+      this.trpc.reports.updateMany.mutate({ items: validated, 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,
+      };
+    }
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Instantiation (protected for subclasses to override)
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Instantiates a Report model from API response data.
+   * Subclasses override this to return their specific model type.
+   */
+  protected instantiate(data: ReportData): Report {
+    return new Report(data);
+  }
+
+  /**
+   * Instantiates a ReportItem model from API response data.
+   * Subclasses override this to return their specific model type.
+   */
+  protected instantiateItem(data: ReportItemData): ReportItem {
+    return new ReportItem(data);
+  }
+}