@uploadista/server 0.0.7 → 0.0.9

package/dist/index.d.cts

@@ -1,14 +1,96 @@
 import { n as getAuthCredentials, t as AuthCredentialsResponse } from "./index-50KlDIjc.cjs";
+import { DataStoreCapabilities, Flow, FlowData, FlowJob, FlowServer, UploadEvent, UploadFile, UploadServer, UploadistaError } from "@uploadista/core";
 import { Context, Effect, Layer } from "effect";
-import { UploadistaError } from "@uploadista/core/errors";
-import * as _uploadista_core0 from "@uploadista/core";
-import { Flow, UploadServer } from "@uploadista/core";
-import { FlowProvider } from "@uploadista/core/flow";
-import { BaseEventEmitterService, BaseKvStoreService, UploadFileDataStore, UploadFileDataStores, UploadFileKVStore } from "@uploadista/core/types";
-import { UploadServer as UploadServer$1 } from "@uploadista/core/upload";
+import { Flow as Flow$1, FlowProvider, FlowServerShape } from "@uploadista/core/flow";
+import { BaseEventEmitterService, BaseKvStoreService, DataStoreConfig, EventBroadcasterService, UploadFileDataStore, UploadFileDataStores, UploadFileKVStore } from "@uploadista/core/types";
 import { GenerateId } from "@uploadista/core/utils";
-import z from "zod";
+import z$1, { z } from "zod";
+import { UploadServer as UploadServer$1, UploadServerShape } from "@uploadista/core/upload";
+import { UploadistaError as UploadistaError$1 } from "@uploadista/core/errors";
 
+//#region src/core/routes.d.ts
+type UploadistaRouteType = "create-upload" | "get-capabilities" | "get-upload" | "upload-chunk" | "get-flow" | "run-flow" | "job-status" | "resume-flow" | "pause-flow" | "cancel-flow" | "not-found" | "bad-request" | "method-not-allowed" | "unsupported-content-type";
+type UploadistaRoute<T extends UploadistaRouteType> = {
+  type: T;
+};
+type UploadistaStandardResponse<T extends UploadistaRouteType, ResponseBody, Status extends number = 200> = UploadistaRoute<T> & {
+  status: Status;
+  headers: {
+    "Content-Type": "application/json";
+  };
+  body: ResponseBody;
+};
+type NotFoundRequest = UploadistaRoute<"not-found">;
+type NotFoundResponse = UploadistaStandardResponse<"not-found", {
+  error: "Not found";
+}, 404>;
+type MethodNotAllowedRequest = UploadistaRoute<"method-not-allowed">;
+type MethodNotAllowedResponse = UploadistaStandardResponse<"method-not-allowed", {
+  error: "Method not allowed";
+}, 405>;
+type BadRequestRequest = UploadistaRoute<"bad-request"> & {
+  message: string;
+};
+type BadRequestResponse = UploadistaStandardResponse<"bad-request", {
+  error: "Bad request";
+  message: string;
+}, 400>;
+type UnsupportedContentTypeRequest = UploadistaRoute<"unsupported-content-type">;
+type UnsupportedContentTypeResponse = UploadistaStandardResponse<"unsupported-content-type", {
+  error: "Unsupported content type";
+}, 415>;
+type CreateUploadRequest = UploadistaRoute<"create-upload"> & {
+  data: unknown;
+};
+type CreateUploadResponse = UploadistaStandardResponse<"create-upload", UploadFile>;
+type GetCapabilitiesRequest = UploadistaRoute<"get-capabilities"> & {
+  storageId: string;
+};
+type GetCapabilitiesResponse = UploadistaStandardResponse<"get-capabilities", {
+  storageId: string;
+  capabilities: DataStoreCapabilities;
+  timestamp: string;
+}>;
+type GetUploadRequest = UploadistaRoute<"get-upload"> & {
+  uploadId: string;
+};
+type GetUploadResponse = UploadistaStandardResponse<"get-upload", UploadFile>;
+type UploadChunkRequest = UploadistaRoute<"upload-chunk"> & {
+  uploadId: string;
+  data: ReadableStream;
+};
+type UploadChunkResponse = UploadistaStandardResponse<"upload-chunk", UploadFile>;
+type GetFlowRequest = UploadistaRoute<"get-flow"> & {
+  flowId: string;
+};
+type GetFlowResponse = UploadistaStandardResponse<"get-flow", FlowData>;
+type RunFlowRequest = UploadistaRoute<"run-flow"> & {
+  flowId: string;
+  storageId: string;
+  inputs: Record<string, unknown>;
+};
+type RunFlowResponse = UploadistaStandardResponse<"run-flow", FlowJob>;
+type GetJobStatusRequest = UploadistaRoute<"job-status"> & {
+  jobId: string;
+};
+type GetJobStatusResponse = UploadistaStandardResponse<"job-status", FlowJob>;
+type ResumeFlowRequest = UploadistaRoute<"resume-flow"> & {
+  jobId: string;
+  nodeId: string;
+  newData: unknown;
+};
+type ResumeFlowResponse = UploadistaStandardResponse<"resume-flow", FlowJob>;
+type PauseFlowRequest = UploadistaRoute<"pause-flow"> & {
+  jobId: string;
+};
+type PauseFlowResponse = UploadistaStandardResponse<"pause-flow", FlowJob>;
+type CancelFlowRequest = UploadistaRoute<"cancel-flow"> & {
+  jobId: string;
+};
+type CancelFlowResponse = UploadistaStandardResponse<"cancel-flow", FlowJob>;
+type UploadistaRequest = CreateUploadRequest | GetCapabilitiesRequest | GetUploadRequest | UploadChunkRequest | GetFlowRequest | RunFlowRequest | GetJobStatusRequest | ResumeFlowRequest | PauseFlowRequest | CancelFlowRequest | NotFoundRequest | BadRequestRequest | MethodNotAllowedRequest | UnsupportedContentTypeRequest;
+type UploadistaResponse = CreateUploadResponse | GetCapabilitiesResponse | GetUploadResponse | UploadChunkResponse | GetFlowResponse | RunFlowResponse | GetJobStatusResponse | ResumeFlowResponse | PauseFlowResponse | CancelFlowResponse | NotFoundResponse | BadRequestResponse | MethodNotAllowedResponse | UnsupportedContentTypeResponse | StandardResponse;
+//#endregion
 //#region src/types.d.ts
 /**
  * Authentication context containing user identity and authorization metadata.
@@ -48,6 +130,210 @@ type AuthContext = {
  */
 type AuthResult = AuthContext | null;
 //#endregion
