@uploadista/server 0.0.10 → 0.0.12

package/dist/index.d.mts

@@ -1,13 +1,15 @@
 import { n as getAuthCredentials, t as AuthCredentialsResponse } from "./index--Lny6VJP.mjs";
 import { Context, Effect, Layer } from "effect";
-import { Flow, FlowProvider, FlowServerShape } from "@uploadista/core/flow";
+import { CredentialProviderLayer, ExtractLayerServices, Flow, FlowProvider, FlowServerShape, ImageAiPluginLayer, ImagePluginLayer, ZipPluginLayer } from "@uploadista/core/flow";
 import { BaseEventEmitterService, BaseKvStoreService, DataStoreConfig, EventBroadcasterService, UploadFileDataStore, UploadFileDataStores, UploadFileKVStore } from "@uploadista/core/types";
 import { GenerateId } from "@uploadista/core/utils";
+import { MetricsService } from "@uploadista/observability";
 import { UploadServer, UploadServerShape } from "@uploadista/core/upload";
 import { UploadistaError } from "@uploadista/core/errors";
 import * as _uploadista_core0 from "@uploadista/core";
-import { DataStoreCapabilities, Flow as Flow$1, FlowData, FlowJob, FlowServer as FlowServer$1, UploadEvent, UploadFile, UploadServer as UploadServer$1, UploadistaError as UploadistaError$1 } from "@uploadista/core";
+import { DataStoreCapabilities, Flow as Flow$1, FlowData, FlowJob, FlowServer as FlowServer$1, PluginLayer, UploadEvent, UploadFile, UploadServer as UploadServer$1, UploadistaError as UploadistaError$1 } from "@uploadista/core";
 import z$1, { z } from "zod";
+import { ExtractLayerServices as ExtractLayerServices$1 } from "@uploadista/core/flow/types";
 
 //#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";
@@ -419,6 +421,161 @@ declare const AuthCacheServiceLive: (config?: AuthCacheConfig) => Layer.Layer<Au
  */
 declare const NoAuthCacheServiceLive: Layer.Layer<AuthCacheService>;
 //#endregion
