@uploadista/server 0.0.7 → 0.0.9

package/src/core/websocket-handlers/upload-websocket-handlers.ts

@@ -0,0 +1,47 @@
+import type { UploadServerShape } from "@uploadista/core/upload";
+import { Effect } from "effect";
+import type { WebSocketConnection } from "../websocket-routes";
+
+/**
+ * Handles subscription to upload events
+ * Subscribes the WebSocket connection to receive real-time upload progress events
+ */
+export const handleSubscribeToUploadEvents = (
+  uploadServer: UploadServerShape,
+  uploadId: string | undefined,
+  connection: WebSocketConnection,
+) => {
+  return Effect.gen(function* () {
+    if (!uploadId) {
+      yield* Effect.sync(() => {
+        connection.send(
+          JSON.stringify({
+            type: "error",
+            message: "Upload ID is required for upload event subscription",
+            code: "MISSING_UPLOAD_ID",
+          }),
+        );
+      });
+      return;
+    }
+
+    yield* uploadServer.subscribeToUploadEvents(uploadId, connection);
+  });
+};
+
+/**
+ * Handles unsubscription from upload events
+ * Removes the WebSocket connection from receiving upload events
+ */
+export const handleUnsubscribeFromUploadEvents = (
+  uploadServer: UploadServerShape,
+  uploadId: string | undefined,
+) => {
+  return Effect.gen(function* () {
+    if (!uploadId) {
+      return;
+    }
+
+    yield* uploadServer.unsubscribeFromUploadEvents(uploadId);
+  });
+};

package/src/core/websocket-handlers/websocket-handlers.ts

@@ -0,0 +1,151 @@
+import { UploadistaError } from "@uploadista/core/errors";
+import type { FlowServerShape } from "@uploadista/core/flow";
+import type { UploadServerShape } from "@uploadista/core/upload";
+import { Effect } from "effect";
+import type {
+  WebSocketConnection,
+  WebSocketConnectionRequest,
+} from "../websocket-routes";
+import {
+  handleSubscribeToFlowEvents,
+  handleUnsubscribeFromFlowEvents,
+} from "./flow-websocket-handlers";
+import {
+  handleSubscribeToUploadEvents,
+  handleUnsubscribeFromUploadEvents,
+} from "./upload-websocket-handlers";
+
+export type {
+  WebSocketConnection,
+  WebSocketConnectionRequest,
+} from "../websocket-routes";
+
+/**
+ * Handles WebSocket connection opening
+ * Subscribes to the appropriate events based on the connection request
+ */
+export const handleWebSocketOpen = (
+  request: WebSocketConnectionRequest,
+  uploadServer: UploadServerShape,
+  flowServer: FlowServerShape,
+) => {
+  const { connection, isFlowRoute, isUploadRoute, jobId, uploadId, eventId } =
+    request;
+
+  return Effect.gen(function* () {
+    // Subscribe to flow events if this is a flow route
+    if (isFlowRoute) {
+      yield* handleSubscribeToFlowEvents(flowServer, jobId, connection);
+    }
+
+    // Subscribe to upload events if this is an upload route
+    if (isUploadRoute) {
+      yield* handleSubscribeToUploadEvents(uploadServer, uploadId, connection);
+    }
+
+    // Send connection confirmation
+    connection.send(
+      JSON.stringify({
+        type: "connection",
+        message: "Uploadista WebSocket connected",
+        id: eventId,
+        jobId,
+        uploadId,
+        timestamp: new Date().toISOString(),
+      }),
+    );
+  }).pipe(
+    Effect.catchAll((error) =>
+      Effect.sync(() => {
+        console.error("Error subscribing to events:", error);
+        const errorMessage =
+          error instanceof UploadistaError
+            ? error.body
+            : "Failed to subscribe to events";
+        connection.send(
+          JSON.stringify({
+            type: "error",
+            message: errorMessage,
+            code:
+              error instanceof UploadistaError
+                ? error.code
+                : "SUBSCRIPTION_ERROR",
+          }),
+        );
+      }),
+    ),
+  );
+};
+
+/**
+ * Handles incoming WebSocket messages
+ * Currently supports ping/pong for connection keep-alive
+ */
+export const handleWebSocketMessage = (
+  message: string,
+  connection: WebSocketConnection,
+) => {
+  return Effect.sync(() => {
+    try {
+      const parsed = JSON.parse(message);
+      if (parsed.type === "ping") {
+        connection.send(
+          JSON.stringify({
+            type: "pong",
+            timestamp: new Date().toISOString(),
+          }),
+        );
+      }
+    } catch (error) {
+      console.error("Error handling WebSocket message:", error);
+      connection.send(
+        JSON.stringify({
+          type: "error",
+          message: "Invalid message format",
+        }),
+      );
+    }
+  });
+};
+
+/**
+ * Handles WebSocket connection closing
+ * Unsubscribes from all events and cleans up resources
+ */
+export const handleWebSocketClose = (
+  request: WebSocketConnectionRequest,
+  uploadServer: UploadServerShape,
+  flowServer: FlowServerShape,
+) => {
+  const { isFlowRoute, isUploadRoute, jobId, uploadId } = request;
+
+  return Effect.gen(function* () {
+    // Unsubscribe from flow events if this was a flow route
+    if (isFlowRoute) {
+      yield* handleUnsubscribeFromFlowEvents(flowServer, jobId);
+    }
+
+    // Unsubscribe from upload events if this was an upload route
+    if (isUploadRoute) {
+      yield* handleUnsubscribeFromUploadEvents(uploadServer, uploadId);
+    }
+  }).pipe(
+    Effect.catchAll((error) =>
+      Effect.sync(() => {
+        console.error(
+          "Error unsubscribing from events:",
+          error instanceof UploadistaError ? error.body : error,
+        );
+      }),
+    ),
+  );
+};
+
+/**
+ * Handles WebSocket errors
+ */
+export const handleWebSocketError = (error: unknown, eventId?: string) => {
+  return Effect.sync(() => {
+    console.error(`WebSocket error for event ${eventId}:`, error);
+  });
+};

