@uploadista/core 0.0.2

package/dist/flow/parallel-scheduler.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Parallel execution scheduler for flow nodes.
+ *
+ * The ParallelScheduler analyzes flow dependencies and groups nodes into execution
+ * levels where nodes at the same level can run in parallel. It manages concurrency
+ * using Effect's built-in concurrency control to prevent resource exhaustion.
+ *
+ * @module flow/parallel-scheduler
+ * @see {@link ParallelScheduler} for the main scheduler class
+ *
+ * @remarks
+ * This scheduler groups nodes by execution level (respecting dependencies) and executes
+ * each level in parallel with controlled concurrency. Levels are executed sequentially
+ * to ensure dependencies are satisfied before dependent nodes execute.
+ *
+ * @example
+ * ```typescript
+ * const scheduler = new ParallelScheduler({ maxConcurrency: 4 });
+ *
+ * // Group nodes by execution level
+ * const levels = scheduler.groupNodesByExecutionLevel(nodes, edges);
+ *
+ * // Execute nodes in a level with Effect
+ * const results = yield* scheduler.executeNodesInParallel([
+ *   () => executeNode("node1"),
+ *   () => executeNode("node2"),
+ *   () => executeNode("node3")
+ * ]);
+ * ```
+ */
+import { Effect } from "effect";
+import type { FlowNode } from "./types/flow-types";
+/**
+ * Represents a level in the execution hierarchy where all nodes can run in parallel.
+ *
+ * @property level - The execution level (0 = first to execute, higher = later)
+ * @property nodes - Array of node IDs that can execute in parallel at this level
+ *
+ * @example
+ * ```
+ * Level 0: [input_node]           (no dependencies)
+ * Level 1: [resize, optimize]     (all depend on level 0)
+ * Level 2: [storage]              (depends on level 1)
+ * ```
+ */
+export interface ExecutionLevel {
+    level: number;
+    nodes: string[];
+}
+/**
+ * Configuration options for the ParallelScheduler.
+ *
+ * @property maxConcurrency - Maximum number of nodes to execute in parallel (default: 4)
+ *                           Controls how many nodes run simultaneously within a level
+ *
+ * @example
+ * ```typescript
+ * const scheduler = new ParallelScheduler({ maxConcurrency: 8 });
+ * ```
+ */
+export interface ParallelSchedulerConfig {
+    maxConcurrency?: number;
+}
+/**
+ * Scheduler for executing flow nodes in parallel while respecting dependencies.
+ *
+ * The scheduler performs topological sorting to identify nodes that can run
+ * concurrently, groups them into execution levels, and provides methods to
+ * execute them with controlled concurrency using Effect.
+ *
+ * Key responsibilities:
+ * - Analyze flow dependencies and detect cycles
+ * - Group nodes into parallel execution levels
+ * - Execute levels in parallel with concurrency limits
+ * - Provide utilities to check parallel execution feasibility
+ */
+export declare class ParallelScheduler {
+    private maxConcurrency;
+    /**
+     * Creates a new ParallelScheduler instance.
+     *
+     * @param config - Configuration for the scheduler
+     * @example
+     * ```typescript
+     * const scheduler = new ParallelScheduler({ maxConcurrency: 4 });
+     * ```
+     */
+    constructor(config?: ParallelSchedulerConfig);
+    /**
+     * Groups nodes into execution levels where nodes in the same level can run in parallel.
+     *
+     * Uses Kahn's algorithm to perform topological sorting with level identification.
+     * Nodes are grouped by their distance from source nodes (input nodes with no dependencies).
+     *
+     * @param nodes - Array of flow nodes to analyze
+     * @param edges - Array of edges defining dependencies between nodes
+     * @returns Array of execution levels, ordered from 0 (no dependencies) onwards
+     * @throws Error if a cycle is detected in the flow graph
+     *
+     * @example
+     * ```typescript
+     * const levels = scheduler.groupNodesByExecutionLevel(nodes, edges);
+     * // levels = [
+     * //   { level: 0, nodes: ['input_1'] },
+     * //   { level: 1, nodes: ['resize_1', 'optimize_1'] },
+     * //   { level: 2, nodes: ['output_1'] }
+     * // ]
+     * ```
+     */
+    groupNodesByExecutionLevel(nodes: FlowNode<unknown, unknown>[], edges: Array<{
+        source: string;
+        target: string;
+    }>): ExecutionLevel[];
+    /**
+     * Executes a batch of Effect-based node executors in parallel with concurrency control.
+     *
+     * All executors are run in parallel, but the number of concurrent executions is limited
+     * by maxConcurrency. This prevents resource exhaustion while maximizing parallelism.
+     *
+     * @template T - The return type of each executor
+     * @template E - The error type of the Effects
+     * @template R - The requirements type of the Effects
+     *
+     * @param nodeExecutors - Array of Effect-returning functions to execute in parallel
+     * @returns Effect that resolves to array of results in the same order as input
+     *
+     * @example
+     * ```typescript
+     * const results = yield* scheduler.executeNodesInParallel([
+     *   () => executeNode("node1"),
+     *   () => executeNode("node2"),
+     *   () => executeNode("node3")
+     * ]);
+     * // results will be in order: [result1, result2, result3]
+     * ```
+     */
+    executeNodesInParallel<T, E, R>(nodeExecutors: Array<() => Effect.Effect<T, E, R>>): Effect.Effect<T[], E, R>;
+    /**
+     * Determines if a set of nodes can be safely executed in parallel.
+     *
+     * Nodes can execute in parallel if all their dependencies have been completed.
+     * This is typically called to verify that nodes in an execution level are ready
+     * to run given the current node results.
+     *
+     * @param nodeIds - Array of node IDs to check
+     * @param nodeResults - Map of completed node IDs to their results
+     * @param reverseGraph - Dependency graph mapping node IDs to their incoming dependencies
+     * @returns true if all dependencies for all nodes are in nodeResults, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const canRun = scheduler.canExecuteInParallel(
+     *   ['resize_1', 'optimize_1'],
+     *   nodeResults,
+     *   reverseGraph
+     * );
+     * ```
+     */
+    canExecuteInParallel(nodeIds: string[], nodeResults: Map<string, unknown>, reverseGraph: Record<string, string[]>): boolean;
+    /**
+     * Gets execution statistics for monitoring and debugging.
+     *
+     * @returns Object containing current scheduler configuration
+     *
+     * @example
+     * ```typescript
+     * const stats = scheduler.getStats();
+     * console.log(`Max concurrency: ${stats.maxConcurrency}`);
+     * ```
+     */
+    getStats(): {
+        maxConcurrency: number;
+    };
+}
+//# sourceMappingURL=parallel-scheduler.d.ts.map

