@uploadista/client-core 0.0.3

package/dist/client/uploadista-api.d.ts

@@ -0,0 +1,284 @@
+import type { FlowData, FlowJob } from "@uploadista/core/flow";
+import type { DataStoreCapabilities, InputFile, UploadFile } from "@uploadista/core/types";
+import { type AuthManager } from "../auth";
+import type { Logger } from "../logger";
+import type { AbortControllerLike } from "../services/abort-controller-service";
+import type { ConnectionMetrics, DetailedConnectionMetrics, HttpClient } from "../services/http-client";
+import type { WebSocketFactory, WebSocketLike } from "../services/websocket-service";
+/**
+ * Response from upload-related API calls.
+ *
+ * Contains the upload metadata and HTTP status code.
+ */
+export type UploadistaUploadResponse = {
+    /** Upload file metadata, undefined if request failed */
+    upload?: UploadFile;
+    /** HTTP status code */
+    status: number;
+};
+/**
+ * Response from delete upload API call.
+ */
+export type UploadistaDeleteUploadResponse = {
+    /** Successfully deleted (no content) */
+    status: 204;
+} | {
+    /** Other status codes (e.g., 404, 500) */
+    status: number;
+};
+/**
+ * Response from flow retrieval API call.
+ */
+export type FlowResponse = {
+    /** HTTP status code */
+    status: number;
+    /** Flow configuration and metadata */
+    flow: FlowData;
+};
+/**
+ * Unified Uploadista API interface combining upload and flow operations.
+ *
+ * This low-level API provides direct access to server endpoints for:
+ * - Upload CRUD operations (create, get, delete, patch chunks)
+ * - Flow operations (get, run, continue)
+ * - Job status tracking
+ * - WebSocket connections for real-time updates
+ * - Server capabilities discovery
+ * - Connection pooling metrics
+ *
+ * Most applications should use the higher-level {@link UploadistaClient} instead,
+ * which provides a more convenient interface with automatic retry, resumption,
+ * and smart chunking.
+ *
+ * @example Direct API usage (advanced)
+ * ```typescript
+ * const api = createUploadistaApi(baseUrl, basePath, {
+ *   httpClient,
+ *   logger,
+ *   authManager,
+ *   webSocketFactory,
+ * });
+ *
+ * // Create an upload
+ * const { upload } = await api.createUpload({
+ *   storageId: 'my-storage',
+ *   size: 1024000,
+ *   metadata: { filename: 'test.txt' },
+ * });
+ *
+ * // Upload a chunk
+ * const chunk = new Uint8Array(1024);
+ * await api.uploadChunk(upload.id, chunk, {});
+ *
+ * // Check status
+ * const { upload: updated } = await api.getUpload(upload.id);
+ * console.log(`Progress: ${updated.offset}/${updated.size}`);
+ * ```
+ *
+ * @see {@link createUploadistaApi} for creating an instance
+ */
+export type UploadistaApi = {
+    /**
+     * Retrieves upload metadata and current status.
+     *
+     * @param uploadId - Unique upload identifier
+     * @returns Upload metadata including current offset and status
+     * @throws {UploadistaError} If upload not found or request fails
+     */
+    getUpload: (uploadId: string) => Promise<UploadistaUploadResponse>;
+    /**
+     * Deletes an upload and its associated data.
+     *
+     * @param uploadId - Unique upload identifier
+     * @returns Response with status 204 on success
+     * @throws {UploadistaError} If upload not found or deletion fails
+     */
+    deleteUpload: (uploadId: string) => Promise<UploadistaDeleteUploadResponse>;
+    /**
+     * Creates a new upload on the server.
+     *
+     * @param body - Upload configuration including storageId, size, and metadata
+     * @returns Created upload metadata with unique ID
+     * @throws {UploadistaError} If creation fails or validation errors occur
+     */
+    createUpload: (body: InputFile) => Promise<UploadistaUploadResponse>;
+    /**
+     * Uploads a chunk of data to an existing upload.
+     *
+     * @param uploadId - Upload identifier to append data to
+     * @param data - Chunk data bytes, or null to finalize without data
+     * @param options - Upload options including abort controller and progress callback
+     * @returns Updated upload metadata with new offset
+     * @throws {UploadistaError} If chunk upload fails or upload is locked
+     */
+    uploadChunk: (uploadId: string, data: Uint8Array | null, options: {
+        abortController?: AbortControllerLike;
+        onProgress?: (bytes: number, total: number) => void;
+    }) => Promise<UploadistaUploadResponse>;
+    /**
+     * Retrieves flow configuration and metadata.
+     *
+     * @param flowId - Unique flow identifier
+     * @returns Flow configuration including nodes and edges
+     * @throws {UploadistaError} If flow not found
+     */
+    getFlow: (flowId: string) => Promise<FlowResponse>;
+    /**
+     * Executes a flow with the provided inputs.
+     *
+     * @param flowId - Flow to execute
+     * @param storageId - Storage backend to use for flow outputs
+     * @param inputs - Input data for flow nodes (keyed by node ID)
+     * @returns Job metadata including job ID and initial state
+     * @throws {UploadistaError} If flow execution fails or inputs are invalid
+     */
+    runFlow: (flowId: string, storageId: string, inputs: Record<string, unknown>) => Promise<{
+        status: number;
+        job: FlowJob;
+    }>;
+    /**
+     * Continues a paused flow execution with new data.
+     *
+     * Used for interactive flows that wait for user input or external data.
+     *
+     * @param jobId - Job identifier for the paused flow
+     * @param nodeId - Node ID where execution should continue
+     * @param newData - Data to provide to the node
+     * @param options - Options including content type for binary data
+     * @returns Updated job metadata
+     * @throws {UploadistaError} If job not found or continuation fails
+     */
+    continueFlow: (jobId: string, nodeId: string, newData: unknown, options?: {
+        contentType?: "application/json" | "application/octet-stream";
+    }) => Promise<FlowJob>;
+    /**
+     * Retrieves current job status and outputs.
+     *
+     * Works for both upload and flow jobs.
+     *
+     * @param jobId - Job identifier
+     * @returns Job metadata including state, progress, and outputs
+     * @throws {UploadistaError} If job not found
+     */
+    getJobStatus: (jobId: string) => Promise<FlowJob>;
+    /**
+     * Opens a WebSocket connection for upload progress events.
+     *
+     * @param uploadId - Upload to monitor
+     * @returns WebSocket instance for receiving real-time updates
+     */
+    openUploadWebSocket: (uploadId: string) => Promise<WebSocketLike>;
+    /**
+     * Opens a WebSocket connection for flow job events.
+     *
+     * @param jobId - Flow job to monitor
+     * @returns WebSocket instance for receiving real-time updates
+     */
+    openFlowWebSocket: (jobId: string) => Promise<WebSocketLike>;
+    /**
+     * Closes a WebSocket connection.
+     *
+     * @param ws - WebSocket instance to close
+     */
+    closeWebSocket: (ws: WebSocketLike) => void;
+    /**
+     * Returns current connection pool metrics.
+     *
+     * @returns Basic metrics including active connections and reuse rate
+     */
+    getConnectionMetrics: () => ConnectionMetrics;
+    /**
+     * Returns detailed connection pool metrics with health diagnostics.
+     *
+     * @returns Comprehensive metrics including health status and recommendations
+     */
+    getDetailedConnectionMetrics: () => DetailedConnectionMetrics;
+    /**
+     * Pre-warms connections to the specified URLs.
+     *
+     * Useful for reducing latency on first upload by establishing
+     * connections ahead of time.
+     *
+     * @param urls - URLs to pre-connect to
+     */
+    warmupConnections: (urls: string[]) => Promise<void>;
+    /**
+     * Fetches server capabilities for the specified storage backend.
+     *
+     * Returns information about chunk size constraints, supported features,
+     * and storage-specific requirements. Falls back to default capabilities
+     * if the request fails.
+     *
+     * @param storageId - Storage backend identifier
+     * @returns Storage capabilities including chunk size limits
+     */
+    getCapabilities: (storageId: string) => Promise<DataStoreCapabilities>;
+};
+/**
+ * Creates an Uploadista API instance for direct server communication.
+ *
+ * This factory creates a low-level API client that handles:
+ * - HTTP requests to upload and flow endpoints
+ * - Authentication via AuthManager (optional)
+ * - WebSocket connections for real-time updates
+ * - Error mapping from server to client error types
+ * - Connection pooling and metrics
+ *
+ * Most applications should use {@link createUploadistaClient} instead,
+ * which wraps this API with higher-level features like automatic retry,
+ * resumption, and smart chunking.
+ *
+ * @param baseURL - Base URL of the Uploadista server (e.g., "https://upload.example.com")
+ * @param uploadistBasePath - Base path for endpoints, typically "uploadista"
+ * @param options - Configuration object
+ * @param options.httpClient - HTTP client for making requests
+ * @param options.logger - Optional logger for debugging
+ * @param options.authManager - Optional authentication manager
+ * @param options.webSocketFactory - Factory for creating WebSocket connections
+ * @returns UploadistaApi instance
+ *
+ * @example Basic API instance
+ * ```typescript
+ * import { createUploadistaApi } from '@uploadista/client-core';
+ *
+ * const api = createUploadistaApi(
+ *   'https://upload.example.com',
+ *   'uploadista',
+ *   {
+ *     httpClient: myHttpClient,
+ *     logger: console,
+ *     webSocketFactory: {
+ *       create: (url) => new WebSocket(url),
+ *     },
+ *   }
+ * );
+ *
+ * // Use the API directly
+ * const { upload } = await api.createUpload({
+ *   storageId: 'my-storage',
+ *   size: 1024,
+ * });
+ * ```
+ *
+ * @example With authentication
+ * ```typescript
+ * const authManager = new DirectAuthManager(authConfig, platformService, logger);
+ *
+ * const api = createUploadistaApi(baseUrl, 'uploadista', {
+ *   httpClient,
+ *   logger,
+ *   authManager, // Automatically adds auth headers to requests
+ *   webSocketFactory,
+ * });
+ * ```
+ *
+ * @see {@link UploadistaApi} for the API interface
+ * @see {@link createUploadistaClient} for the high-level client
+ */
+export declare function createUploadistaApi(baseURL: string, uploadistBasePath: string, { httpClient: baseHttpClient, logger, authManager, webSocketFactory, }: {
+    httpClient: HttpClient;
+    logger?: Logger;
+    authManager?: AuthManager;
+    webSocketFactory: WebSocketFactory;
+}): UploadistaApi;
+//# sourceMappingURL=uploadista-api.d.ts.map

