@lunnoa/client 2.3.0 → 2.5.0

package/dist/index.d.cts

@@ -715,7 +715,7 @@ interface paths {
         put?: never;
         /**
          * Upsert a workflow by slug from a linear step list
-         * @description Creates or updates a workflow identified by workspace-scoped `slug`. Builds a minimal valid graph (one catalogue trigger, Manually Run when omitted, then linear catalogue-action steps). Marks `managedByCode` by default. Prefer the CLI (`npx @lunnoa/client workflows deploy`) over calling this from application code.
+         * @description Creates or updates a workflow identified by workspace-scoped `slug`. Builds a minimal valid graph (one catalogue trigger, Manually Run when omitted, then catalogue-action steps; the last step may branch with `paths`). Marks `managedByCode` by default. Prefer the CLI (`npx @lunnoa/client workflows deploy`) over calling this from application code.
          */
         post: operations["WorkflowsController_upsertBySlug"];
         delete?: never;
@@ -2299,13 +2299,18 @@ interface components {
             requestedCount: number;
         };
         UpsertWorkflowStepDto: {
+            /**
+             * @description Name later steps use in ={{step:<key>,path}}. Keyed steps keep their node id across deploys. "trigger" is reserved.
+             * @example loadCase
+             */
+            key?: string;
             /** @description Workflow app id (catalogue slug). */
             appId: string;
             /** @description Catalogue action id. */
             actionId: string;
             /** @description Connection instance UUID for this step. */
             connectionId?: string;
-            /** @description Action input / config fields. */
+            /** @description Action input / config fields. String values may use ={{step:trigger,field}} or ={{step:<key>,path,to,value}}. */
             input?: {
                 [key: string]: unknown;
             };
@@ -2313,6 +2318,24 @@ interface components {
             name?: string;
             /** @description Step description. */
             description?: string;
+            /** @description Branches after this step. Only on flow-control_action_conditional-paths, flow-control_action_manually-decide-paths, or flow-control_action_request-approval (approved path first, then rejected), and only on the last step of a list. */
+            paths?: components["schemas"]["UpsertWorkflowPathDto"][];
+        };
+        UpsertWorkflowPathConditionDto: {
+            /** @description One step reference, e.g. ={{step:load,amount}}. */
+            field: string;
+            /** @description contains, does_not_contain, equals, does_not_equal, exists, does_not_exist, starts_with, ends_with, is_empty, is_not_empty, comes_before, comes_after, is_in_the_past, is_in_the_future, is_true, is_false, is_truthy, is_falsey, is_greater_than, is_less_than, is_greater_than_or_equal_to, is_less_than_or_equal_to, matches_regex, does_not_match_regex. */
+            condition: string;
+            /** @description Value to compare with. */
+            value?: string;
+        };
+        UpsertWorkflowPathDto: {
+            /** @description Path label, unique on its step. */
+            label: string;
+            /** @description Conditional Paths only. Groups are OR-ed, conditions inside a group AND-ed. Omit to always take this path. */
+            when?: components["schemas"]["UpsertWorkflowPathConditionDto"][][];
+            /** @description Steps on this path. */
+            steps: components["schemas"]["UpsertWorkflowStepDto"][];
         };
         UpsertWorkflowTriggerInputFieldDto: {
             /** @description Field id. Callers pass this key to workflows.execute. */
@@ -2362,7 +2385,7 @@ interface components {
             isActive?: boolean;
             /** @description Catalogue trigger. Omit for a Manually Run trigger with no input fields. */
             trigger?: components["schemas"]["UpsertWorkflowTriggerDto"];
-            /** @description Linear catalogue-action steps (v1; no branches). */
+            /** @description Catalogue-action steps in order. The last step may branch with `paths`. */
             steps: components["schemas"]["UpsertWorkflowStepDto"][];
             /** @description Marks the row as managed by code (CLI / SDK). Defaults to true on this endpoint. */
             managedByCode?: boolean;
@@ -3464,6 +3487,8 @@ interface components {
             executionPath?: components["schemas"]["ExecutionPathStepDto"][];
         };
         RunStepDto: {
+            /** @description Name later steps use in ={{step:<key>,path}}. Ad-hoc runs have no trigger. */
+            key?: string;
             /** @description Workflow app id (catalogue slug), e.g. `http`, `gmail`. */
             appId: string;
             /** @description Action id within the app, e.g. `http_action_send-request`. Discover via GET /workflow-apps. */
@@ -6716,11 +6741,42 @@ interface TriggerDefinition {
     description?: string;
 }
 interface WorkflowStepDefinition {
+    /**
+     * Name later steps use with `ref.step(key, ...)`. Keyed steps keep their
+     * node id across deploys. `trigger` is reserved.
+     */
+    key?: string;
     /** Action definition (or inline action-shaped object). */
     use: ActionDefinition;
-    /** Per-step input overrides. */
+    /** Per-step input overrides. Values may contain `ref.trigger` / `ref.step`. */
     input?: Record<string, unknown>;
     name?: string;
+    /**
+     * Branches after this step. Only on Conditional Paths, Manually Decide Path,
+     * or Request Approval (approved path first, then rejected), and only on the
+     * last step of a list. Put later steps inside each path.
+     */
+    paths?: WorkflowPathDefinition[];
+}
+/** Conditions Conditional Paths evaluates (same list as the builder). */
+declare const PATH_CONDITIONS: readonly ["contains", "does_not_contain", "equals", "does_not_equal", "exists", "does_not_exist", "starts_with", "ends_with", "is_empty", "is_not_empty", "comes_before", "comes_after", "is_in_the_past", "is_in_the_future", "is_true", "is_false", "is_truthy", "is_falsey", "is_greater_than", "is_less_than", "is_greater_than_or_equal_to", "is_less_than_or_equal_to", "matches_regex", "does_not_match_regex"];
+type PathConditionType = (typeof PATH_CONDITIONS)[number];
+interface PathCondition {
+    /** One reference: `ref.trigger(...)` or `ref.step(...)`. */
+    field: string;
+    condition: PathConditionType;
+    /** Compared as text. Omit for exists / is_empty / is_true and similar. */
+    value?: string;
+}
+interface WorkflowPathDefinition {
+    /** Unique on its step. On Request Approval use `Approved` / `Rejected`. */
+    label: string;
+    /**
+     * Conditional Paths only. Groups are OR-ed, conditions in a group AND-ed.
+     * Omit to always take this path.
+     */
+    when?: PathCondition[][];
+    steps: WorkflowStepDefinition[];
 }
 interface WorkflowDefinition {
     kind: typeof DEFINE_KINDS.workflow;
@@ -6734,7 +6790,7 @@ interface WorkflowDefinition {
      * `runs.start` ignores this and runs the steps only.
      */
     trigger?: TriggerDefinition;
-    /** Linear steps (v1; no branches). */
+    /** Steps in order. The last step may branch with `paths`. */
     steps: WorkflowStepDefinition[];
 }
 type AgentToolDefinition = ActionDefinition | WorkflowDefinition | {
@@ -6762,6 +6818,17 @@ declare function defineConnection(config?: Omit<ConnectionDefinition, 'kind'>):
 declare function defineAiConnection(config?: Omit<AiConnectionDefinition, 'kind'>): AiConnectionDefinition;
 declare function defineAction(config: Omit<ActionDefinition, 'kind'>): ActionDefinition;
 declare function defineTrigger(config: Omit<TriggerDefinition, 'kind'>): TriggerDefinition;
+/**
+ * References for step inputs. The server swaps them for the real node ids on
+ * deploy, and the builder shows them as mapped fields from earlier nodes.
+ * They are plain strings, so they also work inside text and nested objects.
+ */
+declare const ref: {
+    /** A trigger output field, e.g. a Manually Run input id. */
+    trigger: (field: string, ...path: Array<string | number>) => string;
+    /** An earlier step's output, by its `key`. Array indexes are numbers. */
+    step: (key: string, ...path: Array<string | number>) => string;
+};
 declare function defineWorkflow(config: Omit<WorkflowDefinition, 'kind'>): WorkflowDefinition;
 declare function defineAgent(config: Omit<AgentDefinition, 'kind'>): AgentDefinition;
 interface EntityTypeDefinition {
@@ -7360,6 +7427,8 @@ declare class QueuesResource {
 }
 
 interface StartRunStep {
+    /** Name later steps use with `ref.step(key, ...)`. */
+    key?: string;
     appId: string;
     actionId: string;
     connectionId?: string;
@@ -7512,12 +7581,21 @@ declare class VariablesResource {
 }
 
 interface UpsertWorkflowStepInput {
+    /** Name later steps use in `={{step:<key>,path}}`. Keeps the node id stable. */
+    key?: string;
     appId: string;
     actionId: string;
     connectionId?: string;
     input?: Record<string, unknown>;
     name?: string;
     description?: string;
+    /** Branches after this step (last step of a list only). */
+    paths?: UpsertWorkflowPathInput[];
+}
+interface UpsertWorkflowPathInput {
+    label: string;
+    when?: WorkflowPathDefinition['when'];
+    steps: UpsertWorkflowStepInput[];
 }
 interface UpsertWorkflowTriggerInput {
     triggerId: string;
@@ -7765,4 +7843,4 @@ interface CreateServerClientOptions {
  */
 declare function createServerClient(options: CreateServerClientOptions): LunnoaClient;
 
-export { API_KEY_PREFIX, type ActionDefinition, ActionsResource, type AddQueueItemErrorInput, type Agent, AgentChatClient, AgentChatStream, type AgentDefinition, type AgentToolDefinition, AgentsResource, type AiConnection, type AiConnectionDefinition, type AiConnectionModel, AiConnectionsResource, type ApprovalInboxItem, ApprovalsResource, AuthResource, type AuthTokens, type BulkCreateQueueItemsInput, type BulkCreateQueueItemsResult, type ChangeEntityStateInput, type ChangeEntityStateResult, type ChatMode, type Connection, type ConnectionDefinition, ConnectionsResource, type CreateBrowserClientOptions, type CreateEntityInput, type CreateKnowledgeInput, type CreateQueueInput, type CreateQueueItemInput, type CreateServerClientOptions, type CreateTaskInput, type CreateVariableInput, type CurrentUser, DEFINE_KINDS, type DefineKind, type DeletedTask, DiscoveryResource, type EligibleApprover, type EnabledFeatures, EntitiesResource, type Entity, type EntityStateHistoryEntry, type EntityStateTransitions, type EntityType, type EntityTypeDefinition, type EntityTypeReadOptions, EntityTypesResource, type ExecuteWorkflowResult, type Execution, type ExecutionPathStep, type ExecutionProgress, type ExecutionProgressPayload, type ExecutionProgressStep, ExecutionProgressStream, type ExecutionStatus, type ExecutionStreamEvent, type ExecutionStreamEventType, ExecutionTimeoutError, ExecutionsResource, type ExportEntitiesInput, type FetchLike, HttpClient, type ImportEntitiesInput, type ImportEntitiesResult, type ImportTemplate, type Knowledge, type KnowledgeDocument, type KnowledgeDocumentGroup, KnowledgeResource, type ListEntitiesOptions, type ListQueryOptions, type ListQueueItemsByObjectOptions, type ListQueueItemsOptions, type LocalStorageTokenStoreOptions, type LoginRequires2FA, type LoginResult, type LoginSuccess, LunnoaApiError, LunnoaClient, type LunnoaClientOptions, type MessageTaskInput, type OffsetPagination, type PagePagination, type PaginatedEntities, type PendingInput, type PendingInputField, type QueryValue, type Queue, type QueueAllowedObjectType, type QueueItem, type QueueItemCreated, type QueueItemErrorEntry, type QueueItemFull, type QueueItemList, type QueueItemObjectSummary, type QueueItemStats, type QueueItemStatus, QueueItemsResource, type QueueStats, QueuesResource, type RecordMeasureValueInput, type RequestOptions, type RunActionInput, type RunActionOptions, type RunActionResult, RunsResource, type SaveUploadedTextInput, type Scorecard, type ScorecardMeasure, type ScorecardMeasureStatus, type ScorecardMeasureValue, type ScorecardObjective, type ScorecardSummary, ScorecardsResource, type SseEvent, SsoAuthResource, type SsoProviderSummary, type SsoProvidersResponse, type StartRunInput, type StartRunInputDto, type StartRunOptions, type StartRunStep, type StopStreamOptions, type StreamMessageOptions, type Table, TablesResource, type Task, type TaskListItem, TasksResource, type TokenStore, type TriggerDefinition, type TriggerInputFieldDefinition, type UpdateEntityInput, type UpdateKnowledgeInput, type UpdateQueueInput, type UpdateQueueItemInput, type UpdateTaskInput, type UpdateVariableInput, type UpsertAgentBySlugInput, type UpsertAgentBySlugInputDto, type UpsertAgentToolInput, type UpsertEntityTypeBySlugInput, type UpsertTableBySlugInput, type UpsertWorkflowBySlugInput, type UpsertWorkflowBySlugInputDto, type UpsertWorkflowStepInput, type UpsertWorkflowTriggerInput, type Variable, VariablesResource, type WaitUntilFinishedOptions, type WatchProgressOptions, type Workflow, type WorkflowApp, WorkflowAppsResource, type WorkflowDefinition, type WorkflowStepDefinition, WorkflowsResource, assertApiKeyAllowedInEnvironment, type components, createBrowserClient, createLocalStorageTokenStore, createMemoryTokenStore, createServerClient, defineAction, defineAgent, defineAiConnection, defineConnection, defineEntityType, defineTrigger, defineWorkflow, entityTypeDefinitionToUpsert, isBrowserEnvironment, isLoginRequires2FA, iterateOffset, iteratePages, type operations, parseSseEvents, parseSseStream, type paths, resolveActionAppId, resolveActionId, resolveTriggerAppId, resolveTriggerId };
+export { API_KEY_PREFIX, type ActionDefinition, ActionsResource, type AddQueueItemErrorInput, type Agent, AgentChatClient, AgentChatStream, type AgentDefinition, type AgentToolDefinition, AgentsResource, type AiConnection, type AiConnectionDefinition, type AiConnectionModel, AiConnectionsResource, type ApprovalInboxItem, ApprovalsResource, AuthResource, type AuthTokens, type BulkCreateQueueItemsInput, type BulkCreateQueueItemsResult, type ChangeEntityStateInput, type ChangeEntityStateResult, type ChatMode, type Connection, type ConnectionDefinition, ConnectionsResource, type CreateBrowserClientOptions, type CreateEntityInput, type CreateKnowledgeInput, type CreateQueueInput, type CreateQueueItemInput, type CreateServerClientOptions, type CreateTaskInput, type CreateVariableInput, type CurrentUser, DEFINE_KINDS, type DefineKind, type DeletedTask, DiscoveryResource, type EligibleApprover, type EnabledFeatures, EntitiesResource, type Entity, type EntityStateHistoryEntry, type EntityStateTransitions, type EntityType, type EntityTypeDefinition, type EntityTypeReadOptions, EntityTypesResource, type ExecuteWorkflowResult, type Execution, type ExecutionPathStep, type ExecutionProgress, type ExecutionProgressPayload, type ExecutionProgressStep, ExecutionProgressStream, type ExecutionStatus, type ExecutionStreamEvent, type ExecutionStreamEventType, ExecutionTimeoutError, ExecutionsResource, type ExportEntitiesInput, type FetchLike, HttpClient, type ImportEntitiesInput, type ImportEntitiesResult, type ImportTemplate, type Knowledge, type KnowledgeDocument, type KnowledgeDocumentGroup, KnowledgeResource, type ListEntitiesOptions, type ListQueryOptions, type ListQueueItemsByObjectOptions, type ListQueueItemsOptions, type LocalStorageTokenStoreOptions, type LoginRequires2FA, type LoginResult, type LoginSuccess, LunnoaApiError, LunnoaClient, type LunnoaClientOptions, type MessageTaskInput, type OffsetPagination, PATH_CONDITIONS, type PagePagination, type PaginatedEntities, type PathCondition, type PathConditionType, type PendingInput, type PendingInputField, type QueryValue, type Queue, type QueueAllowedObjectType, type QueueItem, type QueueItemCreated, type QueueItemErrorEntry, type QueueItemFull, type QueueItemList, type QueueItemObjectSummary, type QueueItemStats, type QueueItemStatus, QueueItemsResource, type QueueStats, QueuesResource, type RecordMeasureValueInput, type RequestOptions, type RunActionInput, type RunActionOptions, type RunActionResult, RunsResource, type SaveUploadedTextInput, type Scorecard, type ScorecardMeasure, type ScorecardMeasureStatus, type ScorecardMeasureValue, type ScorecardObjective, type ScorecardSummary, ScorecardsResource, type SseEvent, SsoAuthResource, type SsoProviderSummary, type SsoProvidersResponse, type StartRunInput, type StartRunInputDto, type StartRunOptions, type StartRunStep, type StopStreamOptions, type StreamMessageOptions, type Table, TablesResource, type Task, type TaskListItem, TasksResource, type TokenStore, type TriggerDefinition, type TriggerInputFieldDefinition, type UpdateEntityInput, type UpdateKnowledgeInput, type UpdateQueueInput, type UpdateQueueItemInput, type UpdateTaskInput, type UpdateVariableInput, type UpsertAgentBySlugInput, type UpsertAgentBySlugInputDto, type UpsertAgentToolInput, type UpsertEntityTypeBySlugInput, type UpsertTableBySlugInput, type UpsertWorkflowBySlugInput, type UpsertWorkflowBySlugInputDto, type UpsertWorkflowPathInput, type UpsertWorkflowStepInput, type UpsertWorkflowTriggerInput, type Variable, VariablesResource, type WaitUntilFinishedOptions, type WatchProgressOptions, type Workflow, type WorkflowApp, WorkflowAppsResource, type WorkflowDefinition, type WorkflowPathDefinition, type WorkflowStepDefinition, WorkflowsResource, assertApiKeyAllowedInEnvironment, type components, createBrowserClient, createLocalStorageTokenStore, createMemoryTokenStore, createServerClient, defineAction, defineAgent, defineAiConnection, defineConnection, defineEntityType, defineTrigger, defineWorkflow, entityTypeDefinitionToUpsert, isBrowserEnvironment, isLoginRequires2FA, iterateOffset, iteratePages, type operations, parseSseEvents, parseSseStream, type paths, ref, resolveActionAppId, resolveActionId, resolveTriggerAppId, resolveTriggerId };

package/dist/index.d.ts

@@ -715,7 +715,7 @@ interface paths {
         put?: never;
         /**
          * Upsert a workflow by slug from a linear step list
-         * @description Creates or updates a workflow identified by workspace-scoped `slug`. Builds a minimal valid graph (one catalogue trigger, Manually Run when omitted, then linear catalogue-action steps). Marks `managedByCode` by default. Prefer the CLI (`npx @lunnoa/client workflows deploy`) over calling this from application code.
+         * @description Creates or updates a workflow identified by workspace-scoped `slug`. Builds a minimal valid graph (one catalogue trigger, Manually Run when omitted, then catalogue-action steps; the last step may branch with `paths`). Marks `managedByCode` by default. Prefer the CLI (`npx @lunnoa/client workflows deploy`) over calling this from application code.
          */
         post: operations["WorkflowsController_upsertBySlug"];
         delete?: never;
@@ -2299,13 +2299,18 @@ interface components {
             requestedCount: number;
         };
         UpsertWorkflowStepDto: {
+            /**
+             * @description Name later steps use in ={{step:<key>,path}}. Keyed steps keep their node id across deploys. "trigger" is reserved.
+             * @example loadCase
+             */
+            key?: string;
             /** @description Workflow app id (catalogue slug). */
             appId: string;
             /** @description Catalogue action id. */
             actionId: string;
             /** @description Connection instance UUID for this step. */
             connectionId?: string;
-            /** @description Action input / config fields. */
+            /** @description Action input / config fields. String values may use ={{step:trigger,field}} or ={{step:<key>,path,to,value}}. */
             input?: {
                 [key: string]: unknown;
             };
@@ -2313,6 +2318,24 @@ interface components {
             name?: string;
             /** @description Step description. */
             description?: string;
+            /** @description Branches after this step. Only on flow-control_action_conditional-paths, flow-control_action_manually-decide-paths, or flow-control_action_request-approval (approved path first, then rejected), and only on the last step of a list. */
+            paths?: components["schemas"]["UpsertWorkflowPathDto"][];
+        };
+        UpsertWorkflowPathConditionDto: {
+            /** @description One step reference, e.g. ={{step:load,amount}}. */
+            field: string;
+            /** @description contains, does_not_contain, equals, does_not_equal, exists, does_not_exist, starts_with, ends_with, is_empty, is_not_empty, comes_before, comes_after, is_in_the_past, is_in_the_future, is_true, is_false, is_truthy, is_falsey, is_greater_than, is_less_than, is_greater_than_or_equal_to, is_less_than_or_equal_to, matches_regex, does_not_match_regex. */
+            condition: string;
+            /** @description Value to compare with. */
+            value?: string;
+        };
+        UpsertWorkflowPathDto: {
+            /** @description Path label, unique on its step. */
+            label: string;
+            /** @description Conditional Paths only. Groups are OR-ed, conditions inside a group AND-ed. Omit to always take this path. */
+            when?: components["schemas"]["UpsertWorkflowPathConditionDto"][][];
+            /** @description Steps on this path. */
+            steps: components["schemas"]["UpsertWorkflowStepDto"][];
         };
         UpsertWorkflowTriggerInputFieldDto: {
             /** @description Field id. Callers pass this key to workflows.execute. */
@@ -2362,7 +2385,7 @@ interface components {
             isActive?: boolean;
             /** @description Catalogue trigger. Omit for a Manually Run trigger with no input fields. */
             trigger?: components["schemas"]["UpsertWorkflowTriggerDto"];
-            /** @description Linear catalogue-action steps (v1; no branches). */
+            /** @description Catalogue-action steps in order. The last step may branch with `paths`. */
             steps: components["schemas"]["UpsertWorkflowStepDto"][];
             /** @description Marks the row as managed by code (CLI / SDK). Defaults to true on this endpoint. */
             managedByCode?: boolean;
@@ -3464,6 +3487,8 @@ interface components {
             executionPath?: components["schemas"]["ExecutionPathStepDto"][];
         };
         RunStepDto: {
+            /** @description Name later steps use in ={{step:<key>,path}}. Ad-hoc runs have no trigger. */
+            key?: string;
             /** @description Workflow app id (catalogue slug), e.g. `http`, `gmail`. */
             appId: string;
             /** @description Action id within the app, e.g. `http_action_send-request`. Discover via GET /workflow-apps. */
@@ -6716,11 +6741,42 @@ interface TriggerDefinition {
     description?: string;
 }
 interface WorkflowStepDefinition {
+    /**
+     * Name later steps use with `ref.step(key, ...)`. Keyed steps keep their
+     * node id across deploys. `trigger` is reserved.
+     */
+    key?: string;
     /** Action definition (or inline action-shaped object). */
     use: ActionDefinition;
-    /** Per-step input overrides. */
+    /** Per-step input overrides. Values may contain `ref.trigger` / `ref.step`. */
     input?: Record<string, unknown>;
     name?: string;
+    /**
+     * Branches after this step. Only on Conditional Paths, Manually Decide Path,
+     * or Request Approval (approved path first, then rejected), and only on the
+     * last step of a list. Put later steps inside each path.
+     */
+    paths?: WorkflowPathDefinition[];
+}
+/** Conditions Conditional Paths evaluates (same list as the builder). */
+declare const PATH_CONDITIONS: readonly ["contains", "does_not_contain", "equals", "does_not_equal", "exists", "does_not_exist", "starts_with", "ends_with", "is_empty", "is_not_empty", "comes_before", "comes_after", "is_in_the_past", "is_in_the_future", "is_true", "is_false", "is_truthy", "is_falsey", "is_greater_than", "is_less_than", "is_greater_than_or_equal_to", "is_less_than_or_equal_to", "matches_regex", "does_not_match_regex"];
+type PathConditionType = (typeof PATH_CONDITIONS)[number];
+interface PathCondition {
+    /** One reference: `ref.trigger(...)` or `ref.step(...)`. */
+    field: string;
+    condition: PathConditionType;
+    /** Compared as text. Omit for exists / is_empty / is_true and similar. */
+    value?: string;
+}
+interface WorkflowPathDefinition {
+    /** Unique on its step. On Request Approval use `Approved` / `Rejected`. */
+    label: string;
+    /**
+     * Conditional Paths only. Groups are OR-ed, conditions in a group AND-ed.
+     * Omit to always take this path.
+     */
+    when?: PathCondition[][];
+    steps: WorkflowStepDefinition[];
 }
 interface WorkflowDefinition {
     kind: typeof DEFINE_KINDS.workflow;
@@ -6734,7 +6790,7 @@ interface WorkflowDefinition {
      * `runs.start` ignores this and runs the steps only.
      */
     trigger?: TriggerDefinition;
-    /** Linear steps (v1; no branches). */
+    /** Steps in order. The last step may branch with `paths`. */
     steps: WorkflowStepDefinition[];
 }
 type AgentToolDefinition = ActionDefinition | WorkflowDefinition | {
@@ -6762,6 +6818,17 @@ declare function defineConnection(config?: Omit<ConnectionDefinition, 'kind'>):
 declare function defineAiConnection(config?: Omit<AiConnectionDefinition, 'kind'>): AiConnectionDefinition;
 declare function defineAction(config: Omit<ActionDefinition, 'kind'>): ActionDefinition;
 declare function defineTrigger(config: Omit<TriggerDefinition, 'kind'>): TriggerDefinition;
+/**
+ * References for step inputs. The server swaps them for the real node ids on
+ * deploy, and the builder shows them as mapped fields from earlier nodes.
+ * They are plain strings, so they also work inside text and nested objects.
+ */
+declare const ref: {
+    /** A trigger output field, e.g. a Manually Run input id. */
+    trigger: (field: string, ...path: Array<string | number>) => string;
+    /** An earlier step's output, by its `key`. Array indexes are numbers. */
+    step: (key: string, ...path: Array<string | number>) => string;
+};
 declare function defineWorkflow(config: Omit<WorkflowDefinition, 'kind'>): WorkflowDefinition;
 declare function defineAgent(config: Omit<AgentDefinition, 'kind'>): AgentDefinition;
 interface EntityTypeDefinition {
@@ -7360,6 +7427,8 @@ declare class QueuesResource {
 }
 
 interface StartRunStep {
+    /** Name later steps use with `ref.step(key, ...)`. */
+    key?: string;
     appId: string;
     actionId: string;
     connectionId?: string;
@@ -7512,12 +7581,21 @@ declare class VariablesResource {
 }
 
 interface UpsertWorkflowStepInput {
+    /** Name later steps use in `={{step:<key>,path}}`. Keeps the node id stable. */
+    key?: string;
     appId: string;
     actionId: string;
     connectionId?: string;
     input?: Record<string, unknown>;
     name?: string;
     description?: string;
+    /** Branches after this step (last step of a list only). */
+    paths?: UpsertWorkflowPathInput[];
+}
+interface UpsertWorkflowPathInput {
+    label: string;
+    when?: WorkflowPathDefinition['when'];
+    steps: UpsertWorkflowStepInput[];
 }
 interface UpsertWorkflowTriggerInput {
     triggerId: string;
@@ -7765,4 +7843,4 @@ interface CreateServerClientOptions {
  */
 declare function createServerClient(options: CreateServerClientOptions): LunnoaClient;
 
-export { API_KEY_PREFIX, type ActionDefinition, ActionsResource, type AddQueueItemErrorInput, type Agent, AgentChatClient, AgentChatStream, type AgentDefinition, type AgentToolDefinition, AgentsResource, type AiConnection, type AiConnectionDefinition, type AiConnectionModel, AiConnectionsResource, type ApprovalInboxItem, ApprovalsResource, AuthResource, type AuthTokens, type BulkCreateQueueItemsInput, type BulkCreateQueueItemsResult, type ChangeEntityStateInput, type ChangeEntityStateResult, type ChatMode, type Connection, type ConnectionDefinition, ConnectionsResource, type CreateBrowserClientOptions, type CreateEntityInput, type CreateKnowledgeInput, type CreateQueueInput, type CreateQueueItemInput, type CreateServerClientOptions, type CreateTaskInput, type CreateVariableInput, type CurrentUser, DEFINE_KINDS, type DefineKind, type DeletedTask, DiscoveryResource, type EligibleApprover, type EnabledFeatures, EntitiesResource, type Entity, type EntityStateHistoryEntry, type EntityStateTransitions, type EntityType, type EntityTypeDefinition, type EntityTypeReadOptions, EntityTypesResource, type ExecuteWorkflowResult, type Execution, type ExecutionPathStep, type ExecutionProgress, type ExecutionProgressPayload, type ExecutionProgressStep, ExecutionProgressStream, type ExecutionStatus, type ExecutionStreamEvent, type ExecutionStreamEventType, ExecutionTimeoutError, ExecutionsResource, type ExportEntitiesInput, type FetchLike, HttpClient, type ImportEntitiesInput, type ImportEntitiesResult, type ImportTemplate, type Knowledge, type KnowledgeDocument, type KnowledgeDocumentGroup, KnowledgeResource, type ListEntitiesOptions, type ListQueryOptions, type ListQueueItemsByObjectOptions, type ListQueueItemsOptions, type LocalStorageTokenStoreOptions, type LoginRequires2FA, type LoginResult, type LoginSuccess, LunnoaApiError, LunnoaClient, type LunnoaClientOptions, type MessageTaskInput, type OffsetPagination, type PagePagination, type PaginatedEntities, type PendingInput, type PendingInputField, type QueryValue, type Queue, type QueueAllowedObjectType, type QueueItem, type QueueItemCreated, type QueueItemErrorEntry, type QueueItemFull, type QueueItemList, type QueueItemObjectSummary, type QueueItemStats, type QueueItemStatus, QueueItemsResource, type QueueStats, QueuesResource, type RecordMeasureValueInput, type RequestOptions, type RunActionInput, type RunActionOptions, type RunActionResult, RunsResource, type SaveUploadedTextInput, type Scorecard, type ScorecardMeasure, type ScorecardMeasureStatus, type ScorecardMeasureValue, type ScorecardObjective, type ScorecardSummary, ScorecardsResource, type SseEvent, SsoAuthResource, type SsoProviderSummary, type SsoProvidersResponse, type StartRunInput, type StartRunInputDto, type StartRunOptions, type StartRunStep, type StopStreamOptions, type StreamMessageOptions, type Table, TablesResource, type Task, type TaskListItem, TasksResource, type TokenStore, type TriggerDefinition, type TriggerInputFieldDefinition, type UpdateEntityInput, type UpdateKnowledgeInput, type UpdateQueueInput, type UpdateQueueItemInput, type UpdateTaskInput, type UpdateVariableInput, type UpsertAgentBySlugInput, type UpsertAgentBySlugInputDto, type UpsertAgentToolInput, type UpsertEntityTypeBySlugInput, type UpsertTableBySlugInput, type UpsertWorkflowBySlugInput, type UpsertWorkflowBySlugInputDto, type UpsertWorkflowStepInput, type UpsertWorkflowTriggerInput, type Variable, VariablesResource, type WaitUntilFinishedOptions, type WatchProgressOptions, type Workflow, type WorkflowApp, WorkflowAppsResource, type WorkflowDefinition, type WorkflowStepDefinition, WorkflowsResource, assertApiKeyAllowedInEnvironment, type components, createBrowserClient, createLocalStorageTokenStore, createMemoryTokenStore, createServerClient, defineAction, defineAgent, defineAiConnection, defineConnection, defineEntityType, defineTrigger, defineWorkflow, entityTypeDefinitionToUpsert, isBrowserEnvironment, isLoginRequires2FA, iterateOffset, iteratePages, type operations, parseSseEvents, parseSseStream, type paths, resolveActionAppId, resolveActionId, resolveTriggerAppId, resolveTriggerId };
+export { API_KEY_PREFIX, type ActionDefinition, ActionsResource, type AddQueueItemErrorInput, type Agent, AgentChatClient, AgentChatStream, type AgentDefinition, type AgentToolDefinition, AgentsResource, type AiConnection, type AiConnectionDefinition, type AiConnectionModel, AiConnectionsResource, type ApprovalInboxItem, ApprovalsResource, AuthResource, type AuthTokens, type BulkCreateQueueItemsInput, type BulkCreateQueueItemsResult, type ChangeEntityStateInput, type ChangeEntityStateResult, type ChatMode, type Connection, type ConnectionDefinition, ConnectionsResource, type CreateBrowserClientOptions, type CreateEntityInput, type CreateKnowledgeInput, type CreateQueueInput, type CreateQueueItemInput, type CreateServerClientOptions, type CreateTaskInput, type CreateVariableInput, type CurrentUser, DEFINE_KINDS, type DefineKind, type DeletedTask, DiscoveryResource, type EligibleApprover, type EnabledFeatures, EntitiesResource, type Entity, type EntityStateHistoryEntry, type EntityStateTransitions, type EntityType, type EntityTypeDefinition, type EntityTypeReadOptions, EntityTypesResource, type ExecuteWorkflowResult, type Execution, type ExecutionPathStep, type ExecutionProgress, type ExecutionProgressPayload, type ExecutionProgressStep, ExecutionProgressStream, type ExecutionStatus, type ExecutionStreamEvent, type ExecutionStreamEventType, ExecutionTimeoutError, ExecutionsResource, type ExportEntitiesInput, type FetchLike, HttpClient, type ImportEntitiesInput, type ImportEntitiesResult, type ImportTemplate, type Knowledge, type KnowledgeDocument, type KnowledgeDocumentGroup, KnowledgeResource, type ListEntitiesOptions, type ListQueryOptions, type ListQueueItemsByObjectOptions, type ListQueueItemsOptions, type LocalStorageTokenStoreOptions, type LoginRequires2FA, type LoginResult, type LoginSuccess, LunnoaApiError, LunnoaClient, type LunnoaClientOptions, type MessageTaskInput, type OffsetPagination, PATH_CONDITIONS, type PagePagination, type PaginatedEntities, type PathCondition, type PathConditionType, type PendingInput, type PendingInputField, type QueryValue, type Queue, type QueueAllowedObjectType, type QueueItem, type QueueItemCreated, type QueueItemErrorEntry, type QueueItemFull, type QueueItemList, type QueueItemObjectSummary, type QueueItemStats, type QueueItemStatus, QueueItemsResource, type QueueStats, QueuesResource, type RecordMeasureValueInput, type RequestOptions, type RunActionInput, type RunActionOptions, type RunActionResult, RunsResource, type SaveUploadedTextInput, type Scorecard, type ScorecardMeasure, type ScorecardMeasureStatus, type ScorecardMeasureValue, type ScorecardObjective, type ScorecardSummary, ScorecardsResource, type SseEvent, SsoAuthResource, type SsoProviderSummary, type SsoProvidersResponse, type StartRunInput, type StartRunInputDto, type StartRunOptions, type StartRunStep, type StopStreamOptions, type StreamMessageOptions, type Table, TablesResource, type Task, type TaskListItem, TasksResource, type TokenStore, type TriggerDefinition, type TriggerInputFieldDefinition, type UpdateEntityInput, type UpdateKnowledgeInput, type UpdateQueueInput, type UpdateQueueItemInput, type UpdateTaskInput, type UpdateVariableInput, type UpsertAgentBySlugInput, type UpsertAgentBySlugInputDto, type UpsertAgentToolInput, type UpsertEntityTypeBySlugInput, type UpsertTableBySlugInput, type UpsertWorkflowBySlugInput, type UpsertWorkflowBySlugInputDto, type UpsertWorkflowPathInput, type UpsertWorkflowStepInput, type UpsertWorkflowTriggerInput, type Variable, VariablesResource, type WaitUntilFinishedOptions, type WatchProgressOptions, type Workflow, type WorkflowApp, WorkflowAppsResource, type WorkflowDefinition, type WorkflowPathDefinition, type WorkflowStepDefinition, WorkflowsResource, assertApiKeyAllowedInEnvironment, type components, createBrowserClient, createLocalStorageTokenStore, createMemoryTokenStore, createServerClient, defineAction, defineAgent, defineAiConnection, defineConnection, defineEntityType, defineTrigger, defineWorkflow, entityTypeDefinitionToUpsert, isBrowserEnvironment, isLoginRequires2FA, iterateOffset, iteratePages, type operations, parseSseEvents, parseSseStream, type paths, ref, resolveActionAppId, resolveActionId, resolveTriggerAppId, resolveTriggerId };

package/dist/index.js

@@ -540,6 +540,32 @@ var DEFINE_KINDS = {
   agent: "agent",
   entityType: "entityType"
 };
+var PATH_CONDITIONS = [
+  "contains",
+  "does_not_contain",
+  "equals",
+  "does_not_equal",
+  "exists",
+  "does_not_exist",
+  "starts_with",
+  "ends_with",
+  "is_empty",
+  "is_not_empty",
+  "comes_before",
+  "comes_after",
+  "is_in_the_past",
+  "is_in_the_future",
+  "is_true",
+  "is_false",
+  "is_truthy",
+  "is_falsey",
+  "is_greater_than",
+  "is_less_than",
+  "is_greater_than_or_equal_to",
+  "is_less_than_or_equal_to",
+  "matches_regex",
+  "does_not_match_regex"
+];
 function defineConnection(config = {}) {
   return { kind: DEFINE_KINDS.connection, ...config };
 }
@@ -561,7 +587,7 @@ function assertTriggerConfig(config) {
       throw new Error("defineTrigger inputs require id");
     }
   }
-  if (config.inputs?.length && config.id.trim() !== "flow-control_trigger_manual") {
+  if (config.inputs?.length && config.id.trim() !== MANUAL_TRIGGER_ID) {
     throw new Error(
       "defineTrigger inputs are only valid on flow-control_trigger_manual"
     );
@@ -571,6 +597,131 @@ function defineTrigger(config) {
   assertTriggerConfig(config);
   return { kind: DEFINE_KINDS.trigger, ...config };
 }
+var MANUAL_TRIGGER_ID = "flow-control_trigger_manual";
+var TRIGGER_KEY = "trigger";
+var STEP_KEY_PATTERN = /^[A-Za-z][A-Za-z0-9_-]*$/;
+var STEP_REF_PATTERN = /={{step:([^}]*)}}/g;
+function refString(key, path) {
+  const parts = [key, ...path.map(String)];
+  for (const part of parts) {
+    if (!part || /[,{}]/.test(part)) {
+      throw new Error(`ref path parts must be non-empty and contain no , { or }: "${part}"`);
+    }
+  }
+  return `={{step:${parts.join(",")}}}`;
+}
+var ref = {
+  /** A trigger output field, e.g. a Manually Run input id. */
+  trigger: (field, ...path) => refString(TRIGGER_KEY, [field, ...path]),
+  /** An earlier step's output, by its `key`. Array indexes are numbers. */
+  step: (key, ...path) => refString(key, path)
+};
+function collectRefs(value, out) {
+  if (typeof value === "string") {
+    for (const match of value.matchAll(STEP_REF_PATTERN)) {
+      out.push(match[1].split(",").map((part) => part.trim()));
+    }
+  } else if (Array.isArray(value)) {
+    value.forEach((item) => collectRefs(item, out));
+  } else if (value && typeof value === "object") {
+    Object.values(value).forEach((item) => collectRefs(item, out));
+  }
+}
+var CONDITIONAL_PATHS_ID = "flow-control_action_conditional-paths";
+var APPROVAL_ID = "flow-control_action_request-approval";
+var BRANCHING_ACTION_IDS = /* @__PURE__ */ new Set([
+  CONDITIONAL_PATHS_ID,
+  "flow-control_action_manually-decide-paths",
+  APPROVAL_ID
+]);
+var PATH_CONDITION_SET = new Set(PATH_CONDITIONS);
+var SINGLE_REF_PATTERN = /^={{step:[^}]*}}$/;
+function collectKeys(steps, seen) {
+  for (const step of steps) {
+    if (step.key !== void 0) {
+      if (!STEP_KEY_PATTERN.test(step.key) || step.key === TRIGGER_KEY) {
+        throw new Error(
+          `Step key "${step.key}" must start with a letter, use letters, digits, - or _, and not be "${TRIGGER_KEY}".`
+        );
+      }
+      if (seen.has(step.key)) {
+        throw new Error(`Step key "${step.key}" is used twice.`);
+      }
+      seen.add(step.key);
+    }
+    for (const path of step.paths ?? []) collectKeys(path.steps ?? [], seen);
+  }
+}
+function assertStepRefs(config) {
+  const triggerId = config.trigger?.id.trim() ?? MANUAL_TRIGGER_ID;
+  const triggerFields = triggerId === MANUAL_TRIGGER_ID ? new Set((config.trigger?.inputs ?? []).map((f) => f.id.trim())) : void 0;
+  const allKeys = /* @__PURE__ */ new Set();
+  collectKeys(config.steps, allKeys);
+  const checkRefs = (value, earlier, where) => {
+    const refs = [];
+    collectRefs(value, refs);
+    for (const [key = "", ...path] of refs) {
+      const shown = `={{step:${[key, ...path].join(",")}}}`;
+      if (!earlier.has(key)) {
+        throw new Error(
+          allKeys.has(key) ? `${where}: ${shown} refers to itself, a later step, or a step on another path. Use the trigger or an earlier step on the same path.` : `${where}: ${shown} names unknown key "${key}". Use "trigger" or an earlier step's key.`
+        );
+      }
+      if (key === TRIGGER_KEY && triggerFields && !triggerFields.has(path[0] ?? "")) {
+        throw new Error(
+          `${where}: ${shown} uses trigger field "${path[0] ?? ""}", which is not declared in trigger inputs.`
+        );
+      }
+    }
+  };
+  const checkChain = (steps, visible) => {
+    const earlier = new Set(visible);
+    steps.forEach((step, index) => {
+      const where = `Step "${step.key ?? step.name ?? index + 1}"`;
+      checkRefs([step.use?.input, step.input], earlier, where);
+      if (step.key) earlier.add(step.key);
+      if (!step.paths?.length) return;
+      const actionId = step.use ? resolveActionId(step.use) : "";
+      if (!BRANCHING_ACTION_IDS.has(actionId)) {
+        throw new Error(`${where}: paths only work on ${[...BRANCHING_ACTION_IDS].join(", ")}.`);
+      }
+      if (index !== steps.length - 1) {
+        throw new Error(
+          `${where}: a step with paths must be the last step in its list. Put later steps inside each path.`
+        );
+      }
+      if (actionId === APPROVAL_ID && step.paths.length > 2) {
+        throw new Error(`${where}: Request Approval takes at most two paths (approved, then rejected).`);
+      }
+      const labels = /* @__PURE__ */ new Set();
+      for (const path of step.paths) {
+        const label = path?.label?.trim();
+        if (!label) throw new Error(`${where}: every path needs a label.`);
+        if (labels.has(label)) throw new Error(`${where}: path label "${label}" is used twice.`);
+        labels.add(label);
+        if (path.when !== void 0 && actionId !== CONDITIONAL_PATHS_ID) {
+          throw new Error(`${where}: "when" only works on Conditional Paths.`);
+        }
+        for (const condition of (path.when ?? []).flat()) {
+          if (!SINGLE_REF_PATTERN.test(condition?.field?.trim() ?? "")) {
+            throw new Error(
+              `${where}, path "${label}": a condition's field must be one ref.trigger(...) or ref.step(...).`
+            );
+          }
+          if (!PATH_CONDITION_SET.has(condition.condition)) {
+            throw new Error(
+              `${where}, path "${label}": condition "${condition.condition}" is not supported. Use one of: ${PATH_CONDITIONS.join(", ")}.`
+            );
+          }
+        }
+        checkRefs(path.when, earlier, `${where}, path "${label}"`);
+        if (!path.steps?.length) throw new Error(`${where}: path "${label}" needs at least one step.`);
+        checkChain(path.steps, earlier);
+      }
+    });
+  };
+  checkChain(config.steps, /* @__PURE__ */ new Set([TRIGGER_KEY]));
+}
 function defineWorkflow(config) {
   if (!config.slug?.trim()) {
     throw new Error("defineWorkflow requires slug");
@@ -581,6 +732,7 @@ function defineWorkflow(config) {
   if (config.trigger) {
     assertTriggerConfig(config.trigger);
   }
+  assertStepRefs(config);
   return { kind: DEFINE_KINDS.workflow, ...config };
 }
 function defineAgent(config) {
@@ -1867,12 +2019,19 @@ function stepFromDefinition(step) {
       ...step.name ? { name: step.name } : {}
     };
   }
+  if (step.paths?.length) {
+    throw new Error(
+      "runs.start runs straight lines only. Deploy workflows with paths, then execute them."
+    );
+  }
   const use = step.use;
   const input = {
     ...use.input ?? {},
     ...step.input ?? {}
   };
+  const key = step.key;
   return {
+    ...key ? { key } : {},
     appId: resolveActionAppId(use),
     actionId: resolveActionId(use),
     ...use.connection?.id ? { connectionId: use.connection.id } : {},
@@ -2088,6 +2247,7 @@ function triggerToUpsertInput(trigger) {
 function stepToUpsertInput(step) {
   const use = step.use;
   return {
+    ...step.key ? { key: step.key } : {},
     appId: resolveActionAppId(use),
     actionId: resolveActionId(use),
     connectionId: use.connection?.id,
@@ -2096,7 +2256,14 @@ function stepToUpsertInput(step) {
       ...step.input ?? {}
     },
     name: step.name ?? use.name,
-    description: use.description
+    description: use.description,
+    ...step.paths?.length ? {
+      paths: step.paths.map((path) => ({
+        label: path.label,
+        ...path.when ? { when: path.when } : {},
+        steps: path.steps.map(stepToUpsertInput)
+      }))
+    } : {}
   };
 }
 function workflowDefinitionToUpsert(def) {
@@ -2304,6 +2471,6 @@ function createServerClient(options) {
   });
 }
 
-export { API_KEY_PREFIX, ActionsResource, AgentChatClient, AgentChatStream, AgentsResource, AiConnectionsResource, ApprovalsResource, AuthResource, ConnectionsResource, DEFINE_KINDS, DiscoveryResource, EntitiesResource, EntityTypesResource, ExecutionProgressStream, ExecutionTimeoutError, ExecutionsResource, HttpClient, KnowledgeResource, LunnoaApiError, LunnoaClient, QueueItemsResource, QueuesResource, RunsResource, ScorecardsResource, SsoAuthResource, TablesResource, TasksResource, VariablesResource, WorkflowAppsResource, WorkflowsResource, assertApiKeyAllowedInEnvironment, createBrowserClient, createLocalStorageTokenStore, createMemoryTokenStore, createServerClient, defineAction, defineAgent, defineAiConnection, defineConnection, defineEntityType, defineTrigger, defineWorkflow, entityTypeDefinitionToUpsert, isBrowserEnvironment, isLoginRequires2FA, iterateOffset, iteratePages, parseSseEvents, parseSseStream, resolveActionAppId, resolveActionId, resolveTriggerAppId, resolveTriggerId };
+export { API_KEY_PREFIX, ActionsResource, AgentChatClient, AgentChatStream, AgentsResource, AiConnectionsResource, ApprovalsResource, AuthResource, ConnectionsResource, DEFINE_KINDS, DiscoveryResource, EntitiesResource, EntityTypesResource, ExecutionProgressStream, ExecutionTimeoutError, ExecutionsResource, HttpClient, KnowledgeResource, LunnoaApiError, LunnoaClient, PATH_CONDITIONS, QueueItemsResource, QueuesResource, RunsResource, ScorecardsResource, SsoAuthResource, TablesResource, TasksResource, VariablesResource, WorkflowAppsResource, WorkflowsResource, assertApiKeyAllowedInEnvironment, createBrowserClient, createLocalStorageTokenStore, createMemoryTokenStore, createServerClient, defineAction, defineAgent, defineAiConnection, defineConnection, defineEntityType, defineTrigger, defineWorkflow, entityTypeDefinitionToUpsert, isBrowserEnvironment, isLoginRequires2FA, iterateOffset, iteratePages, parseSseEvents, parseSseStream, ref, resolveActionAppId, resolveActionId, resolveTriggerAppId, resolveTriggerId };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map