package/dist/flow/parallel-scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parallel-scheduler.d.ts","sourceRoot":"","sources":["../../src/flow/parallel-scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,uBAAuB;IACtC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,cAAc,CAAS;IAE/B;;;;;;;;OAQG;gBACS,MAAM,GAAE,uBAA4B;IAIhD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,0BAA0B,CACxB,KAAK,EAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,EACnC,KAAK,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,GAC/C,cAAc,EAAE;IAwDnB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,sBAAsB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAC5B,aAAa,EAAE,KAAK,CAAC,MAAM,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,GACjD,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;IAS3B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,oBAAoB,CAClB,OAAO,EAAE,MAAM,EAAE,EACjB,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,GACrC,OAAO;IAOV;;;;;;;;;;OAUG;IACH,QAAQ;;;CAKT"}

package/dist/flow/parallel-scheduler.js

@@ -0,0 +1,193 @@
+/**
+ * Parallel execution scheduler for flow nodes.
+ *
+ * The ParallelScheduler analyzes flow dependencies and groups nodes into execution
+ * levels where nodes at the same level can run in parallel. It manages concurrency
+ * using Effect's built-in concurrency control to prevent resource exhaustion.
+ *
+ * @module flow/parallel-scheduler
+ * @see {@link ParallelScheduler} for the main scheduler class
+ *
+ * @remarks
+ * This scheduler groups nodes by execution level (respecting dependencies) and executes
+ * each level in parallel with controlled concurrency. Levels are executed sequentially
+ * to ensure dependencies are satisfied before dependent nodes execute.
+ *
+ * @example
+ * ```typescript
+ * const scheduler = new ParallelScheduler({ maxConcurrency: 4 });
+ *
+ * // Group nodes by execution level
+ * const levels = scheduler.groupNodesByExecutionLevel(nodes, edges);
+ *
+ * // Execute nodes in a level with Effect
+ * const results = yield* scheduler.executeNodesInParallel([
+ *   () => executeNode("node1"),
+ *   () => executeNode("node2"),
+ *   () => executeNode("node3")
+ * ]);
+ * ```
+ */
+import { Effect } from "effect";
+/**
+ * Scheduler for executing flow nodes in parallel while respecting dependencies.
+ *
+ * The scheduler performs topological sorting to identify nodes that can run
+ * concurrently, groups them into execution levels, and provides methods to
+ * execute them with controlled concurrency using Effect.
+ *
+ * Key responsibilities:
+ * - Analyze flow dependencies and detect cycles
+ * - Group nodes into parallel execution levels
+ * - Execute levels in parallel with concurrency limits
+ * - Provide utilities to check parallel execution feasibility
+ */
+export class ParallelScheduler {
+    maxConcurrency;
+    /**
+     * Creates a new ParallelScheduler instance.
+     *
+     * @param config - Configuration for the scheduler
+     * @example
+     * ```typescript
+     * const scheduler = new ParallelScheduler({ maxConcurrency: 4 });
+     * ```
+     */
+    constructor(config = {}) {
+        this.maxConcurrency = config.maxConcurrency ?? 4;
+    }
+    /**
+     * Groups nodes into execution levels where nodes in the same level can run in parallel.
+     *
+     * Uses Kahn's algorithm to perform topological sorting with level identification.
+     * Nodes are grouped by their distance from source nodes (input nodes with no dependencies).
+     *
+     * @param nodes - Array of flow nodes to analyze
+     * @param edges - Array of edges defining dependencies between nodes
+     * @returns Array of execution levels, ordered from 0 (no dependencies) onwards
+     * @throws Error if a cycle is detected in the flow graph
+     *
+     * @example
+     * ```typescript
+     * const levels = scheduler.groupNodesByExecutionLevel(nodes, edges);
+     * // levels = [
+     * //   { level: 0, nodes: ['input_1'] },
+     * //   { level: 1, nodes: ['resize_1', 'optimize_1'] },
+     * //   { level: 2, nodes: ['output_1'] }
+     * // ]
+     * ```
+     */
+    groupNodesByExecutionLevel(nodes, edges) {
+        // Build dependency graph
+        const graph = {};
+        const inDegree = {};
+        // Initialize graph structure
+        nodes.forEach((node) => {
+            graph[node.id] = [];
+            inDegree[node.id] = 0;
+        });
+        // Build edges and calculate in-degrees
+        edges.forEach((edge) => {
+            graph[edge.source]?.push(edge.target);
+            inDegree[edge.target] = (inDegree[edge.target] || 0) + 1;
+        });
+        const levels = [];
+        const processedNodes = new Set();
+        let levelIndex = 0;
+        // Use Kahn's algorithm to group nodes by level
+        while (processedNodes.size < nodes.length) {
+            // Find all nodes with zero in-degree that haven't been processed
+            const currentLevelNodes = Object.keys(inDegree).filter((nodeId) => inDegree[nodeId] === 0 && !processedNodes.has(nodeId));
+            if (currentLevelNodes.length === 0) {
+                throw new Error("Cycle detected in flow graph - cannot execute in parallel");
+            }
+            levels.push({
+                level: levelIndex++,
+                nodes: currentLevelNodes,
+            });
+            // Remove current level nodes and update in-degrees for dependent nodes
+            currentLevelNodes.forEach((nodeId) => {
+                processedNodes.add(nodeId);
+                delete inDegree[nodeId];
+                // Decrease in-degree for all nodes that depend on this node
+                graph[nodeId]?.forEach((dependentId) => {
+                    if (inDegree[dependentId] !== undefined) {
+                        inDegree[dependentId]--;
+                    }
+                });
+            });
+        }
+        return levels;
+    }
+    /**
+     * Executes a batch of Effect-based node executors in parallel with concurrency control.
+     *
+     * All executors are run in parallel, but the number of concurrent executions is limited
+     * by maxConcurrency. This prevents resource exhaustion while maximizing parallelism.
+     *
+     * @template T - The return type of each executor
+     * @template E - The error type of the Effects
+     * @template R - The requirements type of the Effects
+     *
+     * @param nodeExecutors - Array of Effect-returning functions to execute in parallel
+     * @returns Effect that resolves to array of results in the same order as input
+     *
+     * @example
+     * ```typescript
+     * const results = yield* scheduler.executeNodesInParallel([
+     *   () => executeNode("node1"),
+     *   () => executeNode("node2"),
+     *   () => executeNode("node3")
+     * ]);
+     * // results will be in order: [result1, result2, result3]
+     * ```
+     */
+    executeNodesInParallel(nodeExecutors) {
+        return Effect.all(nodeExecutors.map((executor) => executor()), {
+            concurrency: this.maxConcurrency,
+        });
+    }
+    /**
+     * Determines if a set of nodes can be safely executed in parallel.
+     *
+     * Nodes can execute in parallel if all their dependencies have been completed.
+     * This is typically called to verify that nodes in an execution level are ready
+     * to run given the current node results.
+     *
+     * @param nodeIds - Array of node IDs to check
+     * @param nodeResults - Map of completed node IDs to their results
+     * @param reverseGraph - Dependency graph mapping node IDs to their incoming dependencies
+     * @returns true if all dependencies for all nodes are in nodeResults, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const canRun = scheduler.canExecuteInParallel(
+     *   ['resize_1', 'optimize_1'],
+     *   nodeResults,
+     *   reverseGraph
+     * );
+     * ```
+     */
+    canExecuteInParallel(nodeIds, nodeResults, reverseGraph) {
+        return nodeIds.every((nodeId) => {
+            const dependencies = reverseGraph[nodeId] || [];
+            return dependencies.every((depId) => nodeResults.has(depId));
+        });
+    }
+    /**
+     * Gets execution statistics for monitoring and debugging.
+     *
+     * @returns Object containing current scheduler configuration
+     *
+     * @example
+     * ```typescript
+     * const stats = scheduler.getStats();
+     * console.log(`Max concurrency: ${stats.maxConcurrency}`);
+     * ```
+     */
+    getStats() {
+        return {
+            maxConcurrency: this.maxConcurrency,
+        };
+    }
+}

