@artu-ai/compliance-sdk 0.0.5 → 0.2.0

package/src/resources/documents.ts

@@ -0,0 +1,508 @@
+/**
+ * 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,
+  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";
+
+// ─────────────────────────────────────────────────────────────────
+// 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, including presigned upload URL.
+ */
+export interface CreateDocumentResult {
+  /** The created document */
+  document: Document;
+  /** Presigned URL for uploading the file */
+  upload: PresignedUploadUrl;
+}
+
+// ─────────────────────────────────────────────────────────────────
+// 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,
+  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);
+  }
+
+  /**
+   * 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>
+  ): 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>
+  ): 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);
+  }
+}

package/src/resources/index.ts

@@ -0,0 +1,35 @@
+/**
+ * Resource Managers
+ *
+ * This module exports resource classes for interacting with
+ * the compliance API. Each resource handles CRUD operations,
+ * pagination, and error mapping for a specific entity type.
+ *
+ * Resource Hierarchy:
+ * - Base resources: Unscoped, accept full nested input
+ * - Mex resources: Mexico-scoped, accept flattened MX input
+ * - Activity resources: Activity-scoped, accept fully flattened input
+ */
+
+// Base classes
+export { BaseResource, ReadOnlyResource, type ResourceConfig } from "./base";
+
+// Base resource implementations (unscoped)
+export { ClientsResource, type BatchOptions } from "./clients";
+export { TransactionsResource } from "./transactions";
+export type { RelatedClient, LinkedClient } from "@artu-ai/shared";
+export {
+  ReportsResource,
+  type ReportFilter,
+  type ReportItemFilter,
+  type AddItemsResult,
+} from "./reports";
+
+// Supporting resources
+export { AddressesResource } from "./addresses";
+export { ContactMethodsResource } from "./contact-methods";
+export { BankAccountsResource } from "./bank-accounts";
+export { DocumentsResource, type CreateDocumentResult } from "./documents";
+
+// Mexico-scoped resources
+export * from "./mex";