next-workflow-builder 0.1.0

package/src/plugins/_template/index.ts.txt

@@ -0,0 +1,122 @@
+/**
+ * PLUGIN INDEX TEMPLATE
+ *
+ * This is the main plugin definition file. It registers your integration
+ * and defines all actions, configuration fields, and metadata.
+ *
+ * Instructions:
+ * 1. Replace all [PLACEHOLDERS] with your integration's values
+ * 2. Run `pnpm discover-plugins` after creating your plugin
+ */
+
+import type { IntegrationPlugin } from "../registry";
+import { registerIntegration } from "../registry";
+import { [IntegrationName]Icon } from "./icon";
+
+const [integrationName]Plugin: IntegrationPlugin = {
+  // Must be unique and match your folder name (e.g., "my-integration")
+  type: "[integration-type]",
+
+  // Display name shown in the UI
+  label: "[Integration Name]",
+
+  // Brief description of what this integration does
+  description: "[Integration Description]",
+
+  // Icon component - imported from ./icon.tsx
+  // Can be a custom SVG component or use a Lucide icon directly
+  icon: [IntegrationName]Icon,
+
+  // Form fields for the integration settings dialog
+  // These define what credentials/config users need to provide
+  formFields: [
+    {
+      id: "apiKey",
+      label: "API Key",
+      type: "password", // "password" | "text" | "url"
+      placeholder: "[api-key-prefix]...",
+      configKey: "apiKey", // Key stored in database
+      envVar: "[INTEGRATION_NAME]_API_KEY", // Environment variable name
+      helpText: "Get your API key from ",
+      helpLink: {
+        text: "[integration-name].com/api-keys",
+        url: "https://[integration-name].com/api-keys",
+      },
+    },
+    // Add more fields as needed (e.g., workspace ID, region, etc.)
+  ],
+
+  // Test function for validating credentials
+  // Lazy-loaded to avoid bundling server code in client
+  testConfig: {
+    getTestFunction: async () => {
+      const { test[IntegrationName] } = await import("./test");
+      return test[IntegrationName];
+    },
+  },
+
+  // Actions provided by this integration
+  actions: [
+    {
+      // Unique slug for this action (used in URLs and IDs)
+      // Full action ID will be: "[integration-type]/[slug]"
+      slug: "[action-slug]",
+
+      // Display name and description
+      label: "[Action Label]",
+      description: "[Action Description]",
+
+      // Category for grouping in the action picker (usually integration name)
+      category: "[Integration Name]",
+
+      // Step function name and import path
+      // The function must be exported from plugins/[integration]/steps/[stepImportPath].ts
+      stepFunction: "[actionName]Step",
+      stepImportPath: "[action-slug]",
+
+      // Declarative config fields for the action
+      // Supported types: "template-input", "template-textarea", "text", "number", "select", "schema-builder"
+      configFields: [
+        {
+          key: "fieldA",
+          label: "Field A",
+          type: "template-input", // Supports {{NodeName.field}} syntax
+          placeholder: "Enter value or use {{NodeName.field}}",
+          example: "example value", // Used in AI prompt generation
+          required: true,
+        },
+        {
+          key: "fieldB",
+          label: "Field B",
+          type: "template-textarea",
+          placeholder: "Multi-line content...",
+          rows: 5,
+        },
+        // For select fields:
+        // {
+        //   key: "option",
+        //   label: "Option",
+        //   type: "select",
+        //   options: [
+        //     { value: "a", label: "Option A" },
+        //     { value: "b", label: "Option B" },
+        //   ],
+        //   defaultValue: "a",
+        // },
+        // For conditional fields:
+        // {
+        //   key: "conditionalField",
+        //   label: "Conditional Field",
+        //   type: "text",
+        //   showWhen: { field: "option", equals: "b" },
+        // },
+      ],
+    },
+    // Add more actions as needed
+  ],
+};
+
+// Auto-register on import
+registerIntegration([integrationName]Plugin);
+
+export default [integrationName]Plugin;

package/src/plugins/_template/steps/action.ts.txt