package/dist/flow/plugins/credential-provider.d.ts

@@ -0,0 +1,47 @@
+import { Context, type Effect } from "effect";
+import type { UploadistaError } from "@/errors";
+/**
+ * Shape definition for the Credential Provider interface.
+ * Defines the contract for retrieving credentials for various services.
+ */
+export interface CredentialProviderShape {
+    /**
+     * Retrieves credentials for a specific service and client.
+     *
+     * @param params - Parameters for credential retrieval
+     * @param params.clientId - Unique identifier for the client, or null if not available
+     * @param params.serviceType - Optional service type to get specific credentials for
+     * @returns An Effect that resolves to a record of credential key-value pairs
+     * @throws {UploadistaError} When credential retrieval fails
+     */
+    getCredential: (params: {
+        clientId: string | null;
+        serviceType?: string;
+    }) => Effect.Effect<Record<string, unknown>, UploadistaError>;
+}
+declare const CredentialProvider_base: Context.TagClass<CredentialProvider, "CredentialProvider", CredentialProviderShape>;
+/**
+ * Context tag for the Credential Provider.
+ *
+ * This tag provides a type-safe way to access credential functionality
+ * throughout the application using Effect's dependency injection system.
+ *
+ * @example
+ * ```typescript
+ * import { CredentialProvider } from "@uploadista/core/flow/plugins";
+ *
+ * // In your flow node
+ * const program = Effect.gen(function* () {
+ *   const credentialProvider = yield* CredentialProvider;
+ *   const credentials = yield* credentialProvider.getCredential({
+ *     clientId: "user123",
+ *     serviceType: "replicate"
+ *   });
+ *   return credentials;
+ * });
+ * ```
+ */
+export declare class CredentialProvider extends CredentialProvider_base {
+}
+export {};
+//# sourceMappingURL=credential-provider.d.ts.map

