@artu-ai/compliance-sdk 0.4.0 → 0.4.2

package/src/resources/documents.ts

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