@artu-ai/compliance-sdk 0.4.0 → 0.4.2

package/src/resources/reports.ts

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