package/dist/flow/plugins/credential-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-provider.d.ts","sourceRoot":"","sources":["../../../src/flow/plugins/credential-provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAEhD;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;;;;;OAQG;IACH,aAAa,EAAE,CAAC,MAAM,EAAE;QACtB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,KAAK,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,CAAC,CAAC;CAC/D;;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,kBAAmB,SAAQ,uBAGrC;CAAG"}

package/dist/flow/plugins/credential-provider.js

@@ -0,0 +1,24 @@
+import { Context } from "effect";
+/**
+ * Context tag for the Credential Provider.
+ *
+ * This tag provides a type-safe way to access credential functionality
+ * throughout the application using Effect's dependency injection system.
+ *
+ * @example
+ * ```typescript
+ * import { CredentialProvider } from "@uploadista/core/flow/plugins";
+ *
+ * // In your flow node
+ * const program = Effect.gen(function* () {
+ *   const credentialProvider = yield* CredentialProvider;
+ *   const credentials = yield* credentialProvider.getCredential({
+ *     clientId: "user123",
+ *     serviceType: "replicate"
+ *   });
+ *   return credentials;
+ * });
+ * ```
+ */
+export class CredentialProvider extends Context.Tag("CredentialProvider")() {
+}

package/dist/flow/plugins/image-ai-plugin.d.ts