+//#region src/adapter/types.d.ts
+/**
+ * Standard request representation extracted from framework-specific request objects.
+ *
+ * This interface provides a framework-agnostic way to represent HTTP requests,
+ * allowing the core server logic to work uniformly across Hono, Express, Fastify,
+ * and other frameworks.
+ *
+ * @example
+ * ```typescript
+ * const standardRequest: StandardRequest = {
+ *   method: "POST",
+ *   url: new URL("https://example.com/uploadista/api/upload"),
+ *   headers: { "content-type": "application/json" },
+ *   body: { file: "data" }
+ * };
+ * ```
+ */
+interface StandardRequest {
+  /**
+   * HTTP method (GET, POST, PATCH, etc.)
+   */
+  method: string;
+  /**
+   * Full URL of the request including protocol, host, path, and query parameters
+   */
+  url: URL;
+  /**
+   * Request headers as key-value pairs
+   */
+  headers: Record<string, string>;
+  /**
+   * Optional request body (parsed or raw)
+   */
+  body?: unknown;
+}
+/**
+ * Standard response representation to be sent by framework-specific adapters.
+ *
+ * The core server produces StandardResponse objects, which adapters then
+ * translate into framework-specific response formats.
+ *
+ * @example
+ * ```typescript
+ * const standardResponse: StandardResponse = {
+ *   status: 200,
+ *   headers: { "content-type": "application/json" },
+ *   body: { uploadId: "abc123" }
+ * };
+ * ```
+ */
+interface StandardResponse {
+  /**
+   * HTTP status code (200, 404, 500, etc.)
+   */
+  status: number;
+  /**
+   * Optional response headers as key-value pairs
+   */
+  headers?: Record<string, string>;
+  /**
+   * Optional response body (will be JSON-stringified if object)
+   */
+  body?: unknown;
+}
+/**
+ * WebSocket handler interface for framework-agnostic WebSocket management.
+ *
+ * This interface allows the core server to interact with WebSocket connections
+ * without needing to know about framework-specific WebSocket APIs.
+ *
+ * @example
+ * ```typescript
+ * const wsHandler: WebSocketHandler = {
+ *   onMessage: (message) => console.log("Received:", message),
+ *   onClose: () => console.log("Connection closed"),
+ *   onError: (error) => console.error("WebSocket error:", error)
+ * };
+ * ```
+ */
+interface WebSocketHandler {
+  /**
+   * Callback invoked when a message is received from the client
+   *
+   * @param message - The message string received
+   */
+  onMessage: (message: string) => void;
+  /**
+   * Callback invoked when the WebSocket connection is closed
+   */
+  onClose: () => void;
+  /**
+   * Callback invoked when a WebSocket error occurs
+   *
+   * @param error - The error that occurred
+   */
+  onError: (error: Error) => void;
+}
+/**
+ * ServerAdapter interface that framework adapters must implement.
+ *
+ * This interface defines the contract between the core server (framework-agnostic)
+ * and framework-specific adapters (Hono, Express, Fastify, etc.).
+ *
+ * Each adapter translates between framework-specific request/response types
+ * and the standard types used by the core server.
+ *
+ * @template TRequest - Framework-specific request type (e.g., Context for Hono, Request for Express)
+ * @template TResponse - Framework-specific response type (e.g., Context for Hono, Response for Express)
+ * @template TWebSocket - Framework-specific WebSocket type (optional, defaults to unknown)
+ *
+ * @example
+ * ```typescript
+ * // Hono adapter example
+ * const honoAdapter: ServerAdapter<Context, Context, WSEvents> = {
+ *   extractRequest: (c) => Effect.succeed({
+ *     method: c.req.raw.method,
+ *     url: new URL(c.req.raw.url),
+ *     headers: Object.fromEntries(c.req.raw.headers.entries()),
+ *     body: c.req.raw.body
+ *   }),
+ *   sendResponse: (c, response) => Effect.sync(() =>
+ *     new Response(JSON.stringify(response.body), {
+ *       status: response.status,
+ *       headers: response.headers
+ *     })
+ *   ),
+ *   runAuthMiddleware: (c) => Effect.tryPromise(() => authMiddleware(c)),
+ *   createWebSocketHandler: (ws) => ({ ... })
+ * };
+ * ```
+ */
+interface ServerAdapter<TContext, TResponse, TWebSocketHandler = unknown> {
+  /**
+   * Extract standard request details from framework-specific request.
+   *
+   * This method converts the framework's native request object into a
+   * UploadistaRequest that the core server can process uniformly.
+   *
+   * @param req - Framework-specific request object
+   * @returns Effect that produces UploadistaRequest on success
+   */
+  extractRequest(req: TContext, {
+    baseUrl
+  }: {
+    baseUrl: string;
+  }): Effect.Effect<UploadistaRequest, never, never>;
+  /**
+   * Send standard response using framework-specific response object.
+   *
+   * This method converts a UploadistaResponse from the core server into
+   * the format required by the framework (e.g., Web API Response, Express res.json()).
+   *
+   * @param response - Standard response to send
+   * @returns Effect that completes when response is sent
+   */
+  sendResponse(response: UploadistaResponse, context: TContext): Effect.Effect<TResponse, never, never>;
+  /**
+   * Optional: Run framework-specific auth middleware.
+   *
+   * If provided, this method is called before each request is processed.
+   * It should execute the framework's authentication middleware and return
+   * an AuthResult (AuthContext on success, null on failure).
+   *
+   * If not provided, the adapter assumes no authentication is required.
+   *
+   * @param ctx - Framework-specific context object
+   * @param res - Framework-specific response object
+   * @returns Effect that produces AuthResult (AuthContext or null)
+   */
+  runAuthMiddleware?(ctx: TContext): Effect.Effect<AuthResult, never, never>;
+  /**
+   * Optional: Create WebSocket handler for real-time updates.
+   *
+   * Only needed if the framework supports WebSocket connections for
+   * real-time upload progress and flow status updates.
+   *
+   * @param ws - Framework-specific WebSocket object
+   * @param ctx - Framework-specific context object (for initial handshake)
+   * @param context - Server context with baseUrl, uploadServer, and flowServer
+   * @returns WebSocketHandler with callbacks for message, close, and error events
+   */
+  webSocketHandler(context: {
+    baseUrl: string;
+  }): Effect.Effect<TWebSocketHandler, never, UploadServer | FlowServer>;
+  /**
+   * Optional: Extract waitUntil callback from the framework context.
+   *
+   * When provided, allows flows to execute beyond the HTTP response lifecycle.
+   * This function is called per-request to extract the waitUntil callback from
+   * the framework-specific context.
+   *
+   * @param ctx - Framework-specific context object
+   * @returns The waitUntil callback or undefined if not available
+   *
+   * @example
+   * ```typescript
+   * // Cloudflare Workers with Hono:
+   * extractWaitUntil: (c) => c.executionCtx.waitUntil.bind(c.executionCtx)
+   * ```
+   */
+  extractWaitUntil?: (ctx: TContext) => ((promise: Promise<unknown>) => void) | undefined;
+}
+//#endregion
 //#region src/cache.d.ts
 /**
  * Configuration options for the auth cache.
@@ -132,6 +418,443 @@ declare const AuthCacheServiceLive: (config?: AuthCacheConfig) => Layer.Layer<Au
  */
 declare const NoAuthCacheServiceLive: Layer.Layer<AuthCacheService>;
 //#endregion
