@artu-ai/compliance-sdk 0.13.4 → 0.17.0

package/dist/resources/documents.js

@@ -4,7 +4,7 @@
  * CRUD operations for documents. File upload/download operations are handled separately.
  * All documents are created with pending_upload status.
  */
-import { confirmUploadInputSchema, createDocumentInputSchema, updateDocumentInputSchema, upsertDocumentInputSchema, } from "@artu-ai/shared";
+import { confirmUploadInputSchema, createDocumentInputSchema, extractDocumentInputSchema, updateDocumentInputSchema, upsertDocumentInputSchema, } from "@artu-ai/shared";
 import { z } from "zod";
 import { UploadError } from "../errors/upload";
 import { Document } from "../models/Document";
@@ -21,7 +21,7 @@ import { BaseResource } from "./base";
  * // Create a document record
  * const doc = await sdk.documents.create({
  *   clientId: "client_123",
- *   jurisdiction: "MX",
+ *   scope: "MX",
  *   type: "ine_front",
  *   category: "identity",
  * });
@@ -55,7 +55,7 @@ export class DocumentsResource extends BaseResource {
      * // Create document and get upload URL
      * const { document, upload } = await compliance.documents.create({
      *   clientId: "client-123",
-     *   jurisdiction: "MX",
+     *   scope: "MX",
      *   type: "ine_front",
      * });
      *
@@ -116,7 +116,7 @@ export class DocumentsResource extends BaseResource {
      * and `confirmUpload()` separately.
      *
      * @param file - The file to upload (File, Blob, or UploadableFile)
-     * @param data - Document metadata (clientId, jurisdiction, type, etc.)
+     * @param data - Document metadata (clientId, scope, type, etc.)
      * @param options - Upload options (progress callback, abort signal, timeout)
      * @returns The created and uploaded document
      *
@@ -125,14 +125,14 @@ export class DocumentsResource extends BaseResource {
      * // Simple upload
      * const document = await sdk.documents.upload(file, {
      *   clientId: "client-123",
-     *   jurisdiction: "MX",
+     *   scope: "MX",
      *   type: "ine_front",
      * });
      *
      * // With progress tracking
      * const document = await sdk.documents.upload(file, {
      *   clientId: "client-123",
-     *   jurisdiction: "MX",
+     *   scope: "MX",
      *   type: "ine_front",
      * }, {
      *   onProgress: (progress) => {
@@ -190,19 +190,95 @@ export class DocumentsResource extends BaseResource {
         if (!upload) {
             throw new UploadError("Server did not return upload URL. This should not happen.", "request");
         }
-        // Step 2: Upload file to storage
-        // Note: If upload fails, the document remains in pending_upload status
-        // and will be cleaned up by the orphan document cleanup job
+        // Step 2: Upload file to storage. If this fails, attach the document
+        // id to the thrown error so callers can call retryUpload(id, file)
+        // instead of orphaning the record in pending_upload.
+        try {
+            await uploadToStorage(normalizedFile, upload, {
+                onProgress,
+                signal,
+                timeout,
+            });
+        }
+        catch (err) {
+            if (err instanceof UploadError) {
+                throw new UploadError(err.message, err.stage, {
+                    cause: err,
+                    details: err.details,
+                    requestId: err.requestId,
+                    resourceId: document.id,
+                });
+            }
+            throw new UploadError(err instanceof Error ? err.message : "Failed to upload file to storage", "upload", { cause: err, resourceId: document.id });
+        }
+        // Step 3: Confirm upload (same wrapping as above).
+        try {
+            return await this.confirmUpload({
+                id: document.id,
+                filename: normalizedFile.name,
+                contentType,
+                size: normalizedFile.size,
+            });
+        }
+        catch (err) {
+            throw new UploadError(err instanceof Error ? err.message : "Failed to confirm upload", "confirm", { cause: err, resourceId: document.id });
+        }
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Retry (failed upload)
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Regenerates a presigned upload URL for a document record that is
+     * stuck in `pending_upload` after a failed upload attempt.
+     *
+     * The record retains its original `storagePath` and `contentType`, so
+     * the new URL is signed against the same path with the same content-type
+     * restriction. After re-uploading, call `confirmUpload()` as usual.
+     *
+     * @param id - Document ID (must be in `pending_upload` status)
+     * @returns Fresh presigned upload URL with expiration
+     */
+    async getUploadUrl(id) {
+        return this.execute(() => this.trpc.documents.getUploadUrl.mutate({ id }));
+    }
+    /**
+     * Retries a failed upload for a document record stuck in `pending_upload`.
+     *
+     * Combines:
+     * 1. Regenerating the presigned upload URL (`getUploadUrl`)
+     * 2. Uploading the file directly to storage
+     * 3. Confirming the upload
+     *
+     * Use this when the original `upload()` call failed at the storage PUT
+     * step (network error, S3 throttling, etc.) but the document record was
+     * created successfully.
+     *
+     * @param id - Document ID (must be in `pending_upload` status)
+     * @param file - The file to upload (must match the original contentType)
+     * @param options - Upload options (progress callback, abort signal, timeout)
+     * @returns The confirmed document record
+     *
+     * @throws {UploadError} If upload fails at any stage
+     * @throws {UploadAbortedError} If upload is cancelled via AbortSignal
+     * @throws {UploadTimeoutError} If upload times out
+     */
+    async retryUpload(id, file, options = {}) {
+        const { onProgress, signal, timeout } = options;
+        const normalizedFile = normalizeFile(file);
+        validateFileSize(normalizedFile.size);
+        if (signal?.aborted) {
+            throw new UploadError("Upload was aborted before starting", "request");
+        }
+        const upload = await this.getUploadUrl(id);
         await uploadToStorage(normalizedFile, upload, {
             onProgress,
             signal,
             timeout,
         });
-        // Step 3: Confirm upload
         return this.confirmUpload({
-            id: document.id,
+            id,
             filename: normalizedFile.name,
-            contentType,
+            contentType: normalizedFile.type,
             size: normalizedFile.size,
         });
     }
@@ -291,6 +367,57 @@ export class DocumentsResource extends BaseResource {
         await this.execute(() => this.trpc.documents.delete.mutate({ id }));
     }
     // ─────────────────────────────────────────────────────────────────
+    // Review Actions
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Submit an uploaded document for officer review.
+     * Transitions: uploaded → pending_review.
+     *
+     * @param id - Document ID
+     * @returns The updated document
+     */
+    async submit(id) {
+        const response = await this.execute(() => this.trpc.documents.submit.mutate({ id }));
+        return this.instantiate(response);
+    }
+    /**
+     * Verify a pending_review document.
+     * Transitions: pending_review → verified.
+     *
+     * @param id - Document ID
+     * @returns The updated document
+     */
+    async verify(id) {
+        const response = await this.execute(() => this.trpc.documents.verify.mutate({ id }));
+        return this.instantiate(response);
+    }
+    /**
+     * Reject a pending_review document with a reason.
+     * Transitions: pending_review → rejected.
+     *
+     * @param id - Document ID
+     * @param input - Rejection details
+     * @returns The updated document
+     */
+    async reject(id, input) {
+        const response = await this.execute(() => this.trpc.documents.reject.mutate({ id, reason: input.reason }));
+        return this.instantiate(response);
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // OCR Extraction
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Extract structured fields from a document via the OCR pipeline.
+     * Status transitions: uploaded → processing → pending_review on success.
+     *
+     * @param documentId - Document ID
+     * @returns Structured OCR extraction result
+     */
+    async extract(documentId) {
+        const validated = this.validate(extractDocumentInputSchema, { documentId });
+        return await this.execute(() => this.trpc.documents.extract.mutate(validated));
+    }
+    // ─────────────────────────────────────────────────────────────────
     // List
     // ─────────────────────────────────────────────────────────────────
     /**
@@ -492,7 +619,7 @@ export class DocumentsResource extends BaseResource {
     // ─────────────────────────────────────────────────────────────────
     /**
      * Instantiates a Document model from raw data.
-     * Override in subclasses to return jurisdiction-specific models.
+     * Override in subclasses to return scope-specific models.
      */
     instantiate(data) {
         return new Document(data);

package/dist/resources/evidence.d.ts

@@ -0,0 +1,393 @@
+/**
+ * Evidence resource
+ *
+ * CRUD operations for compliance evidence records.
+ * Evidence can be created with a file upload, with data fields only, or both.
+ * File upload/download operations are handled separately from metadata operations.
+ * All file-backed evidence is created with pending_upload status.
+ */
+import type { AtomicBatchResult, ConfirmEvidenceUploadInput, CreateEvidenceInput, EvidenceFilter, EvidenceSort, ListOptions, OcrStructuredResult, PaginatedResponse, PartialBatchResult, PresignedEvidenceDownloadUrl, PresignedEvidenceUploadUrl, UpdateEvidenceInput, UpsertEvidenceInput, UpsertResult } from "@artu-ai/shared";
+import { Evidence, type EvidenceData } from "../models/Evidence";
+import { type ProgressCallback, type UploadableFile } from "../utils/upload";
+import { BaseResource } from "./base";
+/**
+ * Result of creating an evidence record.
+ *
+ * - With contentType: Returns evidence + presigned upload URL
+ * - Without contentType: Returns evidence only (no-file evidence)
+ */
+export interface CreateEvidenceResult {
+    /** The created evidence record */
+    evidence: Evidence;
+    /** Presigned URL for uploading the file (only when contentType is provided) */
+    upload?: PresignedEvidenceUploadUrl;
+}
+/**
+ * Input for uploading an evidence file.
+ * Combines evidence metadata with upload options.
+ */
+export type UploadEvidenceInput = Omit<CreateEvidenceInput, "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.evidence.upload(file, data, { signal: controller.signal });
+     * // Later: controller.abort();
+     */
+    signal?: AbortSignal;
+    /**
+     * Upload timeout in milliseconds.
+     * @default 300000 (5 minutes)
+     */
+    timeout?: number;
+}
+/**
+ * Evidence resource for managing compliance evidence records.
+ *
+ * @example
+ * ```typescript
+ * // Create an evidence record
+ * const { evidence, upload } = await sdk.evidence.create({
+ *   scope: "MX",
+ *   type: "contrato_compraventa",
+ *   contentType: "application/pdf",
+ *   transactionIds: ["txn_123"],
+ * });
+ *
+ * // Upload file directly via PUT
+ * await fetch(upload.url, {
+ *   method: "PUT",
+ *   body: file,
+ *   headers: { "Content-Type": file.type },
+ * });
+ *
+ * // Confirm upload
+ * await sdk.evidence.confirmUpload({
+ *   id: evidence.id,
+ *   filename: file.name,
+ *   contentType: file.type,
+ *   size: file.size,
+ * });
+ *
+ * // Or use the high-level upload helper
+ * const confirmed = await sdk.evidence.upload(file, {
+ *   scope: "MX",
+ *   type: "contrato_compraventa",
+ *   transactionIds: ["txn_123"],
+ * });
+ * ```
+ */
+export declare class EvidenceResource extends BaseResource<Evidence, CreateEvidenceInput, UpdateEvidenceInput, EvidenceFilter, EvidenceSort, CreateEvidenceResult> {
+    /**
+     * Creates a new evidence record.
+     *
+     * When contentType is provided, returns the record and a presigned upload URL.
+     * When contentType is omitted, creates a no-file (data-only) evidence record.
+     *
+     * After file upload, call `confirmUpload()` to transition status to "uploaded".
+     *
+     * @param data - Evidence creation data
+     * @returns The created evidence and optional presigned upload URL
+     */
+    create(data: CreateEvidenceInput): Promise<CreateEvidenceResult>;
+    /**
+     * 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 evidence status from "pending_upload" to "uploaded".
+     *
+     * @param data - Upload confirmation data including filename, contentType, and size
+     * @returns The updated evidence record
+     */
+    confirmUpload(data: ConfirmEvidenceUploadInput): Promise<Evidence>;
+    /**
+     * Uploads a file and creates an evidence record in one operation.
+     *
+     * Combines:
+     * 1. Creating an evidence record with presigned URL
+     * 2. Uploading the file directly to storage
+     * 3. Confirming the upload
+     *
+     * For more control over each step, use `create()`, manual upload, and
+     * `confirmUpload()` separately.
+     *
+     * @param file - The file to upload (File, Blob, or UploadableFile)
+     * @param data - Evidence metadata (scope, type, etc.)
+     * @param options - Upload options (progress callback, abort signal, timeout)
+     * @returns The created and confirmed evidence record
+     *
+     * @example
+     * ```typescript
+     * // Simple upload
+     * const evidence = await sdk.evidence.upload(file, {
+     *   scope: "MX",
+     *   type: "contrato_compraventa",
+     * });
+     *
+     * // With progress tracking
+     * const evidence = await sdk.evidence.upload(file, {
+     *   scope: "MX",
+     *   type: "contrato_compraventa",
+     * }, {
+     *   onProgress: (progress) => {
+     *     console.log(`Upload: ${Math.round(progress * 100)}%`);
+     *   },
+     * });
+     * ```
+     *
+     * @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
+     */
+    upload(file: File | Blob | UploadableFile, data: UploadEvidenceInput, options?: UploadOptions): Promise<Evidence>;
+    /**
+     * Regenerates a presigned upload URL for an evidence record that is
+     * stuck in `pending_upload` after a failed upload attempt.
+     *
+     * The record retains its original `storagePath` and `contentType`, so
+     * the new URL is signed against the same path with the same content-type
+     * restriction. After re-uploading, call `confirmUpload()` as usual.
+     *
+     * @param id - Evidence ID (must be in `pending_upload` status)
+     * @returns Fresh presigned upload URL with expiration
+     */
+    getUploadUrl(id: string): Promise<PresignedEvidenceUploadUrl>;
+    /**
+     * Retries a failed upload for an evidence record stuck in `pending_upload`.
+     *
+     * Combines:
+     * 1. Regenerating the presigned upload URL (`getUploadUrl`)
+     * 2. Uploading the file directly to storage
+     * 3. Confirming the upload
+     *
+     * Use this when the original `upload()` call failed at the storage PUT
+     * step (network error, S3 throttling, etc.) but the evidence record was
+     * created successfully.
+     *
+     * @param id - Evidence ID (must be in `pending_upload` status)
+     * @param file - The file to upload (must match the original contentType)
+     * @param options - Upload options (progress callback, abort signal, timeout)
+     * @returns The confirmed evidence record
+     *
+     * @throws {UploadError} If upload fails at any stage
+     * @throws {UploadAbortedError} If upload is cancelled via AbortSignal
+     * @throws {UploadTimeoutError} If upload times out
+     */
+    retryUpload(id: string, file: File | Blob | UploadableFile, options?: UploadOptions): Promise<Evidence>;
+    /**
+     * Gets a presigned URL for downloading/viewing an evidence file.
+     *
+     * @param id - Evidence ID
+     * @returns Presigned download URL with expiration
+     */
+    getDownloadUrl(id: string): Promise<PresignedEvidenceDownloadUrl>;
+    /**
+     * Retrieves an evidence record by ID
+     *
+     * @param id - Evidence ID
+     * @returns The evidence record
+     */
+    retrieve(id: string): Promise<Evidence>;
+    /**
+     * Retrieves an evidence record by metadata key/value.
+     *
+     * @param key - Metadata key to search
+     * @param value - Expected metadata value (string)
+     * @returns The first evidence record matching the key/value pair
+     */
+    retrieveByMetadata(key: string, value: string): Promise<Evidence>;
+    /**
+     * Updates an evidence record's metadata or fields.
+     *
+     * Note: Status cannot be updated directly — it is managed by the system.
+     *
+     * @param id - Evidence ID
+     * @param data - Fields to update
+     * @returns The updated evidence record
+     */
+    update(id: string, data: UpdateEvidenceInput): Promise<Evidence>;
+    /**
+     * Soft-deletes an evidence record
+     *
+     * @param id - Evidence ID
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Submit an uploaded evidence record for officer review.
+     * Transitions: uploaded → pending_review.
+     *
+     * @param id - Evidence ID
+     * @returns The updated evidence record
+     */
+    submit(id: string): Promise<Evidence>;
+    /**
+     * Verify a pending_review evidence record.
+     * Transitions: pending_review → verified.
+     *
+     * @param id - Evidence ID
+     * @returns The updated evidence record
+     */
+    verify(id: string): Promise<Evidence>;
+    /**
+     * Reject a pending_review evidence record with a reason.
+     * Transitions: pending_review → rejected.
+     *
+     * @param id - Evidence ID
+     * @param input - Rejection details
+     * @returns The updated evidence record
+     */
+    reject(id: string, input: {
+        reason: string;
+    }): Promise<Evidence>;
+    /**
+     * Extract structured fields from an evidence record via the OCR pipeline.
+     * Status transitions: uploaded → processing → pending_review on success.
+     *
+     * @param evidenceId - Evidence ID
+     * @returns Structured OCR extraction result
+     */
+    extract(evidenceId: string): Promise<OcrStructuredResult>;
+    /**
+     * Lists evidence records with optional filtering and pagination.
+     *
+     * @param options - List options with filter, cursor, and limit
+     * @returns Paginated list of evidence records
+     */
+    list(options?: ListOptions<EvidenceFilter, EvidenceSort>): Promise<PaginatedResponse<Evidence>>;
+    /**
+     * Counts evidence records matching the given filter.
+     *
+     * @param filter - Optional filter criteria
+     * @returns The count of matching evidence records
+     */
+    count(filter?: EvidenceFilter): Promise<number>;
+    /**
+     * Async iterator over evidence records with optional filtering.
+     *
+     * @param options - Filter and sort options
+     * @yields Evidence records one at a time
+     */
+    iterate(options?: ListOptions<EvidenceFilter, EvidenceSort>): AsyncGenerator<Evidence, void, unknown>;
+    /**
+     * Checks whether a transaction has at least one evidence of a given type.
+     *
+     * Useful for completeness checks — for example, "does this transaction have
+     * a verified CFDI?" Pass `status: "verified"` to restrict to verified evidence.
+     *
+     * @param transactionId - Transaction ID
+     * @param type - Evidence type string (e.g. "factura_cfdi_4_0")
+     * @returns `true` if at least one matching evidence record exists and is available
+     */
+    hasEvidenceType(transactionId: string, type: string): Promise<boolean>;
+    /**
+     * Links this evidence to a transaction.
+     *
+     * @param input - Evidence ID and transaction ID to link
+     */
+    linkTransaction(input: {
+        evidenceId: string;
+        transactionId: string;
+    }): Promise<void>;
+    /**
+     * Unlinks this evidence from a transaction.
+     *
+     * @param input - Evidence ID and transaction ID to unlink
+     */
+    unlinkTransaction(input: {
+        evidenceId: string;
+        transactionId: string;
+    }): Promise<void>;
+    /**
+     * Replaces all transaction links for this evidence with the given transaction IDs.
+     *
+     * @param input - Evidence ID and new list of transaction IDs
+     */
+    setTransactions(input: {
+        evidenceId: string;
+        transactionIds: string[];
+    }): Promise<void>;
+    /**
+     * Lists all transaction IDs linked to an evidence record.
+     *
+     * @param evidenceId - Evidence ID
+     * @returns Array of linked transaction UUIDs
+     */
+    listLinkedTransactions(evidenceId: string): Promise<string[]>;
+    /**
+     * Lists all evidence records linked to a transaction.
+     *
+     * @param transactionId - Transaction ID
+     * @returns Paginated list of evidence records for the transaction
+     */
+    listForTransaction(transactionId: string): Promise<PaginatedResponse<Evidence>>;
+    /**
+     * Creates multiple evidence records in a batch.
+     *
+     * @param items - Array of evidence creation data
+     * @param options - Batch options (atomic: true by default)
+     * @returns Atomic result with data array, or partial result with succeeded/failed
+     */
+    createMany(items: CreateEvidenceInput[], options?: {
+        atomic?: true;
+    }): Promise<AtomicBatchResult<Evidence>>;
+    createMany(items: CreateEvidenceInput[], options: {
+        atomic: false;
+    }): Promise<PartialBatchResult<Evidence>>;
+    /**
+     * Updates multiple evidence records 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
+     */
+    updateMany(updates: {
+        id: string;
+        data: UpdateEvidenceInput;
+    }[], options?: {
+        atomic?: true;
+    }): Promise<AtomicBatchResult<Evidence>>;
+    updateMany(updates: {
+        id: string;
+        data: UpdateEvidenceInput;
+    }[], options: {
+        atomic: false;
+    }): Promise<PartialBatchResult<Evidence>>;
+    /**
+     * Creates or updates an evidence record by externalId.
+     *
+     * @param data - Evidence upsert data (must include externalId)
+     * @returns The created or updated evidence record with action indicator
+     */
+    upsertByExternalId(data: UpsertEvidenceInput): Promise<UpsertResult<Evidence>>;
+    /**
+     * Creates or updates multiple evidence records by externalId in a single request.
+     *
+     * @param items - Array of evidence upsert data (each must include externalId)
+     * @param options - Batch options (atomic: true by default)
+     * @returns Atomic or partial batch result
+     */
+    upsertManyByExternalId(items: UpsertEvidenceInput[], options?: {
+        atomic?: true;
+    }): Promise<AtomicBatchResult<UpsertResult<Evidence>>>;
+    upsertManyByExternalId(items: UpsertEvidenceInput[], options: {
+        atomic: false;
+    }): Promise<PartialBatchResult<UpsertResult<Evidence>>>;
+    /**
+     * Instantiates an Evidence model from raw data.
+     * Override in subclasses to return scope-specific models.
+     */
+    protected instantiate(data: EvidenceData): Evidence;
+}