@@ -0,0 +1,103 @@
+/**
+ * STEP FUNCTION TEMPLATE
+ *
+ * This file contains the server-side execution logic for your action.
+ *
+ * Structure:
+ * 1. `stepHandler` - Core logic that receives credentials as a parameter
+ * 2. `[actionName]Step` - Entry point that fetches credentials and wraps with logging
+ *
+ * TODO:
+ * 1. Update the input/result types to match your action's fields
+ * 2. Implement your API call logic in stepHandler
+ * 3. The step function must be exported and match the name in index.ts
+ */
+
+import { fetchCredentials } from "@/lib/credential-fetcher";
+import { type StepInput, withStepLogging } from "@/lib/steps/step-handler";
+import { getErrorMessage } from "@/lib/utils";
+import type { [IntegrationName]Credentials } from "../credentials";
+
+// TODO: Customize result fields for your action
+type [ActionName]Result =
+  | { success: true; resultId: string }
+  | { success: false; error: string };
+
+// Core input fields
+export type [ActionName]CoreInput = {
+  fieldA: string;
+  fieldB?: string;
+};
+
+// Full input includes integrationId and step context
+export type [ActionName]Input = StepInput &
+  [ActionName]CoreInput & {
+    integrationId?: string;
+  };
+
+/**
+ * Core logic
+ */
+async function stepHandler(
+  input: [ActionName]CoreInput,
+  credentials: [IntegrationName]Credentials
+): Promise<[ActionName]Result> {
+  const apiKey = credentials.[INTEGRATION_NAME]_API_KEY;
+
+  if (!apiKey) {
+    return {
+      success: false,
+      error:
+        "[INTEGRATION_NAME]_API_KEY is not configured. Please add it in Project Integrations.",
+    };
+  }
+
+  try {
+    // Your API call or business logic here
+    // Example:
+    // const client = new MyClient(apiKey);
+    // const result = await client.doSomething(input.fieldA);
+
+    const response = await fetch("https://api.[integration-name].com/endpoint", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify({
+        fieldA: input.fieldA,
+        fieldB: input.fieldB,
+      }),
+    });
+
+    if (!response.ok) {
+      throw new Error(`API request failed: ${response.statusText}`);
+    }
+
+    const result = await response.json();
+
+    return { success: true, resultId: result.id };
+  } catch (error) {
+    return {
+      success: false,
+      error: `Failed to execute action: ${getErrorMessage(error)}`,
+    };
+  }
+}
+
+/**
+ * Step entry point
+ */
+export async function [actionName]Step(
+  input: [ActionName]Input
+): Promise<[ActionName]Result> {
+  "use step";
+
+  const credentials = input.integrationId
+    ? await fetchCredentials(input.integrationId)
+    : {};
+
+  return withStepLogging(input, () => stepHandler(input, credentials));
+}
+
+export const _integrationType = "[integration-type]";

package/src/plugins/_template/test.ts.txt