+//#region src/core/plugin-types.d.ts
+/**
+ * Utility type to extract all services from a tuple of layers.
+ * Given [Layer<A>, Layer<B>], extracts A | B.
+ *
+ * This is a wrapper around the shared ExtractLayerServices utility from @uploadista/core.
+ *
+ * @deprecated Use ExtractLayerServices from @uploadista/core/flow/types instead.
+ *   This will be removed in a future version.
+ */
+type ExtractServicesFromLayers<T extends readonly Layer.Layer<any, any, any>[]> = ExtractLayerServices<T>;
+/**
+ * Known plugin layer types for better type inference.
+ * This union helps TypeScript understand which plugins are available.
+ */
+type KnownPluginLayer = ImagePluginLayer | ImageAiPluginLayer | CredentialProviderLayer | ZipPluginLayer;
+/**
+ * Type-safe plugin tuple that only accepts known plugin layers.
+ * This provides autocomplete and validation for plugin arrays.
+ */
+type PluginTuple = readonly KnownPluginLayer[];
+/**
+ * Extracts the union of all plugin services from a plugin tuple.
+ *
+ * Uses the shared ExtractLayerServices utility from @uploadista/core for consistency.
+ *
+ * @example
+ * ```typescript
+ * type Plugins = [ImagePluginLayer, ZipPluginLayer];
+ * type Services = PluginServices<Plugins>;
+ * // Services = ImagePlugin | ZipPlugin
+ * ```
+ */
+type PluginServices<TPlugins extends PluginTuple> = ExtractLayerServices<TPlugins>;
+/**
+ * Type-safe flow function that declares its plugin requirements.
+ *
+ * @template TRequirements - Union of plugin services this flow needs
+ *
+ * @example
+ * ```typescript
+ * // Flow that requires ImagePlugin
+ * const myFlow: TypeSafeFlowFunction<ImagePlugin> = (flowId, clientId) =>
+ *   Effect.gen(function* () {
+ *     const imageService = yield* ImagePlugin;
+ *     // ...
+ *   });
+ * ```
+ */
+type TypeSafeFlowFunction<TRequirements$1 = never> = (flowId: string, clientId: string | null) => Effect.Effect<Flow<z.ZodSchema<unknown>, z.ZodSchema<unknown>, TRequirements$1>, UploadistaError$1, TRequirements$1>;
+/**
+ * Validates that plugins satisfy flow requirements.
+ *
+ * This type creates a compile-time error if required plugins are missing.
+ * When validation fails, it returns an error object with detailed information
+ * including a human-readable message.
+ *
+ * @template TPlugins - The plugin tuple provided
+ * @template TRequirements - The services required by flows
+ *
+ * @example
+ * ```typescript
+ * // ✅ Valid: ImagePlugin is provided and required
+ * type Valid = ValidatePlugins<[ImagePluginLayer], ImagePlugin>;
+ * // Result: true
+ *
+ * // ❌ Error: ImagePlugin required but not provided
+ * type Invalid = ValidatePlugins<[], ImagePlugin>;
+ * // Result: {
+ * //   __error: "MISSING_REQUIRED_PLUGINS";
+ * //   __message: "Missing required plugins: ...";
+ * //   __required: ImagePlugin;
+ * //   __provided: never;
+ * //   __missing: ImagePlugin;
+ * // }
+ * ```
+ */
+type ValidatePlugins<TPlugins extends PluginTuple, TRequirements$1> = TRequirements$1 extends never ? true : TRequirements$1 extends PluginServices<TPlugins> ? true : {
+  readonly __error: "MISSING_REQUIRED_PLUGINS";
+  readonly __message: "Missing required plugins. Check __missing field for details.";
+  readonly __required: TRequirements$1;
+  readonly __provided: PluginServices<TPlugins>;
+  readonly __missing: Exclude<TRequirements$1, PluginServices<TPlugins>>;
+  readonly __hint: "Add the missing plugins to your server configuration's plugins array.";
+};
+/**
+ * Type-safe server configuration with compile-time plugin validation.
+ *
+ * This ensures that all plugins required by flows are actually provided.
+ *
+ * @template TPlugins - Tuple of plugin layers
+ * @template TFlowRequirements - Union of services that flows need
+ *
+ * @example
+ * ```typescript
+ * // ✅ Compiles: ImagePlugin provided and required
+ * const config: TypeSafePluginConfig<
+ *   [ImagePluginLayer],
+ *   ImagePlugin
+ * > = {
+ *   plugins: [sharpImagePlugin],
+ *   flows: (flowId, clientId) => imageFlow
+ * };
+ *
+ * // ❌ Compile error: ImagePlugin required but not provided
+ * const bad: TypeSafePluginConfig<
+ *   [],
+ *   ImagePlugin
+ * > = {
+ *   plugins: [],
+ *   flows: (flowId, clientId) => imageFlow
+ * };
+ * ```
+ */
+type TypeSafePluginConfig<TPlugins extends PluginTuple, TFlowRequirements> = ValidatePlugins<TPlugins, TFlowRequirements> extends true ? {
+  plugins: TPlugins;
+  flows: TypeSafeFlowFunction<TFlowRequirements>;
+} : ValidatePlugins<TPlugins, TFlowRequirements>;
+/**
+ * Extracts plugin requirements from a flow function type.
+ *
+ * This navigates through the flow function signature to extract the requirements
+ * from the Flow type it returns, excluding UploadServer (provided by runtime).
+ *
+ * @template TFlowFn - The flow function type to extract requirements from
+ *
+ * @example
+ * ```typescript
+ * const myFlow = (flowId: string, clientId: string | null) =>
+ *   Effect.succeed(
+ *     createFlow({ ... }) // Returns Flow<..., ..., ImagePlugin | ZipPlugin>
+ *   );
+ *
+ * type Requirements = ExtractFlowPluginRequirements<typeof myFlow>;
+ * // Requirements = ImagePlugin | ZipPlugin
+ * ```
+ */
+type ExtractFlowPluginRequirements<TFlowFn extends (flowId: string, clientId: string | null) => Effect.Effect<unknown, unknown, unknown>> = ReturnType<TFlowFn> extends Effect.Effect<infer TFlow, any, any> ? TFlow extends Flow<any, any, infer TRequirements> ? Exclude<TRequirements, never> : never : never;
+/**
+ * Helper type to infer plugin requirements from a flow function.
+ *
+ * @example
+ * ```typescript
+ * const myFlow: TypeSafeFlowFunction<ImagePlugin | ZipPlugin> = ...;
+ * type Requirements = InferFlowRequirements<typeof myFlow>;
+ * // Requirements = ImagePlugin | ZipPlugin
+ * ```
+ */
+type InferFlowRequirements<T> = T extends TypeSafeFlowFunction<infer R> ? R : never;
+/**
+ * Converts PluginLayer types to Layer.Layer<any, never, any> for runtime use.
+ * Maintains type safety at compile time while allowing flexible runtime composition.
+ */
+type RuntimePluginLayers<T extends PluginTuple> = { [K in keyof T]: T[K] extends Layer.Layer<infer S, infer E, infer R> ? Layer.Layer<S, E, R> : never };
+//#endregion
 //#region src/core/types.d.ts
 /**
  * Function type for retrieving flows based on flow ID and client ID.
@@ -454,6 +611,8 @@ type FlowsFunction = (flowId: string, clientId: string | null) => Effect.Effect<
  * @template TRequest - Framework-specific request type
  * @template TResponse - Framework-specific response type
  * @template TWebSocket - Framework-specific WebSocket type (optional)
+ * @template TFlows - Function type for retrieving flows
+ * @template TPlugins - Tuple of plugin layers that provide requirements for flows
  *
  * @example
  * ```typescript
@@ -478,7 +637,7 @@ type FlowsFunction = (flowId: string, clientId: string | null) => Effect.Effect<
  * const server = await createUploadistaServer(config);
  * ```
  */