+//#region src/core/types.d.ts
+/**
+ * Function type for retrieving flows based on flow ID and client ID.
+ *
+ * This function is called by the core server when a flow needs to be executed.
+ * It should return an Effect that resolves to the requested Flow or fails with
+ * an UploadistaError if the flow is not found or not authorized.
+ *
+ * @param flowId - The unique identifier of the flow to retrieve
+ * @param clientId - The authenticated client ID (null if not authenticated)
+ * @returns Effect that produces the Flow or fails with an error
+ *
+ * @example
+ * ```typescript
+ * const flows: FlowsFunction = (flowId, clientId) =>
+ *   Effect.gen(function* () {
+ *     if (flowId === "image-resize") {
+ *       return imageResizeFlow;
+ *     }
+ *     return yield* Effect.fail(
+ *       new UploadistaError({ code: "FLOW_NOT_FOUND", status: 404 })
+ *     );
+ *   });
+ * ```
+ */
+type FlowsFunction = (flowId: string, clientId: string | null) => Effect.Effect<Flow$1<z.ZodSchema<unknown>, z.ZodSchema<unknown>, unknown>, UploadistaError, unknown>;
+/**
+ * Configuration for creating the unified Uploadista server.
+ *
+ * This configuration is framework-agnostic and contains all the business logic
+ * configuration. Framework-specific details are provided via the `adapter` field.
+ *
+ * @template TRequest - Framework-specific request type
+ * @template TResponse - Framework-specific response type
+ * @template TWebSocket - Framework-specific WebSocket type (optional)
+ *
+ * @example
+ * ```typescript
+ * import { createUploadistaServer, honoAdapter } from "@uploadista/server";
+ *
+ * const config: UploadistaServerConfig<Context, Context, WSEvents> = {
+ *   // Core business logic configuration
+ *   flows: getFlowById,
+ *   dataStore: { type: "s3", config: { bucket: "my-bucket" } },
+ *   kvStore: redisKvStore,
+ *   baseUrl: "/uploadista",
+ *
+ *   // Framework-specific adapter
+ *   adapter: honoAdapter({
+ *     authMiddleware: async (c) => {
+ *       // Hono-specific auth logic
+ *       return { clientId: "user-123" };
+ *     },
+ *   }),
+ * };
+ *
+ * const server = await createUploadistaServer(config);
+ * ```
+ */
+interface UploadistaServerConfig<TRequest, TResponse, TWebSocket = unknown> {
+  /**
+   * Function for retrieving flows by ID.
+   *
+   * This function is called when a flow execution is requested.
+   * It receives the flow ID and client ID (from auth context) and should
+   * return an Effect that resolves to the Flow definition.
+   *
+   * @example
+   * ```typescript
+   * flows: (flowId, clientId) => Effect.succeed(myFlows[flowId])
+   * ```
+   */
+  flows: FlowsFunction;
+  /**
+   * Data store configuration for file storage.
+   *
+   * Specifies where uploaded files should be stored (S3, Azure, GCS, filesystem).
+   * The core server creates the appropriate data store layer from this configuration.
+   *
+   * @example
+   * ```typescript
+   * dataStore: {
+   *   type: "s3",
+   *   config: {
+   *     bucket: "my-uploads",
+   *     region: "us-east-1"
+   *   }
+   * }
+   * ```
+   */
+  dataStore: DataStoreConfig;
+  /**
+   * Key-value store layer for metadata storage.
+   *
+   * Used for storing upload metadata, flow job state, and other persistent data.
+   * Can be Redis, Cloudflare KV, in-memory, or any implementation of BaseKvStoreService.
+   *
+   * @example
+   * ```typescript
+   * import { redisKvStore } from "@uploadista/kv-store-redis";
+   *
+   * kvStore: redisKvStore({ url: "redis://localhost:6379" })
+   * ```
+   */
+  kvStore: Layer.Layer<BaseKvStoreService>;
+  /**
+   * Optional: Plugins to extend functionality.
+   *
+   * Plugins are Effect layers that add additional capabilities to the upload
+   * and flow servers. They are merged into the server layer composition.
+   *
+   * @example
+   * ```typescript
+   * plugins: [imageProcessingPlugin, virusScanPlugin]
+   * ```
+   */
+  plugins?: readonly Layer.Layer<any, never, never>[];
+  /**
+   * Optional: Event emitter layer for progress notifications.
+   *
+   * Used to emit upload progress, flow status updates, and other events.
+   * Defaults to in-memory event emitter if not provided.
+   *
+   * @example
+   * ```typescript
+   * import { webSocketEventEmitter } from "@uploadista/event-emitter-websocket";
+   *
+   * eventEmitter: webSocketEventEmitter()
+   * ```
+   */
+  eventEmitter?: Layer.Layer<BaseEventEmitterService>;
+  /**
+   * Optional: Event broadcaster layer for real-time updates.
+   *
+   * Used to broadcast events to multiple subscribers (e.g., WebSocket connections).
+   * Defaults to in-memory broadcaster if not provided.
+   *
+   * @example
+   * ```typescript
+   * import { memoryEventBroadcaster } from "@uploadista/event-broadcaster-memory";
+   *
+   * eventBroadcaster: memoryEventBroadcaster()
+   * ```
+   */
+  eventBroadcaster?: Layer.Layer<EventBroadcasterService>;
+  /**
+   * Optional: Base URL path for Uploadista endpoints.
+   *
+   * All Uploadista routes will be prefixed with `{baseUrl}/api/`.
+   * For example, with baseUrl="/uploadista", routes become:
+   * - POST /uploadista/api/upload
+   * - POST /uploadista/api/flow/{flowId}/{storageId}
+   *
+   * @default "" (no prefix, routes start with /api/)
+   */
+  baseUrl?: string;
+  /**
+   * Optional: Custom ID generator layer.
+   *
+   * Used for generating upload IDs, job IDs, and other unique identifiers.
+   * Defaults to built-in ID generator if not provided.
+   *
+   * @example
+   * ```typescript
+   * import { nanoidGenerator } from "@uploadista/utils";
+   *
+   * generateId: nanoidGenerator()
+   * ```
+   */
+  generateId?: Layer.Layer<GenerateId>;
+  /**
+   * Optional: Enable distributed tracing with OpenTelemetry.
+   *
+   * When true, Effect programs run with OpenTelemetry tracing enabled,
+   * allowing observability into upload and flow execution.
+   *
+   * @default false
+   */
+  withTracing?: boolean;
+  /**
+   * Optional: Metrics layer for observability.
+   *
+   * Used to collect metrics about upload/flow performance, errors, and usage.
+   * Defaults to NoOp metrics if not provided.
+   *
+   * @example
+   * ```typescript
+   * import { prometheusMetrics } from "@uploadista/observability";
+   *
+   * metricsLayer: prometheusMetrics()
+   * ```
+   */
+  metricsLayer?: Layer.Layer<any, never, never>;
+  /**
+   * Optional: Buffered data store layer for performance optimization.
+   *
+   * Provides in-memory buffering for frequently accessed data,
+   * reducing latency for chunk uploads and reads.
+   *
+   * @example
+   * ```typescript
+   * import { bufferedDataStore } from "@uploadista/core/data-store";
+   *
+   * bufferedDataStore: bufferedDataStore({ maxSize: 1024 * 1024 * 10 })
+   * ```
+   */
+  bufferedDataStore?: Layer.Layer<UploadFileDataStore, never, UploadFileKVStore>;
+  /**
+   * Framework-specific adapter.
+   *
+   * The adapter provides the bridge between framework-specific request/response
+   * types and the standard types used by the core server. Each framework
+   * (Hono, Express, Fastify) has its own adapter implementation.
+   *
+   * @example
+   * ```typescript
+   * import { honoAdapter } from "@uploadista/adapters-hono";
+   *
+   * adapter: honoAdapter({
+   *   authMiddleware: async (c) => ({ clientId: "user-123" })
+   * })
+   * ```
+   */
+  adapter: ServerAdapter<TRequest, TResponse, TWebSocket>;
+  /**
+   * Optional: Configuration for auth context caching.
+   *
+   * Caching allows subsequent requests (chunk uploads, flow continuations) to
+   * reuse the auth context from the initial request without re-authenticating.
+   *
+   * @example
+   * ```typescript
+   * authCacheConfig: {
+   *   maxSize: 10000,
+   *   ttl: 3600000 // 1 hour
+   * }
+   * ```
+   */
+  authCacheConfig?: AuthCacheConfig;
+}
+/**
+ * Return type from createUploadistaServer.
+ *
+ * Contains the handler function and exposed server layers for framework-specific routing.
+ *
+ * @template TRequest - Framework-specific request type
+ * @template TResponse - Framework-specific response type
+ * @template TWebSocket - Framework-specific WebSocket type (optional)
+ */
+interface UploadistaServer<TRequest, TResponse, TWebSocketHandler = unknown> {
+  /**
+   * Main request handler that processes HTTP requests through the adapter.
+   */
+  handler: (req: TRequest) => Promise<TResponse>;
+  /**
+   * Optional WebSocket handler if the adapter supports WebSocket connections.
+   */
+  websocketHandler: TWebSocketHandler;
+  /**
+   * Base URL path for Uploadista endpoints.
+   */
+  baseUrl: string;
+  /**
+   * Dispose function for graceful shutdown.
+   * Cleans up all resources associated with the managed runtime.
+   * Should be called when the server is shutting down.
+   */
+  dispose: () => Promise<void>;
+}
+//#endregion
+//#region src/core/server.d.ts
+/**
+ * Creates the unified Uploadista server with framework-specific adapter.
+ *
+ * This function composes all layers (upload server, flow server, auth, metrics)
+ * and returns a handler that works with any framework via the provided adapter.
+ *
+ * The core server handles:
+ * - Route parsing and matching
+ * - Auth middleware execution with timeout protection
+ * - Layer composition (upload/flow servers, auth cache, metrics)
+ * - Error handling and response formatting
+ * - Effect program execution with optional tracing
+ *
+ * @param config - Server configuration including adapter and business logic
+ * @returns Object with handler function, optional WebSocket handler, and base URL
+ *
+ * @example
+ * ```typescript
+ * import { createUploadistaServer, honoAdapter } from "@uploadista/server";
+ *
+ * const server = await createUploadistaServer({
+ *   flows: getFlowById,
+ *   dataStore: { type: "s3", config: { bucket: "uploads" } },
+ *   kvStore: redisKvStore,
+ *   adapter: honoAdapter({
+ *     authMiddleware: async (c) => ({ clientId: "user-123" })
+ *   })
+ * });
+ *
+ * // Use with Hono
+ * app.all("/uploadista/*", server.handler);
+ * ```
+ */
+declare const createUploadistaServer: <TContext, TResponse, TWebSocketHandler = unknown>({
+  flows,
+  dataStore,
+  kvStore,
+  plugins,
+  eventEmitter,
+  eventBroadcaster,
+  withTracing,
+  baseUrl: configBaseUrl,
+  generateId,
+  metricsLayer,
+  bufferedDataStore,
+  adapter,
+  authCacheConfig
+}: UploadistaServerConfig<TContext, TResponse, TWebSocketHandler>) => Promise<UploadistaServer<TContext, TResponse, TWebSocketHandler>>;
+//#endregion
+//#region src/core/websocket-routes.d.ts
+/**
+ * Framework-agnostic WebSocket connection interface
+ * Adapters should wrap their native WebSocket implementations to match this interface
+ */
+type WebSocketConnection = {
+  id: string;
+  send: (data: string) => void;
+  close: (code?: number, reason?: string) => void;
+  readyState: number;
+};
+/**
+ * WebSocket event types for real-time communication
+ */
+type WebSocketEventType = "subscribe-upload" | "subscribe-flow" | "unsubscribe-upload" | "unsubscribe-flow" | "ping" | "connection" | "upload-event" | "flow-event" | "error" | "invalid-path" | "auth-failed";
+/**
+ * Base WebSocket event structure
+ */
+type WebSocketEvent<T extends WebSocketEventType> = {
+  type: T;
+};
+/**
+ * Incoming WebSocket messages (client -> server)
+ */
+type SubscribeUploadEvent = WebSocketEvent<"subscribe-upload"> & {
+  uploadId: string;
+};
+type SubscribeFlowEvent = WebSocketEvent<"subscribe-flow"> & {
+  jobId: string;
+};
+type UnsubscribeUploadEvent = WebSocketEvent<"unsubscribe-upload"> & {
+  uploadId: string;
+};
+type UnsubscribeFlowEvent = WebSocketEvent<"unsubscribe-flow"> & {
+  jobId: string;
+};
+type PingEvent = WebSocketEvent<"ping">;
+type WebSocketIncomingEvent = SubscribeUploadEvent | SubscribeFlowEvent | UnsubscribeUploadEvent | UnsubscribeFlowEvent | PingEvent;
+/**
+ * Outgoing WebSocket messages (server -> client)
+ */
+type ConnectionEvent = WebSocketEvent<"connection"> & {
+  message: string;
+  id?: string;
+  jobId?: string;
+  uploadId?: string;
+  timestamp: string;
+};
+type UploadEventMessage = WebSocketEvent<"upload-event"> & {
+  uploadId: string;
+  event: UploadEvent;
+  timestamp: string;
+};
+type FlowEventMessage = WebSocketEvent<"flow-event"> & {
+  jobId: string;
+  event: unknown;
+  timestamp: string;
+};
+type ErrorEvent = WebSocketEvent<"error"> & {
+  message: string;
+  code?: string;
+};
+type InvalidPathEvent = WebSocketEvent<"invalid-path"> & {
+  message: string;
+  expectedPrefix: string;
+};
+type AuthFailedEvent = WebSocketEvent<"auth-failed"> & {
+  message: string;
+  authMethod: "token" | "cookies";
+};
+type WebSocketOutgoingEvent = ConnectionEvent | UploadEventMessage | FlowEventMessage | ErrorEvent | InvalidPathEvent | AuthFailedEvent;
+/**
+ * WebSocket connection request with routing information
+ * Extracted from the WebSocket URL and query parameters
+ */
+type WebSocketConnectionRequest = {
+  /** Base URL prefix for WebSocket connections */
+  baseUrl: string;
+  /** Full pathname from the URL */
+  pathname: string;
+  /** Parsed route segments after baseUrl/ws/ */
+  routeSegments: string[];
+  /** Whether this is an upload route */
+  isUploadRoute: boolean;
+  /** Whether this is a flow route */
+  isFlowRoute: boolean;
+  /** Job ID (for flows) */
+  jobId?: string;
+  /** Upload ID (for uploads) */
+  uploadId?: string;
+  /** Event ID (jobId or uploadId) */
+  eventId?: string;
+  /** WebSocket connection instance */
+  connection: WebSocketConnection;
+};
+//#endregion
+//#region src/core/websocket-handlers/websocket-handlers.d.ts
+/**
+ * Handles WebSocket connection opening
+ * Subscribes to the appropriate events based on the connection request
+ */
+declare const handleWebSocketOpen: (request: WebSocketConnectionRequest, uploadServer: UploadServerShape, flowServer: FlowServerShape) => Effect.Effect<void, never, unknown>;
+/**
+ * Handles incoming WebSocket messages
+ * Currently supports ping/pong for connection keep-alive
+ */
+declare const handleWebSocketMessage: (message: string, connection: WebSocketConnection) => Effect.Effect<void, never, never>;
+/**
+ * Handles WebSocket connection closing
+ * Unsubscribes from all events and cleans up resources
+ */
+declare const handleWebSocketClose: (request: WebSocketConnectionRequest, uploadServer: UploadServerShape, flowServer: FlowServerShape) => Effect.Effect<void, never, unknown>;
+/**
+ * Handles WebSocket errors
+ */
+declare const handleWebSocketError: (error: unknown, eventId?: string) => Effect.Effect<void, never, never>;
+//#endregion
 //#region src/error-types.d.ts
 /**
  * Base adapter error class for HTTP adapters.
@@ -237,7 +960,7 @@ declare const createErrorResponseBody: (error: AdapterError) => {
  * }
  * ```
  */
