@uploadista/server 0.0.18-beta.8 → 0.0.18

package/dist/index.d.cts

@@ -672,6 +672,168 @@ type InferFlowRequirements<T> = T extends TypeSafeFlowFunction<infer R> ? R : ne
  */
 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/usage-hooks/types.d.ts
+/**
+ * Result of a usage hook that can abort processing.
+ * Used by onUploadStart and onFlowStart hooks.
+ */
+type UsageHookResult = {
+  readonly action: "continue";
+} | {
+  readonly action: "abort";
+  readonly reason: string;
+  readonly code?: string;
+};
+/**
+ * Helper to create a continue result.
+ */
+declare const continueResult: () => UsageHookResult;
+/**
+ * Helper to create an abort result.
+ */
+declare const abortResult: (reason: string, code?: string) => UsageHookResult;
+/**
+ * Base metadata shared across all usage contexts.
+ */
+interface BaseUsageMetadata {
+  /** File size in bytes (if known) */
+  fileSize?: number;
+  /** MIME type of the file */
+  mimeType?: string;
+  /** Original file name */
+  fileName?: string;
+}
+/**
+ * Metadata specific to upload operations.
+ */
+interface UploadUsageMetadata extends BaseUsageMetadata {
+  /** Unique upload identifier */
+  uploadId?: string;
+  /** Duration of the upload in milliseconds */
+  duration?: number;
+}
+/**
+ * Metadata specific to flow operations.
+ */
+interface FlowUsageMetadata extends BaseUsageMetadata {
+  /** Flow identifier being executed */
+  flowId?: string;
+  /** Unique job identifier */
+  jobId?: string;
+  /** Number of nodes in the flow */
+  nodeCount?: number;
+  /** Total size of input files */
+  inputFileSize?: number;
+  /** Total size of output files (on complete) */
+  outputSize?: number;
+  /** Number of nodes that were executed (on complete) */
+  nodesExecuted?: number;
+  /** Duration of flow execution in milliseconds (on complete) */
+  duration?: number;
+  /** Flow completion status (on complete) */
+  status?: "success" | "failed" | "cancelled";
+}
+/**
+ * Context passed to usage hooks containing client and operation information.
+ */
+interface UsageContext<TMetadata extends BaseUsageMetadata = BaseUsageMetadata> {
+  /** Organization/client identifier */
+  clientId: string;
+  /** Type of operation */
+  operation: "upload" | "flow";
+  /** Operation-specific metadata */
+  metadata: TMetadata;
+}
+/**
+ * Upload-specific usage context.
+ */
+type UploadUsageContext = UsageContext<UploadUsageMetadata>;
+/**
+ * Flow-specific usage context.
+ */
+type FlowUsageContext = UsageContext<FlowUsageMetadata>;
+/**
+ * Hook called before upload processing begins.
+ * Can return abort to reject the upload (e.g., quota exceeded).
+ */
+type OnUploadStartHook = (ctx: UploadUsageContext) => Effect.Effect<UsageHookResult>;
+/**
+ * Hook called after upload completes successfully.
+ * Used for recording usage. Errors are logged but don't fail the upload.
+ */
+type OnUploadCompleteHook = (ctx: UploadUsageContext) => Effect.Effect<void>;
+/**
+ * Hook called before flow execution begins.
+ * Can return abort to reject the flow (e.g., subscription expired).
+ */
+type OnFlowStartHook = (ctx: FlowUsageContext) => Effect.Effect<UsageHookResult>;
+/**
+ * Hook called after flow completes (success, failure, or cancellation).
+ * Used for recording usage. Errors are logged but don't fail the response.
+ */
+type OnFlowCompleteHook = (ctx: FlowUsageContext) => Effect.Effect<void>;
+/**
+ * Configuration for usage tracking hooks.
+ * All hooks are optional - unconfigured hooks are no-ops.
+ *
+ * @example
+ * ```typescript
+ * const usageHooks: UsageHooks = {
+ *   onUploadStart: (ctx) => Effect.gen(function* () {
+ *     const hasQuota = yield* checkQuota(ctx.clientId, ctx.metadata.fileSize);
+ *     if (!hasQuota) {
+ *       return abortResult("Storage quota exceeded", "QUOTA_EXCEEDED");
+ *     }
+ *     return continueResult();
+ *   }),
+ *   onUploadComplete: (ctx) => Effect.gen(function* () {
+ *     yield* recordUsage(ctx.clientId, ctx.metadata.fileSize);
+ *   }),
+ * };
+ * ```
+ */
+interface UsageHooks {
+  /**
+   * Called before upload processing begins.
+   * Return abort to reject the upload.
+   */
+  onUploadStart?: OnUploadStartHook;
+  /**
+   * Called after upload completes successfully.
+   * Errors are logged but don't fail the upload.
+   */
+  onUploadComplete?: OnUploadCompleteHook;
+  /**
+   * Called before flow execution begins.
+   * Return abort to reject the flow.
+   */
+  onFlowStart?: OnFlowStartHook;
+  /**
+   * Called after flow completes (success, failure, or cancellation).
+   * Errors are logged but don't fail the response.
+   */
+  onFlowComplete?: OnFlowCompleteHook;
+}
+/**
+ * Configuration for the usage hook service.
+ */
+interface UsageHookConfig {
+  /**
+   * The usage hooks to execute.
+   */
+  hooks?: UsageHooks;
+  /**
+   * Timeout for hook execution in milliseconds.
+   * If a hook takes longer than this, it will be considered failed.
+   * Default: 5000ms (5 seconds)
+   */
+  timeout?: number;
+}
+/**
+ * Default timeout for usage hooks (5 seconds).
+ */
+declare const DEFAULT_USAGE_HOOK_TIMEOUT = 5000;
+//#endregion
 //#region src/core/types.d.ts
 /**
  * Function type for retrieving flows based on flow ID and client ID.
@@ -853,6 +1015,40 @@ interface UploadistaServerConfig<TRequest, TResponse, TWebSocket = unknown, TFlo
    * @default false
    */
   withTracing?: boolean;
