@artu-ai/compliance-sdk 0.2.0 → 0.3.0

package/src/resources/addresses.ts

@@ -9,6 +9,7 @@ import type {
   CreateAddressInput,
   UpdateAddressInput,
   AddressFilter,
+  AddressSort,
   AddressType,
   ListOptions,
   PaginatedResponse,
@@ -51,11 +52,14 @@ import type { BatchOptions } from "./clients";
  * const addresses = await sdk.addresses.listByClient("client_123");
  * ```
  */
-export class AddressesResource extends BaseResource<
+export class AddressesResource<
+  TSort = AddressSort,
+> extends BaseResource<
   Address,
   CreateAddressInput,
   UpdateAddressInput,
-  AddressFilter
+  AddressFilter,
+  TSort
 > {
   // ─────────────────────────────────────────────────────────────────
   // CRUD Operations
@@ -145,10 +149,10 @@ export class AddressesResource extends BaseResource<
    * @returns Paginated list of Addresses
    */
   async list(
-    options?: ListOptions<AddressFilter>
+    options?: ListOptions<AddressFilter, TSort>
   ): Promise<PaginatedResponse<Address>> {
     const response = await this.execute(() =>
-      this.trpc.addresses.list.query(options)
+      this.trpc.addresses.list.query(options as ListOptions<AddressFilter, AddressSort>)
     );
     return {
       data: response.data.map((a) => this.instantiate(a)),

package/src/resources/bank-accounts.ts

@@ -12,6 +12,7 @@ import type {
   CreateBankAccountInput,
   UpdateBankAccountInput,
   BankAccountFilter,
+  BankAccountSort,
   PaginatedResponse,
   ListOptions,
   AtomicBatchResult,
@@ -54,11 +55,14 @@ import { BankAccount, type BankAccountData } from "../models/BankAccount";
  * const accounts = await sdk.bankAccounts.list("client_123");
  * ```
  */
-export class BankAccountsResource extends BaseResource<
+export class BankAccountsResource<
+  TSort = BankAccountSort,
+> extends BaseResource<
   BankAccount,
   CreateBankAccountInput,
   UpdateBankAccountInput,
-  BankAccountFilter
+  BankAccountFilter,
+  TSort
 > {
   // ─────────────────────────────────────────────────────────────────
   // CRUD Operations
@@ -137,10 +141,10 @@ export class BankAccountsResource extends BaseResource<
    * Lists bank accounts with optional filtering.
    */
   async list(
-    options?: ListOptions<BankAccountFilter>
+    options?: ListOptions<BankAccountFilter, TSort>
   ): Promise<PaginatedResponse<BankAccount>> {
     const response = await this.execute(() =>
-      this.trpc.bankAccounts.list.query(options)
+      this.trpc.bankAccounts.list.query(options as ListOptions<BankAccountFilter, BankAccountSort>)
     );
 
     return {

package/src/resources/base.ts

@@ -85,6 +85,7 @@ export abstract class BaseResource<
   TCreateInput,
   TUpdateInput,
   TFilter = Record<string, unknown>,
+  TSort = unknown,
   TCreateResult = TModel,
 > {
   /**
@@ -172,7 +173,7 @@ export abstract class BaseResource<
    * @returns Paginated response
    */
   abstract list(
-    options?: ListOptions<TFilter>
+    options?: ListOptions<TFilter, TSort>
   ): Promise<PaginatedResponse<TModel>>;
 
   // ===========================
@@ -244,12 +245,13 @@ export abstract class BaseResource<
    * ```
    */
   protected createIterator<T = TModel>(
-    options?: IterateOptions<TFilter>
+    options?: IterateOptions<TFilter, TSort>
   ): AsyncGenerator<T, void, undefined> {
     return createPaginatedIterator<T>(
       (pagination) =>
         this.list({
           filter: options?.filter,
+          sort: options?.sort,
           ...pagination,
         }) as unknown as Promise<PaginatedResponse<T>>,
       { limit: options?.pageSize }
@@ -267,10 +269,12 @@ export abstract class BaseResource<
  *
  * @typeParam TModel - The model type returned by this resource
  * @typeParam TFilter - Filter type for list operations
+ * @typeParam TSort - Sort type for list operations
  */
 export abstract class ReadOnlyResource<
   TModel,
   TFilter = Record<string, unknown>,
+  TSort = unknown,
 > {
   protected readonly trpc: TRPCClient;
 
@@ -287,7 +291,7 @@ export abstract class ReadOnlyResource<
    * Lists resources with optional filtering and pagination
    */
   abstract list(
-    options?: ListOptions<TFilter>
+    options?: ListOptions<TFilter, TSort>
   ): Promise<PaginatedResponse<TModel>>;
 
   /**
@@ -308,12 +312,13 @@ export abstract class ReadOnlyResource<
    * Creates an async iterator for paginated results
    */
   protected createIterator<T = TModel>(
-    options?: IterateOptions<TFilter>
+    options?: IterateOptions<TFilter, TSort>
   ): AsyncGenerator<T, void, undefined> {
     return createPaginatedIterator<T>(
       (pagination) =>
         this.list({
           filter: options?.filter,
+          sort: options?.sort,
           ...pagination,
         }) as unknown as Promise<PaginatedResponse<T>>,
       { limit: options?.pageSize }

package/src/resources/clients.ts

@@ -21,6 +21,7 @@ import type {
   CreateBankAccountInput,
   UpdateBankAccountInput,
   ClientFilter,
+  ClientSort,
   ListOptions,
   PaginatedResponse,
   AtomicBatchResult,
@@ -112,11 +113,14 @@ export interface ClientIncludeMap {
  * }
  * ```
  */
-export class ClientsResource extends BaseResource<
+export class ClientsResource<
+  TSort = ClientSort,
+> extends BaseResource<
   Client,
   CreateClientInput,
   UpdateClientInput,
-  ClientFilter
+  ClientFilter,
+  TSort
 > {
   // ─────────────────────────────────────────────────────────────────
   // CRUD Operations
@@ -256,10 +260,12 @@ export class ClientsResource extends BaseResource<
    * ```
    */
   async list(
-    options?: ListOptions<ClientFilter> & { includePrimaryContacts?: boolean }
+    options?: ListOptions<ClientFilter, TSort> & { includePrimaryContacts?: boolean }
   ): Promise<PaginatedResponse<Client>> {
     const response = await this.execute(() =>
-      this.trpc.clients.list.query(options)
+      this.trpc.clients.list.query(
+        options as ListOptions<ClientFilter, ClientSort> & { includePrimaryContacts?: boolean }
+      )
     );
 
     return {

package/src/resources/contact-methods.ts

@@ -10,6 +10,7 @@ import type {
   UpdateContactMethodInput,
   ContactMethodType,
   ContactMethodFilter,
+  ContactMethodSort,
   ListOptions,
   PaginatedResponse,
   AtomicBatchResult,
@@ -52,7 +53,8 @@ export class ContactMethodsResource extends BaseResource<
   ContactMethod,
   CreateContactMethodInput,
   UpdateContactMethodInput,
-  ContactMethodFilter
+  ContactMethodFilter,
+  ContactMethodSort
 > {
   // ─────────────────────────────────────────────────────────────────
   // CRUD Operations
@@ -145,7 +147,7 @@ export class ContactMethodsResource extends BaseResource<
    * @returns Paginated list of ContactMethods
    */
   async list(
-    options?: ListOptions<ContactMethodFilter>
+    options?: ListOptions<ContactMethodFilter, ContactMethodSort>
   ): Promise<PaginatedResponse<ContactMethod>> {
     const response = await this.execute(() =>
       this.trpc.contactMethods.list.query(options)

package/src/resources/documents.ts

@@ -8,6 +8,7 @@
 import type {
   PaginatedResponse,
   DocumentFilter,
+  DocumentSort,
   CreateDocumentInput,
   UpdateDocumentInput,
   ListOptions,
@@ -23,6 +24,14 @@ import {
 import { z } from "zod";
 import { Document, type DocumentData } from "../models/Document";
 import { BaseResource } from "./base";
+import {
+  uploadToS3,
+  normalizeFile,
+  validateFileSize,
+  type UploadableFile,
+  type ProgressCallback,
+} from "../utils/upload";
+import { UploadError } from "../errors/upload";
 
 // ─────────────────────────────────────────────────────────────────
 // Types
@@ -44,13 +53,51 @@ export interface PartialBatchResult<T> {
 }
 
 /**
- * Result of creating a document, including presigned upload URL.
+ * Result of creating a document.
+ *
+ * - With contentType: Returns document + presigned upload URL
+ * - Without contentType: Returns document only (no-file document)
  */
 export interface CreateDocumentResult {
   /** The created document */
   document: Document;
-  /** Presigned URL for uploading the file */
-  upload: PresignedUploadUrl;
+  /** Presigned URL for uploading the file (only for file uploads) */
+  upload?: PresignedUploadUrl;
+}
+
+/**
+ * Input for uploading a document file.
+ * Combines document metadata with upload options.
+ */
+export type UploadDocumentInput = Omit<CreateDocumentInput, "contentType"> & {
+  /** Optional content type override. If not provided, will be inferred from file. */
+  contentType?: string;
+};
+
+/**
+ * Options for the upload operation.
+ */
+export interface UploadOptions {
+  /**
+   * Progress callback, called with a value from 0 to 1.
+   * Only works in browser environments.
+   */
+  onProgress?: ProgressCallback;
+
+  /**
+   * AbortSignal for cancelling the upload.
+   * @example
+   * const controller = new AbortController();
+   * sdk.documents.upload(file, data, { signal: controller.signal });
+   * // Later: controller.abort();
+   */
+  signal?: AbortSignal;
+
+  /**
+   * Upload timeout in milliseconds.
+   * @default 300000 (5 minutes)
+   */
+  timeout?: number;
 }
 
 // ─────────────────────────────────────────────────────────────────
@@ -82,6 +129,7 @@ export class DocumentsResource extends BaseResource<
   CreateDocumentInput,
   UpdateDocumentInput,
   DocumentFilter,
+  DocumentSort,
   CreateDocumentResult
 > {
   // ─────────────────────────────────────────────────────────────────
@@ -169,6 +217,138 @@ export class DocumentsResource extends BaseResource<
     return this.instantiate(response as DocumentData);
   }
 
+  // ─────────────────────────────────────────────────────────────────
+  // Upload (High-Level Helper)
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Uploads a file and creates a document in one operation.
+   *
+   * This is a convenience method that combines:
+   * 1. Creating a document record with presigned URL
+   * 2. Uploading the file directly to storage
+   * 3. Confirming the upload
+   *
+   * For more control over the upload process, use `create()`, manual upload,
+   * and `confirmUpload()` separately.
+   *
+   * @param file - The file to upload (File, Blob, or UploadableFile)
+   * @param data - Document metadata (clientId, jurisdiction, type, etc.)
+   * @param options - Upload options (progress callback, abort signal, timeout)
+   * @returns The created and uploaded document
+   *
+   * @example
+   * ```typescript
+   * // Simple upload
+   * const document = await sdk.documents.upload(file, {
+   *   clientId: "client-123",
+   *   jurisdiction: "MX",
+   *   type: "ine_front",
+   * });
+   *
+   * // With progress tracking
+   * const document = await sdk.documents.upload(file, {
+   *   clientId: "client-123",
+   *   jurisdiction: "MX",
+   *   type: "ine_front",
+   * }, {
+   *   onProgress: (progress) => {
+   *     console.log(`Upload: ${Math.round(progress * 100)}%`);
+   *   },
+   * });
+   *
+   * // With abort support
+   * const controller = new AbortController();
+   * const uploadPromise = sdk.documents.upload(file, data, {
+   *   signal: controller.signal,
+   * });
+   *
+   * // Cancel the upload
+   * controller.abort();
+   * ```
+   *
+   * @throws {FileTooLargeError} If file exceeds 25 MB limit
+   * @throws {UploadError} If upload fails at any stage
+   * @throws {UploadAbortedError} If upload is cancelled via AbortSignal
+   * @throws {UploadTimeoutError} If upload times out
+   */
+  async upload(
+    file: File | Blob | UploadableFile,
+    data: UploadDocumentInput,
+    options: UploadOptions = {}
+  ): Promise<Document> {
+    const { onProgress, signal, timeout } = options;
+
+    // Normalize file input
+    const normalizedFile = normalizeFile(file);
+
+    // Validate file size before starting
+    validateFileSize(normalizedFile.size);
+
+    // Check if already aborted
+    if (signal?.aborted) {
+      throw new UploadError("Upload was aborted before starting", "request");
+    }
+
+    // Determine content type (use provided or infer from file)
+    const contentType = data.contentType || normalizedFile.type;
+    if (!contentType || contentType === "application/octet-stream") {
+      throw new UploadError(
+        "Could not determine file content type. Please provide contentType explicitly.",
+        "request"
+      );
+    }
+
+    // Validate content type is allowed
+    const allowedTypes = [
+      "image/jpeg",
+      "image/png",
+      "image/webp",
+      "application/pdf",
+    ] as const;
+    type AllowedContentType = (typeof allowedTypes)[number];
+
+    if (!allowedTypes.includes(contentType as AllowedContentType)) {
+      throw new UploadError(
+        `Invalid file type: ${contentType}. Allowed types: ${allowedTypes.join(", ")}`,
+        "request"
+      );
+    }
+
+    // Step 1: Create document and get presigned URL
+    const createInput: CreateDocumentInput = {
+      ...data,
+      contentType: contentType as AllowedContentType,
+    };
+
+    const { document, upload } = await this.create(createInput);
+
+    // upload should always be present when contentType is provided
+    if (!upload) {
+      throw new UploadError(
+        "Server did not return upload URL. This should not happen.",
+        "request"
+      );
+    }
+
+    // Step 2: Upload file to S3
+    // Note: If upload fails, the document remains in pending_upload status
+    // and will be cleaned up by the orphan document cleanup job
+    await uploadToS3(normalizedFile, upload, {
+      onProgress,
+      signal,
+      timeout,
+    });
+
+    // Step 3: Confirm upload
+    return this.confirmUpload({
+      id: document.id,
+      filename: normalizedFile.name,
+      contentType,
+      size: normalizedFile.size,
+    });
+  }
+
   /**
    * Gets a presigned URL for downloading/viewing a document.
    *
@@ -285,7 +465,7 @@ export class DocumentsResource extends BaseResource<
    * @returns Paginated list of documents
    */
   async list(
-    options?: ListOptions<DocumentFilter>
+    options?: ListOptions<DocumentFilter, DocumentSort>
   ): Promise<PaginatedResponse<Document>> {
     const response = await this.execute(() =>
       this.trpc.documents.list.query(options)
@@ -335,7 +515,7 @@ export class DocumentsResource extends BaseResource<
    * @yields Documents one at a time
    */
   async *iterate(
-    options?: ListOptions<DocumentFilter>
+    options?: ListOptions<DocumentFilter, DocumentSort>
   ): AsyncGenerator<Document, void, unknown> {
     let cursor: string | undefined;
     let hasMore = true;

package/src/resources/index.ts

@@ -29,7 +29,12 @@ export {
 export { AddressesResource } from "./addresses";
 export { ContactMethodsResource } from "./contact-methods";
 export { BankAccountsResource } from "./bank-accounts";
-export { DocumentsResource, type CreateDocumentResult } from "./documents";
+export {
+  DocumentsResource,
+  type CreateDocumentResult,
+  type UploadDocumentInput,
+  type UploadOptions,
+} from "./documents";
 
 // Mexico-scoped resources
 export * from "./mex";

package/src/resources/mex/actividad-vulnerable/avi/clients.ts

@@ -11,6 +11,7 @@ import type {
   CreateClientInput,
   UpdateClientInput,
   ClientFilter,
+  ClientSort,
   ListOptions,
   PaginatedResponse,
   CreateAVIClientInput,
@@ -31,12 +32,15 @@ import type {
   SyncResult,
   MexClientFilter,
   AVIClientFilter,
+  AVIClientSort,
 } from "@artu-ai/shared";
 import {
   CodigoActividad,
   createAVIClientInputSchema,
   updateAVIClientInputSchema,
   linkedClientSchema,
+  transformSort,
+  aviClientFieldMapping,
 } from "@artu-ai/shared";
 import { MexClientsResource } from "../../clients";
 import { type BatchOptions, type ClientIncludeMap } from "../../../clients";
@@ -81,7 +85,7 @@ import {
  * console.log(client.username);
  * ```
  */
-export class AVIClientsResource extends MexClientsResource {
+export class AVIClientsResource extends MexClientsResource<AVIClientSort> {
   // ─────────────────────────────────────────────────────────────────
   // CRUD Operations
   // ─────────────────────────────────────────────────────────────────
@@ -158,14 +162,16 @@ export class AVIClientsResource extends MexClientsResource {
    * ```
    */
   async list(
-    options?: ListOptions<AVIClientFilter>
+    options?: ListOptions<AVIClientFilter, AVIClientSort>
   ): Promise<PaginatedResponse<MexAVIClient>> {
     const scopedFilter = this.applyScopeToFilter(options?.filter);
+    const scopedSort = this.applyScopeToSort(options?.sort);
 
     const response = await this.execute(() =>
       this.trpc.clients.list.query({
         ...options,
         filter: scopedFilter,
+        sort: scopedSort,
       })
     );
 
@@ -386,8 +392,12 @@ export class AVIClientsResource extends MexClientsResource {
     data: {
       client?: UpdateAVIClientInput;
       addresses?: SyncItem<UpdateMexAddressInput | CreateMexAddressInput>[];
-      contactMethods?: SyncItem<UpdateContactMethodInput | CreateContactMethodInput>[];
-      bankAccounts?: SyncItem<UpdateBankAccountInput | CreateBankAccountInput>[];
+      contactMethods?: SyncItem<
+        UpdateContactMethodInput | CreateContactMethodInput
+      >[];
+      bankAccounts?: SyncItem<
+        UpdateBankAccountInput | CreateBankAccountInput
+      >[];
       linkedClients?: LinkedClientInput[];
     },
     options?: { replaceMode?: boolean }
@@ -430,7 +440,9 @@ export class AVIClientsResource extends MexClientsResource {
    * Extracts AVI-specific fields (username) from root level and nests them
    * under jurisdictions.MX.actividadVulnerable.AVI.
    */
-  protected override applyScopeToFilter(filter?: AVIClientFilter): ClientFilter {
+  protected override applyScopeToFilter(
+    filter?: AVIClientFilter
+  ): ClientFilter {
     if (!filter) {
       return super.applyScopeToFilter(undefined);
     }
@@ -439,9 +451,7 @@ export class AVIClientsResource extends MexClientsResource {
     const { username, ...mexFilter } = filter;
 
     // Let parent handle MX fields
-    const nestedFilter = super.applyScopeToFilter(
-      mexFilter as MexClientFilter
-    );
+    const nestedFilter = super.applyScopeToFilter(mexFilter as MexClientFilter);
 
     // Only add AVI activity filter if username is provided
     if (username !== undefined) {
@@ -467,6 +477,18 @@ export class AVIClientsResource extends MexClientsResource {
     return nestedFilter;
   }
 
+  /**
+   * Transforms a flattened AVIClientSort to nested ClientSort format.
+   *
+   * Maps flattened field names (username, rfc, curp) to their full API paths.
+   */
+  protected override applyScopeToSort(sort?: AVIClientSort): ClientSort | undefined {
+    if (!sort || sort.length === 0) {
+      return undefined;
+    }
+    return transformSort(sort, aviClientFieldMapping);
+  }
+
   /**
    * Transforms flattened AVI input to nested API format.
    */