@lunnoa/client 2.4.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_...

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,6 +1832,11 @@ 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 ?? {},
@@ -2037,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 };
 }
@@ -603,32 +629,44 @@ function collectRefs(value, out) {
     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();
-  for (const step of config.steps) {
-    if (step.key === void 0) continue;
-    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 (allKeys.has(step.key)) {
-      throw new Error(`Step key "${step.key}" is used twice.`);
-    }
-    allKeys.add(step.key);
-  }
-  const earlier = /* @__PURE__ */ new Set([TRIGGER_KEY]);
-  config.steps.forEach((step, index) => {
+  collectKeys(config.steps, allKeys);
+  const checkRefs = (value, earlier, where) => {
     const refs = [];
-    collectRefs([step.use?.input, step.input], refs);
-    const where = `Step "${step.key ?? step.name ?? index + 1}"`;
+    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 or a later step. Use the trigger or an earlier step.` : `${where}: ${shown} names unknown key "${key}". Use "trigger" or an earlier step's key.`
+          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] ?? "")) {
@@ -637,8 +675,54 @@ function assertStepRefs(config) {
         );
       }
     }
-    if (step.key) earlier.add(step.key);
-  });
+  };
+  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()) {
@@ -1937,6 +2021,11 @@ 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 ?? {},
@@ -2169,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) {
@@ -2397,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;