package/src/core/websocket-routes.ts

@@ -0,0 +1,136 @@
+import type { UploadEvent } from "@uploadista/core";
+
+/**
+ * Framework-agnostic WebSocket connection interface
+ * Adapters should wrap their native WebSocket implementations to match this interface
+ */
+export type WebSocketConnection = {
+  id: string;
+  send: (data: string) => void;
+  close: (code?: number, reason?: string) => void;
+  readyState: number;
+};
+
+/**
+ * WebSocket event types for real-time communication
+ */
+export 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
+ */
+export type WebSocketEvent<T extends WebSocketEventType> = {
+  type: T;
+};
+
+/**
+ * Incoming WebSocket messages (client -> server)
+ */
+
+export type SubscribeUploadEvent = WebSocketEvent<"subscribe-upload"> & {
+  uploadId: string;
+};
+
+export type SubscribeFlowEvent = WebSocketEvent<"subscribe-flow"> & {
+  jobId: string;
+};
+
+export type UnsubscribeUploadEvent = WebSocketEvent<"unsubscribe-upload"> & {
+  uploadId: string;
+};
+
+export type UnsubscribeFlowEvent = WebSocketEvent<"unsubscribe-flow"> & {
+  jobId: string;
+};
+
+export type PingEvent = WebSocketEvent<"ping">;
+
+export type WebSocketIncomingEvent =
+  | SubscribeUploadEvent
+  | SubscribeFlowEvent
+  | UnsubscribeUploadEvent
+  | UnsubscribeFlowEvent
+  | PingEvent;
+
+/**
+ * Outgoing WebSocket messages (server -> client)
+ */
+
+export type ConnectionEvent = WebSocketEvent<"connection"> & {
+  message: string;
+  id?: string;
+  jobId?: string;
+  uploadId?: string;
+  timestamp: string;
+};
+
+export type UploadEventMessage = WebSocketEvent<"upload-event"> & {
+  uploadId: string;
+  event: UploadEvent;
+  timestamp: string;
+};
+
+export type FlowEventMessage = WebSocketEvent<"flow-event"> & {
+  jobId: string;
+  event: unknown;
+  timestamp: string;
+};
+
+export type ErrorEvent = WebSocketEvent<"error"> & {
+  message: string;
+  code?: string;
+};
+
+export type InvalidPathEvent = WebSocketEvent<"invalid-path"> & {
+  message: string;
+  expectedPrefix: string;
+};
+
+export type AuthFailedEvent = WebSocketEvent<"auth-failed"> & {
+  message: string;
+  authMethod: "token" | "cookies";
+};
+
+export type WebSocketOutgoingEvent =
+  | ConnectionEvent
+  | UploadEventMessage
+  | FlowEventMessage
+  | ErrorEvent
+  | InvalidPathEvent
+  | AuthFailedEvent;
+
+/**
+ * WebSocket connection request with routing information
+ * Extracted from the WebSocket URL and query parameters
+ */
+export 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;
+};

package/src/index.ts

@@ -1,5 +1,7 @@
+export * from "./adapter";
 export * from "./auth";
 export * from "./cache";
+export * from "./core";
 export * from "./error-types";
 export * from "./http-utils";
 export * from "./layer-utils";