@@ -0,0 +1,57 @@
+/**
+ * TEST FUNCTION TEMPLATE
+ *
+ * This function validates credentials when users click "Test Connection".
+ * It should verify credentials are valid without performing destructive actions.
+ *
+ * The function is lazy-loaded via getTestFunction() in index.ts to avoid
+ * bundling server-side code in the client.
+ *
+ * Approaches for testing:
+ * 1. Format validation (e.g., check API key prefix)
+ * 2. Lightweight API call (e.g., fetch user info, list resources)
+ * 3. Dedicated test endpoint if the API provides one
+ */
+
+export async function test[IntegrationName](credentials: Record<string, string>) {
+  try {
+    const apiKey = credentials.[INTEGRATION_NAME]_API_KEY;
+
+    // Validate API key is provided
+    if (!apiKey) {
+      return {
+        success: false,
+        error: "[INTEGRATION_NAME]_API_KEY is required",
+      };
+    }
+
+    // Option 1: Format validation (if API keys have a known format)
+    // if (!apiKey.startsWith("sk_")) {
+    //   return {
+    //     success: false,
+    //     error: "Invalid API key format. API keys should start with 'sk_'",
+    //   };
+    // }
+
+    // Option 2: Make a lightweight API call to verify the key works
+    const response = await fetch("https://api.[integration-name].com/v1/test", {
+      method: "GET",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`,
+      },
+    });
+
+    if (response.ok) {
+      return { success: true };
+    }
+
+    const error = await response.text();
+    return { success: false, error: error || "Invalid API key" };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}

package/src/plugins/condition/components/condition-fields.tsx

@@ -0,0 +1,32 @@
+import { Label } from "../../../client/components/ui/label";
+import { TemplateBadgeInput } from "../../../client/components/ui/template-badge-input";
+
+// Condition fields component
+function ConditionFields({
+  config,
+  onUpdateConfig,
+  disabled,
+}: {
+  config: Record<string, unknown>;
+  onUpdateConfig: (key: string, value: string) => void;
+  disabled: boolean;
+}) {
+  return (
+    <div className="space-y-2">
+      <Label htmlFor="condition">Condition Expression</Label>
+      <TemplateBadgeInput
+        disabled={ disabled }
+        id="condition"
+        onChange={ (value) => onUpdateConfig("condition", value) }
+        placeholder="e.g., 5 > 3, status === 200, {{PreviousNode.value}} > 100"
+        value={ (config?.condition as string) || "" }
+      />
+      <p className="text-muted-foreground text-xs">
+        Enter a JavaScript expression that evaluates to true or false. You can
+        use @ to reference previous node outputs.
+      </p>
+    </div>
+  );
+}
+
+export { ConditionFields };

package/src/plugins/condition/index.ts

@@ -0,0 +1,27 @@
+import { GitBranchIcon } from "lucide-react";
+import type { IntegrationPlugin } from "../registry";
+
+const conditionPlugin: IntegrationPlugin = {
+  type: "condition",
+  label: "Condition",
+  description: "",
+  icon: GitBranchIcon,
+  isBuiltIn: true,
+
+  formFields: [],
+
+  actions: [
+    {
+      slug: "iterate",
+      label: "Iterate",
+      description: "Split data into batches and iterate over each batch",
+      category: "System",
+      stepFunction: "iterateStep",
+      stepImportPath: "iterate",
+      configFields: [],
+      outputFields: [],
+    },
+  ],
+};
+
+export default conditionPlugin;

package/src/plugins/condition/steps/evaluate.ts

@@ -0,0 +1,32 @@
+/**
+ * Executable step function for Condition action
+ */
+import { StepInput, withStepLogging } from "../../../lib/steps/step-handler";
+
+export type ConditionInput = StepInput & {
+  condition: boolean;
+  /** Original condition expression string for logging (e.g., "{{@nodeId:Label.field}} === 'good'") */
+  expression?: string;
+  /** Resolved values of template variables for logging (e.g., { "Label.field": "actual_value" }) */
+  values?: Record<string, unknown>;
+};
+
+type ConditionResult = {
+  condition: boolean;
+};
+
+function evaluateCondition(input: ConditionInput): ConditionResult {
+  return { condition: input.condition };
+}
+
+// biome-ignore lint/suspicious/useAwait: workflow "use step" requires async
+export async function conditionStep(
+  input: ConditionInput,
+): Promise<ConditionResult> {
+  "use step";
+  return withStepLogging(input, () =>
+    Promise.resolve(evaluateCondition(input)),
+  );
+}
+
+conditionStep.maxRetries = 0;

package/src/plugins/database/components/database-query-fields.tsx

@@ -0,0 +1,58 @@
+import { CodeEditor } from "../../../client/components/ui/code-editor";
+import { Label } from "../../../client/components/ui/label";
+import { SchemaBuilder, SchemaField } from "../../../client/components/workflow/config/schema-builder";
+
+// Database Query fields component
+function DatabaseQueryFields({
+  config,
+  onUpdateConfig,
+  disabled,
+}: {
+  config: Record<string, unknown>;
+  onUpdateConfig: (key: string, value: string) => void;
+  disabled: boolean;
+}) {
+  return (
+    <>
+      <div className="space-y-2">
+        <Label htmlFor="dbQuery">SQL Query</Label>
+        <div className="overflow-hidden rounded-md border">
+          <CodeEditor
+            defaultLanguage="sql"
+            height="150px"
+            onChange={ (value) => onUpdateConfig("dbQuery", value || "") }
+            options={ {
+              minimap: { enabled: false },
+              lineNumbers: "on",
+              scrollBeyondLastLine: false,
+              fontSize: 12,
+              readOnly: disabled,
+              wordWrap: "off",
+            } }
+            value={ (config?.dbQuery as string) || "" }
+          />
+        </div>
+        <p className="text-muted-foreground text-xs">
+          The DATABASE_URL from your project integrations will be used to
+          execute this query.
+        </p>
+      </div>
+      <div className="space-y-2">
+        <Label>Schema (Optional)</Label>
+        <SchemaBuilder
+          disabled={ disabled }
+          onChange={ (schema) =>
+            onUpdateConfig("dbSchema", JSON.stringify(schema))
+          }
+          schema={
+            config?.dbSchema
+              ? (JSON.parse(config.dbSchema as string) as SchemaField[])
+              : []
+          }
+        />
+      </div>
+    </>
+  );
+}
+
+export { DatabaseQueryFields };

package/src/plugins/database/index.ts

@@ -0,0 +1,27 @@
+import { DatabaseIcon } from "lucide-react";
+import type { IntegrationPlugin } from "../registry";
+
+const databasePlugin: IntegrationPlugin = {
+  type: "database",
+  label: "Database",
+  description: "",
+  icon: DatabaseIcon,
+  isBuiltIn: true,
+
+  formFields: [],
+
+  actions: [
+    {
+      slug: "query",
+      label: "Query",
+      description: "Execute a database query",
+      category: "Database",
+      stepFunction: "databaseQueryStep",
+      stepImportPath: "query",
+      configFields: [],
+      outputFields: [],
+    },
+  ],
+};
+
+export default databasePlugin;

package/src/plugins/database/steps/query.ts

@@ -0,0 +1,141 @@
+/**
+ * Executable step function for Database Query action
+ *
+ * SECURITY PATTERN - External Secret Store:
+ * Step fetches credentials using workflow ID reference
+ */
+import { sql } from "drizzle-orm";
+import { drizzle } from "drizzle-orm/postgres-js";
+import postgres from "postgres";
+import { fetchCredentials } from "../../../lib/credential-fetcher";
+import { type StepInput, withStepLogging } from "../../../lib/steps/step-handler";
+
+type DatabaseQueryResult =
+  | { success: true; rows: unknown; count: number }
+  | { success: false; error: string };
+
+export type DatabaseQueryInput = StepInput & {
+  integrationId?: string;
+  dbQuery?: string;
+  query?: string;
+};
+
+function validateInput(input: DatabaseQueryInput): string | null {
+  const queryString = input.dbQuery || input.query;
+
+  if (!queryString || queryString.trim() === "") {
+    return "SQL query is required";
+  }
+
+  return null;
+}
+
+function createDatabaseClient(databaseUrl: string): postgres.Sql {
+  return postgres(databaseUrl, {
+    max: 1,
+    connect_timeout: 10,
+    idle_timeout: 20,
+  });
+}
+
+async function executeQuery(
+  client: postgres.Sql,
+  queryString: string,
+): Promise<unknown> {
+  const db = drizzle(client);
+  return await db.execute(sql.raw(queryString));
+}
+
+function getDatabaseErrorMessage(error: unknown): string {
+  if (!(error instanceof Error)) {
+    return "Unknown database error";
+  }
+
+  const errorMessage = error.message;
+
+  if (errorMessage.includes("ECONNREFUSED")) {
+    return "Connection refused. Please check your database URL and ensure the database is running.";
+  }
+  if (errorMessage.includes("ENOTFOUND")) {
+    return "Database host not found. Please check your database URL.";
+  }
+  if (errorMessage.includes("authentication failed")) {
+    return "Authentication failed. Please check your database credentials.";
+  }
+  if (errorMessage.includes("does not exist")) {
+    return `Database error: ${ errorMessage }`;
+  }
+
+  return errorMessage;
+}
+
+async function cleanupClient(client: postgres.Sql | null): Promise<void> {
+  if (client) {
+    try {
+      await client.end();
+    } catch {
+      // Ignore errors during cleanup
+    }
+  }
+}
+
+/**
+ * Database query logic
+ */
+async function query(
+  input: DatabaseQueryInput,
+): Promise<DatabaseQueryResult> {
+  const validationError = validateInput(input);
+  if (validationError) {
+    return { success: false, error: validationError };
+  }
+
+  const credentials = input.integrationId
+    ? await fetchCredentials(input.integrationId)
+    : {};
+
+  const databaseUrl = credentials.DATABASE_URL;
+
+  if (!databaseUrl) {
+    return {
+      success: false,
+      error:
+        "DATABASE_URL is not configured. Please add it in Project Integrations.",
+    };
+  }
+
+  const queryString = (input.dbQuery || input.query) as string;
+  let client: postgres.Sql | null = null;
+
+  try {
+    client = createDatabaseClient(databaseUrl);
+    const result = await executeQuery(client, queryString);
+    await client.end();
+
+    return {
+      success: true,
+      rows: result,
+      count: Array.isArray(result) ? result.length : 0,
+    };
+  } catch (error) {
+    await cleanupClient(client);
+    return {
+      success: false,
+      error: `Database query failed: ${ getDatabaseErrorMessage(error) }`,
+    };
+  }
+}
+
+/**
+ * Database Query Step
+ * Executes a SQL query against a PostgreSQL database
+ */
+// biome-ignore lint/suspicious/useAwait: workflow "use step" requires async
+export async function databaseQueryStep(
+  input: DatabaseQueryInput,
+): Promise<DatabaseQueryResult> {
+  "use step";
+  return withStepLogging(input, () => query(input));
+}
+
+databaseQueryStep.maxRetries = 0;

package/src/plugins/index.ts

@@ -0,0 +1,37 @@
+// Export the lib utilities
+export { getErrorMessage, getErrorMessageAsync } from "../lib/utils";
+export type { IntegrationType } from "../lib/types/integration";
+export { fetchCredentials } from "../lib/credential-fetcher";
+export { type StepInput, withStepLogging } from "../lib/steps/step-handler";
+
+// Export the registry utilities
+export {
+  registerIntegration,
+  getAllIntegrations,
+  registerCodegenTemplates,
+  getCodegenTemplate,
+  registerOutputDisplayConfigs,
+  getOutputDisplayConfig,
+} from "./registry";
+export type { SerializableOutputDisplayConfig, ResultComponentProps, IntegrationPlugin } from "./registry";
+
+// Export the steps utilities
+export type { StepImporter } from "../lib/steps/index";
+
+// Export managed connection types, atoms, and registration for plugins that provide managed key flows
+export {
+  registerManagedConnectionProvider,
+  managedConnectionProviderAtom,
+  managedConnectionStatusAtom,
+  managedConnectionTeamsAtom,
+  managedConnectionTeamsLoadingAtom,
+  managedConnectionTeamsFetchedAtom,
+} from "../lib/managed-connection";
+export type {
+  ManagedConnectionProvider,
+  ManagedConnectionApi,
+  ManagedConnectionStatus,
+  ManagedConnectionTeam,
+  ManagedConsentResponse,
+  ConsentOverlayProps,
+} from "../lib/managed-connection";

package/src/plugins/legacy-mappings.ts

@@ -0,0 +1,11 @@
+/**
+ * Legacy Action Mappings
+ *
+ * This file maps old action type names to new namespaced action IDs.
+ * Used for backward compatibility with existing workflows.
+ *
+ * Format: "Old Label" -> "plugin-type/action-slug"
+ *
+ * TODO: Remove this file once all workflows have been migrated to the new format.
+ */
+export const LEGACY_ACTION_MAPPINGS: Record<string, string> = {};