@@ -0,0 +1,61 @@
+import type { UploadistaError } from "@uploadista/core/errors";
+import { Context, type Effect } from "effect";
+/**
+ * Context information for AI image processing operations.
+ * Contains client identification for tracking and billing purposes.
+ */
+export type ImageAiContext = {
+    /** Unique identifier for the client making the request, or null if not available */
+    clientId: string | null;
+};
+/**
+ * Shape definition for the Image AI Plugin interface.
+ * Defines the contract that all image AI implementations must follow.
+ */
+export type ImageAiPluginShape = {
+    /**
+     * Removes the background from an image using AI processing.
+     *
+     * @param inputUrl - The URL of the input image to process
+     * @param context - Context information including client ID for tracking
+     * @returns An Effect that resolves to an object containing the output image URL
+     * @throws {UploadistaError} When the background removal fails
+     */
+    removeBackground: (inputUrl: string, context: ImageAiContext) => Effect.Effect<{
+        outputUrl: string;
+    }, UploadistaError>;
+    /**
+     * Generates a textual description of an image using AI analysis.
+     *
+     * @param inputUrl - The URL of the input image to analyze
+     * @param context - Context information including client ID for tracking
+     * @returns An Effect that resolves to an object containing the image description
+     * @throws {UploadistaError} When the image analysis fails
+     */
+    describeImage: (inputUrl: string, context: ImageAiContext) => Effect.Effect<{
+        description: string;
+    }, UploadistaError>;
+};
+declare const ImageAiPlugin_base: Context.TagClass<ImageAiPlugin, "ImageAiPlugin", ImageAiPluginShape>;
+/**
+ * Context tag for the Image AI Plugin.
+ *
+ * This tag provides a type-safe way to access image AI functionality
+ * throughout the application using Effect's dependency injection system.
+ *
+ * @example
+ * ```typescript
+ * import { ImageAiPlugin } from "@uploadista/core/flow/plugins";
+ *
+ * // In your flow node
+ * const program = Effect.gen(function* () {
+ *   const imageAi = yield* ImageAiPlugin;
+ *   const result = yield* imageAi.removeBackground(imageUrl, { clientId: "user123" });
+ *   return result.outputUrl;
+ * });
+ * ```
+ */
+export declare class ImageAiPlugin extends ImageAiPlugin_base {
+}
+export {};
+//# sourceMappingURL=image-ai-plugin.d.ts.map