package/dist/auth/index.d.ts

@@ -1,2 +0,0 @@
-import { n as getAuthCredentials, t as AuthCredentialsResponse } from "../index-CvDNB1lJ.js";
-export { AuthCredentialsResponse, getAuthCredentials };

package/dist/auth/index.js

@@ -1 +0,0 @@
-import{t as e}from"../auth-C77S4vQd.js";export{e as getAuthCredentials};

package/dist/auth-C77S4vQd.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"auth-C77S4vQd.js","names":[],"sources":["../src/auth/get-auth-credentials.ts"],"sourcesContent":["/**\n * Response type for authentication credential requests.\n * - `isValid: true` with token and expiration\n * - `isValid: false` with error message\n *\n * @example\n * ```typescript\n * const response = await getAuthCredentials({\n *   uploadistaClientId: \"my-client\",\n *   uploadistaApiKey: \"sk_...\"\n * });\n * if (response.isValid) {\n *   console.log(`Token: ${response.data.token}`);\n * } else {\n *   console.error(`Auth failed: ${response.error}`);\n * }\n * ```\n */\nexport type AuthCredentialsResponse =\n  | {\n      isValid: true;\n      data: { token: string; expiresIn: number };\n    }\n  | {\n      isValid: false;\n      error: string;\n    };\n\n/**\n * Retrieve JWT authentication credentials from the Uploadista server.\n * This function exchanges client credentials (ID + API key) for a signed JWT token.\n *\n * The JWT token is then used in subsequent API requests via the Authorization header.\n * Tokens are time-limited and should be refreshed before expiration.\n *\n * @param params - Credential exchange parameters\n * @param params.uploadistaClientId - Your Uploadista client ID\n * @param params.uploadistaApiKey - Your Uploadista API key (secret)\n * @param params.baseUrl - Uploadista server base URL (default: https://api.uploadista.com)\n * @returns Promise resolving to authentication response with token or error\n *\n * @example\n * ```typescript\n * import { getAuthCredentials } from \"@uploadista/server\";\n *\n * // Get JWT token for API requests\n * const response = await getAuthCredentials({\n *   uploadistaClientId: process.env.UPLOADISTA_CLIENT_ID,\n *   uploadistaApiKey: process.env.UPLOADISTA_API_KEY,\n * });\n *\n * if (response.isValid) {\n *   // Use token in API requests\n *   const headers = {\n *     Authorization: `Bearer ${response.data.token}`,\n *   };\n *\n *   // Token expires in response.data.expiresIn seconds\n *   setTimeout(\n *     () => {\n *       // Refresh token before expiration\n *     },\n *     response.data.expiresIn * 1000,\n *   );\n * }\n * ```\n */\nexport const getAuthCredentials = async ({\n  uploadistaClientId,\n  uploadistaApiKey,\n  baseUrl = \"https://api.uploadista.com\",\n}: {\n  uploadistaClientId: string;\n  uploadistaApiKey: string;\n  baseUrl?: string;\n}): Promise<AuthCredentialsResponse> => {\n  const response = await fetch(\n    `${baseUrl}/uploadista/auth/jwt?apiKey=${uploadistaApiKey}&clientId=${uploadistaClientId}`,\n    {\n      method: \"GET\",\n      headers: {\n        \"Content-Type\": \"application/json\",\n      },\n    },\n  );\n\n  if (response.ok !== true) {\n    return { isValid: false, error: \"Failed to get auth credentials\" };\n  }\n\n  const data = (await response.json()) as { token: string; expiresIn: number };\n\n  return {\n    isValid: true,\n    data,\n  };\n};\n"],"mappings":"AAmEA,MAAa,EAAqB,MAAO,CACvC,qBACA,mBACA,UAAU,gCAK4B,CACtC,IAAM,EAAW,MAAM,MACrB,GAAG,EAAQ,8BAA8B,EAAiB,YAAY,IACtE,CACE,OAAQ,MACR,QAAS,CACP,eAAgB,mBACjB,CACF,CACF,CAQD,OANI,EAAS,KAAO,GAMb,CACL,QAAS,GACT,KAJY,MAAM,EAAS,MAAM,CAKlC,CARQ,CAAE,QAAS,GAAO,MAAO,iCAAkC"}

package/dist/index-CvDNB1lJ.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index-CvDNB1lJ.d.ts","names":[],"sources":["../src/auth/get-auth-credentials.ts"],"sourcesContent":[],"mappings":";;AAkBA;AAiDA;;;;;;;;;;;;;;;;KAjDY,uBAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAiDC;;;;;;;;MAQT,QAAQ"}