-interface UploadistaServerConfig<TRequest, TResponse, TWebSocket = unknown> {
+interface UploadistaServerConfig<TRequest, TResponse, TWebSocket = unknown, TFlows extends (flowId: string, clientId: string | null) => Effect.Effect<Flow<z.ZodSchema<unknown>, z.ZodSchema<unknown>, any>, UploadistaError$1, any> = any, TPlugins extends readonly PluginLayer[] = readonly PluginLayer[]> {
   /**
    * Function for retrieving flows by ID.
    *
@@ -491,7 +650,7 @@ interface UploadistaServerConfig<TRequest, TResponse, TWebSocket = unknown> {
    * flows: (flowId, clientId) => Effect.succeed(myFlows[flowId])
    * ```
    */
-  flows: FlowsFunction;
+  flows: TFlows;
   /**
    * Data store configuration for file storage.
    *
@@ -535,7 +694,7 @@ interface UploadistaServerConfig<TRequest, TResponse, TWebSocket = unknown> {
    * plugins: [imageProcessingPlugin, virusScanPlugin]
    * ```
    */
-  plugins?: readonly Layer.Layer<any, never, never>[];
+  plugins?: TPlugins;
   /**
    * Optional: Event emitter layer for progress notifications.
    *
@@ -611,7 +770,7 @@ interface UploadistaServerConfig<TRequest, TResponse, TWebSocket = unknown> {
    * metricsLayer: prometheusMetrics()
    * ```
    */
-  metricsLayer?: Layer.Layer<any, never, never>;
+  metricsLayer?: Layer.Layer<MetricsService, never, never>;
   /**
    * Optional: Buffered data store layer for performance optimization.
    *
@@ -689,29 +848,398 @@ interface UploadistaServer<TRequest, TResponse, TWebSocketHandler = unknown> {
   dispose: () => Promise<void>;
 }
 //#endregion
+//#region src/core/create-type-safe-server.d.ts
+/**
+ * Type-safe configuration for Uploadista server with compile-time plugin validation.
+ *
+ * This configuration extends the base UploadistaServerConfig with stricter typing
+ * that validates plugins match flow requirements at compile time.
+ *
+ * @template TContext - Framework-specific request context type
+ * @template TResponse - Framework-specific response type
+ * @template TWebSocket - Framework-specific WebSocket handler type
+ * @template TPlugins - Tuple of plugin layers provided to the server
+ * @template TFlowRequirements - Union of plugin services required by flows
+ */
+type TypeSafeServerConfig<TContext, TResponse, TWebSocket, TPlugins extends PluginTuple, TFlowRequirements = PluginServices<TPlugins>> = Omit<UploadistaServerConfig<TContext, TResponse, TWebSocket>, "flows" | "plugins"> & {
+  /**
+   * Tuple of plugin layers that provide services to flows.
+   * The plugins must satisfy all requirements declared by the flows.
+   */
+  plugins: TPlugins;
+  /**
+   * Type-safe flow function with explicit requirements.
+   * TypeScript validates that all required plugins are provided.
+   */
+  flows: TypeSafeFlowFunction<TFlowRequirements>;
+  /**
+   * Compile-time validation that plugins satisfy flow requirements.
+   * If this field has type errors, required plugins are missing.
+   */
+  __validate?: ValidatePlugins<TPlugins, TFlowRequirements>;
+};
+/**
+ * @deprecated Use `createUploadistaServer` with optional type utilities instead.
+ *
+ * This function is deprecated in favor of the unified `createUploadistaServer` API.
+ * The new approach separates validation concerns from server creation, making the
+ * API simpler while still providing compile-time validation when desired.
+ *
+ * ## Migration Guide
+ *
+ * ### Old Approach (Deprecated)
+ * ```typescript
+ * import { createTypeSafeServer } from "@uploadista/server";
+ *
+ * const server = await createTypeSafeServer({
+ *   plugins: [sharpImagePlugin] as const,
+ *   flows: myFlowFunction,
+ *   // ...
+ * });
+ * ```
+ *
+ * ### New Approach (Recommended)
+ *
+ * **Option 1: Runtime validation only (simplest)**
+ * ```typescript
+ * import { createUploadistaServer } from "@uploadista/server";
+ *
+ * const server = await createUploadistaServer({
+ *   plugins: [sharpImagePlugin, zipPlugin],
+ *   flows: myFlowFunction,
+ *   // ... Effect validates at runtime
+ * });
+ * ```
+ *
+ * **Option 2: With compile-time validation (optional)**
+ * ```typescript
+ * import {
+ *   createUploadistaServer,
+ *   ValidatePlugins,
+ *   ExtractFlowPluginRequirements
+ * } from "@uploadista/server";
+ *
+ * type Requirements = ExtractFlowPluginRequirements<typeof myFlowFunction>;
+ * const plugins = [sharpImagePlugin, zipPlugin] as const;
+ * type Validation = ValidatePlugins<typeof plugins, Requirements>;
+ * // IDE shows error if plugins don't match requirements
+ *
+ * const server = await createUploadistaServer({
+ *   plugins,
+ *   flows: myFlowFunction,
+ *   // ...
+ * });
+ * ```
+ *
+ * ## Why This Changed
+ *
+ * 1. **Simpler API**: One function instead of two reduces confusion
+ * 2. **Separation of Concerns**: Validation is now optional and separate
+ * 3. **Better Flexibility**: Choose validation approach per use case
+ * 4. **Clearer Intent**: Explicit validation via type utilities
+ * 5. **Same Safety**: Effect-TS still validates at runtime
+ *
+ * The new approach trusts Effect-TS's design for dynamic dependency injection
+ * while providing optional compile-time validation through type utilities.
+ *
+ * @see createUploadistaServer - The unified server creation API
+ * @see ValidatePlugins - Compile-time validation type utility
+ * @see ExtractFlowPluginRequirements - Extract requirements from flows
+ * @see API_DECISION_GUIDE.md - Complete migration and usage guide
+ *
+ * @template TContext - Framework-specific request context type
+ * @template TResponse - Framework-specific response type
+ * @template TWebSocket - Framework-specific WebSocket handler type
+ * @template TPlugins - Tuple of plugin layers
+ * @template TFlowRequirements - Union of services required by flows
+ *
+ * @param config - Type-safe server configuration
+ * @returns Promise resolving to UploadistaServer instance
+ */
+declare function createTypeSafeServer<TContext, TResponse, TWebSocket = unknown, TPlugins extends PluginTuple = PluginTuple, TFlowRequirements = PluginServices<TPlugins>>(config: TypeSafeServerConfig<TContext, TResponse, TWebSocket, TPlugins, TFlowRequirements> & (ValidatePlugins<TPlugins, TFlowRequirements> extends true ? object : ValidatePlugins<TPlugins, TFlowRequirements>)): Promise<UploadistaServer<TContext, TResponse, TWebSocket>>;
+/**
+ * Helper function to define flow functions with explicit type requirements.
+ * Provides better type inference and autocomplete for plugin services.
+ *
+ * @template TRequirements - Union of plugin services this flow needs
+ *
+ * @param fn - The flow function implementation
+ * @returns The same function with explicit type annotation
+ *
+ * @example
+ * ```typescript
+ * import { ImagePlugin } from "@uploadista/core/flow";
+ * import { defineFlow } from "@uploadista/server";
+ *
+ * // Explicitly declare that this flow requires ImagePlugin
+ * const imageProcessingFlow = defineFlow<ImagePlugin>((flowId, clientId) =>
+ *   Effect.gen(function* () {
+ *     const imageService = yield* ImagePlugin;  // Autocomplete works!
+ *     const optimized = yield* imageService.optimize(data, { quality: 80 });
+ *     return createFlow({ ... });
+ *   })
+ * );
+ * ```
+ */
+declare function defineFlow<TRequirements$1 = never>(fn: TypeSafeFlowFunction<TRequirements$1>): TypeSafeFlowFunction<TRequirements$1>;
+/**
+ * Helper to create a flow that requires no plugins.
+ * Useful for simple flows that only use built-in functionality.
+ *
+ * @example
+ * ```typescript
+ * import { defineSimpleFlow } from "@uploadista/server";
+ *
+ * const simpleFlow = defineSimpleFlow((flowId, clientId) =>
+ *   Effect.succeed(createFlow({
+ *     id: "simple",
+ *     nodes: [],
+ *     edges: [],
+ *     inputSchema: myInputSchema,
+ *     outputSchema: myOutputSchema
+ *   }))
+ * );
+ * ```
+ */
+declare function defineSimpleFlow(fn: TypeSafeFlowFunction<never>): TypeSafeFlowFunction<never>;
+//#endregion
+//#region src/core/plugin-validation.d.ts
+/**
+ * Result of plugin validation.
+ */
+type PluginValidationResult = {
+  success: true;
+} | {
+  success: false;
+  required: string[];
+  provided: string[];
+  missing: string[];
+  suggestions: Array<{
+    name: string;
+    packageName: string;
+    importStatement: string;
+  }>;
+};
+/**
+ * Extracts service identifiers from an array of plugin layers.
+ *
+ * @param plugins - Array of plugin layers
+ * @returns Array of service identifier strings
+ */
+declare function extractServiceIdentifiers(plugins: readonly PluginLayer[]): string[];
+/**
+ * Validates that all required plugins are provided.
+ *
+ * This is a runtime validation function that checks if the plugins array
+ * contains all services required by the flows. It's called during server
+ * initialization to provide early, clear error messages.
+ *
+ * Note: This validation is best-effort because we can't reliably extract
+ * requirements from flow functions at runtime without executing them.
+ * The main validation happens via Effect-TS's dependency injection.
+ *
+ * @param config - Validation configuration
+ * @returns Validation result with detailed error information if validation fails
+ *
+ * @example
+ * ```typescript
+ * const result = validatePluginRequirements({
+ *   plugins: [sharpImagePlugin, zipPlugin],
+ *   expectedServices: ['ImagePlugin', 'ZipPlugin']
+ * });
+ *
+ * if (!result.success) {
+ *   console.error('Missing plugins:', result.missing);
+ *   console.error('Suggestions:', result.suggestions);
+ * }
+ * ```
+ */
+declare function validatePluginRequirements(config: {
+  plugins: readonly PluginLayer[];
+  expectedServices?: string[];
+}): PluginValidationResult;
+/**
+ * Creates a formatted error message for plugin validation failures.
+ *
+ * This generates a detailed, human-readable error message that includes:
+ * - List of required plugins
+ * - List of provided plugins
+ * - List of missing plugins
+ * - Import statements for missing plugins (if known)
+ * - Example server configuration
+ *
+ * @param result - Failed validation result
+ * @returns Formatted error message string
+ *
+ * @example
+ * ```typescript
+ * const result = validatePluginRequirements({ ... });
+ * if (!result.success) {
+ *   const message = formatPluginValidationError(result);
+ *   throw new Error(message);
+ * }
+ * ```
+ */
+declare function formatPluginValidationError(result: Extract<PluginValidationResult, {
+  success: false;
+}>): string;
+/**
+ * Effect-based plugin validation that can be composed with other Effects.
+ *
+ * This provides an Effect-TS native way to validate plugins, allowing it
+ * to be composed with other Effects in the server initialization pipeline.
+ *
+ * @param config - Validation configuration
+ * @returns Effect that succeeds if validation passes, fails with UploadistaError if not
+ *
+ * @example
+ * ```typescript
+ * const validatedServer = Effect.gen(function* () {
+ *   yield* validatePluginRequirementsEffect({
+ *     plugins: [sharpImagePlugin],
+ *     expectedServices: ['ImagePlugin', 'ZipPlugin']
+ *   });
+ *
+ *   return yield* createServerEffect(...);
+ * });
+ * ```
+ */
+declare function validatePluginRequirementsEffect(config: {
+  plugins: readonly PluginLayer[];
+  expectedServices?: string[];
+}): Effect.Effect<void, Error>;
+/**
+ * Validates plugin configuration at runtime during server initialization.
+ *
+ * This is a convenience function that performs validation and throws a
+ * descriptive error if validation fails. Use this at the beginning of
+ * createUploadistaServer to fail fast with clear error messages.
+ *
+ * @param config - Validation configuration
+ * @throws Error with detailed message if validation fails
+ *
+ * @example
+ * ```typescript
+ * export const createUploadistaServer = async (config) => {
+ *   // Validate plugins early
+ *   validatePluginsOrThrow({
+ *     plugins: config.plugins,
+ *     expectedServices: ['ImagePlugin', 'ZipPlugin']
+ *   });
+ *
+ *   // Continue with server creation...
+ * };
+ * ```
+ */
+declare function validatePluginsOrThrow(config: {
+  plugins: readonly PluginLayer[];
+  expectedServices?: string[];
+}): 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.
+ * This is the single, unified API for creating an Uploadista server. It handles
+ * all server initialization, layer composition, and runtime setup.
+ *
+ * ## Core Responsibilities
  *
- * The core server handles:
+ * The server handles:
+ * - Layer composition (upload/flow servers, auth cache, metrics, plugins)
  * - 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
+ * - Plugin validation and dependency injection
+ *
+ * ## Plugin Validation
+ *
+ * The server supports two validation approaches:
+ *
+ * ### 1. Runtime Validation (Recommended for Most Cases)
+ *
+ * The server relies on Effect-TS's dependency injection to validate plugins
+ * at runtime. If a required plugin is missing, Effect will fail with a clear
+ * MissingService error.
+ *
+ * ```typescript
+ * const server = await createUploadistaServer({
+ *   flows: getFlowById,
+ *   plugins: [sharpImagePlugin, zipPlugin],
+ *   dataStore: s3DataStore,
+ *   kvStore: redisKvStore,
+ *   adapter: honoAdapter({ ... })
+ * });
+ * // If plugins don't match flow requirements, Effect fails with clear error
+ * ```
+ *
+ * ### 2. Compile-Time Validation (Optional)
+ *
+ * For IDE feedback during development, use the ValidatePlugins type utility:
+ *
+ * ```typescript
+ * import {
+ *   createUploadistaServer,
+ *   ValidatePlugins,
+ *   ExtractFlowPluginRequirements
+ * } from '@uploadista/server';
+ *
+ * // Extract requirements from flows
+ * type Requirements = ExtractFlowPluginRequirements<typeof getFlowById>;
+ *
+ * // Define plugins
+ * const plugins = [sharpImagePlugin, zipPlugin] as const;
+ *
+ * // Validate at compile time (optional, for IDE feedback)
+ * type Validation = ValidatePlugins<typeof plugins, Requirements>;
+ * // IDE shows error if plugins don't match requirements
+ *
+ * const server = await createUploadistaServer({
+ *   flows: getFlowById,
+ *   plugins,
+ *   // ...
+ * });
+ * ```
+ *
+ * ### 3. Early Runtime Validation (Optional)
+ *
+ * For better error messages before server starts:
+ *
+ * ```typescript
+ * import { validatePluginsOrThrow } from '@uploadista/server/core';
+ *
+ * validatePluginsOrThrow({
+ *   plugins: [sharpImagePlugin],
+ *   expectedServices: ['ImagePlugin', 'ZipPlugin']
+ * });
+ * // Throws with helpful error message including import suggestions
+ * ```
+ *
+ * ## Type Safety
+ *
+ * - Plugin requirements are inferred from flow definitions
+ * - Effect-TS ensures dependencies are satisfied at runtime
+ * - Type casting is intentional (see inline docs for rationale)
+ * - Optional compile-time validation available via type utilities
+ *
+ * @template TContext - Framework-specific context type
+ * @template TResponse - Framework-specific response type
+ * @template TWebSocketHandler - WebSocket handler type (if supported)
+ * @template TFlows - Flow function type with plugin requirements
+ * @template TPlugins - Tuple of plugin layers provided
  *
  * @param config - Server configuration including adapter and business logic
- * @returns Object with handler function, optional WebSocket handler, and base URL
+ * @returns Promise resolving to server instance with handler and metadata
  *
- * @example
+ * @example Basic Usage
  * ```typescript
  * import { createUploadistaServer, honoAdapter } from "@uploadista/server";
+ * import { sharpImagePlugin } from "@uploadista/flow-images-sharp";
  *
  * const server = await createUploadistaServer({
  *   flows: getFlowById,
+ *   plugins: [sharpImagePlugin],
  *   dataStore: { type: "s3", config: { bucket: "uploads" } },
  *   kvStore: redisKvStore,
  *   adapter: honoAdapter({
@@ -722,8 +1250,32 @@ interface UploadistaServer<TRequest, TResponse, TWebSocketHandler = unknown> {
  * // Use with Hono
  * app.all("/uploadista/*", server.handler);
  * ```
+ *
+ * @example With Compile-Time Validation
+ * ```typescript
+ * import {
+ *   createUploadistaServer,
+ *   ValidatePlugins,
+ *   ExtractFlowPluginRequirements
+ * } from "@uploadista/server";
+ *
+ * type Requirements = ExtractFlowPluginRequirements<typeof getFlowById>;
+ * const plugins = [sharpImagePlugin, zipPlugin] as const;
+ * type Validation = ValidatePlugins<typeof plugins, Requirements>;
+ *
+ * const server = await createUploadistaServer({
+ *   flows: getFlowById,
+ *   plugins,
+ *   // ... rest of config
+ * });
+ * ```
+ *
+ * @see ValidatePlugins - Compile-time plugin validation
+ * @see ExtractFlowPluginRequirements - Extract requirements from flows
+ * @see validatePluginRequirements - Runtime validation helper
+ * @see API_DECISION_GUIDE.md - Complete guide for choosing validation approach
  */
-declare const createUploadistaServer: <TContext, TResponse, TWebSocketHandler = unknown>({
+declare const createUploadistaServer: <TContext, TResponse, TWebSocketHandler = unknown, TFlows extends (flowId: string, clientId: string | null) => Effect.Effect<Flow<z.ZodSchema<unknown>, z.ZodSchema<unknown>, any>, UploadistaError$1, any> = any, TPlugins extends readonly PluginLayer[] = readonly PluginLayer[]>({
   flows,
   dataStore,
   kvStore,
@@ -737,7 +1289,7 @@ declare const createUploadistaServer: <TContext, TResponse, TWebSocketHandler =
   bufferedDataStore,
   adapter,
   authCacheConfig
-}: UploadistaServerConfig<TContext, TResponse, TWebSocketHandler>) => Promise<UploadistaServer<TContext, TResponse, TWebSocketHandler>>;
+}: UploadistaServerConfig<TContext, TResponse, TWebSocketHandler, TFlows, TPlugins>) => Promise<UploadistaServer<TContext, TResponse, TWebSocketHandler>>;
 //#endregion
 //#region src/core/websocket-routes.d.ts
 /**
@@ -1272,10 +1824,80 @@ declare const createFlowServerLayer: ({
 }: FlowServerLayerConfig) => Layer.Layer<_uploadista_core0.FlowServer, never, never>;
 //#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;
+/**
+ * @deprecated Use `ExtractLayerServices` from `@uploadista/core/flow/types` instead.
+ *
+ * Extracts service types from a tuple of layers.
+ *
+ * @example Migration
+ * ```typescript
+ * // Old
+ * import { LayerSuccessUnion } from '@uploadista/server/plugins-typing';
+ * type Services = LayerSuccessUnion<[ImagePluginLayer, ZipPluginLayer]>;
+ *
+ * // New
+ * import { ExtractLayerServices } from '@uploadista/core/flow/types';
+ * type Services = ExtractLayerServices<[ImagePluginLayer, ZipPluginLayer]>;
+ * ```
+ */
+type LayerSuccessUnion<Layers extends readonly Layer.Layer<any, never, never>[]> = ExtractLayerServices$1<Layers>;
+/**
+ * @deprecated This type is deprecated. Extract flow requirements directly from your flow types instead.
+ *
+ * Extracts the success type from a flow function's Effect return value.
+ */
 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;
+/**
+ * @deprecated Use `ExtractFlowPluginRequirements` from `@uploadista/server/core/plugin-types` instead.
+ *
+ * Extracts plugin requirements from a flow function, excluding UploadServer.
+ *
+ * @example Migration
+ * ```typescript
+ * // Old
+ * import { FlowRequirementsOf } from '@uploadista/server/plugins-typing';
+ * type Requirements = FlowRequirementsOf<typeof myFlowFunction>;
+ *
+ * // New
+ * import { ExtractFlowPluginRequirements } from '@uploadista/server/core/plugin-types';
+ * type Requirements = ExtractFlowPluginRequirements<typeof myFlowFunction>;
+ * ```
+ */
 type FlowRequirementsOf<TFlows extends (flowId: string, clientId: string | null) => Effect.Effect<unknown, unknown, unknown>> = FlowSuccess<TFlows> extends Flow$1<z$1.ZodSchema<unknown>, z$1.ZodSchema<unknown>, infer R> ? Exclude<R, UploadServer$1> : never;
+/**
+ * @deprecated Use `ExtractFlowPluginRequirements` from `@uploadista/server/core/plugin-types` instead.
+ *
+ * This is an alias for FlowRequirementsOf and provides the same functionality.
+ *
+ * @example Migration
+ * ```typescript
+ * // Old
+ * import { RequiredPluginsOf } from '@uploadista/server/plugins-typing';
+ * type Requirements = RequiredPluginsOf<typeof myFlowFunction>;
+ *
+ * // New
+ * import { ExtractFlowPluginRequirements } from '@uploadista/server/core/plugin-types';
+ * type Requirements = ExtractFlowPluginRequirements<typeof myFlowFunction>;
+ * ```
+ */
 type RequiredPluginsOf<TFlows extends (flowId: string, clientId: string | null) => Effect.Effect<unknown, unknown, unknown>> = Exclude<FlowRequirementsOf<TFlows>, UploadServer$1>;
+/**
+ * @deprecated Use `ValidatePlugins` from `@uploadista/server/core/plugin-types` instead.
+ *
+ * This type validates plugin requirements at compile time.
+ *
+ * @example Migration
+ * ```typescript
+ * // Old
+ * import { PluginAssertion } from '@uploadista/server/plugins-typing';
+ * type Validation = PluginAssertion<typeof myFlowFunction, typeof plugins>;
+ *
+ * // New
+ * import { ValidatePlugins, ExtractFlowPluginRequirements } from '@uploadista/server/core/plugin-types';
+ * type Requirements = ExtractFlowPluginRequirements<typeof myFlowFunction>;
+ * type Validation = ValidatePlugins<typeof plugins, Requirements>;
+ * ```
+ */
 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>>;
 };
@@ -1340,5 +1962,5 @@ declare const AuthContextServiceLive: (authContext: AuthContext | null) => Layer
  */
 declare const NoAuthContextServiceLive: Layer.Layer<AuthContextService>;
 //#endregion
-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 };
+export { AdapterError, AuthCacheConfig, AuthCacheService, AuthCacheServiceLive, AuthContext, AuthContextService, AuthContextServiceLive, AuthCredentialsResponse, AuthFailedEvent, AuthResult, BadRequestError, BadRequestRequest, BadRequestResponse, CancelFlowRequest, CancelFlowResponse, ConnectionEvent, CreateUploadRequest, CreateUploadResponse, ErrorEvent, ExtractFlowPluginRequirements, ExtractServicesFromLayers, FlowEventMessage, FlowRequirementsOf, FlowServerLayerConfig, FlowSuccess, FlowsFunction, GetCapabilitiesRequest, GetCapabilitiesResponse, GetFlowRequest, GetFlowResponse, GetJobStatusRequest, GetJobStatusResponse, GetUploadRequest, GetUploadResponse, InferFlowRequirements, InvalidPathEvent, KnownPluginLayer, LayerSuccessUnion, MethodNotAllowedRequest, MethodNotAllowedResponse, NoAuthCacheServiceLive, NoAuthContextServiceLive, NotFoundError, NotFoundRequest, NotFoundResponse, PauseFlowRequest, PauseFlowResponse, PingEvent, PluginAssertion, PluginServices, PluginTuple, PluginValidationResult, RequiredPluginsOf, ResumeFlowRequest, ResumeFlowResponse, RunFlowRequest, RunFlowResponse, RuntimePluginLayers, ServerAdapter, StandardRequest, StandardResponse, SubscribeFlowEvent, SubscribeUploadEvent, TypeSafeFlowFunction, TypeSafePluginConfig, TypeSafeServerConfig, UnsubscribeFlowEvent, UnsubscribeUploadEvent, UnsupportedContentTypeRequest, UnsupportedContentTypeResponse, UploadChunkRequest, UploadChunkResponse, UploadEventMessage, UploadServerLayerConfig, UploadistaRequest, UploadistaResponse, UploadistaRoute, UploadistaRouteType, UploadistaServer, UploadistaServerConfig, UploadistaStandardResponse, ValidatePlugins, ValidationError, type WebSocketConnection, type WebSocketConnectionRequest, WebSocketEvent, WebSocketEventType, WebSocketHandler, WebSocketIncomingEvent, WebSocketOutgoingEvent, createErrorResponseBody, createFlowServerLayer, createGenericErrorResponseBody, createTypeSafeServer, createUploadServerLayer, createUploadistaErrorResponseBody, createUploadistaServer, defineFlow, defineSimpleFlow, extractFlowAndStorageId, extractJobAndNodeId, extractJobIdFromStatus, extractServiceIdentifiers, formatPluginValidationError, getAuthCredentials, getLastSegment, getRouteSegments, handleFlowError, handleWebSocketClose, handleWebSocketError, handleWebSocketMessage, handleWebSocketOpen, hasBasePath, parseUrlSegments, validatePluginRequirements, validatePluginRequirementsEffect, validatePluginsOrThrow };
 //# sourceMappingURL=index.d.mts.map