package/dist/flow/plugins/image-ai-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-ai-plugin.d.ts","sourceRoot":"","sources":["../../../src/flow/plugins/image-ai-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,QAAQ,CAAC;AAE9C;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,oFAAoF;IACpF,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B;;;;;;;OAOG;IACH,gBAAgB,EAAE,CAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,cAAc,KACpB,MAAM,CAAC,MAAM,CAAC;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,EAAE,eAAe,CAAC,CAAC;IAE3D;;;;;;;OAOG;IACH,aAAa,EAAE,CACb,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,cAAc,KACpB,MAAM,CAAC,MAAM,CAAC;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,EAAE,eAAe,CAAC,CAAC;CAC9D,CAAC;;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,aAAc,SAAQ,kBAGhC;CAAG"}

package/dist/flow/plugins/image-ai-plugin.js

@@ -0,0 +1,21 @@
+import { Context } from "effect";
+/**
+ * Context tag for the Image AI Plugin.
+ *
+ * This tag provides a type-safe way to access image AI functionality
+ * throughout the application using Effect's dependency injection system.
+ *
+ * @example
+ * ```typescript
+ * import { ImageAiPlugin } from "@uploadista/core/flow/plugins";
+ *
+ * // In your flow node
+ * const program = Effect.gen(function* () {
+ *   const imageAi = yield* ImageAiPlugin;
+ *   const result = yield* imageAi.removeBackground(imageUrl, { clientId: "user123" });
+ *   return result.outputUrl;
+ * });
+ * ```
+ */
+export class ImageAiPlugin extends Context.Tag("ImageAiPlugin")() {
+}

package/dist/flow/plugins/image-plugin.d.ts

@@ -0,0 +1,52 @@
+import type { UploadistaError } from "@uploadista/core/errors";
+import { Context, type Effect } from "effect";
+import type { OptimizeParams } from "./types/optimize-node";
+import type { ResizeParams } from "./types/resize-node";
+/**
+ * Shape definition for the Image Plugin interface.
+ * Defines the contract that all image processing implementations must follow.
+ */
+export type ImagePluginShape = {
+    /**
+     * Optimizes an image by adjusting quality and format.
+     *
+     * @param input - The input image as a Uint8Array
+     * @param options - Optimization parameters including quality and format
+     * @returns An Effect that resolves to the optimized image as a Uint8Array
+     * @throws {UploadistaError} When image optimization fails
+     */
+    optimize: (input: Uint8Array, options: OptimizeParams) => Effect.Effect<Uint8Array, UploadistaError>;
+    /**
+     * Resizes an image to specified dimensions.
+     *
+     * @param input - The input image as a Uint8Array
+     * @param options - Resize parameters including width, height, and fit mode
+     * @returns An Effect that resolves to the resized image as a Uint8Array
+     * @throws {UploadistaError} When image resizing fails
+     */
+    resize: (input: Uint8Array, options: ResizeParams) => Effect.Effect<Uint8Array, UploadistaError>;
+};
+declare const ImagePlugin_base: Context.TagClass<ImagePlugin, "ImagePlugin", ImagePluginShape>;
+/**
+ * Context tag for the Image Plugin.
+ *
+ * This tag provides a type-safe way to access image processing functionality
+ * throughout the application using Effect's dependency injection system.
+ *
+ * @example
+ * ```typescript
+ * import { ImagePlugin } from "@uploadista/core/flow/plugins";
+ *
+ * // In your flow node
+ * const program = Effect.gen(function* () {
+ *   const imagePlugin = yield* ImagePlugin;
+ *   const optimized = yield* imagePlugin.optimize(imageData, { quality: 80, format: "webp" });
+ *   const resized = yield* imagePlugin.resize(optimized, { width: 800, height: 600, fit: "cover" });
+ *   return resized;
+ * });
+ * ```
+ */
+export declare class ImagePlugin extends ImagePlugin_base {
+}
+export {};
+//# sourceMappingURL=image-plugin.d.ts.map

