@uploadista/client-core 0.0.3

package/dist/auth/saas-auth.js

@@ -0,0 +1,167 @@
+import { BaseAuthManager } from "./types";
+/**
+ * SaaS auth manager - handles JWT token exchange with an auth server.
+ *
+ * Token exchange flow:
+ * 1. Client calls getCredentials() to get user credentials
+ * 2. Manager sends credentials to authServerUrl
+ * 3. Auth server validates credentials and returns JWT token
+ * 4. Manager caches token and attaches it to uploadista requests
+ * 5. Token is cached per job to minimize auth overhead
+ *
+ * Security: API keys are kept server-side in the auth server, never exposed to clients.
+ */
+export class SaasAuthManager extends BaseAuthManager {
+    constructor(config, httpClient) {
+        super("saas");
+        this.config = config;
+        this.httpClient = httpClient;
+        /** Token cache: maps job ID to cached token */
+        this.tokenCache = new Map();
+        /** Global token for requests without a specific job ID */
+        this.globalToken = null;
+    }
+    /**
+     * Fetch a JWT token from the auth server using user credentials.
+     *
+     * @returns Token response with JWT and optional expiry
+     * @throws Error if auth server is unreachable or returns an error
+     */
+    async fetchToken() {
+        try {
+            // Make POST request to auth server
+            const response = await this.httpClient.request(`${this.config.authServerUrl}/${this.config.clientId}`, {
+                method: "GET",
+                headers: {
+                    "Content-Type": "application/json",
+                },
+            });
+            // Handle error responses
+            if (!response.ok) {
+                const errorText = await response.text();
+                let errorMessage = `Auth server returned ${response.status}`;
+                try {
+                    const errorJson = JSON.parse(errorText);
+                    errorMessage = errorJson.error || errorJson.message || errorMessage;
+                }
+                catch {
+                    // If response is not JSON, use status text
+                    errorMessage = errorText || response.statusText || errorMessage;
+                }
+                throw new Error(errorMessage);
+            }
+            // Parse token response
+            const data = (await response.json());
+            if (!data.token || typeof data.token !== "string") {
+                throw new Error("Auth server response missing 'token' field or token is not a string");
+            }
+            return data;
+        }
+        catch (error) {
+            // Wrap errors with context
+            if (error instanceof Error) {
+                throw new Error(`Failed to fetch auth token: ${error.message}`);
+            }
+            throw new Error(`Failed to fetch auth token: ${String(error)}`);
+        }
+    }
+    /**
+     * Get a cached token for a specific job, or fetch a new one if not cached.
+     *
+     * @param jobId - Optional job ID to cache token for specific job
+     * @returns Cached or newly fetched token
+     */
+    async getOrFetchToken(jobId) {
+        // Check if we have a cached token for this job
+        if (jobId) {
+            const cached = this.tokenCache.get(jobId);
+            if (cached && !this.isTokenExpired(cached)) {
+                return cached.token;
+            }
+        }
+        // Check global token cache
+        if (!jobId && this.globalToken && !this.isTokenExpired(this.globalToken)) {
+            return this.globalToken.token;
+        }
+        // No valid cached token - fetch a new one
+        const tokenResponse = await this.fetchToken();
+        // Calculate expiration time if provided
+        const expiresAt = tokenResponse.expiresIn
+            ? Date.now() + tokenResponse.expiresIn * 1000
+            : undefined;
+        const cachedToken = {
+            token: tokenResponse.token,
+            expiresAt,
+        };
+        // Cache the token
+        if (jobId) {
+            this.tokenCache.set(jobId, cachedToken);
+        }
+        else {
+            this.globalToken = cachedToken;
+        }
+        return tokenResponse.token;
+    }
+    /**
+     * Check if a cached token is expired.
+     * Adds a 60-second buffer to avoid using tokens that are about to expire.
+     */
+    isTokenExpired(cached) {
+        if (!cached.expiresAt) {
+            // No expiry set - assume token is valid
+            return false;
+        }
+        // Add 60-second buffer before actual expiry
+        const bufferMs = 60 * 1000;
+        return Date.now() > cached.expiresAt - bufferMs;
+    }
+    /**
+     * Attach JWT token to an HTTP request as Authorization Bearer header.
+     *
+     * @param headers - Existing request headers
+     * @param jobId - Optional job ID to use cached token for specific job
+     * @returns Updated headers with Authorization header
+     * @throws Error if token fetch fails
+     */
+    async attachToken(headers = {}, jobId) {
+        try {
+            // Get token (from cache or fetch new)
+            const token = await this.getOrFetchToken(jobId);
+            // Attach as Bearer token
+            return {
+                ...headers,
+                Authorization: `Bearer ${token}`,
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to attach auth token: ${message}`);
+        }
+    }
+    /**
+     * Clear cached token for a specific job.
+     * Should be called when a job completes to free memory.
+     *
+     * @param jobId - Job ID to clear token for
+     */
+    clearToken(jobId) {
+        this.tokenCache.delete(jobId);
+    }
+    /**
+     * Clear all cached tokens.
+     * Useful for logout or when switching users.
+     */
+    clearAllTokens() {
+        this.tokenCache.clear();
+        this.globalToken = null;
+    }
+    /**
+     * Get cache statistics for debugging and monitoring.
+     */
+    getCacheStats() {
+        return {
+            cachedJobCount: this.tokenCache.size,
+            hasGlobalToken: this.globalToken !== null,
+        };
+    }
+}

package/dist/auth/types.d.ts

@@ -0,0 +1,101 @@
+export declare class BaseAuthManager {
+    private type;
+    constructor(type: "direct" | "saas" | "no-auth");
+    getType(): "direct" | "saas" | "no-auth";
+}
+/**
+ * Credentials that can be attached to HTTP requests.
+ * Supports headers and cookies for maximum flexibility.
+ */
+export type RequestCredentials = {
+    /** HTTP headers to attach (e.g., Authorization, X-API-Key) */
+    headers?: Record<string, string>;
+    /** Cookies to attach (primarily for browser environments) */
+    cookies?: Record<string, string>;
+};
+/**
+ * Direct auth mode configuration.
+ * Users provide a function that returns credentials to attach to every request.
+ * This mode supports any authentication protocol (OAuth, JWT, sessions, API keys, etc.)
+ *
+ * @example Bearer token
+ * ```typescript
+ * {
+ *   mode: 'direct',
+ *   getCredentials: async () => ({
+ *     headers: {
+ *       'Authorization': `Bearer ${await getAccessToken()}`
+ *     }
+ *   })
+ * }
+ * ```
+ *
+ * @example API key
+ * ```typescript
+ * {
+ *   mode: 'direct',
+ *   getCredentials: () => ({
+ *     headers: {
+ *       'X-API-Key': process.env.API_KEY
+ *     }
+ *   })
+ * }
+ * ```
+ */
+export type DirectAuthConfig = {
+    mode: "direct";
+    /**
+     * Function called before each HTTP request to obtain credentials.
+     * Can be async to support token refresh or other async operations.
+     * Should not throw - return empty object if credentials unavailable.
+     */
+    getCredentials?: () => RequestCredentials | Promise<RequestCredentials>;
+};
+/**
+ * SaaS auth mode configuration.
+ * Client requests JWT tokens from a user-controlled auth server,
+ * which validates credentials and issues tokens using a secure API key.
+ *
+ * Token exchange flow:
+ * 1. Client calls getCredentials() to get user credentials
+ * 2. Client sends credentials to authServerUrl
+ * 3. Auth server validates and returns JWT token
+ * 4. Client attaches token to uploadista engine requests
+ *
+ * @example
+ * ```typescript
+ * {
+ *   mode: 'saas',
+ *   authServerUrl: 'https://auth.myapp.com/token',
+ *   getCredentials: async () => ({
+ *     username: await getUsername(),
+ *     password: await getPassword()
+ *   })
+ * }
+ * ```
+ */
+export type SaasAuthConfig = {
+    mode: "saas";
+    /**
+     * URL of the user's auth server that issues JWT tokens.
+     * Should be a GET endpoint that accepts client id and returns { token, expiresIn }.
+     */
+    authServerUrl: string;
+    /**
+     * Function that returns user credentials to send to the auth server.
+     * The auth server will validate these credentials before issuing a token.
+     * Credentials format is client id
+     */
+    clientId: string;
+};
+/**
+ * Authentication configuration for the uploadista client.
+ * Supports two modes:
+ * - Direct: Bring your own auth (any protocol)
+ * - SaaS: Standard JWT token exchange with auth server
+ *
+ * Use a discriminated union to ensure type safety - TypeScript will
+ * enforce that the correct fields are present for each mode.
+ */
+export type AuthConfig = DirectAuthConfig | SaasAuthConfig;
+//# sourceMappingURL=types.d.ts.map

package/dist/auth/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/auth/types.ts"],"names":[],"mappings":"AAAA,qBAAa,eAAe;IACd,OAAO,CAAC,IAAI;gBAAJ,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS;IAEvD,OAAO;CAGR;AACD;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,QAAQ,CAAC;IACf;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACzE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,UAAU,GAAG,gBAAgB,GAAG,cAAc,CAAC"}

package/dist/auth/types.js

@@ -0,0 +1,8 @@
+export class BaseAuthManager {
+    constructor(type) {
+        this.type = type;
+    }
+    getType() {
+        return this.type;
+    }
+}

package/dist/chunk-buffer.d.ts

@@ -0,0 +1,209 @@
+import type { BufferedChunk } from "./types/buffered-chunk";
+/**
+ * Configuration options for ChunkBuffer.
+ *
+ * Controls how the buffer accumulates chunks before flushing them to the datastore.
+ * This is essential for datastores with minimum chunk size requirements (e.g., AWS S3's 5MB minimum).
+ */
+export interface ChunkBufferConfig {
+    /**
+     * Minimum chunk size required by the datastore before flushing (in bytes).
+     * For example, AWS S3 requires a minimum of 5MB per multipart upload part.
+     */
+    minThreshold: number;
+    /**
+     * Maximum buffer size before forcing a flush (in bytes).
+     * Defaults to 2x minThreshold. Prevents memory issues with very slow uploads.
+     */
+    maxBufferSize?: number;
+    /**
+     * Maximum time to wait before flushing pending data (in milliseconds).
+     * Defaults to 30000ms (30 seconds). Ensures timely uploads even with slow data arrival.
+     */
+    timeoutMs?: number;
+}
+/**
+ * ChunkBuffer accumulates small chunks until they meet the minimum threshold
+ * required by the datastore (e.g., S3's 5MB minimum part size).
+ *
+ * This prevents inefficient upload/download cycles of incomplete parts by buffering
+ * small chunks in memory until they reach the datastore's minimum size requirement.
+ * The buffer automatically flushes when the threshold is met, the maximum buffer
+ * size is exceeded, or a timeout occurs.
+ *
+ * @example Basic usage with S3's 5MB minimum
+ * ```typescript
+ * const buffer = new ChunkBuffer({
+ *   minThreshold: 5 * 1024 * 1024, // 5MB
+ *   maxBufferSize: 10 * 1024 * 1024, // 10MB
+ *   timeoutMs: 30000, // 30 seconds
+ * });
+ *
+ * // Add chunks as they arrive
+ * const chunk1 = new Uint8Array(2 * 1024 * 1024); // 2MB
+ * buffer.add(chunk1); // Returns null (below threshold)
+ *
+ * const chunk2 = new Uint8Array(3 * 1024 * 1024); // 3MB
+ * const buffered = buffer.add(chunk2); // Returns combined 5MB chunk
+ * ```
+ *
+ * @example Handling incomplete uploads
+ * ```typescript
+ * const buffer = new ChunkBuffer({ minThreshold: 5 * 1024 * 1024 });
+ *
+ * // After adding several small chunks
+ * buffer.add(smallChunk1);
+ * buffer.add(smallChunk2);
+ *
+ * // Force flush remaining data at end of upload
+ * if (buffer.hasPendingData()) {
+ *   const finalChunk = buffer.flush();
+ *   await uploadFinalChunk(finalChunk);
+ * }
+ * ```
+ */
+export declare class ChunkBuffer {
+    private buffer;
+    private currentSize;
+    private config;
+    private lastAddTime;
+    /**
+     * Creates a new ChunkBuffer instance.
+     *
+     * @param config - Buffer configuration including thresholds and timeout
+     */
+    constructor(config: ChunkBufferConfig);
+    /**
+     * Adds a chunk to the buffer and returns the accumulated chunk if the flush threshold is met.
+     *
+     * The buffer will automatically flush (return the combined chunk) when:
+     * - The total buffered size meets or exceeds minThreshold
+     * - The total buffered size exceeds maxBufferSize
+     * - The time since the last chunk exceeds timeoutMs
+     *
+     * @param chunk - The chunk data to add to the buffer
+     * @returns The combined buffered chunk if flush conditions are met, null otherwise
+     *
+     * @example Progressive buffering
+     * ```typescript
+     * const buffer = new ChunkBuffer({ minThreshold: 1024 * 1024 }); // 1MB
+     *
+     * // First chunk doesn't meet threshold
+     * const result1 = buffer.add(new Uint8Array(512 * 1024)); // 512KB
+     * console.log(result1); // null
+     *
+     * // Second chunk triggers flush
+     * const result2 = buffer.add(new Uint8Array(512 * 1024)); // 512KB
+     * console.log(result2?.size); // 1048576 (1MB total)
+     * ```
+     */
+    add(chunk: Uint8Array): BufferedChunk | null;
+    /**
+     * Forces the buffer to flush immediately, returning all accumulated data.
+     *
+     * This is typically called at the end of an upload to ensure any remaining
+     * buffered data is sent, even if it hasn't reached the minimum threshold.
+     *
+     * @returns The combined buffered chunk, or null if the buffer is empty
+     *
+     * @example Flushing at upload completion
+     * ```typescript
+     * const buffer = new ChunkBuffer({ minThreshold: 5 * 1024 * 1024 });
+     *
+     * // Upload file in chunks
+     * for (const chunk of fileChunks) {
+     *   const buffered = buffer.add(chunk);
+     *   if (buffered) await uploadChunk(buffered);
+     * }
+     *
+     * // Upload any remaining data
+     * const final = buffer.flush();
+     * if (final) await uploadChunk(final);
+     * ```
+     */
+    flush(): BufferedChunk | null;
+    /**
+     * Checks if the buffer should be flushed based on size, max buffer, or timeout conditions.
+     *
+     * Returns true if any of these conditions are met:
+     * - Current size >= minThreshold
+     * - Current size >= maxBufferSize
+     * - Time since last add > timeoutMs
+     *
+     * @returns True if the buffer should be flushed
+     *
+     * @example Manual flush control
+     * ```typescript
+     * const buffer = new ChunkBuffer({ minThreshold: 1024 * 1024 });
+     *
+     * buffer.add(smallChunk);
+     *
+     * if (buffer.shouldFlush()) {
+     *   const data = buffer.flush();
+     *   await upload(data);
+     * }
+     * ```
+     */
+    shouldFlush(): boolean;
+    /**
+     * Returns the current buffer state without flushing.
+     *
+     * Useful for monitoring buffer status and making informed decisions
+     * about when to manually flush or adjust upload strategies.
+     *
+     * @returns Object containing buffer metrics
+     *
+     * @example Monitoring buffer state
+     * ```typescript
+     * const buffer = new ChunkBuffer({ minThreshold: 1024 * 1024 });
+     * buffer.add(chunk);
+     *
+     * const info = buffer.getBufferInfo();
+     * console.log(`Buffered: ${info.size} bytes in ${info.chunkCount} chunks`);
+     * console.log(`Ready to flush: ${info.isReadyToFlush}`);
+     * console.log(`Time since last add: ${info.timeSinceLastAdd}ms`);
+     * ```
+     */
+    getBufferInfo(): {
+        size: number;
+        chunkCount: number;
+        isReadyToFlush: boolean;
+        timeSinceLastAdd: number;
+    };
+    /**
+     * Checks if the buffer has any pending data that hasn't been flushed.
+     *
+     * Useful for determining if a final flush is needed at upload completion.
+     *
+     * @returns True if there are chunks waiting in the buffer
+     *
+     * @example Ensuring complete upload
+     * ```typescript
+     * // Upload all chunks
+     * for (const chunk of chunks) {
+     *   const buffered = buffer.add(chunk);
+     *   if (buffered) await upload(buffered);
+     * }
+     *
+     * // Don't forget the last partial chunk!
+     * if (buffer.hasPendingData()) {
+     *   await upload(buffer.flush());
+     * }
+     * ```
+     */
+    hasPendingData(): boolean;
+    /**
+     * Clears the buffer without returning data.
+     *
+     * This discards all buffered chunks and resets the buffer state.
+     * Use with caution as this will lose any pending data.
+     */
+    reset(): void;
+    /**
+     * Returns the minimum threshold this buffer is configured for.
+     *
+     * @returns Minimum chunk size in bytes before flushing
+     */
+    getMinThreshold(): number;
+}
+//# sourceMappingURL=chunk-buffer.d.ts.map

package/dist/chunk-buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk-buffer.d.ts","sourceRoot":"","sources":["../src/chunk-buffer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,MAAM,CAA8B;IAC5C,OAAO,CAAC,WAAW,CAAK;IAExB;;;;OAIG;gBACS,MAAM,EAAE,iBAAiB;IAQrC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,GAAG,CAAC,KAAK,EAAE,UAAU,GAAG,aAAa,GAAG,IAAI;IAY5C;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,KAAK,IAAI,aAAa,GAAG,IAAI;IAuB7B;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,WAAW,IAAI,OAAO;IAiBtB;;;;;;;;;;;;;;;;;;OAkBG;IACH,aAAa,IAAI;QACf,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,EAAE,MAAM,CAAC;QACnB,cAAc,EAAE,OAAO,CAAC;QACxB,gBAAgB,EAAE,MAAM,CAAC;KAC1B;IASD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,cAAc,IAAI,OAAO;IAIzB;;;;;OAKG;IACH,KAAK,IAAI,IAAI;IAMb;;;;OAIG;IACH,eAAe,IAAI,MAAM;CAG1B"}