-declare const createUploadistaErrorResponseBody: (error: UploadistaError) => {
+declare const createUploadistaErrorResponseBody: (error: UploadistaError$1) => {
   error: string;
   code: string;
   timestamp: string;
@@ -510,7 +1233,7 @@ declare const createUploadServerLayer: ({
   dataStore,
   bufferedDataStore,
   generateId
-}: UploadServerLayerConfig) => Layer.Layer<UploadServer$1, never, never>;
+}: UploadServerLayerConfig) => Layer.Layer<unknown, unknown, any>;
 /**
  * Creates the flow server layer with all dependencies composed.
  * This layer handles file processing workflows with multi-stage pipelines.
@@ -545,12 +1268,12 @@ declare const createFlowServerLayer: ({
   eventEmitter,
   flowProvider,
   uploadServer
-}: FlowServerLayerConfig) => Layer.Layer<_uploadista_core0.FlowServer, never, never>;
+}: FlowServerLayerConfig) => Layer.Layer<unknown, unknown, any>;
 //#endregion
 //#region src/plugins-typing.d.ts
 type LayerSuccessUnion<Layers extends readonly Layer.Layer<any, never, never>[]> = Layers[number] extends Layer.Layer<infer Success, never, never> ? Success : never;
 type FlowSuccess<TFlows extends (flowId: string, clientId: string | null) => Effect.Effect<unknown, unknown, unknown>> = ReturnType<TFlows> extends Effect.Effect<infer Success, unknown, unknown> ? Success : never;
-type FlowRequirementsOf<TFlows extends (flowId: string, clientId: string | null) => Effect.Effect<unknown, unknown, unknown>> = FlowSuccess<TFlows> extends Flow<z.ZodSchema<unknown>, z.ZodSchema<unknown>, infer R> ? Exclude<R, UploadServer> : never;
+type FlowRequirementsOf<TFlows extends (flowId: string, clientId: string | null) => Effect.Effect<unknown, unknown, unknown>> = FlowSuccess<TFlows> extends Flow<z$1.ZodSchema<unknown>, z$1.ZodSchema<unknown>, infer R> ? Exclude<R, UploadServer> : never;
 type RequiredPluginsOf<TFlows extends (flowId: string, clientId: string | null) => Effect.Effect<unknown, unknown, unknown>> = Exclude<FlowRequirementsOf<TFlows>, UploadServer>;
 type PluginAssertion<TFlows extends (flowId: string, clientId: string | null) => Effect.Effect<unknown, unknown, unknown>, TPlugins extends readonly Layer.Layer<any, never, never>[]> = Exclude<RequiredPluginsOf<TFlows>, LayerSuccessUnion<TPlugins>> extends never ? unknown : {
   __missingPlugins: Exclude<RequiredPluginsOf<TFlows>, LayerSuccessUnion<TPlugins>>;
@@ -616,5 +1339,5 @@ declare const AuthContextServiceLive: (authContext: AuthContext | null) => Layer
  */
 declare const NoAuthContextServiceLive: Layer.Layer<AuthContextService>;
 //#endregion