package/dist/flow/plugins/image-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-plugin.d.ts","sourceRoot":"","sources":["../../../src/flow/plugins/image-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;;;;;;OAOG;IACH,QAAQ,EAAE,CACR,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,cAAc,KACpB,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,eAAe,CAAC,CAAC;IAEhD;;;;;;;OAOG;IACH,MAAM,EAAE,CACN,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,YAAY,KAClB,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,eAAe,CAAC,CAAC;CACjD,CAAC;;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,WAAY,SAAQ,gBAG9B;CAAG"}

package/dist/flow/plugins/image-plugin.js

@@ -0,0 +1,22 @@
+import { Context } from "effect";
+/**
+ * Context tag for the Image Plugin.
+ *
+ * This tag provides a type-safe way to access image processing functionality
+ * throughout the application using Effect's dependency injection system.
+ *
+ * @example
+ * ```typescript
+ * import { ImagePlugin } from "@uploadista/core/flow/plugins";
+ *
+ * // In your flow node
+ * const program = Effect.gen(function* () {
+ *   const imagePlugin = yield* ImagePlugin;
+ *   const optimized = yield* imagePlugin.optimize(imageData, { quality: 80, format: "webp" });
+ *   const resized = yield* imagePlugin.resize(optimized, { width: 800, height: 600, fit: "cover" });
+ *   return resized;
+ * });
+ * ```
+ */
+export class ImagePlugin extends Context.Tag("ImagePlugin")() {
+}

package/dist/flow/plugins/types/describe-image-node.d.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+/**
+ * Zod schema for validating describe image node parameters.
+ * Defines the structure and validation rules for image description requests.
+ */
+export declare const describeImageParamsSchema: z.ZodObject<{
+    serviceType: z.ZodOptional<z.ZodEnum<{
+        replicate: "replicate";
+    }>>;
+}, z.core.$strip>;
+/**
+ * Parameters for the describe image node.
+ * Controls which AI service to use for generating image descriptions.
+ */
+export type DescribeImageParams = z.infer<typeof describeImageParamsSchema>;
+//# sourceMappingURL=describe-image-node.d.ts.map

package/dist/flow/plugins/types/describe-image-node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-image-node.d.ts","sourceRoot":"","sources":["../../../../src/flow/plugins/types/describe-image-node.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,eAAO,MAAM,yBAAyB;;;;iBAGpC,CAAC;AAEH;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC"}

package/dist/flow/plugins/types/describe-image-node.js

@@ -0,0 +1,9 @@
+import { z } from "zod";
+/**
+ * Zod schema for validating describe image node parameters.
+ * Defines the structure and validation rules for image description requests.
+ */
+export const describeImageParamsSchema = z.object({
+    /** Optional service type to use for image description (currently supports "replicate") */
+    serviceType: z.enum(["replicate"]).optional(),
+});

package/dist/flow/plugins/types/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Re-exports all type definitions for flow plugin nodes.
+ * This module provides a centralized way to import all plugin node types.
+ */
+export * from "./describe-image-node";
+export * from "./optimize-node";
+export * from "./remove-background-node";
+export * from "./resize-node";
+//# sourceMappingURL=index.d.ts.map

package/dist/flow/plugins/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/flow/plugins/types/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,uBAAuB,CAAC;AACtC,cAAc,iBAAiB,CAAC;AAChC,cAAc,0BAA0B,CAAC;AACzC,cAAc,eAAe,CAAC"}

package/dist/flow/plugins/types/index.js

@@ -0,0 +1,8 @@
+/**
+ * Re-exports all type definitions for flow plugin nodes.
+ * This module provides a centralized way to import all plugin node types.
+ */
+export * from "./describe-image-node";
+export * from "./optimize-node";
+export * from "./remove-background-node";
+export * from "./resize-node";