+  /**
+   * Optional: Custom observability layer for distributed tracing.
+   *
+   * When provided, this layer will be used instead of the default NodeSdkLive.
+   * This allows you to configure custom OTLP exporters (e.g., for Grafana Cloud,
+   * Jaeger, or other OpenTelemetry-compatible backends).
+   *
+   * Requires `withTracing: true` to be effective.
+   *
+   * @example
+   * ```typescript
+   * import { OtlpNodeSdkLive, createOtlpNodeSdkLayer } from "@uploadista/observability";
+   *
+   * // Option 1: Use default OTLP layer (reads from env vars)
+   * const server = await createUploadistaServer({
+   *   withTracing: true,
+   *   observabilityLayer: OtlpNodeSdkLive,
+   *   // ...
+   * });
+   *
+   * // Option 2: Custom configuration with tenant attributes
+   * const server = await createUploadistaServer({
+   *   withTracing: true,
+   *   observabilityLayer: createOtlpNodeSdkLayer({
+   *     serviceName: "uploadista-cloud-api",
+   *     resourceAttributes: {
+   *       "deployment.environment": "production",
+   *     },
+   *   }),
+   *   // ...
+   * });
+   * ```
+   */
+  observabilityLayer?: Layer.Layer<any, never, never>;
   /**
    * Optional: Metrics layer for observability.
    *
@@ -988,6 +1184,39 @@ interface UploadistaServerConfig<TRequest, TResponse, TWebSocket = unknown, TFlo
    * ```
    */
   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;
 }
 /**
  * Return type from createUploadistaServer.
@@ -1454,6 +1683,7 @@ declare const createUploadistaServer: <TContext, TResponse, TWebSocketHandler =
   eventEmitter,
   eventBroadcaster,
   withTracing,
+  observabilityLayer,
   baseUrl: configBaseUrl,
   generateId,
   metricsLayer,
@@ -1462,7 +1692,8 @@ declare const createUploadistaServer: <TContext, TResponse, TWebSocketHandler =
   authCacheConfig,
   circuitBreaker,
   deadLetterQueue,
-  healthCheck
+  healthCheck,
+  usageHooks
 }: UploadistaServerConfig<TContext, TResponse, TWebSocketHandler, TFlows, TPlugins>) => Promise<UploadistaServer<TContext, TResponse, TWebSocketHandler>>;
 //#endregion
 //#region src/core/websocket-routes.d.ts
@@ -1997,6 +2228,295 @@ declare const createFlowServerLayer: ({
   uploadServer
 }: FlowServerLayerConfig) => Layer.Layer<_uploadista_core0.FlowServer, never, never>;
 //#endregion
+//#region src/permissions/types.d.ts
+/**
+ * Permission Types and Constants
+ *
+ * Defines the permission model for fine-grained access control in the uploadista engine.
+ * Permissions follow a hierarchical format: `resource:action` with support for wildcards.
+ */
+/**
+ * Engine permissions for administrative operations.
+ * These control access to health, readiness, metrics, and DLQ endpoints.
+ */
+declare const ENGINE_PERMISSIONS: {
+  /** Full admin access to all engine operations */
+  readonly ALL: "engine:*";
+  /** Access health endpoint */
+  readonly HEALTH: "engine:health";
+  /** Access readiness endpoint */
+  readonly READINESS: "engine:readiness";
+  /** Access metrics endpoint */
+  readonly METRICS: "engine:metrics";
+  /** Full DLQ access (implies read and write) */
+  readonly DLQ: "engine:dlq";
+  /** Read DLQ entries */
+  readonly DLQ_READ: "engine:dlq:read";
+  /** Retry/delete DLQ entries */
+  readonly DLQ_WRITE: "engine:dlq:write";
+};
+/**
+ * Flow permissions for flow execution operations.
+ */
+declare const FLOW_PERMISSIONS: {
+  /** Full access to all flow operations */
+  readonly ALL: "flow:*";
+  /** Execute flows */
+  readonly EXECUTE: "flow:execute";
+  /** Cancel running flows */
+  readonly CANCEL: "flow:cancel";
+  /** Check flow status */
+  readonly STATUS: "flow:status";
+};
+/**
+ * Upload permissions for file upload operations.
+ */
+declare const UPLOAD_PERMISSIONS: {
+  /** Full access to all upload operations */
+  readonly ALL: "upload:*";
+  /** Create uploads */
+  readonly CREATE: "upload:create";
+  /** Read upload status */
+  readonly READ: "upload:read";
+  /** Cancel uploads */
+  readonly CANCEL: "upload:cancel";
+};
+/**
+ * All available permissions organized by category.
+ *
+ * @example
+ * ```typescript
+ * import { PERMISSIONS } from "@uploadista/server";
+ *
+ * const adminPermissions = [PERMISSIONS.ENGINE.ALL];
+ * const userPermissions = [PERMISSIONS.FLOW.ALL, PERMISSIONS.UPLOAD.ALL];
+ * ```
+ */
+declare const PERMISSIONS: {
+  readonly ENGINE: {
+    /** Full admin access to all engine operations */
+    readonly ALL: "engine:*";
+    /** Access health endpoint */
+    readonly HEALTH: "engine:health";
+    /** Access readiness endpoint */
+    readonly READINESS: "engine:readiness";
+    /** Access metrics endpoint */
+    readonly METRICS: "engine:metrics";
+    /** Full DLQ access (implies read and write) */
+    readonly DLQ: "engine:dlq";
+    /** Read DLQ entries */
+    readonly DLQ_READ: "engine:dlq:read";
+    /** Retry/delete DLQ entries */
+    readonly DLQ_WRITE: "engine:dlq:write";
+  };
+  readonly FLOW: {
+    /** Full access to all flow operations */
+    readonly ALL: "flow:*";
+    /** Execute flows */
+    readonly EXECUTE: "flow:execute";
+    /** Cancel running flows */
+    readonly CANCEL: "flow:cancel";
+    /** Check flow status */
+    readonly STATUS: "flow:status";
+  };
+  readonly UPLOAD: {
+    /** Full access to all upload operations */
+    readonly ALL: "upload:*";
+    /** Create uploads */
+    readonly CREATE: "upload:create";
+    /** Read upload status */
+    readonly READ: "upload:read";
+    /** Cancel uploads */
+    readonly CANCEL: "upload:cancel";
+  };
+};
+/** All engine permission strings */
+type EnginePermission = (typeof ENGINE_PERMISSIONS)[keyof typeof ENGINE_PERMISSIONS];
+/** All flow permission strings */
+type FlowPermission = (typeof FLOW_PERMISSIONS)[keyof typeof FLOW_PERMISSIONS];
+/** All upload permission strings */
+type UploadPermission = (typeof UPLOAD_PERMISSIONS)[keyof typeof UPLOAD_PERMISSIONS];
+/**
+ * Union type of all valid permission strings.
+ * Includes standard permissions and allows custom permissions via string.
+ */
+type Permission = EnginePermission | FlowPermission | UploadPermission | (string & {});
+/**
+ * Predefined permission sets for common use cases.
+ */
+declare const PERMISSION_SETS: {
+  /** Full admin access - all engine, flow, and upload permissions */
+  readonly ADMIN: readonly ["engine:*"];
+  /** Organization owner - all flow and upload permissions */
+  readonly ORGANIZATION_OWNER: readonly ["flow:*", "upload:*"];
+  /** Organization member - same as owner for now */
+  readonly ORGANIZATION_MEMBER: readonly ["flow:*", "upload:*"];
+  /** API key - limited to execute flows and create uploads */
+  readonly API_KEY: readonly ["flow:execute", "upload:create"];
+};
+/**
+ * Hierarchical permission relationships.
+ * When a parent permission is granted, all child permissions are implied.
+ */
+declare const PERMISSION_HIERARCHY: Record<string, readonly string[]>;
+//#endregion
+//#region src/permissions/matcher.d.ts
+/**
+ * Permission Matching Logic
+ *
+ * Implements permission matching with support for:
+ * - Exact match: `engine:health` matches `engine:health`
+ * - Wildcard match: `engine:*` matches `engine:health`, `engine:metrics`, etc.
+ * - Hierarchical match: `engine:dlq` implies `engine:dlq:read` and `engine:dlq:write`
+ */
+/**
+ * Checks if a granted permission matches a required permission.
+ *
+ * @param granted - The permission that has been granted to the user
+ * @param required - The permission that is required for the operation
+ * @returns true if the granted permission satisfies the required permission
+ *
+ * @example
+ * ```typescript
+ * matchesPermission("engine:*", "engine:health") // true (wildcard)
+ * matchesPermission("engine:health", "engine:health") // true (exact)
+ * matchesPermission("engine:dlq", "engine:dlq:read") // true (hierarchical)
+ * matchesPermission("flow:execute", "engine:health") // false
+ * ```
+ */
+declare const matchesPermission: (granted: string, required: string) => boolean;
+/**
+ * Checks if any of the granted permissions satisfy the required permission.
+ *
+ * @param grantedPermissions - Array of permissions granted to the user
+ * @param required - The permission that is required for the operation
+ * @returns true if any granted permission satisfies the required permission
+ *
+ * @example
+ * ```typescript
+ * hasPermission(["flow:*", "upload:create"], "flow:execute") // true
+ * hasPermission(["upload:create"], "flow:execute") // false
+ * ```
+ */
+declare const hasPermission: (grantedPermissions: readonly string[], required: string) => boolean;
+/**
+ * Checks if any of the granted permissions satisfy any of the required permissions.
+ *
+ * @param grantedPermissions - Array of permissions granted to the user
+ * @param requiredPermissions - Array of permissions, any of which would be sufficient
+ * @returns true if any granted permission satisfies any required permission
+ *
+ * @example
+ * ```typescript
+ * hasAnyPermission(["upload:create"], ["flow:execute", "upload:create"]) // true
+ * hasAnyPermission(["upload:read"], ["flow:execute", "upload:create"]) // false
+ * ```
+ */
+declare const hasAnyPermission: (grantedPermissions: readonly string[], requiredPermissions: readonly string[]) => boolean;
+/**
+ * Checks if all of the required permissions are satisfied.
+ *
+ * @param grantedPermissions - Array of permissions granted to the user
+ * @param requiredPermissions - Array of permissions, all of which must be satisfied
+ * @returns true if all required permissions are satisfied
+ *
+ * @example
+ * ```typescript
+ * hasAllPermissions(["flow:*", "upload:*"], ["flow:execute", "upload:create"]) // true
+ * hasAllPermissions(["flow:execute"], ["flow:execute", "upload:create"]) // false
+ * ```
+ */
+declare const hasAllPermissions: (grantedPermissions: readonly string[], requiredPermissions: readonly string[]) => boolean;
+/**
+ * Expands a permission to include all implied permissions.
+ * Useful for display or audit purposes.
+ *
+ * @param permission - The permission to expand
+ * @returns Array of the permission and all implied permissions
+ *
+ * @example
+ * ```typescript
+ * expandPermission("engine:dlq") // ["engine:dlq", "engine:dlq:read", "engine:dlq:write"]
+ * expandPermission("engine:health") // ["engine:health"]
+ * ```
+ */
+declare const expandPermission: (permission: string) => string[];
+//#endregion
+//#region src/permissions/errors.d.ts
+/**
+ * Authorization error - indicates the user lacks required permissions.
+ * Returns HTTP 403 Forbidden status.
+ *
+ * @example
+ * ```typescript
+ * if (!hasPermission(permissions, "engine:metrics")) {
+ *   throw new AuthorizationError("engine:metrics");
+ * }
+ * ```
+ */
+declare class AuthorizationError extends AdapterError {
+  /**
+   * The permission that was required but not granted.
+   */
+  readonly requiredPermission: string;
+  constructor(requiredPermission: string, message?: string);
+}
+/**
+ * Authentication required error - indicates no authentication context.
+ * Returns HTTP 401 Unauthorized status.
+ *
+ * @example
+ * ```typescript
+ * if (!authContext) {
+ *   throw new AuthenticationRequiredError();
+ * }
+ * ```
+ */
+declare class AuthenticationRequiredError extends AdapterError {
+  constructor(message?: string);
+}
+/**
+ * Organization mismatch error - indicates accessing a resource from another organization.
+ * Returns HTTP 403 Forbidden status.
+ *
+ * @example
+ * ```typescript
+ * if (resource.organizationId !== clientId) {
+ *   throw new OrganizationMismatchError();
+ * }
+ * ```
+ */
+declare class OrganizationMismatchError extends AdapterError {
+  constructor(message?: string);
+}
+/**
+ * Quota exceeded error - indicates usage quota has been exceeded.
+ * Returns HTTP 402 Payment Required status.
+ *
+ * @example
+ * ```typescript
+ * if (usage > quota) {
+ *   throw new QuotaExceededError("Storage quota exceeded");
+ * }
+ * ```
+ */
+declare class QuotaExceededError extends AdapterError {
+  constructor(message?: string, code?: string);
+}
+/**
+ * Creates a standardized error response body for AuthorizationError.
+ * Includes the required permission in the response.
+ *
+ * @param error - The AuthorizationError to format
+ * @returns Standardized error response body
+ */
+declare const createAuthorizationErrorResponseBody: (error: AuthorizationError) => {
+  error: string;
+  code: string;
+  requiredPermission: string;
+  timestamp: string;
+};
+//#endregion
 //#region src/plugins-typing.d.ts
 /**
  * @deprecated Use `ExtractLayerServices` from `@uploadista/core/flow/types` instead.
@@ -2090,9 +2610,56 @@ declare const AuthContextService_base: Context.TagClass<AuthContextService, "Aut
   readonly getMetadata: () => Effect.Effect<Record<string, unknown>>;
   /**
    * Check if the current client has a specific permission.
+   * Supports exact match, wildcard match, and hierarchical match.
    * Returns false if no authentication context or permission not found.
+   *
+   * @example
+   * ```typescript
+   * // Exact match
+   * yield* authService.hasPermission("engine:health")
+   *
+   * // Wildcard: user with "engine:*" will match "engine:health"
+   * yield* authService.hasPermission("engine:health")
+   *
+   * // Hierarchical: user with "engine:dlq" will match "engine:dlq:read"
+   * yield* authService.hasPermission("engine:dlq:read")
+   * ```
    */
   readonly hasPermission: (permission: string) => Effect.Effect<boolean>;
