@artu-ai/compliance-sdk 0.0.6 → 0.2.0

package/dist/resources/contact-methods.js

@@ -0,0 +1,215 @@
+/**
+ * Contact Methods Resource
+ *
+ * Manages communication channels (email, phone, etc.) for clients.
+ */
+import { z } from "zod";
+import { createContactMethodInputSchema, updateContactMethodInputSchema, replaceSyncItemSchema, } from "@artu-ai/shared";
+import { BaseResource } from "./base";
+import { ContactMethod } from "../models/ContactMethod";
+// ===========================
+// ContactMethodsResource
+// ===========================
+/**
+ * Resource for managing client contact methods.
+ *
+ * @example
+ * ```typescript
+ * // Create an email contact for a client
+ * const email = await sdk.contactMethods.create({
+ *   clientId: "client_123",
+ *   type: "email",
+ *   value: "juan@example.com",
+ *   label: "Personal",
+ *   isPrimary: true,
+ * });
+ *
+ * // Get the primary email for a client
+ * const primary = await sdk.contactMethods.getPrimary("client_123", "email");
+ * ```
+ */
+export class ContactMethodsResource extends BaseResource {
+    // ─────────────────────────────────────────────────────────────────
+    // CRUD Operations
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Creates a contact method for a client
+     *
+     * @param data - Contact method data including clientId
+     * @returns The created ContactMethod
+     */
+    async create(data) {
+        const validated = this.validate(createContactMethodInputSchema, data);
+        const response = await this.execute(() => this.trpc.contactMethods.create.mutate(validated));
+        return this.instantiate(response);
+    }
+    /**
+     * Retrieves a contact method by ID
+     *
+     * @param id - The contact method ID
+     * @returns The ContactMethod
+     */
+    async retrieve(id) {
+        const response = await this.execute(() => this.trpc.contactMethods.retrieve.query({ id }));
+        return this.instantiate(response);
+    }
+    /**
+     * Retrieves a contact method by metadata key/value.
+     */
+    async retrieveByMetadata(key, value) {
+        const response = await this.execute(() => this.trpc.contactMethods.retrieveByMetadata.query({ key, value }));
+        return this.instantiate(response);
+    }
+    /**
+     * Retrieves a contact method by externalId.
+     */
+    async retrieveByExternalId(externalId) {
+        const response = await this.execute(() => this.trpc.contactMethods.retrieveByExternalId.query({ externalId }));
+        return this.instantiate(response);
+    }
+    /**
+     * Updates a contact method
+     *
+     * @param id - The contact method ID
+     * @param data - Fields to update
+     * @returns The updated ContactMethod
+     */
+    async update(id, data) {
+        const validated = this.validate(updateContactMethodInputSchema, data);
+        const response = await this.execute(() => this.trpc.contactMethods.update.mutate({ id, data: validated }));
+        return this.instantiate(response);
+    }
+    /**
+     * Deletes a contact method
+     *
+     * @param id - The contact method ID
+     */
+    async delete(id) {
+        await this.execute(() => this.trpc.contactMethods.delete.mutate({ id }));
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // List Operations
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Lists contact methods with optional filtering
+     *
+     * @param options - Filtering and pagination options
+     * @returns Paginated list of ContactMethods
+     */
+    async list(options) {
+        const response = await this.execute(() => this.trpc.contactMethods.list.query(options));
+        return {
+            data: response.data.map((c) => this.instantiate(c)),
+            pagination: response.pagination,
+        };
+    }
+    /**
+     * Lists all contact methods for a specific client
+     *
+     * @param clientId - The client ID
+     * @param options - Optional pagination options
+     * @returns Paginated list of ContactMethods
+     */
+    async listByClient(clientId, options) {
+        const response = await this.execute(() => this.trpc.contactMethods.listByClient.query({ clientId, ...options }));
+        return {
+            data: response.data.map((c) => this.instantiate(c)),
+            pagination: response.pagination,
+        };
+    }
+    /**
+     * Returns an async iterator over all contact methods matching the filter.
+     */
+    iterate(filter) {
+        return this.createIterator({ filter });
+    }
+    async createMany(contacts, options = {}) {
+        const atomic = options.atomic ?? true;
+        const validated = this.validate(z.array(createContactMethodInputSchema), contacts);
+        const response = await this.execute(() => this.trpc.contactMethods.createMany.mutate({ items: validated, atomic }));
+        if (response.atomic) {
+            return {
+                atomic: true,
+                data: response.data.map((c) => this.instantiate(c)),
+            };
+        }
+        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 updateItemSchema = z.object({
+            id: z.uuid(),
+            data: updateContactMethodInputSchema,
+        });
+        const validated = this.validate(z.array(updateItemSchema), updates);
+        const response = await this.execute(() => this.trpc.contactMethods.updateMany.mutate({ items: validated, atomic }));
+        if (response.atomic) {
+            return {
+                atomic: true,
+                data: response.data.map((c) => this.instantiate(c)),
+            };
+        }
+        else {
+            return {
+                atomic: false,
+                succeeded: response.succeeded.map((item) => ({
+                    index: item.index,
+                    data: this.instantiate(item.data),
+                })),
+                failed: response.failed,
+            };
+        }
+    }
+    async sync(clientId, items, options) {
+        const validated = this.validate(z.array(replaceSyncItemSchema(createContactMethodInputSchema, updateContactMethodInputSchema)), items);
+        const response = await this.execute(() => this.trpc.contactMethods.sync.mutate({
+            clientId,
+            items: validated,
+            replaceMode: options?.replaceMode,
+        }));
+        return {
+            created: response.created.map((c) => this.instantiate(c)),
+            updated: response.updated.map((c) => this.instantiate(c)),
+            deleted: response.deleted,
+        };
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Specialized Methods
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Gets the primary contact method of a specific type for a client
+     *
+     * @param clientId - The client ID
+     * @param type - The contact method type
+     * @returns The primary ContactMethod or null
+     */
+    async getPrimary(clientId, type) {
+        const response = await this.execute(() => this.trpc.contactMethods.getPrimary.query({ clientId, type }));
+        return response ? this.instantiate(response) : null;
+    }
+    /**
+     * Marks a contact method as verified
+     *
+     * @param id - The contact method ID
+     * @returns The updated ContactMethod
+     */
+    async markVerified(id) {
+        const response = await this.execute(() => this.trpc.contactMethods.markVerified.mutate({ id }));
+        return this.instantiate(response);
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Instantiation
+    // ─────────────────────────────────────────────────────────────────
+    instantiate(data) {
+        return new ContactMethod(data);
+    }
+}

package/dist/resources/documents.d.ts

@@ -0,0 +1,253 @@
+/**
+ * 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 { Document, type DocumentData } from "../models/Document";
+import { BaseResource } from "./base";
+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;
+}
+/**
+ * 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 declare class DocumentsResource extends BaseResource<Document, CreateDocumentInput, UpdateDocumentInput, DocumentFilter, CreateDocumentResult> {
+    /**
+     * 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,
+     * });
+     * ```
+     */
+    create(data: CreateDocumentInput): Promise<CreateDocumentResult>;
+    /**
+     * 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
+     */
+    confirmUpload(data: ConfirmUploadInput): Promise<Document>;
+    /**
+     * 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" />
+     * ```
+     */
+    getDownloadUrl(id: string): Promise<PresignedDownloadUrl>;
+    /**
+     * Retrieves a document by ID
+     *
+     * @param id - Document ID
+     * @returns The document
+     */
+    retrieve(id: string): Promise<Document>;
+    /**
+     * Retrieves a document by metadata key/value.
+     */
+    retrieveByMetadata(key: string, value: string): Promise<Document>;
+    /**
+     * Retrieves a document by externalId
+     */
+    retrieveByExternalId(externalId: string): Promise<Document>;
+    /**
+     * 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
+     */
+    update(id: string, data: UpdateDocumentInput): Promise<Document>;
+    /**
+     * Soft-deletes a document
+     *
+     * @param id - Document ID
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Lists documents with optional filtering and pagination.
+     *
+     * @param options - List options with filter, cursor, and limit
+     * @returns Paginated list of documents
+     */
+    list(options?: ListOptions<DocumentFilter>): Promise<PaginatedResponse<Document>>;
+    /**
+     * Lists all documents for a specific client with pagination.
+     *
+     * @param clientId - Client ID
+     * @param options - Pagination options
+     * @returns Paginated list of documents
+     */
+    listByClient(clientId: string, options?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<PaginatedResponse<Document>>;
+    /**
+     * Async iterator for documents with optional filtering.
+     *
+     * @param options - Filter options
+     * @yields Documents one at a time
+     */
+    iterate(options?: ListOptions<DocumentFilter>): AsyncGenerator<Document, void, unknown>;
+    /**
+     * 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
+     */
+    createMany(documents: CreateDocumentInput[], options?: {
+        atomic?: true;
+    }): Promise<AtomicBatchResult<Document>>;
+    createMany(documents: CreateDocumentInput[], options: {
+        atomic: false;
+    }): Promise<PartialBatchResult<Document>>;
+    /**
+     * 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
+     */
+    updateMany(updates: {
+        id: string;
+        data: UpdateDocumentInput;
+    }[], options?: {
+        atomic?: true;
+    }): Promise<AtomicBatchResult<Document>>;
+    updateMany(updates: {
+        id: string;
+        data: UpdateDocumentInput;
+    }[], options: {
+        atomic: false;
+    }): Promise<PartialBatchResult<Document>>;
+    /**
+     * Gets document count for a client
+     *
+     * @param clientId - Client ID
+     * @returns Count of documents
+     */
+    countByClient(clientId: string): Promise<number>;
+    /**
+     * 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
+     */
+    hasDocumentType(clientId: string, type: string): Promise<boolean>;
+    /**
+     * Instantiates a Document model from raw data.
+     * Override in subclasses to return jurisdiction-specific models.
+     */
+    protected instantiate(data: DocumentData): Document;
+}
+//# sourceMappingURL=documents.d.ts.map

package/dist/resources/documents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"documents.d.ts","sourceRoot":"","sources":["../../src/resources/documents.ts"],"names":[],"mappings":"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"}