@artu-ai/compliance-sdk 0.13.4 → 0.17.0

package/dist/resources/evidence.js

@@ -0,0 +1,603 @@
+/**
+ * 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 { confirmEvidenceUploadInputSchema, createEvidenceInputSchema, extractEvidenceInputSchema, updateEvidenceInputSchema, upsertEvidenceInputSchema, } from "@artu-ai/shared";
+import { z } from "zod";
+import { UploadError } from "../errors/upload";
+import { Evidence } from "../models/Evidence";
+import { normalizeFile, uploadToStorage, validateFileSize, } from "../utils/upload";
+import { BaseResource } from "./base";
+// ─────────────────────────────────────────────────────────────────
+// Resource
+// ─────────────────────────────────────────────────────────────────
+/**
+ * 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 class EvidenceResource extends BaseResource {
+    // ─────────────────────────────────────────────────────────────────
+    // Create
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * 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
+     */
+    async create(data) {
+        const validated = this.validate(createEvidenceInputSchema, data);
+        const response = await this.execute(() => this.trpc.evidence.create.mutate(validated));
+        return {
+            evidence: this.instantiate(response.evidence),
+            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 evidence status from "pending_upload" to "uploaded".
+     *
+     * @param data - Upload confirmation data including filename, contentType, and size
+     * @returns The updated evidence record
+     */
+    async confirmUpload(data) {
+        const validated = this.validate(confirmEvidenceUploadInputSchema, data);
+        const response = await this.execute(() => this.trpc.evidence.confirmUpload.mutate(validated));
+        return this.instantiate(response);
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Upload (High-Level Helper)
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * 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
+     */
+    async upload(file, data, options = {}) {
+        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 for evidence
+        const allowedTypes = [
+            "image/jpeg",
+            "image/png",
+            "image/webp",
+            "application/pdf",
+            "application/xml",
+            "text/xml",
+        ];
+        if (!allowedTypes.includes(contentType)) {
+            throw new UploadError(`Invalid file type: ${contentType}. Allowed types: ${allowedTypes.join(", ")}`, "request");
+        }
+        // Step 1: Create evidence record and get presigned URL
+        const createInput = {
+            ...data,
+            contentType: contentType,
+        };
+        const { evidence, 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 storage. If this fails, attach the evidence
+        // 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: evidence.id,
+                });
+            }
+            throw new UploadError(err instanceof Error ? err.message : "Failed to upload file to storage", "upload", { cause: err, resourceId: evidence.id });
+        }
+        // Step 3: Confirm upload. Same wrapping — confirm-upload failures
+        // also leave the record in pending_upload (or worse, in a half-confirmed
+        // state) and the caller benefits from knowing the id.
+        try {
+            return await this.confirmUpload({
+                id: evidence.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: evidence.id });
+        }
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Retry (failed upload)
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * 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
+     */
+    async getUploadUrl(id) {
+        return this.execute(() => this.trpc.evidence.getUploadUrl.mutate({ id }));
+    }
+    /**
+     * 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
+     */
+    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");
+        }
+        // Get a fresh presigned URL against the existing storagePath + contentType.
+        const upload = await this.getUploadUrl(id);
+        // PUT the file to storage. contentType comes from the existing record
+        // (server-signed), so the client doesn't have to re-supply it.
+        await uploadToStorage(normalizedFile, upload, {
+            onProgress,
+            signal,
+            timeout,
+        });
+        // Confirm-upload requires the contentType — reuse the file's type, which
+        // must match what the record was created with (the storage PUT would have
+        // rejected anything else).
+        return this.confirmUpload({
+            id,
+            filename: normalizedFile.name,
+            contentType: normalizedFile.type,
+            size: normalizedFile.size,
+        });
+    }
+    /**
+     * Gets a presigned URL for downloading/viewing an evidence file.
+     *
+     * @param id - Evidence ID
+     * @returns Presigned download URL with expiration
+     */
+    async getDownloadUrl(id) {
+        const response = await this.execute(() => this.trpc.evidence.getDownloadUrl.query({ id }));
+        return response;
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Retrieve
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Retrieves an evidence record by ID
+     *
+     * @param id - Evidence ID
+     * @returns The evidence record
+     */
+    async retrieve(id) {
+        const response = await this.execute(() => this.trpc.evidence.retrieve.query({ id }));
+        return this.instantiate(response);
+    }
+    /**
+     * 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
+     */
+    async retrieveByMetadata(key, value) {
+        const response = await this.execute(() => this.trpc.evidence.retrieveByMetadata.query({ key, value }));
+        return this.instantiate(response);
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Update
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * 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
+     */
+    async update(id, data) {
+        const validated = this.validate(updateEvidenceInputSchema, data);
+        const response = await this.execute(() => this.trpc.evidence.update.mutate({
+            id,
+            data: validated,
+        }));
+        return this.instantiate(response);
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Delete
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Soft-deletes an evidence record
+     *
+     * @param id - Evidence ID
+     */
+    async delete(id) {
+        await this.execute(() => this.trpc.evidence.delete.mutate({ id }));
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Review Actions
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Submit an uploaded evidence record for officer review.
+     * Transitions: uploaded → pending_review.
+     *
+     * @param id - Evidence ID
+     * @returns The updated evidence record
+     */
+    async submit(id) {
+        const response = await this.execute(() => this.trpc.evidence.submit.mutate({ id }));
+        return this.instantiate(response);
+    }
+    /**
+     * Verify a pending_review evidence record.
+     * Transitions: pending_review → verified.
+     *
+     * @param id - Evidence ID
+     * @returns The updated evidence record
+     */
+    async verify(id) {
+        const response = await this.execute(() => this.trpc.evidence.verify.mutate({ id }));
+        return this.instantiate(response);
+    }
+    /**
+     * 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
+     */
+    async reject(id, input) {
+        const response = await this.execute(() => this.trpc.evidence.reject.mutate({ id, reason: input.reason }));
+        return this.instantiate(response);
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // OCR Extraction
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * 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
+     */
+    async extract(evidenceId) {
+        const validated = this.validate(extractEvidenceInputSchema, { evidenceId });
+        return await this.execute(() => this.trpc.evidence.extract.mutate(validated));
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // List
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Lists evidence records with optional filtering and pagination.
+     *
+     * @param options - List options with filter, cursor, and limit
+     * @returns Paginated list of evidence records
+     */
+    async list(options) {
+        const response = await this.execute(() => this.trpc.evidence.list.query(options));
+        const typedResponse = response;
+        return {
+            data: typedResponse.data.map((d) => this.instantiate(d)),
+            pagination: typedResponse.pagination,
+        };
+    }
+    /**
+     * Counts evidence records matching the given filter.
+     *
+     * @param filter - Optional filter criteria
+     * @returns The count of matching evidence records
+     */
+    async count(filter) {
+        const response = await this.execute(() => this.trpc.evidence.count.query({ filter }));
+        return response.count;
+    }
+    /**
+     * Async iterator over evidence records with optional filtering.
+     *
+     * @param options - Filter and sort options
+     * @yields Evidence records one at a time
+     */
+    async *iterate(options) {
+        let cursor;
+        let hasMore = true;
+        while (hasMore) {
+            const response = await this.list({
+                ...options,
+                cursor,
+                limit: options?.limit ?? 100,
+            });
+            for (const ev of response.data) {
+                yield ev;
+            }
+            cursor = response.pagination.nextCursor;
+            hasMore = response.pagination.hasMore;
+        }
+    }
+    /**
+     * 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
+     */
+    async hasEvidenceType(transactionId, type) {
+        const response = await this.listForTransaction(transactionId);
+        return response.data.some((e) => e.type === type && e.isAvailable);
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Transaction Link Operations
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Links this evidence to a transaction.
+     *
+     * @param input - Evidence ID and transaction ID to link
+     */
+    async linkTransaction(input) {
+        await this.execute(() => this.trpc.evidence.linkTransaction.mutate(input));
+    }
+    /**
+     * Unlinks this evidence from a transaction.
+     *
+     * @param input - Evidence ID and transaction ID to unlink
+     */
+    async unlinkTransaction(input) {
+        await this.execute(() => this.trpc.evidence.unlinkTransaction.mutate(input));
+    }
+    /**
+     * Replaces all transaction links for this evidence with the given transaction IDs.
+     *
+     * @param input - Evidence ID and new list of transaction IDs
+     */
+    async setTransactions(input) {
+        await this.execute(() => this.trpc.evidence.setTransactions.mutate(input));
+    }
+    /**
+     * Lists all transaction IDs linked to an evidence record.
+     *
+     * @param evidenceId - Evidence ID
+     * @returns Array of linked transaction UUIDs
+     */
+    async listLinkedTransactions(evidenceId) {
+        const response = await this.execute(() => this.trpc.evidence.listLinkedTransactions.query({ evidenceId }));
+        return response;
+    }
+    /**
+     * Lists all evidence records linked to a transaction.
+     *
+     * @param transactionId - Transaction ID
+     * @returns Paginated list of evidence records for the transaction
+     */
+    async listForTransaction(transactionId) {
+        const response = await this.execute(() => this.trpc.evidence.listForTransaction.query({ transactionId }));
+        const typedResponse = response;
+        return {
+            data: typedResponse.data.map((d) => this.instantiate(d)),
+            pagination: typedResponse.pagination,
+        };
+    }
+    async createMany(items, options = {}) {
+        const atomic = options.atomic ?? true;
+        const validated = this.validate(z.array(createEvidenceInputSchema), items);
+        const response = await this.execute(() => this.trpc.evidence.createMany.mutate({ items: validated, atomic }));
+        if (response.atomic) {
+            return {
+                atomic: true,
+                data: response.data.map((d) => this.instantiate(d)),
+            };
+        }
+        else {
+            return {
+                atomic: false,
+                succeeded: response.succeeded.map((item) => ({
+                    index: item.index,
+                    data: this.instantiate(item.data),
+                })),
+                failed: response.failed,
+            };
+        }
+    }
+    async updateMany(updates, options = {}) {
+        const atomic = options.atomic ?? true;
+        const validated = updates.map((u) => ({
+            id: u.id,
+            data: this.validate(updateEvidenceInputSchema, u.data),
+        }));
+        const response = await this.execute(() => this.trpc.evidence.updateMany.mutate({ items: validated, atomic }));
+        if (response.atomic) {
+            return {
+                atomic: true,
+                data: response.data.map((d) => this.instantiate(d)),
+            };
+        }
+        else {
+            return {
+                atomic: false,
+                succeeded: response.succeeded.map((item) => ({
+                    index: item.index,
+                    data: this.instantiate(item.data),
+                })),
+                failed: response.failed,
+            };
+        }
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Upsert Operations
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * 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
+     */
+    async upsertByExternalId(data) {
+        const validated = this.validate(upsertEvidenceInputSchema, data);
+        const response = await this.execute(() => this.trpc.evidence.upsertByExternalId.mutate(validated));
+        return {
+            data: this.instantiate(response.data),
+            action: response.action,
+        };
+    }
+    async upsertManyByExternalId(items, options = {}) {
+        const atomic = options.atomic ?? true;
+        const validated = this.validate(z.array(upsertEvidenceInputSchema), items);
+        const response = await this.execute(() => this.trpc.evidence.upsertManyByExternalId.mutate({
+            items: validated,
+            atomic,
+        }));
+        if (response.atomic) {
+            return {
+                atomic: true,
+                data: response.data.map((item) => ({
+                    data: this.instantiate(item.data),
+                    action: item.action,
+                })),
+            };
+        }
+        else {
+            return {
+                atomic: false,
+                succeeded: response.succeeded.map((item) => ({
+                    index: item.index,
+                    data: {
+                        data: this.instantiate(item.data.data),
+                        action: item.data.action,
+                    },
+                })),
+                failed: response.failed,
+            };
+        }
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Protected Methods
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Instantiates an Evidence model from raw data.
+     * Override in subclasses to return scope-specific models.
+     */
+    instantiate(data) {
+        return new Evidence(data);
+    }
+}

package/dist/resources/exchange-rates.d.ts

@@ -5,10 +5,7 @@
  * This is a lightweight resource (not CRUD-based).
  */
 import type { ExchangeRateResponse, GetExchangeRateInput } from "@artu-ai/shared";
-import type { TRPCClient } from "../utils/trpc-client";
 export declare class ExchangeRatesResource {
     private readonly trpc;
-    constructor(trpc: TRPCClient);
     getRate(input: GetExchangeRateInput): Promise<ExchangeRateResponse>;
 }
-//# sourceMappingURL=exchange-rates.d.ts.map

package/dist/resources/exchange-rates.js

@@ -9,6 +9,7 @@ import { TRPCClientError } from "@trpc/client";
 import { mapTRPCError, ValidationError } from "../errors";
 export class ExchangeRatesResource {
     trpc;
+    /** @internal */
     constructor(trpc) {
         this.trpc = trpc;
     }

package/dist/resources/identity/identity.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Identity Resource
+ *
+ * Raw passthrough to the `identity` procedures: each method forwards its
+ * argument verbatim to tRPC and returns the response verbatim. No SDK-side
+ * validation, no error mapping, no model wrapping.
+ * The server re-runs the same Zod schemas from `@artu-ai/shared`.
+ */
+import type { GetIdentityRunDetailInput, IdentityListSummaryInput, ListIdentityInput, RunIdentityInput } from "@artu-ai/shared/schemas/identity";
+import type { TRPCClient } from "../../utils/trpc-client";
+export declare class IdentityResource {
+    private readonly trpc;
+    constructor(trpc: TRPCClient);
+    run(input: RunIdentityInput): Promise<{
+        id: string;
+        clientId: string;
+        checkedBy: string;
+        results: Record<string, "pass" | "flag" | "inconclusive">;
+        createdAt: string;
+    }>;
+    listByClient(input: ListIdentityInput): Promise<{
+        id: string;
+        clientId: string;
+        checkedBy: string;
+        results: Record<string, "pass" | "flag" | "inconclusive">;
+        createdAt: string;
+    }[]>;
+    getRunDetail(input: GetIdentityRunDetailInput): Promise<{
+        id: string;
+        clientId: string;
+        createdAt: string;
+        checkedBy: string;
+        results: Record<string, "pass" | "flag" | "inconclusive">;
+        checkResults: {
+            reason: {
+                code: "timeout" | "unknown" | "parse" | "http" | "provider-semantic";
+                message?: string | undefined;
+            } | null;
+            createdAt: string;
+            outcome: "pass" | "flag" | "inconclusive";
+            checkId: string;
+            providerId: string;
+            data?: unknown;
+        }[];
+    }>;
+    listSummary(input: IdentityListSummaryInput): Promise<{
+        name: string;
+        providerId: string;
+        checkId: string;
+        status: "failed" | "hit" | "cleared";
+        checkedAt: string;
+    }[]>;
+    getEligibleChecks(input: {
+        clientId: string;
+    }): Promise<readonly {
+        check: string;
+        displayName: string;
+        eligible: boolean;
+        missingFields: string[];
+    }[]>;
+}