+  /**
+   * Check if the current client has any of the specified permissions.
+   * Returns true if at least one permission is granted.
+   */
+  readonly hasAnyPermission: (permissions: readonly string[]) => Effect.Effect<boolean>;
+  /**
+   * Require a specific permission, failing with AuthorizationError if not granted.
+   * Use this when you want to fail fast on missing permissions.
+   *
+   * @throws AuthorizationError if permission is not granted
+   * @throws AuthenticationRequiredError if no auth context
+   *
+   * @example
+   * ```typescript
+   * const protectedHandler = Effect.gen(function* () {
+   *   const authService = yield* AuthContextService;
+   *   yield* authService.requirePermission("engine:metrics");
+   *   // Only reaches here if permission is granted
+   *   return yield* getMetrics();
+   * });
+   * ```
+   */
+  readonly requirePermission: (permission: string) => Effect.Effect<void, AuthorizationError | AuthenticationRequiredError>;
+  /**
+   * Require authentication, failing with AuthenticationRequiredError if not authenticated.
+   *
+   * @throws AuthenticationRequiredError if no auth context
+   */
+  readonly requireAuthentication: () => Effect.Effect<AuthContext, AuthenticationRequiredError>;
+  /**
+   * Get all permissions granted to the current client.
+   * Returns empty array if no authentication context or no permissions.
+   */
+  readonly getPermissions: () => Effect.Effect<readonly string[]>;
   /**
    * Get the full authentication context if available.
    * Returns null if no authentication context is available.
@@ -2121,14 +2688,26 @@ declare const AuthContextService_base: Context.TagClass<AuthContextService, "Aut
  * ```
  */
 declare class AuthContextService extends AuthContextService_base {}