-export { AdapterError, AuthCacheConfig, AuthCacheService, AuthCacheServiceLive, AuthContext, AuthContextService, AuthContextServiceLive, AuthCredentialsResponse, AuthResult, BadRequestError, FlowRequirementsOf, FlowServerLayerConfig, FlowSuccess, LayerSuccessUnion, NoAuthCacheServiceLive, NoAuthContextServiceLive, NotFoundError, PluginAssertion, RequiredPluginsOf, UploadServerLayerConfig, ValidationError, createErrorResponseBody, createFlowServerLayer, createGenericErrorResponseBody, createUploadServerLayer, createUploadistaErrorResponseBody, extractFlowAndStorageId, extractJobAndNodeId, extractJobIdFromStatus, getAuthCredentials, getLastSegment, getRouteSegments, handleFlowError, hasBasePath, parseUrlSegments };
+export { AdapterError, AuthCacheConfig, AuthCacheService, AuthCacheServiceLive, AuthContext, AuthContextService, AuthContextServiceLive, AuthCredentialsResponse, AuthFailedEvent, AuthResult, BadRequestError, BadRequestRequest, BadRequestResponse, CancelFlowRequest, CancelFlowResponse, ConnectionEvent, CreateUploadRequest, CreateUploadResponse, ErrorEvent, FlowEventMessage, FlowRequirementsOf, FlowServerLayerConfig, FlowSuccess, FlowsFunction, GetCapabilitiesRequest, GetCapabilitiesResponse, GetFlowRequest, GetFlowResponse, GetJobStatusRequest, GetJobStatusResponse, GetUploadRequest, GetUploadResponse, InvalidPathEvent, LayerSuccessUnion, MethodNotAllowedRequest, MethodNotAllowedResponse, NoAuthCacheServiceLive, NoAuthContextServiceLive, NotFoundError, NotFoundRequest, NotFoundResponse, PauseFlowRequest, PauseFlowResponse, PingEvent, PluginAssertion, RequiredPluginsOf, ResumeFlowRequest, ResumeFlowResponse, RunFlowRequest, RunFlowResponse, ServerAdapter, StandardRequest, StandardResponse, SubscribeFlowEvent, SubscribeUploadEvent, UnsubscribeFlowEvent, UnsubscribeUploadEvent, UnsupportedContentTypeRequest, UnsupportedContentTypeResponse, UploadChunkRequest, UploadChunkResponse, UploadEventMessage, UploadServerLayerConfig, UploadistaRequest, UploadistaResponse, UploadistaRoute, UploadistaRouteType, UploadistaServer, UploadistaServerConfig, UploadistaStandardResponse, ValidationError, type WebSocketConnection, type WebSocketConnectionRequest, WebSocketEvent, WebSocketEventType, WebSocketHandler, WebSocketIncomingEvent, WebSocketOutgoingEvent, createErrorResponseBody, createFlowServerLayer, createGenericErrorResponseBody, createUploadServerLayer, createUploadistaErrorResponseBody, createUploadistaServer, extractFlowAndStorageId, extractJobAndNodeId, extractJobIdFromStatus, getAuthCredentials, getLastSegment, getRouteSegments, handleFlowError, handleWebSocketClose, handleWebSocketError, handleWebSocketMessage, handleWebSocketOpen, hasBasePath, parseUrlSegments };
 //# sourceMappingURL=index.d.cts.map