package/dist/client/uploadista-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uploadista-api.d.ts","sourceRoot":"","sources":["../../src/client/uploadista-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,KAAK,EACV,qBAAqB,EACrB,SAAS,EACT,UAAU,EACX,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAExC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAChF,OAAO,KAAK,EACV,iBAAiB,EACjB,yBAAyB,EACzB,UAAU,EAEX,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EACV,gBAAgB,EAChB,aAAa,EACd,MAAM,+BAA+B,CAAC;AAsCvC;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC,wDAAwD;IACxD,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,8BAA8B,GACtC;IACE,wCAAwC;IACxC,MAAM,EAAE,GAAG,CAAC;CACb,GACD;IACE,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEN;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,IAAI,EAAE,QAAQ,CAAC;CAChB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B;;;;;;OAMG;IACH,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,wBAAwB,CAAC,CAAC;IAEnE;;;;;;OAMG;IACH,YAAY,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,8BAA8B,CAAC,CAAC;IAE5E;;;;;;OAMG;IACH,YAAY,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,OAAO,CAAC,wBAAwB,CAAC,CAAC;IAErE;;;;;;;;OAQG;IACH,WAAW,EAAE,CACX,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,UAAU,GAAG,IAAI,EACvB,OAAO,EAAE;QACP,eAAe,CAAC,EAAE,mBAAmB,CAAC;QACtC,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;KACrD,KACE,OAAO,CAAC,wBAAwB,CAAC,CAAC;IAEvC;;;;;;OAMG;IACH,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;IAEnD;;;;;;;;OAQG;IACH,OAAO,EAAE,CACP,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAE/C;;;;;;;;;;;OAWG;IACH,YAAY,EAAE,CACZ,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE;QACR,WAAW,CAAC,EAAE,kBAAkB,GAAG,0BAA0B,CAAC;KAC/D,KACE,OAAO,CAAC,OAAO,CAAC,CAAC;IAEtB;;;;;;;;OAQG;IACH,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAElD;;;;;OAKG;IACH,mBAAmB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;IAElE;;;;;OAKG;IACH,iBAAiB,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;IAE7D;;;;OAIG;IACH,cAAc,EAAE,CAAC,EAAE,EAAE,aAAa,KAAK,IAAI,CAAC;IAE5C;;;;OAIG;IACH,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;IAE9C;;;;OAIG;IACH,4BAA4B,EAAE,MAAM,yBAAyB,CAAC;IAE9D;;;;;;;OAOG;IACH,iBAAiB,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAErD;;;;;;;;;OASG;IACH,eAAe,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAC;CACxE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,iBAAiB,EAAE,MAAM,EACzB,EACE,UAAU,EAAE,cAAc,EAC1B,MAAM,EACN,WAAW,EACX,gBAAgB,GACjB,EAAE;IACD,UAAU,EAAE,UAAU,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,gBAAgB,EAAE,gBAAgB,CAAC;CACpC,GACA,aAAa,CAoef"}