@uploadista/client-core 0.0.6 → 0.0.7

package/src/auth/auth-http-client.ts

@@ -5,12 +5,15 @@ import type {
 } from "../services/http-client";
 import type { DirectAuthManager } from "./direct-auth";
 import type { NoAuthManager } from "./no-auth";
-import type { SaasAuthManager } from "./saas-auth";
+import type { UploadistaCloudAuthManager } from "./uploadista-cloud-auth";
 
 /**
  * Union type of all auth managers
  */
-export type AuthManager = DirectAuthManager | SaasAuthManager | NoAuthManager;
+export type AuthManager =
+  | DirectAuthManager
+  | UploadistaCloudAuthManager
+  | NoAuthManager;
 
 /**
  * Auth-aware HTTP client wrapper.
@@ -49,7 +52,7 @@ export class AuthHttpClient implements HttpClient {
         // include credentials for cors if needed
         credentials:
           this.authManager.getType() === "no-auth" ||
-          this.authManager.getType() === "saas"
+          this.authManager.getType() === "uploadista-cloud"
             ? "omit"
             : (options.credentials ?? "include"),
       });
@@ -72,14 +75,14 @@ export class AuthHttpClient implements HttpClient {
     headers: Record<string, string>,
     url: string,
   ): Promise<Record<string, string>> {
-    // Check if this is a DirectAuthManager or SaasAuthManager
+    // Check if this is a DirectAuthManager or UploadistaCloudAuthManager
     if ("attachCredentials" in this.authManager) {
       // DirectAuthManager or NoAuthManager
       return await this.authManager.attachCredentials(headers);
     }
 
     if ("attachToken" in this.authManager) {
-      // SaasAuthManager - extract job ID from URL if present
+      // UploadistaCloudAuthManager - extract job ID from URL if present
       const jobId = this.extractJobIdFromUrl(url);
       return await this.authManager.attachToken(headers, jobId);
     }
@@ -97,7 +100,7 @@ export class AuthHttpClient implements HttpClient {
     // - /api/upload/{uploadId}
     // - /api/flow/{flowId}/{storageId}
     // - /api/jobs/{jobId}/status
-    // - /api/jobs/{jobId}/continue/{nodeId}
+    // - /api/jobs/{jobId}/resume/{nodeId}
 
     const uploadMatch = url.match(/\/api\/upload\/([^/?]+)/);
     if (uploadMatch) {
@@ -114,7 +117,7 @@ export class AuthHttpClient implements HttpClient {
       return jobMatch[1];
     }
 
-    // No job ID found - SaaS mode will use global token
+    // No job ID found - UploadistaCloud mode will use global token
     return undefined;
   }
 

package/src/auth/index.ts

@@ -1,5 +1,5 @@
 export * from "./auth-http-client";
 export * from "./direct-auth";
 export * from "./no-auth";
-export * from "./saas-auth";
 export * from "./types";
+export * from "./uploadista-cloud-auth";

package/src/auth/types.ts

@@ -1,5 +1,5 @@
 export class BaseAuthManager {
-  constructor(private type: "direct" | "saas" | "no-auth") {}
+  constructor(private type: "direct" | "uploadista-cloud" | "no-auth") {}
 
   getType() {
     return this.type;
@@ -56,7 +56,7 @@ export type DirectAuthConfig = {
 };
 
 /**
- * SaaS auth mode configuration.
+ * UploadistaCloud auth mode configuration.
  * Client requests JWT tokens from a user-controlled auth server,
  * which validates credentials and issues tokens using a secure API key.
  *
@@ -69,26 +69,21 @@ export type DirectAuthConfig = {
  * @example
  * ```typescript
  * {
- *   mode: 'saas',
+ *   mode: 'uploadista-cloud',
  *   authServerUrl: 'https://auth.myapp.com/token',
- *   getCredentials: async () => ({
- *     username: await getUsername(),
- *     password: await getPassword()
- *   })
+ *   clientId: 'my-client-id'
  * }
  * ```
  */
