@arke-institute/sdk 0.1.0 → 0.1.1

package/dist/errors-BrNZWPE7.d.cts

@@ -0,0 +1,477 @@
+import { f as CreateCollectionPayload, b as Collection, o as PiPermissions, C as CollectionsClient } from './client-dAk3E64p.cjs';
+
+/**
+ * Processing configuration types for per-directory control
+ */
+/**
+ * Configuration for processing stages applied to files
+ */
+interface ProcessingConfig {
+    /** Enable OCR on eligible files */
+    ocr: boolean;
+    /** Enable description/summary generation */
+    describe: boolean;
+    /** Enable pinax metadata generation */
+    pinax: boolean;
+}
+
+/**
+ * SDK Configuration Types
+ */
+
+/**
+ * Custom prompts for AI services in the ingest pipeline
+ * All fields are optional. Prompts are appended to base system prompts.
+ */
+interface CustomPrompts {
+    /**
+     * Applied to all AI service calls across all phases
+     * @example "All content is from 18th century manuscripts. Use period-appropriate terminology."
+     */
+    general?: string;
+    /**
+     * Phase-specific: file reorganization
+     * @example "Group documents by subject matter (astronomy, biology, chemistry, physics)."
+     */
+    reorganization?: string;
+    /**
+     * Phase-specific: PINAX metadata extraction
+     * @example "Focus on extracting dates, locations, and institutional affiliations. Use Library of Congress Subject Headings."
+     */
+    pinax?: string;
+    /**
+     * Phase-specific: description generation
+     * @example "Write descriptions in scholarly, academic tone with focus on historical context."
+     */
+    description?: string;
+    /**
+     * Phase-specific: knowledge graph extraction
+     * @example "Focus on extracting people, institutions, and their relationships."
+     */
+    cheimarros?: string;
+}
+/**
+ * Configuration for the ArkeUploader SDK
+ */
+interface UploaderConfig {
+    /**
+     * Gateway base URL (e.g., https://api.arke.institute)
+     * All requests route through /ingest/* endpoints
+     * @example 'https://api.arke.institute'
+     */
+    gatewayUrl: string;
+    /**
+     * Bearer token for authentication (required for all upload operations)
+     */
+    authToken: string;
+    /**
+     * Name of person/service uploading files
+     */
+    uploader: string;
+    /**
+     * Root path in the archive hierarchy
+     * @default '/'
+     */
+    rootPath?: string;
+    /**
+     * Parent persistent identifier (for hierarchical archives)
+     */
+    parentPi?: string;
+    /**
+     * Custom metadata to attach to batch
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * Custom prompts for AI services in the ingest pipeline
+     */
+    customPrompts?: CustomPrompts;
+    /**
+     * Processing options (OCR, IIIF, etc.)
+     */
+    processing?: ProcessingConfig;
+    /**
+     * Number of files to upload in parallel
+     * @default 5
+     */
+    parallelUploads?: number;
+    /**
+     * Number of parts to upload in parallel for multipart uploads
+     * @default 3
+     */
+    parallelParts?: number;
+    /**
+     * Maximum number of retry attempts for failed requests
+     * @default 3
+     */
+    maxRetries?: number;
+    /**
+     * Initial delay between retries in milliseconds
+     * @default 1000
+     */
+    retryInitialDelay?: number;
+    /**
+     * Maximum delay between retries in milliseconds
+     * @default 30000
+     */
+    retryMaxDelay?: number;
+    /**
+     * Add random jitter to retry delays to prevent thundering herd
+     * @default true
+     */
+    retryJitter?: boolean;
+    /**
+     * Timeout for API requests in milliseconds
+     * @default 30000
+     */
+    timeout?: number;
+}
+/**
+ * Options for batch upload operation
+ */
+interface UploadOptions {
+    /**
+     * Progress callback for upload tracking
+     */
+    onProgress?: (progress: UploadProgress) => void;
+    /**
+     * Dry run mode - validate without uploading
+     * @default false
+     */
+    dryRun?: boolean;
+}
+/**
+ * Progress information during upload
+ */
+interface UploadProgress {
+    /**
+     * Current phase of upload
+     */
+    phase: 'scanning' | 'uploading' | 'finalizing' | 'discovery' | 'complete';
+    /**
+     * Total number of files to upload
+     */
+    filesTotal: number;
+    /**
+     * Number of files uploaded so far
+     */
+    filesUploaded: number;
+    /**
+     * Total bytes to upload
+     */
+    bytesTotal: number;
+    /**
+     * Bytes uploaded so far
+     */
+    bytesUploaded: number;
+    /**
+     * Current file being processed
+     */
+    currentFile?: string;
+    /**
+     * Percentage complete (0-100)
+     */
+    percentComplete: number;
+}
+/**
+ * Result of batch upload
+ */
+interface BatchResult {
+    /**
+     * Batch ID assigned by worker
+     */
+    batchId: string;
+    /**
+     * Root PI of the uploaded content (entity identifier)
+     * This is the canonical identifier for the uploaded collection.
+     */
+    rootPi: string;
+    /**
+     * Number of files uploaded
+     */
+    filesUploaded: number;
+    /**
+     * Total bytes uploaded
+     */
+    bytesUploaded: number;
+    /**
+     * Upload duration in milliseconds
+     */
+    durationMs: number;
+}
+
+/**
+ * Upload Client with Collections Integration
+ * Provides high-level upload operations with permission checks
+ */
+
+interface UploadClientConfig {
+    /**
+     * Gateway base URL (e.g., https://api.arke.institute)
+     */
+    gatewayUrl: string;
+    /**
+     * Bearer token for authentication
+     */
+    authToken: string;
+    /**
+     * Name of person/service uploading files (defaults to user ID from JWT)
+     */
+    uploader?: string;
+    /**
+     * Custom fetch implementation (optional, for testing)
+     */
+    fetchImpl?: typeof fetch;
+}
+interface CreateCollectionUploadOptions {
+    /**
+     * Files to upload - directory path (Node.js) or File[]/FileList (browser)
+     */
+    files: string | File[] | FileList;
+    /**
+     * Collection metadata
+     */
+    collectionMetadata: CreateCollectionPayload;
+    /**
+     * Custom prompts for AI processing
+     */
+    customPrompts?: CustomPrompts;
+    /**
+     * Processing options (OCR, IIIF, etc.)
+     */
+    processing?: ProcessingConfig;
+    /**
+     * Progress callback
+     */
+    onProgress?: (progress: UploadProgress) => void;
+    /**
+     * Dry run mode
+     */
+    dryRun?: boolean;
+}
+interface AddToCollectionOptions {
+    /**
+     * Files to upload - directory path (Node.js) or File[]/FileList (browser)
+     */
+    files: string | File[] | FileList;
+    /**
+     * Parent PI to add files under (must be within a collection you can edit)
+     */
+    parentPi: string;
+    /**
+     * Custom prompts for AI processing
+     */
+    customPrompts?: CustomPrompts;
+    /**
+     * Processing options (OCR, IIIF, etc.)
+     */
+    processing?: ProcessingConfig;
+    /**
+     * Progress callback
+     */
+    onProgress?: (progress: UploadProgress) => void;
+    /**
+     * Dry run mode
+     */
+    dryRun?: boolean;
+}
+interface CreateCollectionUploadResult extends BatchResult {
+    /**
+     * The created collection
+     */
+    collection: Collection & {
+        rootPi: string;
+    };
+}
+/**
+ * High-level upload client with collections integration
+ *
+ * @example
+ * ```typescript
+ * import { UploadClient } from '@arke-institute/sdk';
+ *
+ * const client = new UploadClient({
+ *   gatewayUrl: 'https://api.arke.institute',
+ *   authToken: 'your-jwt-token',
+ *   uploader: 'my-app',
+ * });
+ *
+ * // Create a new collection from files
+ * const result = await client.createCollection({
+ *   files: './photos',
+ *   collectionMetadata: { title: 'My Archive', slug: 'my-archive' },
+ * });
+ *
+ * // Add files to an existing collection
+ * await client.addToCollection({
+ *   files: './more-photos',
+ *   parentPi: result.collection.rootPi,
+ * });
+ * ```
+ */
+declare class UploadClient {
+    private config;
+    private collectionsClient;
+    constructor(config: UploadClientConfig);
+    /**
+     * Update the auth token (e.g., after token refresh)
+     */
+    setAuthToken(token: string): void;
+    /**
+     * Create a new collection and upload files to it
+     *
+     * Anyone authenticated can create a new collection.
+     * The root PI of the uploaded files becomes the collection's root.
+     */
+    createCollection(options: CreateCollectionUploadOptions): Promise<CreateCollectionUploadResult>;
+    /**
+     * Add files to an existing collection
+     *
+     * Requires owner or editor role on the collection containing the parent PI.
+     * Use this to add a folder or files to an existing collection hierarchy.
+     */
+    addToCollection(options: AddToCollectionOptions): Promise<BatchResult>;
+    /**
+     * Check if you can edit a specific PI (i.e., add files to its collection)
+     */
+    canEdit(pi: string): Promise<PiPermissions>;
+    /**
+     * Get access to the underlying collections client for other operations
+     */
+    get collections(): CollectionsClient;
+}
+
+/**
+ * File metadata and upload tracking types
+ */
+
+interface FileInfo {
+    /** Absolute path on local filesystem */
+    localPath: string;
+    /** Logical path within the batch (e.g., /series_1/box_7/page_001.tiff) */
+    logicalPath: string;
+    /** File name only */
+    fileName: string;
+    /** File size in bytes */
+    size: number;
+    /** MIME type */
+    contentType: string;
+    /** IPFS CID v1 (base32) - optional, may be undefined if computation failed */
+    cid?: string;
+    /** Processing configuration for this file */
+    processingConfig: ProcessingConfig;
+}
+interface UploadTask extends FileInfo {
+    /** Current status of the upload */
+    status: 'pending' | 'uploading' | 'completed' | 'failed';
+    /** R2 key assigned by worker */
+    r2Key?: string;
+    /** Upload type determined by worker */
+    uploadType?: 'simple' | 'multipart';
+    /** Multipart upload ID (if applicable) */
+    uploadId?: string;
+    /** Completed parts for multipart uploads */
+    completedParts?: Array<{
+        part_number: number;
+        etag: string;
+    }>;
+    /** Error message if failed */
+    error?: string;
+    /** Bytes uploaded so far */
+    bytesUploaded?: number;
+    /** Timestamp when upload started */
+    startedAt?: Date;
+    /** Timestamp when upload completed */
+    completedAt?: Date;
+}
+interface ScanResult {
+    files: FileInfo[];
+    totalSize: number;
+    totalFiles: number;
+    largestFile: number;
+    smallestFile: number;
+}
+
+/**
+ * Common platform types and utilities
+ */
+
+/**
+ * Platform-specific file source
+ * Can be a path string (Node.js) or File object (Browser)
+ */
+type FileSource = string | File;
+
+/**
+ * Main ArkeUploader SDK class
+ */
+
+/**
+ * Upload client for Arke Institute's ingest service
+ * Works in Node.js, browsers, and other JavaScript runtimes
+ */
+declare class ArkeUploader {
+    private config;
+    private workerClient;
+    private scanner;
+    private platform;
+    constructor(config: UploaderConfig);
+    /**
+     * Get platform-specific scanner
+     */
+    private getScanner;
+    /**
+     * Upload a batch of files
+     * @param source - Directory path (Node.js) or File[]/FileList (browser)
+     * @param options - Upload options
+     */
+    uploadBatch(source: FileSource | FileSource[], options?: UploadOptions): Promise<BatchResult>;
+    /**
+     * Poll for root_pi during async discovery
+     */
+    private pollForRootPi;
+    /**
+     * Upload files with controlled concurrency
+     */
+    private uploadFilesWithConcurrency;
+    /**
+     * Upload a single file
+     */
+    private uploadSingleFile;
+    /**
+     * Get file data based on platform
+     */
+    private getFileData;
+    /**
+     * Report progress to callback
+     */
+    private reportProgress;
+}
+
+/**
+ * Custom error classes for better error handling
+ */
+declare class WorkerAPIError extends Error {
+    statusCode?: number | undefined;
+    details?: any | undefined;
+    constructor(message: string, statusCode?: number | undefined, details?: any | undefined);
+}
+declare class UploadError extends Error {
+    fileName?: string | undefined;
+    statusCode?: number | undefined;
+    cause?: Error | undefined;
+    constructor(message: string, fileName?: string | undefined, statusCode?: number | undefined, cause?: Error | undefined);
+}
+declare class ValidationError extends Error {
+    field?: string | undefined;
+    constructor(message: string, field?: string | undefined);
+}
+declare class NetworkError extends Error {
+    cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+declare class ScanError extends Error {
+    path?: string | undefined;
+    constructor(message: string, path?: string | undefined);
+}
+
+export { type AddToCollectionOptions as A, type BatchResult as B, type CreateCollectionUploadOptions as C, type FileInfo as F, NetworkError as N, type ProcessingConfig as P, ScanError as S, UploadClient as U, ValidationError as V, WorkerAPIError as W, type UploadClientConfig as a, type CreateCollectionUploadResult as b, ArkeUploader as c, type UploaderConfig as d, type UploadOptions as e, type UploadProgress as f, type CustomPrompts as g, UploadError as h, type UploadTask as i, type ScanResult as j };