@flowdrop/flowdrop 1.15.0 → 2.0.0-beta.2

package/dist/utils/colors.js

@@ -3,9 +3,6 @@
  * Ensures consistent category colors across sidebar and canvas
  * Uses BEM syntax for CSS classes
  */
-import { getPortCompatibilityChecker } from './connections.js';
-import { getCategoryColor as getCategoryColorFromStore } from '../stores/categoriesStore.svelte.js';
-import { logger } from './logger.js';
 /**
  * Category color mapping to design tokens (CSS variables)
  * Uses --fd-node-* tokens from tokens.css
@@ -67,51 +64,38 @@ const DEFAULT_DATA_TYPE_COLORS = {
  * Get the design token for a category color.
  * Checks the categories store first (which includes API overrides),
  * then falls back to the static CATEGORY_COLOR_TOKENS map, then to slate.
+ * @param categories - The instance's categories store (e.g. `fd.categories`)
+ * @param category - The node category
  */
-export function getCategoryColorToken(category) {
-    return getCategoryColorFromStore(category);
+export function getCategoryColorToken(categories, category) {
+    return categories.getColor(category);
 }
 /**
  * Get the reference color token for a data type (configurable version)
+ * @param checker - The instance's port compatibility checker (provides data-type config)
+ * @param dataType - The data type
  */
-export function getDataTypeColorToken(dataType) {
-    try {
-        const checker = getPortCompatibilityChecker();
-        const config = checker.getDataTypeConfig(dataType);
-        if (config?.color) {
-            return config.color;
-        }
-    }
-    catch {
-        // Fallback to static color mapping if port checker not initialized
+export function getDataTypeColorToken(checker, dataType) {
+    const config = checker.getDataTypeConfig(dataType);
+    if (config?.color) {
+        return config.color;
     }
     return DEFAULT_DATA_TYPE_COLORS[dataType.toLowerCase()] || 'var(--fd-node-slate)';
 }
 /**
  * Get data type configuration from port config
+ * @param checker - The instance's port compatibility checker
+ * @param dataType - The data type
  */
-export function getDataTypeConfig(dataType) {
-    try {
-        const checker = getPortCompatibilityChecker();
-        return checker.getDataTypeConfig(dataType);
-    }
-    catch (error) {
-        logger.warn('Port compatibility checker not initialized:', error);
-        return undefined;
-    }
+export function getDataTypeConfig(checker, dataType) {
+    return checker.getDataTypeConfig(dataType);
 }
 /**
  * Get all available data types from port configuration
+ * @param checker - The instance's port compatibility checker
  */
-export function getAvailableDataTypes() {
-    try {
-        const checker = getPortCompatibilityChecker();
-        return checker.getEnabledDataTypes();
-    }
-    catch (error) {
-        logger.warn('Port compatibility checker not initialized:', error);
-        return [];
-    }
+export function getAvailableDataTypes(checker) {
+    return checker.getEnabledDataTypes();
 }
 /**
  * Default colors for fallback cases
@@ -124,54 +108,60 @@ export const DEFAULT_COLORS = {
 };
 /**
  * Get category colors
+ * @param categories - The instance's categories store (e.g. `fd.categories`)
  * @param category - The node category
  * @returns The color configuration for the category
  */
-export function getCategoryColors(category) {
-    return getCategoryColorFromStore(category);
+export function getCategoryColors(categories, category) {
+    return categories.getColor(category);
 }
 /**
  * Get category background color
+ * @param categories - The instance's categories store (e.g. `fd.categories`)
  * @param category - The node category
  * @returns The background color class
  */
-export function getCategoryBackground(category) {
-    return getCategoryColors(category);
+export function getCategoryBackground(categories, category) {
+    return getCategoryColors(categories, category);
 }
 /**
  * Get category accent color
+ * @param categories - The instance's categories store (e.g. `fd.categories`)
  * @param category - The node category
  * @returns The accent color class
  */
-export function getCategoryAccent(category) {
-    return getCategoryColors(category);
+export function getCategoryAccent(categories, category) {
+    return getCategoryColors(categories, category);
 }
 /**
  * Get category text color
+ * @param categories - The instance's categories store (e.g. `fd.categories`)
  * @param category - The node category
  * @returns The text color class
  */
-export function getCategoryText(category) {
-    return getCategoryColors(category);
+export function getCategoryText(categories, category) {
+    return getCategoryColors(categories, category);
 }
 /**
  * Get category border color
+ * @param categories - The instance's categories store (e.g. `fd.categories`)
  * @param category - The node category
  * @returns The border color class
  */
-export function getCategoryBorder(category) {
-    return getCategoryColors(category);
+export function getCategoryBorder(categories, category) {
+    return getCategoryColors(categories, category);
 }
 /**
  * Get node colors based on category and state
+ * @param categories - The instance's categories store (e.g. `fd.categories`)
  * @param category - The node category
  * @param isError - Whether the node is in error state
  * @param isProcessing - Whether the node is processing
  * @param isSelected - Whether the node is selected
  * @returns The color configuration object
  */
-export function getNodeColors(category, isError = false, isProcessing = false, isSelected = false) {
-    const baseColor = getCategoryColors(category);
+export function getNodeColors(categories, category, isError = false, isProcessing = false, isSelected = false) {
+    const baseColor = getCategoryColors(categories, category);
     if (isError) {
         return {
             background: 'var(--fd-error-muted)',
@@ -205,67 +195,73 @@ export function getNodeColors(category, isError = false, isProcessing = false, i
 }
 /**
  * Get node background color
+ * @param categories - The instance's categories store (e.g. `fd.categories`)
  * @param category - The node category
  * @param isError - Whether the node is in error state
  * @param isProcessing - Whether the node is processing
  * @param isSelected - Whether the node is selected
  * @returns The background color
  */
-export function getNodeBackground(category, isError = false, isProcessing = false, isSelected = false) {
-    return getNodeColors(category, isError, isProcessing, isSelected).background;
+export function getNodeBackground(categories, category, isError = false, isProcessing = false, isSelected = false) {
+    return getNodeColors(categories, category, isError, isProcessing, isSelected).background;
 }
 /**
  * Get node accent color
+ * @param categories - The instance's categories store (e.g. `fd.categories`)
  * @param category - The node category
  * @param isError - Whether the node is in error state
  * @param isProcessing - Whether the node is processing
  * @param isSelected - Whether the node is selected
  * @returns The accent color
  */
-export function getNodeAccent(category, isError = false, isProcessing = false, isSelected = false) {
-    return getNodeColors(category, isError, isProcessing, isSelected).accent;
+export function getNodeAccent(categories, category, isError = false, isProcessing = false, isSelected = false) {
+    return getNodeColors(categories, category, isError, isProcessing, isSelected).accent;
 }
 /**
  * Get node text color
+ * @param categories - The instance's categories store (e.g. `fd.categories`)
  * @param category - The node category
  * @param isError - Whether the node is in error state
  * @param isProcessing - Whether the node is processing
  * @param isSelected - Whether the node is selected
  * @returns The text color
  */
-export function getNodeText(category, isError = false, isProcessing = false, isSelected = false) {
-    return getNodeColors(category, isError, isProcessing, isSelected).text;
+export function getNodeText(categories, category, isError = false, isProcessing = false, isSelected = false) {
+    return getNodeColors(categories, category, isError, isProcessing, isSelected).text;
 }
 /**
  * Get node border color
+ * @param categories - The instance's categories store (e.g. `fd.categories`)
  * @param category - The node category
  * @param isError - Whether the node is in error state
  * @param isProcessing - Whether the node is processing
  * @param isSelected - Whether the node is selected
  * @returns The border color
  */
-export function getNodeBorder(category, isError = false, isProcessing = false, isSelected = false) {
-    return getNodeColors(category, isError, isProcessing, isSelected).border;
+export function getNodeBorder(categories, category, isError = false, isProcessing = false, isSelected = false) {
+    return getNodeColors(categories, category, isError, isProcessing, isSelected).border;
 }
 /**
  * Get data type color
+ * @param checker - The instance's port compatibility checker
  * @param dataType - The data type
  * @returns The color for the data type
  */
-export function getDataTypeColor(dataType) {
-    return getDataTypeColorToken(dataType);
+export function getDataTypeColor(checker, dataType) {
+    return getDataTypeColorToken(checker, dataType);
 }
 /**
  * Parse typed array notation and get display information
+ * @param checker - The instance's port compatibility checker
  * @param dataType - The data type (e.g., "string[]", "number", "object[]")
  * @returns Object with display information
  */
-export function parseDataTypeDisplay(dataType) {
+export function parseDataTypeDisplay(checker, dataType) {
     // Check if it's a typed array (ends with [])
     const isArray = dataType.endsWith('[]');
     if (isArray) {
         const elementType = dataType.slice(0, -2); // Remove []
-        const config = getDataTypeConfig(dataType);
+        const config = getDataTypeConfig(checker, dataType);
         return {
             baseType: dataType,
             isArray: true,
@@ -274,7 +270,7 @@ export function parseDataTypeDisplay(dataType) {
         };
     }
     else {
-        const config = getDataTypeConfig(dataType);
+        const config = getDataTypeConfig(checker, dataType);
         return {
             baseType: dataType,
             isArray: false,
@@ -284,11 +280,12 @@ export function parseDataTypeDisplay(dataType) {
 }
 /**
  * Get formatted display text for a data type
+ * @param checker - The instance's port compatibility checker
  * @param dataType - The data type
  * @returns Formatted display text
  */
-export function getDataTypeDisplayText(dataType) {
-    const parsed = parseDataTypeDisplay(dataType);
+export function getDataTypeDisplayText(checker, dataType) {
+    const parsed = parseDataTypeDisplay(checker, dataType);
     return parsed.displayName;
 }
 /**
@@ -391,42 +388,46 @@ export function resolveColorToken(token) {
 }
 /**
  * Get the appropriate contrast text color for a data type badge
+ * @param checker - The instance's port compatibility checker
  * @param dataType - The data type (e.g., "array", "string", "number")
  * @returns CSS color value for text that provides good contrast on the data type's background
  */
-export function getContrastTextColorForDataType(dataType) {
-    const colorToken = getDataTypeColorToken(dataType);
+export function getContrastTextColorForDataType(checker, dataType) {
+    const colorToken = getDataTypeColorToken(checker, dataType);
     const hexColor = resolveColorToken(colorToken);
     return getContrastTextColor(hexColor);
 }
 /**
  * Get the appropriate contrast text color for a category badge
+ * @param categories - The instance's categories store (e.g. `fd.categories`)
  * @param category - The node category
  * @returns CSS color value for text that provides good contrast on the category's background
  */
-export function getContrastTextColorForCategory(category) {
-    const colorToken = getCategoryColorToken(category);
+export function getContrastTextColorForCategory(categories, category) {
+    const colorToken = getCategoryColorToken(categories, category);
     const hexColor = resolveColorToken(colorToken);
     return getContrastTextColor(hexColor);
 }
 /**
  * Get a semi-transparent tinted background color for ports
  * Creates a cohesive look with the icon wrapper styling
+ * @param checker - The instance's port compatibility checker
  * @param dataType - The data type
  * @param opacity - Opacity percentage (default 25%)
  * @returns CSS color-mix expression for the tinted background
  */
-export function getPortBackgroundColor(dataType, opacity = 25) {
-    const colorToken = getDataTypeColorToken(dataType);
+export function getPortBackgroundColor(checker, dataType, opacity = 25) {
+    const colorToken = getDataTypeColorToken(checker, dataType);
     return `color-mix(in srgb, ${colorToken} ${opacity}%, transparent)`;
 }
 /**
  * Get the border color for ports (solid data type color)
+ * @param checker - The instance's port compatibility checker
  * @param dataType - The data type
  * @returns CSS color value for the port border
  */
-export function getPortBorderColor(dataType) {
-    return getDataTypeColorToken(dataType);
+export function getPortBorderColor(checker, dataType) {
+    return getDataTypeColorToken(checker, dataType);
 }
 /**
  * Convert RGB components to hex color string

package/dist/utils/connections.d.ts

@@ -32,6 +32,12 @@ export declare class PortCompatibilityChecker {
     private portConfig;
     private compatibilityMap;
     constructor(portConfig: PortConfig);
+    /**
+     * Replace the port configuration and rebuild the compatibility map in place.
+     * Used by mount to apply the backend-fetched port config to an instance's
+     * checker without swapping the instance field.
+     */
+    reinitialize(portConfig: PortConfig): void;
     /**
      * Build the compatibility map from configuration rules
      */
@@ -53,22 +59,10 @@ export declare class PortCompatibilityChecker {
      */
     getEnabledDataTypes(): PortDataTypeConfig[];
 }
-/**
- * Initialize the global port compatibility checker
- */
-export declare function initializePortCompatibility(portConfig: PortConfig): void;
-/**
- * Returns true if the port compatibility checker has been initialized.
- */
-export declare function isPortCompatibilityInitialized(): boolean;
-/**
- * Get the global port compatibility checker
- */
-export declare function getPortCompatibilityChecker(): PortCompatibilityChecker;
 /**
  * Get all possible connections from a source node to target nodes
  */
-export declare function getPossibleConnections(sourceNode: WorkflowNode, targetNodes: WorkflowNode[], nodeTypes: NodeMetadata[]): Array<{
+export declare function getPossibleConnections(checker: PortCompatibilityChecker, sourceNode: WorkflowNode, targetNodes: WorkflowNode[], nodeTypes: NodeMetadata[]): Array<{
     sourceNodeId: string;
     sourcePortId: string;
     sourcePort: NodePort;
@@ -80,14 +74,14 @@ export declare function getPossibleConnections(sourceNode: WorkflowNode, targetN
 /**
  * Validate if a specific connection is valid
  */
-export declare function validateConnection(sourceNodeId: string, sourcePortId: string, targetNodeId: string, targetPortId: string, nodes: WorkflowNode[], nodeTypes: NodeMetadata[]): {
+export declare function validateConnection(checker: PortCompatibilityChecker, sourceNodeId: string, sourcePortId: string, targetNodeId: string, targetPortId: string, nodes: WorkflowNode[], nodeTypes: NodeMetadata[]): {
     valid: boolean;
     error?: string;
 };
 /**
  * Get connection suggestions for a node
  */
-export declare function getConnectionSuggestions(nodeId: string, nodes: WorkflowNode[], nodeTypes: NodeMetadata[]): Array<{
+export declare function getConnectionSuggestions(checker: PortCompatibilityChecker, nodeId: string, nodes: WorkflowNode[], nodeTypes: NodeMetadata[]): Array<{
     nodeId: string;
     nodeName: string;
     portId: string;

package/dist/utils/connections.js

@@ -45,6 +45,15 @@ export class PortCompatibilityChecker {
         this.compatibilityMap = new Map();
         this.buildCompatibilityMap();
     }
+    /**
+     * Replace the port configuration and rebuild the compatibility map in place.
+     * Used by mount to apply the backend-fetched port config to an instance's
+     * checker without swapping the instance field.
+     */
+    reinitialize(portConfig) {
+        this.portConfig = portConfig;
+        this.buildCompatibilityMap();
+    }
     /**
      * Build the compatibility map from configuration rules
      */
@@ -106,41 +115,16 @@ export class PortCompatibilityChecker {
         return this.portConfig.dataTypes.filter((dt) => dt.enabled !== false);
     }
 }
-// Global instance - will be initialized with configuration
-let globalCompatibilityChecker = null;
-/**
- * Initialize the global port compatibility checker
- */
-export function initializePortCompatibility(portConfig) {
-    globalCompatibilityChecker = new PortCompatibilityChecker(portConfig);
-}
-/**
- * Returns true if the port compatibility checker has been initialized.
- */
-export function isPortCompatibilityInitialized() {
-    return globalCompatibilityChecker !== null;
-}
-/**
- * Get the global port compatibility checker
- */
-export function getPortCompatibilityChecker() {
-    if (!globalCompatibilityChecker) {
-        throw new Error('Port compatibility checker not initialized. Call initializePortCompatibility() first.');
-    }
-    return globalCompatibilityChecker;
-}
 /**
  * Get all possible connections from a source node to target nodes
  */
-export function getPossibleConnections(sourceNode, targetNodes, nodeTypes) {
+export function getPossibleConnections(checker, sourceNode, targetNodes, nodeTypes) {
     const sourceMetadata = nodeTypes.find((nt) => nt.id === sourceNode.data.metadata.id);
     if (!sourceMetadata)
         return [];
     const possibleConnections = [];
     // Get all output ports from source node
     const sourceOutputs = sourceMetadata.outputs;
-    // Get the compatibility checker instance
-    const checker = getPortCompatibilityChecker();
     // Check each target node
     for (const targetNode of targetNodes) {
         if (targetNode.id === sourceNode.id)
@@ -171,7 +155,7 @@ export function getPossibleConnections(sourceNode, targetNodes, nodeTypes) {
 /**
  * Validate if a specific connection is valid
  */
-export function validateConnection(sourceNodeId, sourcePortId, targetNodeId, targetPortId, nodes, nodeTypes) {
+export function validateConnection(checker, sourceNodeId, sourcePortId, targetNodeId, targetPortId, nodes, nodeTypes) {
     // Check if nodes exist
     const sourceNode = nodes.find((n) => n.id === sourceNodeId);
     const targetNode = nodes.find((n) => n.id === targetNodeId);
@@ -200,8 +184,7 @@ export function validateConnection(sourceNodeId, sourcePortId, targetNodeId, tar
     if (!targetPort) {
         return { valid: false, error: 'Target port not found' };
     }
-    // Check data type compatibility using the global checker
-    const checker = getPortCompatibilityChecker();
+    // Check data type compatibility using the instance's checker
     if (!checker.areDataTypesCompatible(sourcePort.dataType, targetPort.dataType)) {
         return {
             valid: false,
@@ -213,7 +196,7 @@ export function validateConnection(sourceNodeId, sourcePortId, targetNodeId, tar
 /**
  * Get connection suggestions for a node
  */
-export function getConnectionSuggestions(nodeId, nodes, nodeTypes) {
+export function getConnectionSuggestions(checker, nodeId, nodes, nodeTypes) {
     const node = nodes.find((n) => n.id === nodeId);
     if (!node)
         return [];
@@ -223,8 +206,6 @@ export function getConnectionSuggestions(nodeId, nodes, nodeTypes) {
     const suggestions = [];
     // Get all other nodes
     const otherNodes = nodes.filter((n) => n.id !== nodeId);
-    // Get the compatibility checker instance
-    const checker = getPortCompatibilityChecker();
     for (const otherNode of otherNodes) {
         const otherMetadata = nodeTypes.find((nt) => nt.id === otherNode.data.metadata.id);
         if (!otherMetadata)

package/dist/utils/duration.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Duration formatting helpers.
+ *
+ * Mirrors the backend `Drupal\flowdrop\Utility\Duration::formatMicroseconds()`
+ * tiers so the playground and the Drupal admin pages render identical values.
+ */
+/**
+ * Formats a duration in human-readable form from microseconds.
+ *
+ * Examples: `150µs`, `2.5ms`, `25.1ms`, `250ms`, `1.23s`, `45s`,
+ * `2m 30s`, `1h 30m`.
+ */
+export declare function formatMicroseconds(microseconds: number | null | undefined): string | null;

package/dist/utils/duration.js

@@ -0,0 +1,45 @@
+/**
+ * Duration formatting helpers.
+ *
+ * Mirrors the backend `Drupal\flowdrop\Utility\Duration::formatMicroseconds()`
+ * tiers so the playground and the Drupal admin pages render identical values.
+ */
+/**
+ * Formats a duration in human-readable form from microseconds.
+ *
+ * Examples: `150µs`, `2.5ms`, `25.1ms`, `250ms`, `1.23s`, `45s`,
+ * `2m 30s`, `1h 30m`.
+ */
+export function formatMicroseconds(microseconds) {
+    if (microseconds == null || !Number.isFinite(microseconds) || microseconds < 0)
+        return null;
+    const us = Math.round(microseconds);
+    if (us < 1000) {
+        return `${us}µs`;
+    }
+    if (us < 1_000_000) {
+        const ms = us / 1000;
+        if (us < 100_000) {
+            // 2 decimals below 10ms, 1 decimal below 100ms — matches PHP round().
+            const decimals = us < 10_000 ? 2 : 1;
+            // Drop trailing zeros the way PHP round() renders (2.50 → 2.5, 3.00 → 3).
+            return `${parseFloat(ms.toFixed(decimals))}ms`;
+        }
+        return `${Math.round(ms)}ms`;
+    }
+    if (us < 10_000_000) {
+        return `${parseFloat((us / 1_000_000).toFixed(2))}s`;
+    }
+    if (us < 60_000_000) {
+        return `${Math.floor(us / 1_000_000)}s`;
+    }
+    const totalSeconds = Math.floor(us / 1_000_000);
+    if (us < 3_600_000_000) {
+        const minutes = Math.floor(totalSeconds / 60);
+        const secs = totalSeconds % 60;
+        return secs > 0 ? `${minutes}m ${secs}s` : `${minutes}m`;
+    }
+    const hours = Math.floor(totalSeconds / 3600);
+    const minutes = Math.floor((totalSeconds % 3600) / 60);
+    return minutes > 0 ? `${hours}h ${minutes}m` : `${hours}h`;
+}

package/dist/utils/edgeStyling.js

@@ -5,10 +5,14 @@
  * visual styling to workflow edges based on source port data types.
  * Used by both the visual editor and the command DSL system.
  */
-import { MarkerType } from '@xyflow/svelte';
 import { extractPortId } from '../utils/handleIds.js';
 import { isLoopbackEdge } from '../utils/connections.js';
 import { EDGE_MARKER_SIZES } from '../config/constants.js';
+// xyflow's `MarkerType.ArrowClosed`, inlined as its literal value. This module
+// is shared with the headless command DSL (reachable from `@flowdrop/flowdrop/core`),
+// so it must NOT carry a runtime import of @xyflow/svelte — a type-only import
+// plus this constant keeps the marker type-safe without the dependency.
+const ARROW_CLOSED_MARKER = 'arrowclosed';
 /**
  * Check if a port ID matches a dynamic branch in a Gateway node.
  * Gateway nodes store branches in config.branches array.
@@ -101,7 +105,7 @@ export function applyConnectionStyling(edge, sourceNode, targetNode) {
                 'stroke: var(--fd-edge-loopback); stroke-dasharray: var(--fd-edge-loopback-dasharray); stroke-width: var(--fd-edge-loopback-width); opacity: var(--fd-edge-loopback-opacity);';
             edge.class = 'flowdrop--edge--loopback';
             edge.markerEnd = {
-                type: MarkerType.ArrowClosed,
+                type: ARROW_CLOSED_MARKER,
                 ...EDGE_MARKER_SIZES.loopback,
                 color: 'var(--fd-edge-loopback)'
             };
@@ -110,7 +114,7 @@ export function applyConnectionStyling(edge, sourceNode, targetNode) {
             edge.style = 'stroke: var(--fd-edge-trigger); stroke-width: var(--fd-edge-trigger-width);';
             edge.class = 'flowdrop--edge--trigger';
             edge.markerEnd = {
-                type: MarkerType.ArrowClosed,
+                type: ARROW_CLOSED_MARKER,
                 ...EDGE_MARKER_SIZES.trigger,
                 color: 'var(--fd-edge-trigger)'
             };
@@ -119,7 +123,7 @@ export function applyConnectionStyling(edge, sourceNode, targetNode) {
             edge.style = 'stroke: var(--fd-edge-tool); stroke-dasharray: 5 3;';
             edge.class = 'flowdrop--edge--tool';
             edge.markerEnd = {
-                type: MarkerType.ArrowClosed,
+                type: ARROW_CLOSED_MARKER,
                 ...EDGE_MARKER_SIZES.tool,
                 color: 'var(--fd-edge-tool)'
             };
@@ -129,7 +133,7 @@ export function applyConnectionStyling(edge, sourceNode, targetNode) {
             edge.style = 'stroke: var(--fd-edge-data);';
             edge.class = 'flowdrop--edge--data';
             edge.markerEnd = {
-                type: MarkerType.ArrowClosed,
+                type: ARROW_CLOSED_MARKER,
                 ...EDGE_MARKER_SIZES.data,
                 color: 'var(--fd-edge-data)'
             };

package/dist/utils/fetchWithAuth.d.ts

@@ -1,25 +1,46 @@
 /**
- * Fetch authentication utilities
+ * Authenticated fetch
  *
- * Shared logic for building HTTP headers with authentication.
- * Used by components that make authenticated API requests (e.g., FormAutocomplete).
+ * The single fetch path for FlowDrop's per-instance services. It builds request
+ * headers (static endpoint headers + the {@link AuthProvider}'s headers + any
+ * caller headers) and uniformly applies the auth lifecycle: on `401` it invokes
+ * `onUnauthorized()` and — if that reports a successful refresh — retries the
+ * request once with freshly fetched headers; on `403` it invokes
+ * `onForbidden()`. Callers receive the raw {@link Response} and keep their own
+ * status/parse handling.
+ *
+ * Routing every service through this helper means a configured `AuthProvider`
+ * authenticates *and* refreshes consistently — matching the behaviour the typed
+ * workflow/node API gets from {@link EnhancedFlowDropApiClient}.
  *
  * @module utils/fetchWithAuth
  */
+import type { EndpointConfig } from '../config/endpoints.js';
 import type { AuthProvider } from '../types/auth.js';
 /**
- * Build fetch headers with optional authentication
- *
- * Constructs standard JSON request headers and merges in authentication
- * headers from the provided AuthProvider, if available.
+ * Options describing how to authenticate and where the base headers come from.
  *
- * @param authProvider - Optional auth provider to get headers from
- * @returns Promise resolving to a complete headers object
+ * Provide `config` + `endpointKey` to source static endpoint headers (the usual
+ * case for endpoint-keyed services), or `baseHeaders` for ad-hoc requests that
+ * are not tied to a configured endpoint (e.g. a user-configured autocomplete
+ * URL). When neither is given the request carries only JSON defaults plus auth.
+ */
+export interface AuthenticatedFetchOptions {
+    /** Auth provider supplying `Authorization` etc. and 401/403 lifecycle hooks. */
+    authProvider?: AuthProvider;
+    /** Endpoint configuration, used with `endpointKey` to look up static headers. */
+    config?: EndpointConfig;
+    /** Endpoint key identifying which static headers to apply. */
+    endpointKey?: string;
+    /** Base headers for requests not tied to a configured endpoint. */
+    baseHeaders?: Record<string, string>;
+}
+/**
+ * Perform an authenticated fetch with consistent 401/403 handling.
  *
- * @example
- * ```typescript
- * const headers = await buildFetchHeaders(authProvider);
- * const response = await fetch(url, { headers });
- * ```
+ * @param url - The fully-resolved request URL
+ * @param init - Standard fetch options (method, body, signal, headers, …)
+ * @param opts - Auth provider and header source
+ * @returns The raw {@link Response}; callers handle `.ok`/parsing themselves
  */
-export declare function buildFetchHeaders(authProvider?: AuthProvider): Promise<Record<string, string>>;
+export declare function authenticatedFetch(url: string, init?: RequestInit, opts?: AuthenticatedFetchOptions): Promise<Response>;