@artu-ai/compliance-sdk 0.0.6 → 0.3.0

package/src/resources/documents.ts

@@ -0,0 +1,688 @@
+/**
+ * Documents resource
+ *
+ * CRUD operations for documents. File upload/download operations are handled separately.
+ * All documents are created with pending_upload status.
+ */
+
+import type {
+  PaginatedResponse,
+  DocumentFilter,
+  DocumentSort,
+  CreateDocumentInput,
+  UpdateDocumentInput,
+  ListOptions,
+  ConfirmUploadInput,
+  PresignedUploadUrl,
+  PresignedDownloadUrl,
+} from "@artu-ai/shared";
+import {
+  createDocumentInputSchema,
+  updateDocumentInputSchema,
+  confirmUploadInputSchema,
+} from "@artu-ai/shared";
+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
+// ─────────────────────────────────────────────────────────────────
+
+export interface BatchOptions {
+  atomic?: boolean;
+}
+
+export interface AtomicBatchResult<T> {
+  atomic: true;
+  data: T[];
+}
+
+export interface PartialBatchResult<T> {
+  atomic: false;
+  succeeded: { index: number; data: T }[];
+  failed: { index: number; error: { code: string; message: string } }[];
+}
+
+/**
+ * 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 (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;
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Resource
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * Documents resource for managing document records.
+ *
+ * @example
+ * ```typescript
+ * // Create a document record
+ * const doc = await sdk.documents.create({
+ *   clientId: "client_123",
+ *   jurisdiction: "MX",
+ *   type: "ine_front",
+ *   category: "identity",
+ * });
+ *
+ * // List documents
+ * const docs = await sdk.documents.list({ filter: { clientId: "client_123" } });
+ *
+ * // Update document metadata
+ * await sdk.documents.update(doc.id, { metadata: { verified: true } });
+ * ```
+ */
+export class DocumentsResource extends BaseResource<
+  Document,
+  CreateDocumentInput,
+  UpdateDocumentInput,
+  DocumentFilter,
+  DocumentSort,
+  CreateDocumentResult
+> {
+  // ─────────────────────────────────────────────────────────────────
+  // Create
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Creates a new document record and returns a presigned POST upload URL.
+   *
+   * Documents are created with status "pending_upload".
+   * Use the returned presigned URL to upload the file directly to storage.
+   * After upload, call `confirmUpload()` to transition status to "uploaded".
+   *
+   * **Important:** The upload uses POST with FormData (not PUT). This allows
+   * enforcing a 25 MB file size limit at the storage level.
+   *
+   * @param data - Document data
+   * @returns The created document and presigned upload URL with form fields
+   *
+   * @example
+   * ```typescript
+   * // Create document and get upload URL
+   * const { document, upload } = await compliance.documents.create({
+   *   clientId: "client-123",
+   *   jurisdiction: "MX",
+   *   type: "ine_front",
+   * });
+   *
+   * // Build FormData with fields + file (file must be last!)
+   * const formData = new FormData();
+   * Object.entries(upload.fields).forEach(([key, value]) => {
+   *   formData.append(key, value);
+   * });
+   * formData.append("Content-Type", file.type);  // Add content-type
+   * formData.append("file", file);               // File MUST be last
+   *
+   * // Upload via POST
+   * const uploadResponse = await fetch(upload.url, {
+   *   method: "POST",
+   *   body: formData,
+   * });
+   *
+   * if (!uploadResponse.ok) {
+   *   throw new Error(`Upload failed: ${uploadResponse.status}`);
+   * }
+   *
+   * // Confirm upload with file metadata
+   * await compliance.documents.confirmUpload({
+   *   id: document.id,
+   *   filename: file.name,
+   *   contentType: file.type,
+   *   size: file.size,
+   * });
+   * ```
+   */
+  async create(data: CreateDocumentInput): Promise<CreateDocumentResult> {
+    const validated = this.validate(createDocumentInputSchema, data);
+
+    const response = await this.execute(() =>
+      this.trpc.documents.create.mutate(validated)
+    );
+
+    return {
+      document: this.instantiate(response.document as DocumentData),
+      upload: response.upload,
+    };
+  }
+
+  /**
+   * Confirms that a file has been uploaded to storage.
+   *
+   * Call this after uploading a file via the presigned URL returned by `create()`.
+   * This transitions the document status from "pending_upload" to "uploaded".
+   *
+   * @param data - Upload confirmation data
+   * @returns The updated document
+   */
+  async confirmUpload(data: ConfirmUploadInput): Promise<Document> {
+    const validated = this.validate(confirmUploadInputSchema, data);
+
+    const response = await this.execute(() =>
+      this.trpc.documents.confirmUpload.mutate(validated)
+    );
+
+    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.
+   *
+   * The URL allows direct access to the file in storage without going through the backend.
+   * Use this for displaying documents in the UI or downloading them.
+   *
+   * @param id - Document ID
+   * @returns Presigned download URL with expiration
+   * @throws If document doesn't exist, is in pending_upload status, or has no storage path
+   *
+   * @example
+   * ```typescript
+   * // Get download URL for viewing
+   * const { url, expiresAt } = await compliance.documents.getDownloadUrl(docId);
+   *
+   * // Display in browser
+   * window.open(url, '_blank');
+   *
+   * // Or use in an img tag
+   * <img src={url} alt="Document" />
+   * ```
+   */
+  async getDownloadUrl(id: string): Promise<PresignedDownloadUrl> {
+    const response = await this.execute(() =>
+      this.trpc.documents.getDownloadUrl.query({ id })
+    );
+
+    return response;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Retrieve
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Retrieves a document by ID
+   *
+   * @param id - Document ID
+   * @returns The document
+   */
+  async retrieve(id: string): Promise<Document> {
+    const response = await this.execute(() =>
+      this.trpc.documents.retrieve.query({ id })
+    );
+    return this.instantiate(response as DocumentData);
+  }
+
+  /**
+   * Retrieves a document by metadata key/value.
+   */
+  async retrieveByMetadata(key: string, value: string): Promise<Document> {
+    const response = await this.execute(() =>
+      this.trpc.documents.retrieveByMetadata.query({ key, value })
+    );
+    return this.instantiate(response as DocumentData);
+  }
+
+  /**
+   * Retrieves a document by externalId
+   */
+  async retrieveByExternalId(externalId: string): Promise<Document> {
+    const response = await this.execute(() =>
+      this.trpc.documents.retrieveByExternalId.query({ externalId })
+    );
+    return this.instantiate(response as DocumentData);
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Update
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Updates a document's metadata, expiration, or fields.
+   *
+   * Note: Status cannot be updated directly - it's managed by the system.
+   *
+   * @param id - Document ID
+   * @param data - Fields to update
+   * @returns The updated document
+   */
+  async update(id: string, data: UpdateDocumentInput): Promise<Document> {
+    const validated = this.validate(updateDocumentInputSchema, data);
+
+    const response = await this.execute(() =>
+      this.trpc.documents.update.mutate({
+        id,
+        data: validated,
+      })
+    );
+    return this.instantiate(response as DocumentData);
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Delete
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Soft-deletes a document
+   *
+   * @param id - Document ID
+   */
+  async delete(id: string): Promise<void> {
+    await this.execute(() => this.trpc.documents.delete.mutate({ id }));
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // List
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Lists documents with optional filtering and pagination.
+   *
+   * @param options - List options with filter, cursor, and limit
+   * @returns Paginated list of documents
+   */
+  async list(
+    options?: ListOptions<DocumentFilter, DocumentSort>
+  ): Promise<PaginatedResponse<Document>> {
+    const response = await this.execute(() =>
+      this.trpc.documents.list.query(options)
+    );
+
+    const typedResponse = response as {
+      data: DocumentData[];
+      pagination: { nextCursor?: string; hasMore: boolean };
+    };
+
+    return {
+      data: typedResponse.data.map((d) => this.instantiate(d)),
+      pagination: typedResponse.pagination,
+    };
+  }
+
+  /**
+   * Lists all documents for a specific client with pagination.
+   *
+   * @param clientId - Client ID
+   * @param options - Pagination options
+   * @returns Paginated list of documents
+   */
+  async listByClient(
+    clientId: string,
+    options?: { cursor?: string; limit?: number }
+  ): Promise<PaginatedResponse<Document>> {
+    const response = await this.execute(() =>
+      this.trpc.documents.listByClient.query({ clientId, ...options })
+    );
+
+    const typedResponse = response as {
+      data: DocumentData[];
+      pagination: { nextCursor?: string; hasMore: boolean };
+    };
+
+    return {
+      data: typedResponse.data.map((d) => this.instantiate(d)),
+      pagination: typedResponse.pagination,
+    };
+  }
+
+  /**
+   * Async iterator for documents with optional filtering.
+   *
+   * @param options - Filter options
+   * @yields Documents one at a time
+   */
+  async *iterate(
+    options?: ListOptions<DocumentFilter, DocumentSort>
+  ): AsyncGenerator<Document, void, unknown> {
+    let cursor: string | undefined;
+    let hasMore = true;
+
+    while (hasMore) {
+      const response = await this.list({
+        ...options,
+        cursor,
+        limit: options?.limit ?? 100,
+      });
+
+      for (const doc of response.data) {
+        yield doc;
+      }
+
+      cursor = response.pagination.nextCursor;
+      hasMore = response.pagination.hasMore;
+    }
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Batch Operations
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Creates multiple document records in a batch.
+   *
+   * @param documents - Array of document creation data
+   * @param options - Batch options (atomic: true by default)
+   * @returns Atomic result with data array, or partial result with succeeded/failed
+   */
+  async createMany(
+    documents: CreateDocumentInput[],
+    options?: { atomic?: true }
+  ): Promise<AtomicBatchResult<Document>>;
+  async createMany(
+    documents: CreateDocumentInput[],
+    options: { atomic: false }
+  ): Promise<PartialBatchResult<Document>>;
+  async createMany(
+    documents: CreateDocumentInput[],
+    options: BatchOptions = {}
+  ): Promise<AtomicBatchResult<Document> | PartialBatchResult<Document>> {
+    const atomic = options.atomic ?? true;
+    const validated = this.validate(
+      z.array(createDocumentInputSchema),
+      documents
+    );
+
+    const response = await this.execute(() =>
+      this.trpc.documents.createMany.mutate({ items: validated, atomic })
+    );
+
+    if (response.atomic) {
+      return {
+        atomic: true,
+        data: response.data.map((d) => this.instantiate(d as DocumentData)),
+      };
+    } else {
+      return {
+        atomic: false,
+        succeeded: response.succeeded.map((item) => ({
+          index: item.index,
+          data: this.instantiate(item.data as DocumentData),
+        })),
+        failed: response.failed,
+      };
+    }
+  }
+
+  /**
+   * Updates multiple documents in a batch.
+   *
+   * @param updates - Array of { id, data } objects
+   * @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: UpdateDocumentInput }[],
+    options?: { atomic?: true }
+  ): Promise<AtomicBatchResult<Document>>;
+  async updateMany(
+    updates: { id: string; data: UpdateDocumentInput }[],
+    options: { atomic: false }
+  ): Promise<PartialBatchResult<Document>>;
+  async updateMany(
+    updates: { id: string; data: UpdateDocumentInput }[],
+    options: BatchOptions = {}
+  ): Promise<AtomicBatchResult<Document> | PartialBatchResult<Document>> {
+    const atomic = options.atomic ?? true;
+    const validated = updates.map((u) => ({
+      id: u.id,
+      data: this.validate(updateDocumentInputSchema, u.data),
+    }));
+
+    const response = await this.execute(() =>
+      this.trpc.documents.updateMany.mutate({ items: validated, atomic })
+    );
+
+    if (response.atomic) {
+      return {
+        atomic: true,
+        data: response.data.map((d) => this.instantiate(d as DocumentData)),
+      };
+    } else {
+      return {
+        atomic: false,
+        succeeded: response.succeeded.map((item) => ({
+          index: item.index,
+          data: this.instantiate(item.data as DocumentData),
+        })),
+        failed: response.failed,
+      };
+    }
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Helpers
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Gets document count for a client
+   *
+   * @param clientId - Client ID
+   * @returns Count of documents
+   */
+  async countByClient(clientId: string): Promise<number> {
+    const response = await this.listByClient(clientId, { limit: 100 });
+    // For accurate count, we'd need a dedicated endpoint
+    // This is an approximation
+    let count = response.data.length;
+    let cursor = response.pagination.nextCursor;
+
+    while (response.pagination.hasMore && cursor) {
+      const next = await this.listByClient(clientId, { cursor, limit: 100 });
+      count += next.data.length;
+      cursor = next.pagination.nextCursor;
+      if (!next.pagination.hasMore) break;
+    }
+
+    return count;
+  }
+
+  /**
+   * Checks if a document with the given type exists for a client
+   *
+   * @param clientId - Client ID
+   * @param type - Document type
+   * @returns True if document exists and is available
+   */
+  async hasDocumentType(clientId: string, type: string): Promise<boolean> {
+    const response = await this.list({
+      filter: { clientId, type },
+      limit: 1,
+    });
+    return response.data.some((d) => d.type === type && d.isAvailable);
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Protected Methods
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Instantiates a Document model from raw data.
+   * Override in subclasses to return jurisdiction-specific models.
+   */
+  protected instantiate(data: DocumentData): Document {
+    return new Document(data);
+  }
+}