+/**
+ * Options for creating an AuthContextService Layer.
+ */
+interface AuthContextServiceOptions {
+  /**
+   * When true, bypasses all permission checks (grants all permissions).
+   * Used when no auth middleware is configured (backward compatibility).
+   * @default false
+   */
+  bypassAuth?: boolean;
+}
 /**
  * Creates an AuthContextService Layer from an AuthContext.
  * This is typically called by adapters after successful authentication.
  *
  * @param authContext - The authentication context from middleware
+ * @param options - Optional configuration for auth behavior
  * @returns Effect Layer providing AuthContextService
  */
-declare const AuthContextServiceLive: (authContext: AuthContext | null) => Layer.Layer<AuthContextService>;
+declare const AuthContextServiceLive: (authContext: AuthContext | null, options?: AuthContextServiceOptions) => Layer.Layer<AuthContextService>;
 /**
  * No-auth implementation of AuthContextService.
  * Returns null/empty values for all operations.
@@ -2136,5 +2715,49 @@ 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, DlqCleanupRequest, DlqCleanupResponse, DlqDeleteRequest, DlqDeleteResponse, DlqGetRequest, DlqGetResponse, DlqListRequest, DlqListResponse, DlqResolveRequest, DlqResolveResponse, DlqRetryAllRequest, DlqRetryAllResponse, DlqRetryRequest, DlqRetryResponse, DlqStatsRequest, DlqStatsResponse, ErrorEvent, ExtractFlowPluginRequirements, ExtractServicesFromLayers, FlowEventMessage, FlowRequirementsOf, FlowServerLayerConfig, FlowSuccess, FlowsFunction, GetCapabilitiesRequest, GetCapabilitiesResponse, GetFlowRequest, GetFlowResponse, GetJobStatusRequest, GetJobStatusResponse, GetUploadRequest, GetUploadResponse, HealthComponentsRequest, HealthComponentsResponse, HealthReadyRequest, HealthReadyResponse, HealthRequest, HealthResponse, 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 };
+//#region src/usage-hooks/service.d.ts
+declare const UsageHookService_base: Context.TagClass<UsageHookService, "UsageHookService", {
+  /**
+   * Execute onUploadStart hook if configured.
+   * Returns continue result if no hook is configured or on error/timeout.
+   */
+  readonly onUploadStart: (ctx: UploadUsageContext) => Effect.Effect<UsageHookResult>;
+  /**
+   * Execute onUploadComplete hook if configured.
+   * Errors are logged but swallowed (fire-and-forget).
+   */
+  readonly onUploadComplete: (ctx: UploadUsageContext) => Effect.Effect<void>;
+  /**
+   * Execute onFlowStart hook if configured.
+   * Returns continue result if no hook is configured or on error/timeout.
+   */
+  readonly onFlowStart: (ctx: FlowUsageContext) => Effect.Effect<UsageHookResult>;
+  /**
+   * Execute onFlowComplete hook if configured.
+   * Errors are logged but swallowed (fire-and-forget).
+   */
+  readonly onFlowComplete: (ctx: FlowUsageContext) => Effect.Effect<void>;
+}>;
+/**
+ * Usage Hook Service
+ *
+ * Provides methods to execute usage hooks during upload and flow processing.
+ * Handles timeout and error recovery gracefully.
+ */
+declare class UsageHookService extends UsageHookService_base {}
+/**
+ * Creates a UsageHookService Layer from configuration.
+ *
+ * @param config - Usage hook configuration with optional hooks and timeout
+ * @returns Effect Layer providing UsageHookService
+ */
+declare const UsageHookServiceLive: (config?: UsageHookConfig) => Layer.Layer<UsageHookService>;
+/**
+ * No-op implementation of UsageHookService.
+ * All hooks are no-ops that return continue/void.
+ * Used when no usage hooks are configured (default backward compatibility).
+ */
+declare const NoUsageHookServiceLive: Layer.Layer<UsageHookService>;
+//#endregion
+export { AdapterError, AuthCacheConfig, AuthCacheService, AuthCacheServiceLive, AuthContext, AuthContextService, AuthContextServiceLive, AuthContextServiceOptions, AuthCredentialsResponse, AuthFailedEvent, AuthResult, AuthenticationRequiredError, AuthorizationError, BadRequestError, BadRequestRequest, BadRequestResponse, BaseUsageMetadata, CancelFlowRequest, CancelFlowResponse, ConnectionEvent, CreateUploadRequest, CreateUploadResponse, DEFAULT_USAGE_HOOK_TIMEOUT, DlqCleanupRequest, DlqCleanupResponse, DlqDeleteRequest, DlqDeleteResponse, DlqGetRequest, DlqGetResponse, DlqListRequest, DlqListResponse, DlqResolveRequest, DlqResolveResponse, DlqRetryAllRequest, DlqRetryAllResponse, DlqRetryRequest, DlqRetryResponse, DlqStatsRequest, DlqStatsResponse, ENGINE_PERMISSIONS, EnginePermission, ErrorEvent, ExtractFlowPluginRequirements, ExtractServicesFromLayers, FLOW_PERMISSIONS, FlowEventMessage, FlowPermission, FlowRequirementsOf, FlowServerLayerConfig, FlowSuccess, FlowUsageContext, FlowUsageMetadata, FlowsFunction, GetCapabilitiesRequest, GetCapabilitiesResponse, GetFlowRequest, GetFlowResponse, GetJobStatusRequest, GetJobStatusResponse, GetUploadRequest, GetUploadResponse, HealthComponentsRequest, HealthComponentsResponse, HealthReadyRequest, HealthReadyResponse, HealthRequest, HealthResponse, InferFlowRequirements, InvalidPathEvent, KnownPluginLayer, LayerSuccessUnion, MethodNotAllowedRequest, MethodNotAllowedResponse, NoAuthCacheServiceLive, NoAuthContextServiceLive, NoUsageHookServiceLive, NotFoundError, NotFoundRequest, NotFoundResponse, OnFlowCompleteHook, OnFlowStartHook, OnUploadCompleteHook, OnUploadStartHook, OrganizationMismatchError, PERMISSIONS, PERMISSION_HIERARCHY, PERMISSION_SETS, PauseFlowRequest, PauseFlowResponse, Permission, PingEvent, PluginAssertion, PluginServices, PluginTuple, PluginValidationResult, QuotaExceededError, RequiredPluginsOf, ResumeFlowRequest, ResumeFlowResponse, RunFlowRequest, RunFlowResponse, RuntimePluginLayers, ServerAdapter, StandardRequest, StandardResponse, SubscribeFlowEvent, SubscribeUploadEvent, TypeSafeFlowFunction, TypeSafePluginConfig, TypeSafeServerConfig, UPLOAD_PERMISSIONS, UnsubscribeFlowEvent, UnsubscribeUploadEvent, UnsupportedContentTypeRequest, UnsupportedContentTypeResponse, UploadChunkRequest, UploadChunkResponse, UploadEventMessage, UploadPermission, UploadServerLayerConfig, UploadUsageContext, UploadUsageMetadata, UploadistaRequest, UploadistaResponse, UploadistaRoute, UploadistaRouteType, UploadistaServer, UploadistaServerConfig, UploadistaStandardResponse, UsageContext, UsageHookConfig, UsageHookResult, UsageHookService, UsageHookServiceLive, UsageHooks, ValidatePlugins, ValidationError, type WebSocketConnection, type WebSocketConnectionRequest, WebSocketEvent, WebSocketEventType, WebSocketHandler, WebSocketIncomingEvent, WebSocketOutgoingEvent, abortResult, continueResult, createAuthorizationErrorResponseBody, createErrorResponseBody, createFlowServerLayer, createGenericErrorResponseBody, createTypeSafeServer, createUploadServerLayer, createUploadistaErrorResponseBody, createUploadistaServer, defineFlow, defineSimpleFlow, expandPermission, extractFlowAndStorageId, extractJobAndNodeId, extractJobIdFromStatus, extractServiceIdentifiers, formatPluginValidationError, getAuthCredentials, getLastSegment, getRouteSegments, handleFlowError, handleWebSocketClose, handleWebSocketError, handleWebSocketMessage, handleWebSocketOpen, hasAllPermissions, hasAnyPermission, hasBasePath, hasPermission, matchesPermission, parseUrlSegments, validatePluginRequirements, validatePluginRequirementsEffect, validatePluginsOrThrow };
 //# sourceMappingURL=index.d.cts.map