@uploadista/client-core 0.0.3

package/src/auth/saas-auth.ts

@@ -0,0 +1,218 @@
+import type { HttpClient } from "../services/http-client";
+import { BaseAuthManager, type SaasAuthConfig } from "./types";
+
+/**
+ * Token response from the auth server
+ */
+export type TokenResponse = {
+  /** JWT token to use for authentication */
+  token: string;
+  /** Token expiration time in seconds (optional) */
+  expiresIn?: number;
+};
+
+/**
+ * Cached token information
+ */
+type CachedToken = {
+  token: string;
+  expiresAt?: number; // Unix timestamp in milliseconds
+};
+
+/**
+ * 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 {
+  /** Token cache: maps job ID to cached token */
+  private tokenCache = new Map<string, CachedToken>();
+
+  /** Global token for requests without a specific job ID */
+  private globalToken: CachedToken | null = null;
+
+  constructor(
+    private config: SaasAuthConfig,
+    private httpClient: HttpClient,
+  ) {
+    super("saas");
+  }
+
+  /**
+   * 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(): Promise<TokenResponse> {
+    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()) as TokenResponse;
+
+      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
+   */
+  private async getOrFetchToken(jobId?: string): Promise<string> {
+    // 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: 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.
+   */
+  private isTokenExpired(cached: CachedToken): boolean {
+    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: Record<string, string> = {},
+    jobId?: string,
+  ): Promise<Record<string, string>> {
+    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: string): void {
+    this.tokenCache.delete(jobId);
+  }
+
+  /**
+   * Clear all cached tokens.
+   * Useful for logout or when switching users.
+   */
+  clearAllTokens(): void {
+    this.tokenCache.clear();
+    this.globalToken = null;
+  }
+
+  /**
+   * Get cache statistics for debugging and monitoring.
+   */
+  getCacheStats(): {
+    cachedJobCount: number;
+    hasGlobalToken: boolean;
+  } {
+    return {
+      cachedJobCount: this.tokenCache.size,
+      hasGlobalToken: this.globalToken !== null,
+    };
+  }
+}

package/src/auth/types.ts

@@ -0,0 +1,105 @@
+export class BaseAuthManager {
+  constructor(private type: "direct" | "saas" | "no-auth") {}
+
+  getType() {
+    return this.type;
+  }
+}
+/**
+ * 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;

package/src/chunk-buffer.ts

@@ -0,0 +1,287 @@
+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 class ChunkBuffer {
+  private buffer: Uint8Array[] = [];
+  private currentSize = 0;
+  private config: Required<ChunkBufferConfig>;
+  private lastAddTime = 0;
+
+  /**
+   * Creates a new ChunkBuffer instance.
+   *
+   * @param config - Buffer configuration including thresholds and timeout
+   */
+  constructor(config: ChunkBufferConfig) {
+    this.config = {
+      minThreshold: config.minThreshold,
+      maxBufferSize: config.maxBufferSize ?? config.minThreshold * 2,
+      timeoutMs: config.timeoutMs ?? 30000, // 30 seconds
+    };
+  }
+
+  /**
+   * 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 {
+    this.buffer.push(chunk);
+    this.currentSize += chunk.length;
+    this.lastAddTime = Date.now();
+
+    if (this.shouldFlush()) {
+      return this.flush();
+    }
+
+    return 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 {
+    if (this.buffer.length === 0) {
+      return null;
+    }
+
+    const combined = new Uint8Array(this.currentSize);
+    let offset = 0;
+
+    for (const chunk of this.buffer) {
+      combined.set(chunk, offset);
+      offset += chunk.length;
+    }
+
+    const result: BufferedChunk = {
+      data: combined,
+      size: this.currentSize,
+      timestamp: this.lastAddTime,
+    };
+
+    this.reset();
+    return result;
+  }
+
+  /**
+   * 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 {
+    if (this.currentSize >= this.config.minThreshold) {
+      return true;
+    }
+
+    if (this.currentSize >= this.config.maxBufferSize) {
+      return true;
+    }
+
+    const timeSinceLastAdd = Date.now() - this.lastAddTime;
+    if (this.buffer.length > 0 && timeSinceLastAdd > this.config.timeoutMs) {
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * 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;
+  } {
+    return {
+      size: this.currentSize,
+      chunkCount: this.buffer.length,
+      isReadyToFlush: this.shouldFlush(),
+      timeSinceLastAdd: Date.now() - this.lastAddTime,
+    };
+  }
+
+  /**
+   * 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 {
+    return this.buffer.length > 0;
+  }
+
+  /**
+   * 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 {
+    this.buffer = [];
+    this.currentSize = 0;
+    this.lastAddTime = 0;
+  }
+
+  /**
+   * Returns the minimum threshold this buffer is configured for.
+   *
+   * @returns Minimum chunk size in bytes before flushing
+   */
+  getMinThreshold(): number {
+    return this.config.minThreshold;
+  }
+}