@withone/cli 1.40.0 → 1.41.0

package/dist/{chunk-SSEDFOVV.js → chunk-A5AFLKCQ.js}

@@ -811,7 +811,29 @@ async function executeActionStep(step, context, api, permissions, allowedActionI
   const action = step.action;
   const platform = resolveValue(action.platform, context);
   const actionId = resolveValue(action.actionId, context);
-  const connectionKey = resolveValue(action.connectionKey, context);
+  const hasKey = action.connectionKey !== void 0 && action.connectionKey !== null && action.connectionKey !== "";
+  const hasRef = !!action.connection?.platform;
+  if (hasKey && hasRef) {
+    throw new Error(
+      `Action step "${step.id}" has both "connectionKey" and "connection" \u2014 set exactly one. Prefer "connection: { platform, tag? }" so re-auth doesn't break the flow.`
+    );
+  }
+  if (!hasKey && !hasRef) {
+    throw new Error(
+      `Action step "${step.id}" must set "connection: { platform: <name> }" (or legacy "connectionKey: <key>").`
+    );
+  }
+  let connectionKey;
+  if (hasKey) {
+    connectionKey = resolveValue(action.connectionKey, context);
+  } else {
+    const ref = resolveValue(action.connection, context);
+    if (!context._connections) {
+      context._connections = await api.listConnections();
+    }
+    const conn = await api.resolveConnection(ref, context._connections);
+    connectionKey = conn.key;
+  }
   const data = action.data ? resolveValue(action.data, context) : void 0;
   const pathVars = action.pathVars ? resolveValue(action.pathVars, context) : void 0;
   const queryParams = action.queryParams ? resolveValue(action.queryParams, context) : void 0;
@@ -1115,7 +1137,7 @@ async function executeSubflowStep(step, context, api, permissions, allowedAction
   if (flowStack.includes(resolvedKey)) {
     throw new Error(`Circular flow detected: ${[...flowStack, resolvedKey].join(" \u2192 ")}`);
   }
-  const { loadFlowWithMeta: loadFlowWithMeta2 } = await import("./flow-runner-2KVAPP6E.js");
+  const { loadFlowWithMeta: loadFlowWithMeta2 } = await import("./flow-runner-26LNPU4F.js");
   const { flow: subFlow, rootDir: subRootDir } = loadFlowWithMeta2(resolvedKey);
   const subContext = await executeFlow(
     subFlow,
@@ -1661,7 +1683,8 @@ var FLOW_SCHEMA = {
       fields: {
         platform: { type: "string", required: true, description: "Platform name (kebab-case)" },
         actionId: { type: "string", required: true, description: "Action ID from `actions search`" },
-        connectionKey: { type: "string", required: true, description: "Connection key (use $.input selector)" },
+        connection: { type: "object", required: false, description: "Late-bound connection ref { platform, tag? } \u2014 survives re-auth. Exactly one of `connection` or `connectionKey` must be set." },
+        connectionKey: { type: "string", required: false, description: "Literal connection key (or $.input selector). Legacy form \u2014 prefer `connection: { platform, tag? }`. Exactly one of `connection` or `connectionKey` must be set." },
         data: { type: "object", required: false, description: "Request body (POST/PUT/PATCH)" },
         pathVars: { type: "object", required: false, description: "URL path variables" },
         queryParams: { type: "object", required: false, description: "Query parameters" },
@@ -1674,7 +1697,7 @@ var FLOW_SCHEMA = {
         action: {
           platform: "stripe",
           actionId: "conn_mod_def::xxx::yyy",
-          connectionKey: "$.input.stripeConnectionKey",
+          connection: { platform: "stripe" },
           data: { query: "email:'{{$.input.customerEmail}}'" }
         }
       }
@@ -1723,7 +1746,7 @@ var FLOW_SCHEMA = {
         type: "condition",
         condition: {
           expression: "$.steps.search.response.data.length > 0",
-          then: [{ id: "notify", name: "Send notification", type: "action", action: { platform: "slack", actionId: "...", connectionKey: "$.input.slackKey", data: { text: "Found!" } } }],
+          then: [{ id: "notify", name: "Send notification", type: "action", action: { platform: "slack", actionId: "...", connection: { platform: "slack" }, data: { text: "Found!" } } }],
           else: [{ id: "logMiss", name: "Log not found", type: "transform", transform: { expression: "'Not found'" } }]
         }
       }
@@ -1747,7 +1770,7 @@ var FLOW_SCHEMA = {
         loop: {
           over: "$.steps.listOrders.response.data",
           as: "order",
-          steps: [{ id: "createInvoice", name: "Create invoice", type: "action", action: { platform: "stripe", actionId: "...", connectionKey: "$.input.stripeKey", data: { amount: "$.loop.order.total" } } }]
+          steps: [{ id: "createInvoice", name: "Create invoice", type: "action", action: { platform: "stripe", actionId: "...", connection: { platform: "stripe" }, data: { amount: "$.loop.order.total" } } }]
         }
       }
     },
@@ -1765,8 +1788,8 @@ var FLOW_SCHEMA = {
         type: "parallel",
         parallel: {
           steps: [
-            { id: "getStripe", name: "Get Stripe data", type: "action", action: { platform: "stripe", actionId: "...", connectionKey: "$.input.stripeKey" } },
-            { id: "getSlack", name: "Get Slack data", type: "action", action: { platform: "slack", actionId: "...", connectionKey: "$.input.slackKey" } }
+            { id: "getStripe", name: "Get Stripe data", type: "action", action: { platform: "stripe", actionId: "...", connection: { platform: "stripe" } } },
+            { id: "getSlack", name: "Get Slack data", type: "action", action: { platform: "slack", actionId: "...", connection: { platform: "slack" } } }
           ]
         }
       }
@@ -1818,7 +1841,7 @@ var FLOW_SCHEMA = {
         while: {
           condition: "$.steps.paginate.output.lastResult.nextPageToken != null",
           maxIterations: 50,
-          steps: [{ id: "fetchPage", name: "Fetch next page", type: "action", action: { platform: "gmail", actionId: "...", connectionKey: "$.input.gmailKey" } }]
+          steps: [{ id: "fetchPage", name: "Fetch next page", type: "action", action: { platform: "gmail", actionId: "...", connection: { platform: "gmail" } } }]
         }
       }
     },
@@ -1842,7 +1865,7 @@ var FLOW_SCHEMA = {
       configKey: "paginate",
       description: "Auto-paginate API results into a single array",
       fields: {
-        action: { type: "object", required: true, description: "Action config (same shape as action step: platform, actionId, connectionKey)" },
+        action: { type: "object", required: true, description: "Action config (same shape as action step: platform, actionId, plus exactly one of `connection` or `connectionKey`)" },
         pageTokenField: { type: "string", required: true, description: "Dot-path in response to next page token" },
         resultsField: { type: "string", required: true, description: "Dot-path in response to results array" },
         inputTokenParam: { type: "string", required: true, description: "Dot-path in action config where page token is injected" },
@@ -1853,7 +1876,7 @@ var FLOW_SCHEMA = {
         name: "Fetch all Gmail messages",
         type: "paginate",
         paginate: {
-          action: { platform: "gmail", actionId: "...", connectionKey: "$.input.gmailKey", queryParams: { maxResults: 100 } },
+          action: { platform: "gmail", actionId: "...", connection: { platform: "gmail" }, queryParams: { maxResults: 100 } },
           pageTokenField: "nextPageToken",
           resultsField: "messages",
           inputTokenParam: "queryParams.pageToken",
@@ -2051,12 +2074,6 @@ The only differences: (1) prepend the stdin-read line, (2) replace \`return X\`
   "description": "What this flow does",
   "version": "1",
   "inputs": {
-    "connectionKey": {
-      "type": "string",
-      "required": true,
-      "description": "Platform connection key",
-      "connection": { "platform": "stripe" }
-    },
     "param": {
       "type": "string",
       "required": true,
@@ -2071,7 +2088,7 @@ The only differences: (1) prepend the stdin-read line, (2) replace \`return X\`
       "action": {
         "platform": "stripe",
         "actionId": "conn_mod_def::xxx::yyy",
-        "connectionKey": "$.input.connectionKey",
+        "connection": { "platform": "stripe" },
         "data": { "query": "{{$.input.param}}" }
       }
     }
@@ -2165,13 +2182,13 @@ Pipes can be applied to any value (objects/arrays are JSON-stringified first for
 
 ### When to use bare selectors vs \`{{...}}\` interpolation
 
-- **Bare selectors** (\`$.input.x\`): Use for fields the engine resolves directly \u2014 \`connectionKey\`, \`over\`, \`path\`, \`expression\`, \`condition\`, and any field where the entire value is a single selector. The resolved value keeps its original type (object, array, number).
+- **Bare selectors** (\`$.input.x\`): Use for fields the engine resolves directly \u2014 \`connectionKey\`, the \`tag\` (or \`platform\`) inside \`connection\`, \`over\`, \`path\`, \`expression\`, \`condition\`, and any field where the entire value is a single selector. The resolved value keeps its original type (object, array, number).
 - **Interpolation** (\`{{$.input.x}}\`): Use inside string values where the selector is embedded in text \u2014 e.g., \`"Hello {{$.steps.getUser.response.name}}"\`. The resolved value is always stringified. Use this in \`data\`, \`pathVars\`, and \`queryParams\` when mixing selectors with literal text.
 - **Rule of thumb**: If the value is purely a selector, use bare. If it's a string containing a selector, use \`{{...}}\`.
 
 ### Selectors vs expressions
 
-Selectors in data fields (\`data\`, \`queryParams\`, \`pathVars\`, \`connectionKey\`) are **dot-path lookups only** \u2014 they do not support JavaScript operators like \`||\` or \`&&\`. For default values, use the \`default\` field on the input definition:
+Selectors in data fields (\`data\`, \`queryParams\`, \`pathVars\`, \`connectionKey\`, \`connection.tag\`) are **dot-path lookups only** \u2014 they do not support JavaScript operators like \`||\` or \`&&\`. For default values, use the \`default\` field on the input definition:
 
 \`\`\`json
 { "inputs": { "maxResults": { "type": "number", "default": 10 } } }
@@ -2291,9 +2308,30 @@ A \`flow\` step's \`flow.key\` accepts selectors and Handlebars interpolations,
 
 Conditional execution: \`"if": "$.steps.prev.response.data.length > 0"\`
 
-## Input Connection Auto-Resolution
+## Connection Resolution \u2014 late-bound by default
+
+Action steps reference a platform connection in one of two forms:
+
+\`\`\`json
+// preferred \u2014 late-bound, survives re-auth
+"connection": { "platform": "gmail" }
+
+// multi-account: disambiguate with the connection's tag
+"connection": { "platform": "gmail", "tag": "work@example.com" }
+
+// legacy \u2014 works for backwards compat, breaks on re-auth
+"connectionKey": "live::gmail::default::abc123..."
+\`\`\`
+
+The engine resolves the \`connection\` ref once per flow run (cached for the run's lifetime) by calling \`listConnections\` and matching on platform + optional tag. Resolution errors fail the step with a clear message \u2014 \`No connection found for platform "X"\`, \`Multiple "X" connections found (tags: ...). Add a "tag" field\`, or \`No "X" connection has tag "Y"\`.
+
+Both \`platform\` and \`tag\` accept \`$.input.x\` selectors so a flow can be parameterised per-execution (e.g. multi-tenant orchestrators that pass the user's email as the tag).
+
+The validator rejects any action that sets both forms or neither, at \`flow validate\` and \`flow execute\` time.
+
+### Optional input metadata: connection-key auto-resolve (legacy)
 
-When an input has \`"connection": { "platform": "stripe" }\`, the flow engine can automatically resolve the connection key at execution time. If the user has exactly one connection for that platform, the engine fills in the key without requiring \`-i connectionKey=...\`. If multiple connections exist, the user must specify which one. This is metadata for tooling \u2014 it does not affect the flow JSON structure, but it makes execution more convenient.
+For flows that still use literal \`connectionKey\` strings via inputs, an input declaration can carry a \`"connection": { "platform": "..." }\` hint so \`flow execute\` auto-fills a single matching connection's key. New flows don't need this \u2014 switch the action's connection form to \`{ platform, tag? }\` and skip the input entirely.
 
 ## Complete Example: Fetch Data, Transform, Notify
 
@@ -2304,18 +2342,6 @@ When an input has \`"connection": { "platform": "stripe" }\`, the flow engine ca
   "description": "Fetch recent contacts from CRM, build a summary, post to Slack",
   "version": "1",
   "inputs": {
-    "crmConnectionKey": {
-      "type": "string",
-      "required": true,
-      "description": "CRM platform connection key",
-      "connection": { "platform": "attio" }
-    },
-    "slackConnectionKey": {
-      "type": "string",
-      "required": true,
-      "description": "Slack connection key",
-      "connection": { "platform": "slack" }
-    },
     "slackChannel": {
       "type": "string",
       "required": true,
@@ -2330,7 +2356,7 @@ When an input has \`"connection": { "platform": "stripe" }\`, the flow engine ca
       "action": {
         "platform": "attio",
         "actionId": "ATTIO_LIST_PEOPLE_ACTION_ID",
-        "connectionKey": "$.input.crmConnectionKey",
+        "connection": { "platform": "attio" },
         "queryParams": { "limit": "10" }
       }
     },
@@ -2349,7 +2375,7 @@ When an input has \`"connection": { "platform": "stripe" }\`, the flow engine ca
       "action": {
         "platform": "slack",
         "actionId": "SLACK_SEND_MESSAGE_ACTION_ID",
-        "connectionKey": "$.input.slackConnectionKey",
+        "connection": { "platform": "slack" },
         "data": {
           "channel": "$.input.slackChannel",
           "text": "{{$.steps.buildSummary.output.summary}}"

package/dist/{flow-runner-2KVAPP6E.js → flow-runner-26LNPU4F.js}

@@ -11,7 +11,7 @@ import {
   saveFlow,
   summarizeFlowInputs,
   walkSteps
-} from "./chunk-SSEDFOVV.js";
+} from "./chunk-A5AFLKCQ.js";
 export {
   FlowRunner,
   collectStepTypes,

package/dist/index.js

@@ -19,7 +19,7 @@ import {
   resolveFlowPath,
   saveFlow,
   validateActionInput
-} from "./chunk-SSEDFOVV.js";
+} from "./chunk-A5AFLKCQ.js";
 
 // src/index.ts
 import { createRequire as createRequire2 } from "module";
@@ -3269,10 +3269,13 @@ function validateStepsArray(steps, pathPrefix, errors) {
           const a = value;
           if (!a.platform) errors.push({ path: `${fieldPath}.platform`, message: 'Action must have "platform"' });
           if (!a.actionId) errors.push({ path: `${fieldPath}.actionId`, message: 'Action must have "actionId"' });
-          if (!a.connectionKey) errors.push({ path: `${fieldPath}.connectionKey`, message: 'Action must have "connectionKey"' });
+          validateConnectionForm(a, fieldPath, errors);
         }
       }
     }
+    if (descriptor.type === "action") {
+      validateConnectionForm(config2, `${path17}.${configKey}`, errors);
+    }
     if (descriptor.type === "code") {
       const hasSource = typeof config2.source === "string" && config2.source.length > 0;
       const hasModule = typeof config2.module === "string" && config2.module.length > 0;
@@ -3300,6 +3303,43 @@ function validateStepsArray(steps, pathPrefix, errors) {
     }
   }
 }
+function validateConnectionForm(config2, pathPrefix, errors) {
+  const hasKey = config2.connectionKey !== void 0 && config2.connectionKey !== null && config2.connectionKey !== "";
+  const conn = config2.connection;
+  const hasRef = !!conn && typeof conn === "object" && !Array.isArray(conn) && typeof conn.platform === "string" && conn.platform.length > 0;
+  if (hasKey && hasRef) {
+    errors.push({
+      path: pathPrefix,
+      message: `Action has both "connectionKey" and "connection" \u2014 set exactly one. Prefer "connection: { platform, tag? }" so re-auth doesn't break the flow.`
+    });
+    return;
+  }
+  if (!hasKey && !hasRef) {
+    errors.push({
+      path: pathPrefix,
+      message: 'Action must set "connection: { platform: <name> }" (or legacy "connectionKey: <key>").'
+    });
+    return;
+  }
+  if (hasRef) {
+    const c = conn;
+    if (c.tag !== void 0 && typeof c.tag !== "string") {
+      errors.push({
+        path: `${pathPrefix}.connection.tag`,
+        message: '"connection.tag" must be a string when set'
+      });
+    }
+    const allowed = /* @__PURE__ */ new Set(["platform", "tag"]);
+    for (const k of Object.keys(c)) {
+      if (!allowed.has(k)) {
+        errors.push({
+          path: `${pathPrefix}.connection.${k}`,
+          message: `Unknown field "${k}" in connection ref. Allowed: platform, tag.`
+        });
+      }
+    }
+  }
+}
 function detectFlatConfigHint(step, descriptor) {
   const requiredFields = Object.entries(descriptor.fields).filter(([, fd]) => fd.required).map(([name]) => name);
   const flatFields = requiredFields.filter((f) => f in step);
@@ -4107,14 +4147,7 @@ var SCAFFOLD_TEMPLATES = {
     name: "My Workflow",
     description: "A basic workflow with a single action step",
     version: "1",
-    inputs: {
-      connectionKey: {
-        type: "string",
-        required: true,
-        description: "Connection key for the platform",
-        connection: { platform: "PLATFORM_NAME" }
-      }
-    },
+    inputs: {},
     steps: [
       {
         id: "step1",
@@ -4123,7 +4156,7 @@ var SCAFFOLD_TEMPLATES = {
         action: {
           platform: "PLATFORM_NAME",
           actionId: "ACTION_ID_FROM_SEARCH",
-          connectionKey: "$.input.connectionKey",
+          connection: { platform: "PLATFORM_NAME" },
           data: {}
         }
       }
@@ -4134,14 +4167,7 @@ var SCAFFOLD_TEMPLATES = {
     name: "Conditional Workflow",
     description: "Fetch data, then branch based on results",
     version: "1",
-    inputs: {
-      connectionKey: {
-        type: "string",
-        required: true,
-        description: "Connection key",
-        connection: { platform: "PLATFORM_NAME" }
-      }
-    },
+    inputs: {},
     steps: [
       {
         id: "fetch",
@@ -4150,7 +4176,7 @@ var SCAFFOLD_TEMPLATES = {
         action: {
           platform: "PLATFORM_NAME",
           actionId: "ACTION_ID_FROM_SEARCH",
-          connectionKey: "$.input.connectionKey"
+          connection: { platform: "PLATFORM_NAME" }
         }
       },
       {
@@ -4184,14 +4210,7 @@ var SCAFFOLD_TEMPLATES = {
     name: "Loop Workflow",
     description: "Fetch a list, then process each item",
     version: "1",
-    inputs: {
-      connectionKey: {
-        type: "string",
-        required: true,
-        description: "Connection key",
-        connection: { platform: "PLATFORM_NAME" }
-      }
-    },
+    inputs: {},
     steps: [
       {
         id: "fetchList",
@@ -4200,7 +4219,7 @@ var SCAFFOLD_TEMPLATES = {
         action: {
           platform: "PLATFORM_NAME",
           actionId: "ACTION_ID_FROM_SEARCH",
-          connectionKey: "$.input.connectionKey"
+          connection: { platform: "PLATFORM_NAME" }
         }
       },
       {
@@ -4233,14 +4252,7 @@ var SCAFFOLD_TEMPLATES = {
     name: "AI Analysis Workflow",
     description: "Fetch data, analyze with Claude, and send results",
     version: "1",
-    inputs: {
-      connectionKey: {
-        type: "string",
-        required: true,
-        description: "Connection key for data source",
-        connection: { platform: "PLATFORM_NAME" }
-      }
-    },
+    inputs: {},
     steps: [
       {
         id: "fetchData",
@@ -4249,7 +4261,7 @@ var SCAFFOLD_TEMPLATES = {
         action: {
           platform: "PLATFORM_NAME",
           actionId: "ACTION_ID_FROM_SEARCH",
-          connectionKey: "$.input.connectionKey"
+          connection: { platform: "PLATFORM_NAME" }
         }
       },
       {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withone/cli",
-  "version": "1.40.0",
+  "version": "1.41.0",
   "description": "CLI for managing One",
   "type": "module",
   "files": [

package/skills/one/references/flows.md

@@ -282,12 +282,19 @@ The `if`, `unless`, `condition.expression`, `while.condition`, `transform.expres
   "action": {
     "platform": "stripe",
     "actionId": "conn_mod_def::xxx::yyy",
-    "connectionKey": "$.input.stripeConnectionKey",
+    "connection": { "platform": "stripe" },
     "data": { "query": "email:'{{$.input.customerEmail}}'" }
   }
 }
 ```
 
+**Connection forms.** Each action step sets exactly one of:
+
+- **`connection: { platform: "<name>", "tag"?: "<tag>" }`** (preferred) — late-bound, resolved at flow-execute time. Survives re-auth (which always mints a new key). Use `tag` to disambiguate when a platform has multiple connections (e.g. multi-account Gmail). Both `platform` and `tag` accept `$.input.x` selectors so flows can be parameterised per-execution.
+- **`connectionKey: "<literal-or-selector>"`** (legacy) — passes the key string straight through. Still supported for backwards compat, but breaks on re-auth and forces manual edits across every flow that references the stale key. Migrate to `connection` when convenient.
+
+The validator rejects an action that sets both forms (or neither) at `flow validate` and `flow execute` time.
+
 ### `transform` — JS expression (implicit return)
 
 ```json