@uploadista/server 0.0.18-beta.7 → 0.0.18-beta.9

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@uploadista/server",
   "type": "module",
-  "version": "0.0.18-beta.7",
+  "version": "0.0.18-beta.9",
   "description": "Core Server package for Uploadista",
   "license": "MIT",
   "author": "Uploadista",
@@ -20,23 +20,23 @@
     }
   },
   "dependencies": {
-    "@uploadista/core": "0.0.18-beta.7",
-    "@uploadista/observability": "0.0.18-beta.7",
-    "@uploadista/event-emitter-websocket": "0.0.18-beta.7",
-    "@uploadista/event-broadcaster-memory": "0.0.18-beta.7"
+    "@uploadista/core": "0.0.18-beta.9",
+    "@uploadista/observability": "0.0.18-beta.9",
+    "@uploadista/event-emitter-websocket": "0.0.18-beta.9",
+    "@uploadista/event-broadcaster-memory": "0.0.18-beta.9"
   },
   "devDependencies": {
-    "@cloudflare/workers-types": "4.20251126.0",
+    "@cloudflare/workers-types": "4.20251202.0",
     "@effect/vitest": "0.27.0",
     "@types/express": "^5.0.0",
     "@types/node": "24.10.1",
-    "effect": "3.19.6",
+    "effect": "3.19.8",
     "tsd": "0.33.0",
-    "tsdown": "0.16.7",
+    "tsdown": "0.16.8",
     "typescript": "5.9.3",
     "vitest": "4.0.14",
     "zod": "4.1.13",
-    "@uploadista/typescript-config": "0.0.18-beta.7"
+    "@uploadista/typescript-config": "0.0.18-beta.9"
   },
   "peerDependencies": {
     "effect": "^3.0.0",

package/src/core/http-handlers/dlq-http-handlers.ts

@@ -1,5 +1,7 @@
 import { DeadLetterQueueService } from "@uploadista/core/flow";
 import { Effect } from "effect";
+import { PERMISSIONS } from "../../permissions/types";
+import { AuthContextService } from "../../service";
 import type {
   DlqCleanupRequest,
   DlqCleanupResponse,
@@ -24,6 +26,11 @@ import type {
  */
 export const handleDlqList = (req: DlqListRequest) =>
   Effect.gen(function* () {
+    const authService = yield* AuthContextService;
+
+    // Check permission for reading DLQ
+    yield* authService.requirePermission(PERMISSIONS.ENGINE.DLQ_READ);
+
     const dlq = yield* DeadLetterQueueService;
     const result = yield* dlq.list(req.options);
 
@@ -40,6 +47,11 @@ export const handleDlqList = (req: DlqListRequest) =>
  */
 export const handleDlqGet = (req: DlqGetRequest) =>
   Effect.gen(function* () {
+    const authService = yield* AuthContextService;
+
+    // Check permission for reading DLQ
+    yield* authService.requirePermission(PERMISSIONS.ENGINE.DLQ_READ);
+
     const dlq = yield* DeadLetterQueueService;
     const item = yield* dlq.get(req.itemId);
 
@@ -56,6 +68,11 @@ export const handleDlqGet = (req: DlqGetRequest) =>
  */
 export const handleDlqRetry = (req: DlqRetryRequest) =>
   Effect.gen(function* () {
+    const authService = yield* AuthContextService;
+
+    // Check permission for writing to DLQ
+    yield* authService.requirePermission(PERMISSIONS.ENGINE.DLQ_WRITE);
+
     const dlq = yield* DeadLetterQueueService;
 
     // Mark item as retrying
@@ -79,6 +96,11 @@ export const handleDlqRetry = (req: DlqRetryRequest) =>
  */
 export const handleDlqRetryAll = (req: DlqRetryAllRequest) =>
   Effect.gen(function* () {
+    const authService = yield* AuthContextService;
+
+    // Check permission for writing to DLQ
+    yield* authService.requirePermission(PERMISSIONS.ENGINE.DLQ_WRITE);
+
     const dlq = yield* DeadLetterQueueService;
 
     // List items matching the filter
@@ -117,6 +139,11 @@ export const handleDlqRetryAll = (req: DlqRetryAllRequest) =>
  */
 export const handleDlqDelete = (req: DlqDeleteRequest) =>
   Effect.gen(function* () {
+    const authService = yield* AuthContextService;
+
+    // Check permission for writing to DLQ
+    yield* authService.requirePermission(PERMISSIONS.ENGINE.DLQ_WRITE);
+
     const dlq = yield* DeadLetterQueueService;
     yield* dlq.delete(req.itemId);
 
@@ -133,6 +160,11 @@ export const handleDlqDelete = (req: DlqDeleteRequest) =>
  */
 export const handleDlqResolve = (req: DlqResolveRequest) =>
   Effect.gen(function* () {
+    const authService = yield* AuthContextService;
+
+    // Check permission for writing to DLQ
+    yield* authService.requirePermission(PERMISSIONS.ENGINE.DLQ_WRITE);
+
     const dlq = yield* DeadLetterQueueService;
     const item = yield* dlq.markResolved(req.itemId);
 
@@ -149,6 +181,11 @@ export const handleDlqResolve = (req: DlqResolveRequest) =>
  */
 export const handleDlqCleanup = (req: DlqCleanupRequest) =>
   Effect.gen(function* () {
+    const authService = yield* AuthContextService;
+
+    // Check permission for writing to DLQ
+    yield* authService.requirePermission(PERMISSIONS.ENGINE.DLQ_WRITE);
+
     const dlq = yield* DeadLetterQueueService;
     const result = yield* dlq.cleanup(req.options);
 
@@ -165,6 +202,11 @@ export const handleDlqCleanup = (req: DlqCleanupRequest) =>
  */
 export const handleDlqStats = (_req: DlqStatsRequest) =>
   Effect.gen(function* () {
+    const authService = yield* AuthContextService;
+
+    // Check permission for reading DLQ
+    yield* authService.requirePermission(PERMISSIONS.ENGINE.DLQ_READ);
+
     const dlq = yield* DeadLetterQueueService;
     const stats = yield* dlq.getStats();
 

package/src/core/http-handlers/flow-http-handlers.ts

@@ -1,7 +1,10 @@
 import { FlowServer } from "@uploadista/core/flow";
 import { Effect } from "effect";
 import { AuthCacheService } from "../../cache";
+import { PERMISSIONS } from "../../permissions/types";
+import { QuotaExceededError } from "../../permissions/errors";
 import { AuthContextService } from "../../service";
+import { UsageHookService } from "../../usage-hooks/service";
 import type {
   CancelFlowRequest,
   CancelFlowResponse,
@@ -20,10 +23,12 @@ import type {
 export const handleGetFlow = ({ flowId }: GetFlowRequest) => {
   return Effect.gen(function* () {
     const flowServer = yield* FlowServer;
-    // Access auth context if available
     const authService = yield* AuthContextService;
     const clientId = yield* authService.getClientId();
 
+    // Check permission for reading flow status
+    yield* authService.requirePermission(PERMISSIONS.FLOW.STATUS);
+
     if (clientId) {
       yield* Effect.logInfo(
         `[Flow] Getting flow data: ${flowId}, client: ${clientId}`,
@@ -46,11 +51,14 @@ export const handleRunFlow = <TRequirements>({
 }: RunFlowRequest) => {
   return Effect.gen(function* () {
     const flowServer = yield* FlowServer;
-    // Access auth context if available
     const authService = yield* AuthContextService;
     const authCache = yield* AuthCacheService;
+    const usageHookService = yield* UsageHookService;
     const clientId = yield* authService.getClientId();
 
+    // Check permission for executing flows
+    yield* authService.requirePermission(PERMISSIONS.FLOW.EXECUTE);
+
     if (clientId) {
       yield* Effect.logInfo(
         `[Flow] Executing flow: ${flowId}, storage: ${storageId}, client: ${clientId}`,
@@ -65,7 +73,28 @@ export const handleRunFlow = <TRequirements>({
       );
     }
 
+    // Execute onFlowStart hook for quota checking
+    if (clientId) {
+      const hookResult = yield* usageHookService.onFlowStart({
+        clientId,
+        operation: "flow",
+        metadata: {
+          flowId,
+        },
+      });
+
+      if (hookResult.action === "abort") {
+        return yield* Effect.fail(
+          new QuotaExceededError(
+            hookResult.reason,
+            hookResult.code ?? "SUBSCRIPTION_REQUIRED",
+          ),
+        );
+      }
+    }
+
     // Run flow returns immediately with jobId
+    const startTime = Date.now();
     yield* Effect.logInfo(`[Flow] Calling flowServer.runFlow...`);
     const result = yield* flowServer
       .runFlow<TRequirements>({
@@ -91,6 +120,10 @@ export const handleRunFlow = <TRequirements>({
 
     yield* Effect.logInfo(`[Flow] Flow started with jobId: ${result.id}`);
 
+    // Note: onFlowComplete hook is called when the flow actually completes,
+    // which happens asynchronously. The hook should be invoked from the
+    // flow execution pipeline, not here where we just start the flow.
+
     return {
       status: 200,
       body: result,
@@ -101,11 +134,13 @@ export const handleRunFlow = <TRequirements>({
 export const handleJobStatus = ({ jobId }: GetJobStatusRequest) => {
   return Effect.gen(function* () {
     const flowServer = yield* FlowServer;
-    // Access auth context if available
     const authService = yield* AuthContextService;
     const authCache = yield* AuthCacheService;
     const clientId = yield* authService.getClientId();
 
+    // Check permission for checking flow status
+    yield* authService.requirePermission(PERMISSIONS.FLOW.STATUS);
+
     if (!jobId) {
       throw new Error("No job id");
     }
@@ -142,10 +177,12 @@ export const handleResumeFlow = <TRequirements>({
 }: ResumeFlowRequest) => {
   return Effect.gen(function* () {
     const flowServer = yield* FlowServer;
-    // Try to get auth from current request or cached auth
     const authService = yield* AuthContextService;
     const authCache = yield* AuthCacheService;
 
+    // Check permission for executing flows (resume is part of execution)
+    yield* authService.requirePermission(PERMISSIONS.FLOW.EXECUTE);
+
     // Try current auth first, fallback to cached auth
     let clientId = yield* authService.getClientId();
     if (!clientId) {
@@ -186,13 +223,16 @@ export const handleResumeFlow = <TRequirements>({
     } as ResumeFlowResponse;
   });
 };
+
 export const handlePauseFlow = ({ jobId }: PauseFlowRequest) => {
   return Effect.gen(function* () {
     const flowServer = yield* FlowServer;
-    // Try to get auth from current request or cached auth
     const authService = yield* AuthContextService;
     const authCache = yield* AuthCacheService;
 
+    // Check permission for cancelling flows (pause is related to cancel)
+    yield* authService.requirePermission(PERMISSIONS.FLOW.CANCEL);
+
     // Try current auth first, fallback to cached auth
     let clientId = yield* authService.getClientId();
     if (!clientId) {
@@ -224,9 +264,12 @@ export const handlePauseFlow = ({ jobId }: PauseFlowRequest) => {
 export const handleCancelFlow = ({ jobId }: CancelFlowRequest) => {
   return Effect.gen(function* () {
     const flowServer = yield* FlowServer;
-    // Try to get auth from current request or cached auth
     const authService = yield* AuthContextService;
     const authCache = yield* AuthCacheService;
+    const usageHookService = yield* UsageHookService;
+
+    // Check permission for cancelling flows
+    yield* authService.requirePermission(PERMISSIONS.FLOW.CANCEL);
 
     if (!jobId) {
       throw new Error("No job id");
@@ -253,6 +296,18 @@ export const handleCancelFlow = ({ jobId }: CancelFlowRequest) => {
       yield* Effect.logInfo(
         `[Flow] Flow cancelled, cleared auth cache: ${jobId}`,
       );
+
+      // Execute onFlowComplete hook for cancelled flow
+      yield* Effect.forkDaemon(
+        usageHookService.onFlowComplete({
+          clientId,
+          operation: "flow",
+          metadata: {
+            jobId,
+            status: "cancelled",
+          },
+        }),
+      );
     }
 
     return {

package/src/core/http-handlers/health-http-handlers.ts

@@ -15,6 +15,8 @@ import {
   type HealthCheckConfig,
 } from "@uploadista/core/types";
 import { Effect } from "effect";
+import { PERMISSIONS } from "../../permissions/types";
+import { AuthContextService } from "../../service";
 import {
   createLivenessResponse,
   performComponentsCheck,
@@ -66,12 +68,19 @@ export const handleHealthLiveness = (
  * Checks all critical dependencies (storage, KV store) and returns:
  * - 200 OK if all dependencies are healthy
  * - 503 Service Unavailable if any critical dependency is unavailable
+ *
+ * Requires `engine:readiness` permission.
  */
 export const handleHealthReadiness = (
   req: HealthReadyRequest,
   config?: HealthCheckConfig,
 ) =>
   Effect.gen(function* () {
+    const authService = yield* AuthContextService;
+
+    // Check permission for readiness endpoint
+    yield* authService.requirePermission(PERMISSIONS.ENGINE.READINESS);
+
     const response = yield* performReadinessCheck(config);
     const format = getHealthResponseFormat(req.acceptHeader);
 
@@ -106,12 +115,19 @@ export const handleHealthReadiness = (
  * - Dead letter queue (if enabled)
  *
  * Always returns 200 OK for debugging purposes (even if components are degraded).
+ *
+ * Requires `engine:readiness` permission.
  */
 export const handleHealthComponents = (
   req: HealthComponentsRequest,
   config?: HealthCheckConfig,
 ) =>
   Effect.gen(function* () {
+    const authService = yield* AuthContextService;
+
+    // Check permission for components endpoint
+    yield* authService.requirePermission(PERMISSIONS.ENGINE.READINESS);
+
     const response = yield* performComponentsCheck(config);
     const format = getHealthResponseFormat(req.acceptHeader);
 

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

@@ -5,7 +5,10 @@ import { MetricsService } from "@uploadista/observability";
 import { Effect } from "effect";
 import { AuthCacheService } from "../../cache";
 import { ValidationError } from "../../error-types";
+import { PERMISSIONS } from "../../permissions/types";
+import { QuotaExceededError } from "../../permissions/errors";
 import { AuthContextService } from "../../service";
+import { UsageHookService } from "../../usage-hooks/service";
 import type {
   CreateUploadRequest,
   CreateUploadResponse,
@@ -20,11 +23,14 @@ import type {
 export const handleCreateUpload = (req: CreateUploadRequest) =>
   Effect.gen(function* () {
     const server = yield* UploadServer;
-    // Access auth context if available
     const authService = yield* AuthContextService;
     const authCache = yield* AuthCacheService;
+    const usageHookService = yield* UsageHookService;
     const clientId = yield* authService.getClientId();
 
+    // Check permission for creating uploads
+    yield* authService.requirePermission(PERMISSIONS.UPLOAD.CREATE);
+
     if (clientId) {
       yield* Effect.logInfo(`[Upload] Creating upload for client: ${clientId}`);
     }
@@ -51,6 +57,28 @@ export const handleCreateUpload = (req: CreateUploadRequest) =>
       );
     }
 
+    // Execute onUploadStart hook for quota checking
+    if (clientId) {
+      const hookResult = yield* usageHookService.onUploadStart({
+        clientId,
+        operation: "upload",
+        metadata: {
+          fileSize: parsedInputFile.data.size,
+          mimeType: parsedInputFile.data.type,
+          fileName: parsedInputFile.data.fileName,
+        },
+      });
+
+      if (hookResult.action === "abort") {
+        return yield* Effect.fail(
+          new QuotaExceededError(
+            hookResult.reason,
+            hookResult.code ?? "QUOTA_EXCEEDED",
+          ),
+        );
+      }
+    }
+
     const fileCreated = yield* server.createUpload(
       parsedInputFile.data,
       clientId,
@@ -80,6 +108,9 @@ export const handleGetCapabilities = ({ storageId }: GetCapabilitiesRequest) =>
     const authService = yield* AuthContextService;
     const clientId = yield* authService.getClientId();
 
+    // Check permission for reading upload capabilities
+    yield* authService.requirePermission(PERMISSIONS.UPLOAD.READ);
+
     const capabilities = yield* server.getCapabilities(storageId, clientId);
 
     return {
@@ -95,6 +126,11 @@ export const handleGetCapabilities = ({ storageId }: GetCapabilitiesRequest) =>
 export const handleGetUpload = ({ uploadId }: GetUploadRequest) =>
   Effect.gen(function* () {
     const server = yield* UploadServer;
+    const authService = yield* AuthContextService;
+
+    // Check permission for reading upload status
+    yield* authService.requirePermission(PERMISSIONS.UPLOAD.READ);
+
     const fileResult = yield* server.getUpload(uploadId);
 
     return {
@@ -106,13 +142,16 @@ export const handleGetUpload = ({ uploadId }: GetUploadRequest) =>
 export const handleUploadChunk = (req: UploadChunkRequest) =>
   Effect.gen(function* () {
     const server = yield* UploadServer;
-    // Try to get auth from current request or cached auth
     const authService = yield* AuthContextService;
     const authCache = yield* AuthCacheService;
     const metricsService = yield* MetricsService;
+    const usageHookService = yield* UsageHookService;
 
     const { uploadId, data } = req;
 
+    // Check permission for creating uploads (chunks are part of creation)
+    yield* authService.requirePermission(PERMISSIONS.UPLOAD.CREATE);
+
     // Try current auth first, fallback to cached auth
     let clientId = yield* authService.getClientId();
     let authMetadata = yield* authService.getMetadata();
@@ -128,6 +167,7 @@ export const handleUploadChunk = (req: UploadChunkRequest) =>
       );
     }
 
+    const startTime = Date.now();
     const fileResult = yield* server.uploadChunk(uploadId, clientId, data);
 
     // Clear cache and record metrics if upload is complete
@@ -140,7 +180,6 @@ export const handleUploadChunk = (req: UploadChunkRequest) =>
       }
 
       // Record upload metrics if we have organization ID
-
       if (clientId && fileResult.size) {
         yield* Effect.logInfo(
           `[Upload] Recording metrics for org: ${clientId}, size: ${fileResult.size}`,
@@ -148,6 +187,20 @@ export const handleUploadChunk = (req: UploadChunkRequest) =>
         yield* Effect.forkDaemon(
           metricsService.recordUpload(clientId, fileResult.size, authMetadata),
         );
+
+        // Execute onUploadComplete hook for usage tracking
+        const duration = Date.now() - startTime;
+        yield* Effect.forkDaemon(
+          usageHookService.onUploadComplete({
+            clientId,
+            operation: "upload",
+            metadata: {
+              uploadId,
+              fileSize: fileResult.size,
+              duration,
+            },
+          }),
+        );
       } else {
         yield* Effect.logWarning(
           `[Upload] Cannot record metrics - missing organizationId or size`,

package/src/core/server.ts

@@ -24,6 +24,7 @@ import { handleFlowError } from "../http-utils";
 import { createFlowServerLayer, createUploadServerLayer } from "../layer-utils";
 import { AuthContextServiceLive } from "../service";
 import type { AuthContext } from "../types";
+import { UsageHookServiceLive } from "../usage-hooks/service";
 import { handleUploadistaRequest } from "./http-handlers/http-handlers";
 import type { ExtractFlowPluginRequirements } from "./plugin-types";
 import type { NotFoundResponse } from "./routes";
@@ -201,6 +202,7 @@ export const createUploadistaServer = async <
   circuitBreaker = true,
   deadLetterQueue = false,
   healthCheck,
+  usageHooks,
 }: UploadistaServerConfig<
   TContext,
   TResponse,
@@ -285,17 +287,22 @@ export const createUploadistaServer = async <
       )
     : null;
 
+  // Create usage hook layer (defaults to no-op if not configured)
+  const usageHookLayer = UsageHookServiceLive(usageHooks);
+
   /**
    * Merge all server layers including plugins.
    *
    * This combines the core server infrastructure (upload server, flow server,
-   * metrics, auth cache, circuit breaker, dead letter queue) with user-provided plugin layers.
+   * metrics, auth cache, circuit breaker, dead letter queue, usage hooks)
+   * with user-provided plugin layers.
    */
   const serverLayerRaw = Layer.mergeAll(
     uploadServerLayer,
     flowServerLayer,
     effectiveMetricsLayer,
     authCacheLayer,
+    usageHookLayer,
     ...plugins,
     ...(circuitBreakerStoreLayer ? [circuitBreakerStoreLayer] : []),
     ...(dlqLayer ? [dlqLayer] : []),
@@ -497,12 +504,13 @@ export const createUploadistaServer = async <
         }
       }
 
-      // Combine auth context, auth cache, metrics layers, plugins, circuit breaker, DLQ, and waitUntil
+      // Combine auth context, auth cache, metrics layers, usage hooks, plugins, circuit breaker, DLQ, and waitUntil
       // This ensures that flow nodes have access to all required services
       const baseRequestContextLayer = Layer.mergeAll(
         authContextLayer,
         authCacheLayer,
         effectiveMetricsLayer,
+        usageHookLayer,
         ...plugins,
         ...waitUntilLayers,
       );

package/src/core/types.ts

@@ -15,6 +15,7 @@ import type { Effect, Layer } from "effect";
 import type { z } from "zod";
 import type { ServerAdapter } from "../adapter";
 import type { AuthCacheConfig } from "../cache";
+import type { UsageHookConfig } from "../usage-hooks/types";
 
 /**
  * Function type for retrieving flows based on flow ID and client ID.
@@ -374,6 +375,40 @@ export interface UploadistaServerConfig<
    * ```
    */
   healthCheck?: HealthCheckConfig;
+
+  /**
+   * Optional: Usage hooks for tracking and billing integration.
+   *
+   * Usage hooks allow you to intercept upload and flow operations for:
+   * - Quota checking (e.g., verify user has subscription)
+   * - Usage tracking (e.g., count uploads, track bandwidth)
+   * - Billing integration (e.g., report usage to Stripe/Polar)
+   *
+   * Hooks follow a "fail-open" design - if a hook times out or errors,
+   * the operation proceeds (unless the hook explicitly aborts).
+   *
+   * @example
+   * ```typescript
+   * usageHooks: {
+   *   hooks: {
+   *     onUploadStart: (ctx) => Effect.gen(function* () {
+   *       // Check quota before upload starts
+   *       const quota = yield* checkUserQuota(ctx.clientId);
+   *       if (quota.exceeded) {
+   *         return { action: "abort", reason: "Storage quota exceeded" };
+   *       }
+   *       return { action: "continue" };
+   *     }),
+   *     onUploadComplete: (ctx) => Effect.gen(function* () {
+   *       // Track usage after upload completes
+   *       yield* reportUsage(ctx.clientId, ctx.metadata.fileSize);
+   *     }),
+   *   },
+   *   timeout: 5000, // 5 second timeout for hooks
+   * }
+   * ```
+   */
+  usageHooks?: UsageHookConfig;
 }
 
 /**

package/src/index.ts

@@ -5,6 +5,8 @@ export * from "./core";
 export * from "./error-types";
 export * from "./http-utils";
 export * from "./layer-utils";
+export * from "./permissions";
 export * from "./plugins-typing";
 export * from "./service";
 export * from "./types";
+export * from "./usage-hooks";