@lunnoa/client 2.3.0 → 2.5.0

package/README.md

@@ -249,7 +249,7 @@ Re-run codegen whenever entity types, workflows, or agents change on the deploym
 
 ## Define, run, and CLI deploy
 
-Author local definitions with `defineWorkflow` / `defineAgent` / `defineEntityType`, run linear chains with `lunnoa.runs.start`, and upsert with the CLI (prefer CLI over calling upsert from app code). Agent and workflow upsert is by slug inside the workspace on the API key. An entity type slug is unique on the deployment. Deploy grants that type to the API key's workspace when the slug is new, and will not rewrite a type already granted to other workspaces. Instance writes reject unknown attribute keys unless `allowUnknownAttributes` is true — use the reserved `extensions` object for flexible bags:
+Author local definitions with `defineWorkflow` / `defineAgent` / `defineEntityType`, run linear chains with `lunnoa.runs.start`, branch deployed workflows with `paths` on Request Approval or Conditional Paths, and upsert with the CLI (prefer CLI over calling upsert from app code). Agent and workflow upsert is by slug inside the workspace on the API key. An entity type slug is unique on the deployment. Deploy grants that type to the API key's workspace when the slug is new, and will not rewrite a type already granted to other workspaces. Instance writes reject unknown attribute keys unless `allowUnknownAttributes` is true — use the reserved `extensions` object for flexible bags:
 
 ```bash
 npx @lunnoa/client entity-types deploy ./human.ts --url https://lunnoa.example --api-key lna_...
@@ -264,7 +264,7 @@ npx @lunnoa/client agents deploy ./agents/triage.ts \
   --url https://lunnoa.example --api-key lna_...
 ```
 
-`defineAction` binds catalogue actions only; toolkit `createAction` is for in-platform apps. `defineWorkflow` takes an optional `defineTrigger`. Omit it for Manually Run with no input fields. `runs.start` ignores the trigger and runs the steps only. See Lunnoa Docs under `guides/develop/client/define`, `runs`, and `cli-deploy`.
+`defineAction` binds catalogue actions only; toolkit `createAction` is for in-platform apps. `defineWorkflow` takes an optional `defineTrigger`. Omit it for Manually Run with no input fields. `runs.start` ignores the trigger and runs the steps only. Pass data into step settings with `ref.trigger('caseId')` or `ref.step('load', 'rows', 0)` (give the source step a `key`); the server resolves them on deploy and the builder shows them as mapped fields. See Lunnoa Docs under `guides/develop/client/define`, `runs`, and `cli-deploy`.
 
 ### CLI discovery
 

package/dist/cli.js

@@ -546,6 +546,33 @@ 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"
+];
+var PATH_CONDITION_SET = new Set(PATH_CONDITIONS);
 function resolveActionAppId(action) {
   if (action.appId?.trim()) {
     return action.appId.trim();
@@ -1805,12 +1832,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 } : {},
@@ -2026,6 +2060,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,
@@ -2034,7 +2069,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) {

package/dist/index.cjs

@@ -542,6 +542,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 };
 }
@@ -563,7 +589,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"
     );
@@ -573,6 +599,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");
@@ -583,6 +734,7 @@ function defineWorkflow(config) {
   if (config.trigger) {
     assertTriggerConfig(config.trigger);
   }
+  assertStepRefs(config);
   return { kind: DEFINE_KINDS.workflow, ...config };
 }
 function defineAgent(config) {
@@ -1869,12 +2021,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 } : {},
@@ -2090,6 +2249,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,
@@ -2098,7 +2258,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) {
@@ -2326,6 +2493,7 @@ exports.HttpClient = HttpClient;
 exports.KnowledgeResource = KnowledgeResource;
 exports.LunnoaApiError = LunnoaApiError;
 exports.LunnoaClient = LunnoaClient;
+exports.PATH_CONDITIONS = PATH_CONDITIONS;
 exports.QueueItemsResource = QueueItemsResource;
 exports.QueuesResource = QueuesResource;
 exports.RunsResource = RunsResource;
@@ -2355,6 +2523,7 @@ exports.iterateOffset = iterateOffset;
 exports.iteratePages = iteratePages;
 exports.parseSseEvents = parseSseEvents;
 exports.parseSseStream = parseSseStream;
+exports.ref = ref;
 exports.resolveActionAppId = resolveActionAppId;
 exports.resolveActionId = resolveActionId;
 exports.resolveTriggerAppId = resolveTriggerAppId;