-export type SaasAuthConfig = {
-  mode: "saas";
+export type UploadistaCloudAuthConfig = {
+  mode: "uploadista-cloud";
   /**
    * 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
+   * Client ID to use for authentication. It will be used to compare the API Key with the client id on the auth server.
    */
   clientId: string;
 };
@@ -97,9 +92,9 @@ export type SaasAuthConfig = {
  * Authentication configuration for the uploadista client.
  * Supports two modes:
  * - Direct: Bring your own auth (any protocol)
- * - SaaS: Standard JWT token exchange with auth server
+ * - UploadistaCloud: 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;
+export type AuthConfig = DirectAuthConfig | UploadistaCloudAuthConfig;

package/src/auth/{saas-auth.ts → uploadista-cloud-auth.ts}

@@ -1,5 +1,5 @@
 import type { HttpClient } from "../services/http-client";
-import { BaseAuthManager, type SaasAuthConfig } from "./types";
+import { BaseAuthManager, type UploadistaCloudAuthConfig } from "./types";
 
 /**
  * Token response from the auth server
@@ -20,7 +20,7 @@ type CachedToken = {
 };
 
 /**
- * SaaS auth manager - handles JWT token exchange with an auth server.
+ * UploadistaCloud auth manager - handles JWT token exchange with an auth server.
  *
  * Token exchange flow:
  * 1. Client calls getCredentials() to get user credentials
@@ -31,7 +31,7 @@ type CachedToken = {
  *
  * Security: API keys are kept server-side in the auth server, never exposed to clients.
  */
-export class SaasAuthManager extends BaseAuthManager {
+export class UploadistaCloudAuthManager extends BaseAuthManager {
   /** Token cache: maps job ID to cached token */
   private tokenCache = new Map<string, CachedToken>();
 
@@ -39,10 +39,10 @@ export class SaasAuthManager extends BaseAuthManager {
   private globalToken: CachedToken | null = null;
 
   constructor(
-    private config: SaasAuthConfig,
+    private config: UploadistaCloudAuthConfig,
     private httpClient: HttpClient,
   ) {
-    super("saas");
+    super("uploadista-cloud");
   }
 
   /**

package/src/client/create-uploadista-client.ts

@@ -1,6 +1,11 @@
+import type { FlowJob } from "@uploadista/core/flow";
 import type { DataStoreCapabilities } from "@uploadista/core/types";
 import type { AuthConfig, AuthManager } from "../auth";
-import { DirectAuthManager, NoAuthManager, SaasAuthManager } from "../auth";
+import {
+  DirectAuthManager,
+  NoAuthManager,
+  UploadistaCloudAuthManager,
+} from "../auth";
 import type { Logger } from "../logger";
 import { createLogger } from "../logger";
 import { defaultClientCapabilities } from "../mock-data-store";
@@ -175,7 +180,7 @@ export type UploadistaClientOptions<UploadInput> = {
    * Optional authentication configuration.
    * Supports two modes:
    * - Direct: Bring your own auth (headers, cookies, custom tokens)
-   * - SaaS: Standard JWT token exchange with auth server
+   * - UploadistaCloud: Standard JWT token exchange with auth server
    *
    * If omitted, client operates in no-auth mode (backward compatible).
    *
@@ -189,10 +194,10 @@ export type UploadistaClientOptions<UploadInput> = {
    * }
    * ```
    *
-   * @example SaaS mode with auth server
+   * @example UploadistaCloud mode with auth server
    * ```typescript
    * auth: {
-   *   mode: 'saas',
+   *   mode: 'uploadista-cloud',
    *   authServerUrl: 'https://auth.myapp.com/token',
    *   getCredentials: () => ({ username: 'user', password: 'pass' })
    * }
@@ -230,7 +235,7 @@ export const defaultConnectionPoolingConfig: ConnectionPoolConfig = {
  * - Smart chunking based on network conditions
  * - Flow-based file processing pipelines
  * - WebSocket support for real-time progress
- * - Authentication (direct, SaaS, or no-auth modes)
+ * - Authentication (direct, uploadista-cloud, or no-auth modes)
  *
  * The client automatically:
  * - Fetches server capabilities and adapts upload strategy
@@ -369,13 +374,13 @@ export function createUploadistaClient<UploadInput>({
   const authManager: AuthManager = auth
     ? auth.mode === "direct"
       ? new DirectAuthManager(auth, platformService, logger)
-      : new SaasAuthManager(auth, httpClient)
+      : new UploadistaCloudAuthManager(auth, httpClient)
     : new NoAuthManager();
 
   // Log auth mode for debugging (without exposing credentials)
   if (auth) {
     logger.log(
-      `Authentication enabled in ${auth.mode} mode${auth.mode === "saas" ? ` (server: ${auth.authServerUrl})` : ""}`,
+      `Authentication enabled in ${auth.mode} mode${auth.mode === "uploadista-cloud" ? ` (server: ${auth.authServerUrl})` : ""}`,
     );
   }
 
@@ -666,7 +671,11 @@ export function createUploadistaClient<UploadInput>({
       UploadistaUploadOptions,
       "uploadLengthDeferred" | "uploadSize" | "metadata"
     > = {},
-  ): Promise<{ abort: () => void; jobId: string }> => {
+  ): Promise<{
+    abort: () => Promise<void>;
+    pause: () => Promise<FlowJob>;
+    jobId: string;
+  }> => {
     const source = await fileReader.openFile(file, chunkSize);
 
     const initializedSmartChunker = await initializeSmartChunker();
@@ -697,7 +706,10 @@ export function createUploadistaClient<UploadInput>({
 
     if (!result) {
       return {
-        abort: () => {},
+        abort: async () => {},
+        pause: async () => {
+          throw new Error("Flow upload not initialized");
+        },
         jobId: "",
       };
     }
@@ -735,7 +747,17 @@ export function createUploadistaClient<UploadInput>({
     });
 
     return {
-      abort: () => {
+      abort: async () => {
+        // First, tell the server to cancel the flow
+        try {
+          await uploadistaApi.cancelFlow(jobId);
+          logger.log(`Flow cancelled on server: ${jobId}`);
+        } catch (err) {
+          // Log but don't throw - client cleanup should still happen
+          logger.log(`Failed to cancel flow on server: ${err}`);
+        }
+
+        // Then do client-side cleanup
         abortController.abort();
         if (timeoutId) {
           platformService.clearTimeout(timeoutId);
@@ -744,6 +766,7 @@ export function createUploadistaClient<UploadInput>({
         wsManager.closeWebSocket(jobId);
         wsManager.closeUploadWebSocket(uploadFile.id);
       },
+      pause: () => uploadistaApi.pauseFlow(jobId),
       jobId,
     };
   };
@@ -777,7 +800,7 @@ export function createUploadistaClient<UploadInput>({
       return { status, job };
     },
 
-    continueFlow: async ({
+    resumeFlow: async ({
       jobId,
       nodeId,
       newData,
@@ -788,11 +811,19 @@ export function createUploadistaClient<UploadInput>({
       newData: unknown;
       contentType?: "application/json" | "application/octet-stream";
     }) => {
-      return uploadistaApi.continueFlow(jobId, nodeId, newData, {
+      return uploadistaApi.resumeFlow(jobId, nodeId, newData, {
         contentType,
       });
     },
 
+    pauseFlow: async (jobId: string) => {
+      return uploadistaApi.pauseFlow(jobId);
+    },
+
+    cancelFlow: async (jobId: string) => {
+      return uploadistaApi.cancelFlow(jobId);
+    },
+
     // Job operations (unified for both uploads and flows)
     getJobStatus: async (jobId: string) => {
       return uploadistaApi.getJobStatus(jobId);
@@ -874,7 +905,7 @@ export function createUploadistaClient<UploadInput>({
  *
  * The client provides methods for:
  * - **Upload operations**: upload(), uploadWithFlow()
- * - **Flow operations**: getFlow(), runFlow(), continueFlow()
+ * - **Flow operations**: getFlow(), runFlow(), resumeFlow()
  * - **Job management**: getJobStatus()
  * - **WebSocket management**: openUploadWebSocket(), openFlowWebSocket(), closeWebSocket()
  * - **Metrics and diagnostics**: getNetworkMetrics(), getChunkingInsights(), exportMetrics()

package/src/client/uploadista-api.ts

@@ -215,7 +215,7 @@ export type UploadistaApi = {
    * @returns Updated job metadata
    * @throws {UploadistaError} If job not found or continuation fails
    */
-  continueFlow: (
+  resumeFlow: (
     jobId: string,
     nodeId: string,
     newData: unknown,
@@ -224,6 +224,31 @@ export type UploadistaApi = {
     },
   ) => Promise<FlowJob>;
 
+  /**
+   * Pauses a running flow execution.
+   *
+   * The flow will stop at the next node boundary (not mid-node execution).
+   * Can be resumed later using resumeFlow.
+   *
+   * @param jobId - Job identifier for the running flow
+   * @returns Updated job metadata with "paused" status
+   * @throws {UploadistaError} If job not found or cannot be paused
+   */
+  pauseFlow: (jobId: string) => Promise<FlowJob>;
+
+  /**
+   * Cancels a running or paused flow execution.
+   *
+   * The flow will stop at the next node boundary (not mid-node execution).
+   * Intermediate files are automatically cleaned up. This operation is terminal
+   * and cannot be undone.
+   *
+   * @param jobId - Job identifier for the flow to cancel
+   * @returns Updated job metadata with "cancelled" status
+   * @throws {UploadistaError} If job not found or cannot be cancelled
+   */
+  cancelFlow: (jobId: string) => Promise<FlowJob>;
+
   /**
    * Retrieves current job status and outputs.
    *
@@ -390,7 +415,7 @@ export function createUploadistaApi(
 
   /**
    * Helper function to extract auth token for WebSocket connection.
-   * Supports both DirectAuthManager (extracts from headers) and SaasAuthManager (gets cached token).
+   * Supports both DirectAuthManager (extracts from headers) and UploadistaCloudAuthManager (gets cached token).
    */
   const getAuthTokenForWebSocket = async (
     manager: AuthManager,
@@ -398,17 +423,19 @@ export function createUploadistaApi(
   ): Promise<string | null> => {
     logger?.log(`Getting auth token for WebSocket (jobId: ${jobId})`);
 
-    // Check if this is a SaasAuthManager (has attachToken method)
+    // Check if this is a UploadistaCloudAuthManager (has attachToken method)
     if ("attachToken" in manager) {
-      logger?.log("Detected SaasAuthManager, calling attachToken");
+      logger?.log("Detected UploadistaCloudAuthManager, calling attachToken");
       const headers = await manager.attachToken({}, jobId);
       const authHeader = headers.Authorization;
       if (authHeader?.startsWith("Bearer ")) {
-        logger?.log("Successfully extracted Bearer token from SaasAuthManager");
+        logger?.log(
+          "Successfully extracted Bearer token from UploadistaCloudAuthManager",
+        );
         return authHeader.substring(7); // Remove "Bearer " prefix
       }
       logger?.log(
-        `No valid Authorization header from SaasAuthManager: ${authHeader}`,
+        `No valid Authorization header from UploadistaCloudAuthManager: ${authHeader}`,
       );
     }
 
@@ -629,7 +656,7 @@ export function createUploadistaApi(
       return { status: res.status, job: data };
     },
 
-    continueFlow: async (
+    resumeFlow: async (
       jobId: string,
       nodeId: string,
       newData: unknown,
@@ -637,8 +664,6 @@ export function createUploadistaApi(
         contentType?: "application/json" | "application/octet-stream";
       },
     ) => {
-      logger?.log(`continueFlow: ${jobId} at node: ${nodeId}`);
-
       const contentType = options?.contentType || "application/json";
 
       let body: RequestBody;
@@ -651,7 +676,7 @@ export function createUploadistaApi(
       }
 
       const res = await httpClient.request(
-        `${jobsEndpoint}/${jobId}/continue/${nodeId}`,
+        `${jobsEndpoint}/${jobId}/resume/${nodeId}`,
         {
           method: "PATCH",
           headers: {
@@ -665,12 +690,71 @@ export function createUploadistaApi(
         const errorData = (await res.json().catch(() => ({}))) as ErrorResponse;
         const errorName = mapServerErrorCodeToClientName(
           errorData.code,
-          "FLOW_CONTINUE_FAILED",
+          "FLOW_RESUMED_FAILED",
+        );
+        const errorMessage =
+          errorData.error ||
+          errorData.message ||
+          `Failed to resume flow for job ${jobId}`;
+
+        throw new UploadistaError({
+          name: errorName,
+          message: errorData.code
+            ? `${errorMessage} (${errorData.code})`
+            : errorMessage,
+          status: res.status,
+        });
+      }
+
+      const data = (await res.json()) as FlowJob;
+      return data;
+    },
+
+    pauseFlow: async (jobId: string) => {
+      const res = await httpClient.request(`${jobsEndpoint}/${jobId}/pause`, {
+        method: "POST",
+      });
+
+      if (!res.ok) {
+        const errorData = (await res.json().catch(() => ({}))) as ErrorResponse;
+        const errorName = mapServerErrorCodeToClientName(
+          errorData.code,
+          "FLOW_PAUSE_FAILED",
+        );
+        const errorMessage =
+          errorData.error ||
+          errorData.message ||
+          `Failed to pause flow for job ${jobId}`;
+
+        throw new UploadistaError({
+          name: errorName,
+          message: errorData.code
+            ? `${errorMessage} (${errorData.code})`
+            : errorMessage,
+          status: res.status,
+        });
+      }
+
+      const data = (await res.json()) as FlowJob;
+      logger?.log(`Flow paused: ${jobId}, status: ${data.status}`);
+      return data;
+    },
+
+    cancelFlow: async (jobId: string) => {
+      const res = await httpClient.request(`${jobsEndpoint}/${jobId}/cancel`, {
+        method: "POST",
+      });
+
+      if (!res.ok) {
+        const errorData = (await res.json().catch(() => ({}))) as ErrorResponse;
+        const errorName = mapServerErrorCodeToClientName(
+          errorData.code,
+          "FLOW_CANCEL_FAILED",
         );
         const errorMessage =
           errorData.error ||
           errorData.message ||
-          `Failed to continue flow for job ${jobId}`;
+          `Failed to cancel flow for job ${jobId}`;
 
         throw new UploadistaError({
           name: errorName,
@@ -682,6 +766,7 @@ export function createUploadistaApi(
       }
 
       const data = (await res.json()) as FlowJob;
+      logger?.log(`Flow cancelled: ${jobId}, status: ${data.status}`);
       return data;
     },
 

package/src/error.ts

@@ -36,7 +36,9 @@ export type UploadistaErrorName =
   | "FLOW_NOT_FOUND"
   | "FLOW_INIT_FAILED"
   | "FLOW_RUN_FAILED"
-  | "FLOW_CONTINUE_FAILED"
+  | "FLOW_RESUMED_FAILED"
+  | "FLOW_PAUSE_FAILED"
+  | "FLOW_CANCEL_FAILED"
   | "FLOW_UNEXPECTED_STATE"
   | "FLOW_INCOMPATIBLE"
   | "FLOW_NO_UPLOAD_ID"

package/src/upload/flow-upload.ts

@@ -144,7 +144,7 @@ export async function startFlowUpload({
 }
 
 /**
- * Upload chunks directly to the upload API (not through continueFlow)
+ * Upload chunks directly to the upload API (not through resumeFlow)
  * This is more efficient and reuses the existing upload infrastructure
  */
 export async function performFlowUpload({
@@ -265,7 +265,7 @@ export async function performFlowUpload({
       logger.log(`Finalizing flow upload for job ${jobId}`);
 
       try {
-        await uploadistaApi.continueFlow(
+        await uploadistaApi.resumeFlow(
           jobId,
           inputNodeId,
           {