@artu-ai/compliance-sdk 0.2.0 → 0.3.0

package/src/resources/mex/reports.ts

@@ -21,11 +21,12 @@ import type {
   PaginatedResponse,
   AtomicBatchResult,
   PartialBatchResult,
-  MexValidateReportInput,
   MexSubmitReportInput,
   ValidationResult,
   GenerateResult,
   SubmissionResult,
+  MexReportDefaultsInput,
+  ReportDefaultsInput,
 } from "@artu-ai/shared";
 import {
   Jurisdiction,
@@ -33,11 +34,22 @@ import {
   updateMexReportInputSchema,
   createMexReportItemInputSchema,
   updateMexReportItemInputSchema,
-  mexValidateReportInputSchema,
   mexSubmitReportInputSchema,
+  transformSort,
+  mexReportFieldMapping,
+  mexReportDefaultsInputSchema,
 } from "@artu-ai/shared";
-import type { ReportFilter, MexReportFilter } from "@artu-ai/shared";
-import { ReportsResource, type ReportItemFilter } from "../reports";
+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";
@@ -74,7 +86,10 @@ import { MexReportItem } from "../../models/mex";
  * // data is MexReport[]
  * ```
  */
-export class MexReportsResource extends ReportsResource {
+export class MexReportsResource<
+  TSort = MexReportSort,
+  TDefaults = MexReportDefaultsInput,
+> extends ReportsResource<TSort, TDefaults> {
   // ─────────────────────────────────────────────────────────────────
   // Report CRUD (override with flattened input types)
   // ─────────────────────────────────────────────────────────────────
@@ -141,14 +156,16 @@ export class MexReportsResource extends ReportsResource {
    * Automatically filters to reports with Mexico jurisdiction data.
    */
   async list(
-    options?: ListOptions<MexReportFilter>
+    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,
       })
     );
 
@@ -164,7 +181,9 @@ export class MexReportsResource extends ReportsResource {
    * 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> {
+  iterate(
+    filter?: MexReportFilter
+  ): AsyncGenerator<MexReport, void, undefined> {
     const scopedFilter = this.applyScopeToFilter(filter);
     return this.createIterator<MexReport>({ filter: scopedFilter });
   }
@@ -311,11 +330,11 @@ export class MexReportsResource extends ReportsResource {
   }
 
   /**
-   * Lists items in a report.
+   * Lists items in a report with filtering, sorting, and pagination.
    */
   async listItems(
     reportId: string,
-    options?: ListOptions<ReportItemFilter>
+    options?: ListOptions<ReportItemFilter, ReportItemSort>
   ): Promise<PaginatedResponse<MexReportItem>> {
     const response = await this.execute(() =>
       this.trpc.reports.listItems.query({
@@ -362,23 +381,32 @@ export class MexReportsResource extends ReportsResource {
    *
    * 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({
-   *   reportId: report.id,
-   *   actividadVulnerable: "AVI",
-   *   defaults: {
+   * const result = await mexSdk.reports.validateReport(report.id, {
+   *   actividadVulnerable: {
    *     rfc: "ABC200101XXX",
-   *     platformDomain: "https://example.com",
+   *     AVI: {
+   *       platformDomain: "https://example.com",
+   *       alertType: "100",
+   *     },
    *   },
    * });
    * ```
    */
-  async validateReport(
-    input: MexValidateReportInput
+  override async validateReport(
+    reportId: string,
+    defaults: TDefaults
   ): Promise<ValidationResult> {
-    const validated = this.validate(mexValidateReportInputSchema, input);
-    return this.execute(() => this.trpc.reports.validate.mutate(validated));
+    const validated = this.validate(
+      mexReportDefaultsInputSchema,
+      defaults as MexReportDefaultsInput
+    );
+    const nestedInput = this.transformValidateToNested(reportId, validated);
+    return this.execute(() => this.trpc.reports.validate.mutate(nestedInput));
   }
 
   // ─────────────────────────────────────────────────────────────────
@@ -391,22 +419,33 @@ export class MexReportsResource extends ReportsResource {
    * 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({
-   *   reportId: report.id,
-   *   actividadVulnerable: "AVI",
-   *   defaults: {
+   * const result = await mexSdk.reports.generateReport(report.id, {
+   *   actividadVulnerable: {
    *     rfc: "ABC200101XXX",
-   *     platformDomain: "https://example.com",
+   *     AVI: {
+   *       platformDomain: "https://example.com",
+   *       alertType: "100",
+   *     },
    *   },
    * });
    * console.log(result.xml);
    * ```
    */
-  async generateReport(input: MexValidateReportInput): Promise<GenerateResult> {
-    const validated = this.validate(mexValidateReportInputSchema, input);
-    return this.execute(() => this.trpc.reports.generate.mutate(validated));
+  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));
   }
 
   // ─────────────────────────────────────────────────────────────────
@@ -476,6 +515,20 @@ export class MexReportsResource extends ReportsResource {
     } 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.
    */
@@ -572,4 +625,19 @@ export class MexReportsResource extends ReportsResource {
       },
     } 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,
+      },
+    };
+  }
 }

package/src/resources/mex/transactions.ts

@@ -13,6 +13,7 @@ import type {
   CreateTransactionInput,
   UpdateTransactionInput,
   TransactionFilter,
+  TransactionSort,
   ListOptions,
   PaginatedResponse,
   CreateMexTransactionInput,
@@ -21,12 +22,15 @@ import type {
   PartialBatchResult,
   RelatedClient,
   MexTransactionFilter,
+  MexTransactionSort,
 } from "@artu-ai/shared";
 import {
   Jurisdiction,
   createMexTransactionInputSchema,
   updateMexTransactionInputSchema,
   ClientRole,
+  transformSort,
+  mexTransactionFieldMapping,
 } from "@artu-ai/shared";
 import { TransactionsResource } from "../transactions";
 import { type BatchOptions } from "../clients";
@@ -67,7 +71,9 @@ import { MexTransaction, type TransactionData } from "../../models";
  * // data is MexTransaction[]
  * ```
  */
-export class MexTransactionsResource extends TransactionsResource {
+export class MexTransactionsResource<
+  TSort = MexTransactionSort,
+> extends TransactionsResource<TSort> {
   // ─────────────────────────────────────────────────────────────────
   // CRUD Operations (override with flattened input types)
   // ─────────────────────────────────────────────────────────────────
@@ -139,14 +145,16 @@ export class MexTransactionsResource extends TransactionsResource {
    * Accepts flattened MX filter (future MX-specific transaction fields at root level).
    */
   async list(
-    options?: ListOptions<MexTransactionFilter>
+    options?: ListOptions<MexTransactionFilter, TSort>
   ): Promise<PaginatedResponse<MexTransaction>> {
     const scopedFilter = this.applyScopeToFilter(options?.filter);
+    const scopedSort = this.applyScopeToSort(options?.sort);
 
     const response = await this.execute(() =>
       this.trpc.transactions.list.query({
         ...options,
         filter: scopedFilter,
+        sort: scopedSort,
       })
     );
 
@@ -345,6 +353,20 @@ export class MexTransactionsResource extends TransactionsResource {
     } as TransactionFilter;
   }
 
+  /**
+   * Transforms a flattened MexTransactionSort to nested TransactionSort 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): TransactionSort | undefined {
+    if (!sort || !Array.isArray(sort) || sort.length === 0) {
+      return undefined;
+    }
+    return transformSort(sort as MexTransactionSort, mexTransactionFieldMapping);
+  }
+
   /**
    * Transforms flattened MX input to nested API format.
    */

package/src/resources/reports.ts

@@ -14,10 +14,13 @@ import { z } from "zod";
 import type {
   CreateReportInput,
   UpdateReportInput,
+  UpdateReportStatusInput,
   CreateReportItemInput,
   UpdateReportItemInput,
   ReportFilter,
+  ReportSort,
   ReportItemFilter,
+  ReportItemSort,
   ValidationResult,
   GenerateResult,
   SubmitReportInput,
@@ -26,14 +29,15 @@ import type {
   PaginatedResponse,
   AtomicBatchResult,
   PartialBatchResult,
-  ValidateReportInput,
+  ReportDefaultsInput,
 } from "@artu-ai/shared";
 import {
   createReportInputSchema,
   updateReportInputSchema,
+  updateReportStatusInputSchema,
   createReportItemInputSchema,
   updateReportItemInputSchema,
-  validateReportInputSchema,
+  reportDefaultsInputSchema,
   submitReportInputSchema,
 } from "@artu-ai/shared";
 import type { BatchOptions } from "./clients";
@@ -50,7 +54,7 @@ import {
 // ===========================
 
 // Re-export filter types for backwards compatibility
-export type { ReportFilter, ReportItemFilter };
+export type { ReportFilter, ReportItemFilter, ReportItemSort };
 
 /**
  * Add items result
@@ -98,11 +102,15 @@ export interface AddItemsResult {
  * }
  * ```
  */
-export class ReportsResource extends BaseResource<
+export class ReportsResource<
+  TSort = ReportSort,
+  TDefaults = ReportDefaultsInput,
+> extends BaseResource<
   Report,
   CreateReportInput,
   UpdateReportInput,
-  ReportFilter
+  ReportFilter,
+  TSort
 > {
   // ─────────────────────────────────────────────────────────────────
   // Report CRUD
@@ -166,6 +174,24 @@ export class ReportsResource extends BaseResource<
     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.
    */
@@ -177,10 +203,12 @@ export class ReportsResource extends BaseResource<
    * Lists reports with optional filtering and pagination.
    */
   async list(
-    options?: ListOptions<ReportFilter>
+    options?: ListOptions<ReportFilter, TSort>
   ): Promise<PaginatedResponse<Report>> {
     const response = await this.execute(() =>
-      this.trpc.reports.list.query(options)
+      this.trpc.reports.list.query(
+        options as ListOptions<ReportFilter, ReportSort>
+      )
     );
 
     return {
@@ -252,11 +280,11 @@ export class ReportsResource extends BaseResource<
   }
 
   /**
-   * Lists items in a report.
+   * Lists items in a report with filtering, sorting, and pagination.
    */
   async listItems(
     reportId: string,
-    options?: ListOptions<ReportItemFilter>
+    options?: ListOptions<ReportItemFilter, ReportItemSort>
   ): Promise<PaginatedResponse<ReportItem>> {
     const response = await this.execute(() =>
       this.trpc.reports.listItems.query({
@@ -313,49 +341,43 @@ export class ReportsResource extends BaseResource<
   /**
    * Validates a report and its items.
    *
-   * Requires jurisdiction and activity-specific defaults.
+   * Requires jurisdiction-specific defaults.
    * For scoped SDKs, use the scoped resource which provides a simpler API.
    *
-   * @example
-   * ```typescript
-   * const result = await sdk.reports.validateReport({
-   *   reportId: report.id,
-   *   jurisdiction: "MX",
-   *   actividadVulnerable: "AVI",
-   *   defaults: {
-   *     rfc: "ABC200101XXX",
-   *     platformDomain: "https://example.com",
-   *   },
-   * });
-   * ```
+   * @param reportId - The report ID to validate
+   * @param defaults - Jurisdiction-specific defaults for validation
    */
-  async validateReport(input: ValidateReportInput): Promise<ValidationResult> {
-    const validated = this.validate(validateReportInputSchema, input);
-    return this.execute(() => this.trpc.reports.validate.mutate(validated));
+  async validateReport(
+    reportId: string,
+    defaults: TDefaults
+  ): Promise<ValidationResult> {
+    const validated = this.validate(reportDefaultsInputSchema, defaults);
+    return this.execute(() =>
+      this.trpc.reports.validate.mutate({ reportId, ...validated })
+    );
   }
 
   /**
-   * Generates the report output (e.g., XML for Mexico reports).
+   * Validates and generates the report output (e.g., XML for Mexico reports).
    *
-   * Requires the same input as validateReport since generation uses
-   * the same transformation and defaults.
+   * Performs validation first:
+   * - If validation fails, returns `{ status: "validation_failed", validation: {...} }`
+   * - If validation passes, returns `{ status: "success", xml: "...", ... }`
    *
-   * @example
-   * ```typescript
-   * const result = await sdk.reports.generate({
-   *   reportId: report.id,
-   *   jurisdiction: "MX",
-   *   actividadVulnerable: "AVI",
-   *   defaults: {
-   *     rfc: "ABC200101XXX",
-   *     platformDomain: "https://example.com",
-   *   },
-   * });
-   * ```
+   * 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 generate(input: ValidateReportInput): Promise<GenerateResult> {
-    const validated = this.validate(validateReportInputSchema, input);
-    return this.execute(() => this.trpc.reports.generate.mutate(validated));
+  async generateReport(
+    reportId: string,
+    defaults: TDefaults
+  ): Promise<GenerateResult> {
+    const validated = this.validate(reportDefaultsInputSchema, defaults);
+    return this.execute(() =>
+      this.trpc.reports.generate.mutate({ reportId, ...validated })
+    );
   }
 
   // ─────────────────────────────────────────────────────────────────

package/src/resources/transactions.ts

@@ -15,6 +15,7 @@ import type {
   CreateTransactionInput,
   UpdateTransactionInput,
   TransactionFilter,
+  TransactionSort,
   ListOptions,
   PaginatedResponse,
   AtomicBatchResult,
@@ -63,11 +64,14 @@ import { Transaction, type TransactionData } from "../models";
  * });
  * ```
  */
-export class TransactionsResource extends BaseResource<
+export class TransactionsResource<
+  TSort = TransactionSort,
+> extends BaseResource<
   Transaction,
   CreateTransactionInput,
   UpdateTransactionInput,
-  TransactionFilter
+  TransactionFilter,
+  TSort
 > {
   // ─────────────────────────────────────────────────────────────────
   // CRUD Operations
@@ -146,10 +150,10 @@ export class TransactionsResource extends BaseResource<
    * Lists transactions with optional filtering and pagination.
    */
   async list(
-    options?: ListOptions<TransactionFilter>
+    options?: ListOptions<TransactionFilter, TSort>
   ): Promise<PaginatedResponse<Transaction>> {
     const response = await this.execute(() =>
-      this.trpc.transactions.list.query(options)
+      this.trpc.transactions.list.query(options as ListOptions<TransactionFilter, TransactionSort>)
     );
 
     return {

package/src/sdk/ComplianceSDK.ts

@@ -49,7 +49,11 @@ import {
   LATEST_API_VERSION,
   DEFAULT_TIMEOUT,
 } from "../utils/trpc-client";
-import { validateEnvironment, resolveBaseUrl } from "../utils/environment";
+import {
+  resolveEnvironment,
+  resolveBaseUrl,
+  resolveOrganizationId,
+} from "../utils/environment";
 import {
   type SDKScope,
   type Environment,
@@ -254,6 +258,9 @@ export class ComplianceSDKImpl {
   /** Custom headers (cookie mode, for server-side cookie forwarding) */
   protected readonly _headers?: Record<string, string>;
 
+  /** Organization ID for session login (cookie mode) */
+  protected readonly _organizationId?: string;
+
   // ===========================
   // Resource Managers
   // ===========================
@@ -408,6 +415,7 @@ export class ComplianceSDKImpl {
     const {
       environment,
       baseUrl,
+      organizationId,
       apiVersion = LATEST_API_VERSION,
       timeout = DEFAULT_TIMEOUT,
       jurisdiction,
@@ -467,11 +475,14 @@ export class ComplianceSDKImpl {
       }
     }
 
-    // Validate environment
-    const validatedEnvironment = validateEnvironment(environment);
-    this._environment = validatedEnvironment;
+    // Resolve environment (from options or env var, defaults to "test")
+    const resolvedEnv = resolveEnvironment(environment);
+    this._environment = resolvedEnv;
     this._apiVersion = apiVersion;
 
+    // Resolve organization ID (from options or env var)
+    this._organizationId = organizationId ?? resolveOrganizationId();
+
     // Validate actividadVulnerable requires Mexico jurisdiction
     if (actividadVulnerable && jurisdiction !== Jurisdiction.Mexico) {
       throw new Error(
@@ -482,7 +493,7 @@ export class ComplianceSDKImpl {
 
     // Resolve base URL
     const resolvedBaseUrl = resolveBaseUrl({
-      environment: validatedEnvironment,
+      environment: resolvedEnv,
       baseUrl,
     });
 
@@ -500,18 +511,20 @@ export class ComplianceSDKImpl {
             mode: authMode,
             apiKey: resolvedApiKey as string,
             baseUrl: resolvedBaseUrl,
-            environment: validatedEnvironment as SDKEnvironment,
+            environment: resolvedEnv as SDKEnvironment,
             apiVersion,
             timeout,
+            organizationId: this._organizationId,
           }
         : {
             mode: authMode,
             credentials: resolvedCredentials,
             headers: resolvedHeaders,
             baseUrl: resolvedBaseUrl,
-            environment: validatedEnvironment as SDKEnvironment,
+            environment: resolvedEnv as SDKEnvironment,
             apiVersion,
             timeout,
+            organizationId: this._organizationId,
           };
 
     this.trpc = createAPIClient(trpcConfig);
@@ -520,7 +533,7 @@ export class ComplianceSDKImpl {
     const resourceConfig = {
       trpc: this.trpc,
       scope: this._scope,
-      environment: validatedEnvironment,
+      environment: resolvedEnv,
     };
     const factories = getResourceFactories(this._scope);
 
@@ -726,6 +739,8 @@ export class ComplianceSDKImpl {
       environment: this._environment,
       credentials: this._credentials ?? "include",
       headers: this._headers,
+      // Use provided organizationId or fall back to SDK-level config
+      organizationId: options?.organizationId ?? this._organizationId,
     };
 
     if (options?.returnTo) {

package/src/sdk/mex/ComplianceSDK.ts

@@ -40,12 +40,19 @@ export class MexicoComplianceSDKImpl extends ComplianceSDKImpl {
   // ─────────────────────────────────────────────────────────────────
   // Override resource types with Mexico-specific types
   // The registry creates these at runtime, we just need correct types
+  // Note: @ts-expect-error is needed due to sort type parameter variance
+  // (MexClientSort vs ClientSort in list method parameters)
   // ─────────────────────────────────────────────────────────────────
 
+  // @ts-expect-error - Runtime type is correct, variance issue with sort types
   declare public readonly clients: MexClientsResource;
+  // @ts-expect-error - Runtime type is correct, variance issue with sort types
   declare public readonly transactions: MexTransactionsResource;
+  // @ts-expect-error - Runtime type is correct, variance issue with sort types
   declare public readonly reports: MexReportsResource;
+  // @ts-expect-error - Runtime type is correct, variance issue with sort types
   declare public readonly bankAccounts: MexBankAccountsResource;
+  // @ts-expect-error - Runtime type is correct, variance issue with sort types
   declare public readonly addresses: MexAddressesResource;
 
   /**

package/src/sdk/mex/actividad-vulnerable/avi/ComplianceSDK.ts

@@ -40,8 +40,12 @@ import type { AVIReportsResource } from "../../../../resources/mex/actividad-vul
 export class AVIComplianceSDKScoped extends MexicoComplianceSDKScoped {
   // Override resource types with AVI-specific types
   // The registry creates these at runtime, we just need correct types
+  // Note: @ts-expect-error is needed due to sort type parameter variance
+  // @ts-expect-error - Runtime type is correct, variance issue with sort types
   declare public readonly clients: AVIClientsResource;
+  // @ts-expect-error - Runtime type is correct, variance issue with sort types
   declare public readonly transactions: AVITransactionsResource;
+  // @ts-expect-error - Runtime type is correct, variance issue with sort types
   declare public readonly reports: AVIReportsResource;
   // addresses and bankAccounts inherited from MexicoComplianceSDKImpl (MexAddressesResource, MexBankAccountsResource)