@invect/core 0.0.1

package/dist/actions/types.d.cts

@@ -0,0 +1,373 @@
+import { Logger } from "../types/schemas-fresh/invect-config.cjs";
+import { FlowEdge, FlowNodeDefinitions } from "../services/flow-versions/schemas-fresh.cjs";
+import { AgentPromptResult } from "../types/agent-tool.types.cjs";
+import { SubmitPromptRequest } from "../services/node-data.service.cjs";
+import { RecordToolExecutionInput, SubmitAgentPromptRequest, SubmitPromptResult } from "../types-fresh.cjs";
+import { NodeDefinition } from "../types/node-definition.types.cjs";
+import { CredentialsService } from "../services/credentials/credentials.service.cjs";
+import { BaseAIClient } from "../services/ai/base-client.cjs";
+import { z } from "zod/v4";
+
+//#region src/actions/types.d.ts
+/**
+ * Provider category for UI organisation and palette grouping.
+ */
+type ProviderCategory = 'email' | 'messaging' | 'storage' | 'database' | 'development' | 'ai' | 'http' | 'utility' | 'core' | 'custom';
+/**
+ * A provider groups related actions under a service / brand.
+ * Examples: "gmail", "slack", "http", "core".
+ *
+ * Multiple action files can reference the same ProviderDef – the registry
+ * de-duplicates by `id`.
+ */
+interface ProviderDef {
+  /** Unique slug, e.g. "gmail", "slack", "core" */
+  id: string;
+  /** Human-readable name */
+  name: string;
+  /** Lucide icon name for UI (fallback when no static SVG file exists for the provider id) */
+  icon: string;
+  /**
+   * Raw SVG markup for custom provider branding (legacy).
+   *
+   * Prefer adding a static SVG file to `pkg/frontend/src/assets/provider-icons/{id}.svg`
+   * instead. The frontend resolves icons by provider `id` first, then falls back
+   * to `svgIcon`, then to the Lucide `icon` name.
+   */
+  svgIcon?: string;
+  /** Category for palette grouping */
+  category: ProviderCategory;
+  /**
+   * Which section this provider's actions appear in within the node palette.
+   * Maps directly to the frontend sidebar categories.
+   */
+  nodeCategory: 'Common' | 'AI' | 'Data' | 'Logic' | 'IO' | 'Integrations' | 'Custom' | 'Triggers';
+  /** Optional longer description */
+  description?: string;
+  /** Link to provider API docs */
+  docsUrl?: string;
+}
+/**
+ * Declares what kind of credential an action needs (if any).
+ */
+interface CredentialRequirement {
+  required: boolean;
+  type?: 'oauth2' | 'api_key' | 'basic_auth' | 'database' | 'llm';
+  /** OAuth2 provider id from the OAuth2 providers registry */
+  oauth2Provider?: string;
+  /** Shown to the user explaining what the credential is for */
+  description?: string;
+}
+/**
+ * Describes a single parameter field for the config panel / tool schema.
+ */
+interface ParamField {
+  name: string;
+  label: string;
+  type: 'text' | 'textarea' | 'number' | 'boolean' | 'select' | 'json' | 'code';
+  description?: string;
+  placeholder?: string;
+  defaultValue?: unknown;
+  required?: boolean;
+  /** When true, field is hidden from the config panel */
+  hidden?: boolean;
+  options?: {
+    label: string;
+    value: string | number;
+  }[];
+  /** Show in collapsed "More Options" section */
+  extended?: boolean;
+  /**
+   * When true the AI provides this value at runtime (tool mode).
+   * When false the value is treated as a static configuration.
+   * Defaults to `true` when omitted.
+   */
+  aiProvided?: boolean;
+  /**
+   * Declare that this field's options should be loaded from the server
+   * when the values of `dependsOn` fields change.
+   *
+   * The `handler` runs server-side with access to credentials and services.
+   * The frontend only sees the serialised metadata (`dependsOn` + flag).
+   *
+   * Example — load AI models based on the selected credential:
+   * ```ts
+   * loadOptions: {
+   *   dependsOn: ['credentialId'],
+   *   handler: async (deps, ctx) => {
+   *     const cred = await ctx.services.credentials.get(deps.credentialId);
+   *     const models = await fetchModels(cred);
+   *     return { options: models.map(m => ({ label: m.name, value: m.id })) };
+   *   },
+   * }
+   * ```
+   */
+  loadOptions?: LoadOptionsConfig;
+}
+/**
+ * Server-side handler context provided to `loadOptions.handler`.
+ */
+interface LoadOptionsContext {
+  logger: Logger;
+  services: {
+    credentials: CredentialsService;
+  };
+}
+/**
+ * Configuration for dynamic option loading on a field.
+ */
+interface LoadOptionsConfig {
+  /**
+   * Which sibling param fields this depends on.
+   * When any of these change, the frontend calls the server to reload options.
+   */
+  dependsOn: string[];
+  /**
+   * Server-side handler that returns the options for this field.
+   * Receives the current values of the `dependsOn` fields plus the full context.
+   */
+  handler: (dependencyValues: Record<string, unknown>, context: LoadOptionsContext) => Promise<LoadOptionsResult>;
+}
+/**
+ * Result returned by a `loadOptions` handler.
+ */
+interface LoadOptionsResult {
+  /** The options to populate the select/combobox with. */
+  options: {
+    label: string;
+    value: string | number;
+  }[];
+  /** Optional default value to auto-select if the current value is not in the list. */
+  defaultValue?: string | number;
+  /** Optional placeholder text override. */
+  placeholder?: string;
+  /** If true, the field should be disabled (e.g. no options available). */
+  disabled?: boolean;
+}
+/**
+ * Credential shape as provided to an executing action.
+ */
+interface ActionCredential {
+  id: string;
+  name: string;
+  type: string;
+  authType: string;
+  config: Record<string, unknown>;
+}
+/**
+ * Execution context handed to every `execute()` call regardless of whether
+ * the action is running as a flow node or an AI-agent tool.
+ */
+interface ActionExecutionContext {
+  /** Scoped logger */
+  logger: Logger;
+  /** Decrypted credential (null when action doesn't require one) */
+  credential: ActionCredential | null;
+  /**
+   * Upstream node outputs keyed by reference-id.
+   * Present when running inside a flow; `undefined` when running as a standalone tool.
+   */
+  incomingData?: Record<string, unknown>;
+  /**
+   * Flow inputs (top-level inputs provided when starting the flow).
+   * Only present when the action runs as a flow node.
+   */
+  flowInputs?: Record<string, unknown>;
+  /**
+   * Flow-level identifiers. Only present when the action runs as a flow node.
+   */
+  flowContext?: {
+    flowId: string;
+    flowRunId: string;
+    nodeId: string;
+    traceId?: string;
+  };
+  /**
+   * Service functions available from the flow orchestrator.
+   * Only present when running inside a flow. Actions should
+   * gracefully degrade when these are not available (e.g. tool mode).
+   */
+  functions?: {
+    /** Render a Nunjucks template against variables */runTemplateReplacement?: (template: string, variables: Record<string, unknown>) => Promise<string>; /** Submit a prompt to an AI model (for Model node) */
+    submitPrompt?: (request: SubmitPromptRequest) => Promise<SubmitPromptResult>; /** Submit an agent prompt with tools (for Agent node) */
+    submitAgentPrompt?: (request: SubmitAgentPromptRequest) => Promise<AgentPromptResult | {
+      type: 'batch_submitted';
+      batchJobId: string;
+      nodeId: string;
+      flowRunId: string;
+    }>; /** Get a decrypted credential by id */
+    getCredential?: (credentialId: string) => Promise<ActionCredential | null>; /** Mark downstream nodes as skipped (for If-Else node) */
+    markDownstreamNodesAsSkipped?: (nodeId: string, edges: readonly FlowEdge[], skippedNodes: Set<string>, isFromIfElse?: boolean) => void; /** Record a tool execution (for Agent node) */
+    recordToolExecution?: (input: RecordToolExecutionInput) => Promise<{
+      id: string;
+    } | null>;
+  };
+  /**
+   * Additional flow-run context passed through for special nodes (If-Else, Agent).
+   * Not available in tool mode.
+   */
+  flowRunState?: {
+    edges?: readonly FlowEdge[];
+    nodes?: readonly FlowNodeDefinitions[];
+    skippedNodeIds?: Set<string>;
+    flowParams?: Record<string, unknown>;
+    globalConfig?: Record<string, unknown>;
+  };
+}
+/**
+ * Context provided to `onConfigUpdate` — gives access to services needed
+ * for dynamic configuration (e.g. fetching model lists from a provider).
+ */
+interface ActionConfigUpdateContext {
+  logger: Logger;
+  services: {
+    credentials: CredentialsService;
+    baseAIClient: BaseAIClient;
+  };
+}
+/**
+ * Event payload describing which config field changed.
+ */
+interface ActionConfigUpdateEvent {
+  nodeId: string;
+  nodeType: string;
+  flowId?: string;
+  params: Record<string, unknown>;
+  change?: {
+    field: string;
+    value: unknown;
+  };
+}
+/**
+ * Response from `onConfigUpdate` — returns an updated definition and
+ * optionally mutated params, warnings, or errors.
+ */
+interface ActionConfigUpdateResponse {
+  definition: NodeDefinition;
+  params?: Record<string, unknown>;
+  warnings?: string[];
+  errors?: string[];
+}
+/**
+ * Every `execute()` function returns this.
+ * It intentionally matches `AgentToolResult` so tool results need no mapping.
+ *
+ * The `output` field should be one of:
+ *   - `string`           → text, JSON-serialized data, template results
+ *   - plain object/array → structured data (API responses, query results)
+ *   - `undefined`        → batch-pending sentinel (flow pauses, no output stored)
+ *
+ * Avoid returning raw numbers, booleans, `null`, Buffers, Dates, or class instances.
+ * The action executor bridge infers `OutputVariable.type` as `'object'` for non-null
+ * objects, and `'string'` for everything else.
+ */
+interface ActionResult {
+  success: boolean;
+  output?: unknown;
+  error?: string;
+  metadata?: Record<string, unknown>;
+  /**
+   * Optional named output variables.
+   * When provided, the action executor bridge uses these directly
+   * instead of wrapping `output` into a single "output" variable.
+   * Useful for flow-control nodes like If-Else that produce branch-specific outputs.
+   */
+  outputVariables?: Record<string, {
+    value: unknown;
+    type: 'string' | 'object';
+  }>;
+}
+/**
+ * Sub-category within a provider for finer-grained UI grouping.
+ */
+type ActionCategory = 'read' | 'write' | 'delete' | 'manage';
+/**
+ * Complete action definition — the single source of truth for a node/tool.
+ *
+ * @typeParam TParams - Inferred from the Zod `params.schema`
+ */
+interface ActionDefinition<TParams = unknown> {
+  /**
+   * Globally unique action id using `provider.action_name` format.
+   * This is also the **node type** stored in the database and used by the
+   * executor registry.
+   *
+   * Examples: `"gmail.list_messages"`, `"core.javascript"`, `"http.request"`
+   */
+  id: string;
+  /** Human-readable name displayed in the palette and on the node */
+  name: string;
+  /** Description shown in the UI and given to AI agents */
+  description: string;
+  /** Provider this action belongs to */
+  provider: ProviderDef;
+  /** Credential requirements (omit if the action needs no credentials) */
+  credential?: CredentialRequirement;
+  /** Parameter configuration */
+  params: {
+    /** Zod schema — used for validation in both node and tool paths */schema: z.ZodType<TParams>; /** UI field descriptors (drives the config panel and the tool JSON-Schema) */
+    fields: ParamField[];
+  };
+  /**
+   * Custom output handle definitions.
+   * When set, `toNodeDefinition()` will use these instead of the default
+   * single `{ id: 'output', label: 'Output', type: 'object' }` handle.
+   *
+   * Example (if/else node):
+   * ```ts
+   * outputs: [
+   *   { id: 'true_output', label: 'True', type: 'any' },
+   *   { id: 'false_output', label: 'False', type: 'any' },
+   * ]
+   * ```
+   */
+  outputs?: Array<{
+    id: string;
+    label: string;
+    type: string;
+  }>;
+  /**
+   * If true, the node has no input handle (entry-point / trigger nodes).
+   * When set, `toNodeDefinition()` will produce `input: undefined`.
+   */
+  noInput?: boolean;
+  /**
+   * Maximum number of instances of this node type allowed in a single flow.
+   * For example, `maxInstances: 1` ensures only one Manual Trigger per flow.
+   * When omitted there is no limit.
+   */
+  maxInstances?: number;
+  /**
+   * When true the action is still registered and executable but is hidden
+   * from the node palette in the frontend.  Useful for deprecated actions
+   * that must remain functional for backward compatibility.
+   */
+  hidden?: boolean;
+  /** Search / filter tags */
+  tags?: string[];
+  /**
+   * Lucide icon name for this specific action.
+   * When set, overrides `provider.icon` for the node definition.
+   * Use this to give each core node a contextually meaningful icon
+   * instead of inheriting the generic provider icon.
+   */
+  icon?: string;
+  /** Sub-category inside the provider */
+  actionCategory?: ActionCategory;
+  /**
+   * The execute function — called identically whether the action is
+   * running as a flow node or as an AI-agent tool.
+   */
+  execute(params: TParams, context: ActionExecutionContext): Promise<ActionResult>;
+  /**
+   * Optional hook for dynamic configuration updates.
+   * Called when the frontend changes a config field (e.g. selecting a credential
+   * for a Model node triggers fetching the available models).
+   *
+   * If not provided, the default behaviour returns the static definition + params.
+   */
+  onConfigUpdate?(event: ActionConfigUpdateEvent, context: ActionConfigUpdateContext): Promise<ActionConfigUpdateResponse>;
+}
+//#endregion
+export { ActionCategory, ActionConfigUpdateContext, ActionConfigUpdateEvent, ActionConfigUpdateResponse, ActionCredential, ActionDefinition, ActionExecutionContext, ActionResult, CredentialRequirement, LoadOptionsConfig, LoadOptionsContext, LoadOptionsResult, ParamField, ProviderCategory, ProviderDef };
+//# sourceMappingURL=types.d.cts.map

package/dist/actions/types.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.cts","names":[],"sources":["../../src/actions/types.ts"],"mappings":"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"}