@koda-sl/baker-cli 0.208.1 → 0.209.0

package/README.md

@@ -3000,7 +3000,7 @@ baker history list --category ads --full    # ad writes with raw metadata
 
 ---
 
-### `baker hubspot forms list | view | submissions` · `baker hubspot workflows list` · `baker hubspot pipelines list` · `baker hubspot contacts summary | lookup` · `baker hubspot meetings list | view`
+### `baker hubspot forms list | view | submissions` · `baker hubspot workflows list | view` · `baker hubspot pipelines list` · `baker hubspot contacts summary | lookup` · `baker hubspot meetings list | view`
 
 Read-only view of the company's **connected HubSpot account** — the forms and meeting links (calendars) that live there, the leads those forms received, and the workflows, deal pipelines, and contact records a lead runs through afterwards. Fetched from HubSpot live on every call; nothing is cached and nothing is ever written back.
 
@@ -3016,6 +3016,8 @@ baker hubspot forms view <formId> --as-node     # the form.external blob for a f
 baker hubspot forms submissions <formId>        # how many leads it received, and when
 baker hubspot forms submissions <formId> --days 90 --full
 baker hubspot workflows list --enabled-only     # what runs after a lead is captured
+baker hubspot workflows view <workflowId>       # enrolment, branches in order, what each step writes
+baker hubspot workflows view <workflowId> --full  # + the values each branch compares
 baker hubspot pipelines list                    # where a lead lands, and the stages after it
 baker hubspot contacts summary --days 30        # are recent leads being worked? (counts only)
 baker hubspot contacts lookup lead@example.com  # was this one lead picked up?
@@ -3028,6 +3030,7 @@ baker hubspot meetings view <slug> --as-node    # the form.external blob for a f
 **`forms view`:** positional `<formId>`; `--full` adds the untouched HubSpot payload; `--as-node` returns the resource blob instead of the readable view.
 **`forms submissions`:** positional `<formId>`; `--days <1-365>` (default 30) sets the window; `--full` adds each submission's field values. The default response is counts and dates only — `total`, `inWindow`, `lastSubmittedAt`, and per-day counts — because submissions carry the lead's own contact details. `truncated: true` means the page budget ran out before the window was covered, so `inWindow` is a floor rather than an exact count.
 **`workflows list` flags:** `--search <text>`, `--enabled-only`. Disabled workflows are listed too — a form wired to one that is off looks connected and does nothing.
+**`workflows view`:** positional `<workflowId>` (the id from `workflows list`, and the one in HubSpot's own URL — the command translates it to HubSpot's separate internal flow id for you). Returns the enrolment criteria and whether it re-enrols (`null` = HubSpot does not report it for that criteria type, so it is unknown rather than off), plus every step with the property it writes. On a `LIST_BRANCH` step, branches come back in **evaluation order** (`order: 1` wins over `order: 2`) — a broad branch above a narrower one silently swallows the records the narrow one was written for, and HubSpot reports nothing. A `STATIC_BRANCH` matches on a value rather than top down, so its `order` is display only. `steps` is **not** in execution order; follow `nextActionId`. `--full` adds the raw payload, the only place the branch filter criteria (which property is compared to which value) can be read.
 **`pipelines list`:** no flags; stages come back in the order they run in HubSpot.
 **`contacts summary` flags:** `--days <1-365>` (default 30) over contact creation date. Returns counts only — total contacts, how many have an owner, and the lifecycle-stage split — never a name or an email. `truncated: true` means the page budget ran out, so the counts are floors.
 **`contacts lookup`:** positional `<email>`; returns that contact's lifecycle stage, owner, the account (company) it was filed under, and associated deals with their stage. `dealsReadable: false` / `companyReadable: false` mean the connection does not cover deals or accounts, so an empty `deals` or a null `company` is unknown rather than absent. `found: false` means no contact with that email — the lead never reached the CRM, which is a finding rather than an error.

package/dist/cli.js

@@ -4794,6 +4794,60 @@ var hubspotWorkflowsListResponseSchema = z12.object({
   ok: z12.literal(true),
   data: z12.object({ workflows: z12.array(hubspotWorkflowSummarySchema) })
 });
+var hubspotWorkflowsViewRequestSchema = z12.object({
+  /** The id from `workflows list`. Resolved to HubSpot's internal flow id server-side. */
+  workflowId: z12.string().min(1),
+  /**
+   * Include the untouched HubSpot payload — the only place the branch filter
+   * criteria (which property is compared to which value) can be read.
+   */
+  full: z12.boolean().optional()
+});
+var hubspotWorkflowBranchSchema = z12.object({
+  /**
+   * 1-based position in the order HubSpot lists the branches. On a `LIST_BRANCH`
+   * that is precedence — branch 1 wins over branch 2. On a `STATIC_BRANCH` it is
+   * only display order; those match on the value in `name`, not top down.
+   */
+  order: z12.number().int(),
+  name: z12.string(),
+  nextActionId: z12.string().nullable()
+});
+var hubspotWorkflowStepSchema = z12.object({
+  actionId: z12.string(),
+  /** HubSpot's action kind: LIST_BRANCH, SINGLE_CONNECTION, CUSTOM_CODE, WEBHOOK... */
+  type: z12.string(),
+  actionTypeId: z12.string().nullable(),
+  /** The step's configured inputs — for a property-setting step, what it writes and where. */
+  fields: z12.record(z12.string(), z12.unknown()).nullable(),
+  nextActionId: z12.string().nullable(),
+  /** Present only on branch steps, in evaluation order. */
+  branches: z12.array(hubspotWorkflowBranchSchema).nullable(),
+  defaultBranch: z12.object({ name: z12.string().nullable(), nextActionId: z12.string().nullable() }).nullable()
+});
+var hubspotWorkflowDetailSchema = z12.object({
+  /** HubSpot's internal flow id, which differs from the workflow id. */
+  id: z12.string(),
+  /** The id this workflow is known by in `workflows list` and in HubSpot's own URLs. */
+  workflowId: z12.string(),
+  name: z12.string(),
+  enabled: z12.boolean(),
+  flowType: z12.string().nullable(),
+  /** The record type it runs on: "0-1" contacts, "0-2" companies, "0-3" deals. */
+  objectTypeId: z12.string().nullable(),
+  enrollment: z12.object({
+    type: z12.string().nullable(),
+    /** Null means HubSpot's criteria shape does not report it — unknown, not off. */
+    reEnrollment: z12.boolean().nullable()
+  }),
+  /** Every step. Execution order follows `nextActionId`, not the array index. */
+  steps: z12.array(hubspotWorkflowStepSchema),
+  raw: z12.record(z12.string(), z12.unknown()).optional()
+});
+var hubspotWorkflowsViewResponseSchema = z12.object({
+  ok: z12.literal(true),
+  data: z12.object({ workflow: hubspotWorkflowDetailSchema })
+});
 var hubspotContactsSummaryRequestSchema = z12.object({
   /** Window in days, counted back from now, over contact creation date. */
   days: z12.number().int().min(1).max(365).default(30)
@@ -29872,6 +29926,23 @@ registerSchema({
     "enabled-only": { type: "boolean", description: "Only workflows that are on", required: false, default: false }
   }
 });
+registerSchema({
+  command: "hubspot.workflows.view",
+  description: "One workflow's actual configuration: what enrols a record, whether it re-enrols, and every step with the property it writes. Read it before saying a workflow is correct \u2014 `workflows list` only tells you it exists and whether it is on. Branches come back in HubSpot's order, and on a LIST_BRANCH step that is evaluation order (`order: 1` wins over `order: 2`) \u2014 which is where this kind of setup silently breaks: a broad branch placed above a narrow one swallows the records the narrow one was written for, and nothing reports it. A STATIC_BRANCH matches on a value instead, so its order carries no precedence. Steps are NOT in execution order \u2014 follow `nextActionId` from step to step. Add --full for the branch filter criteria (which property is compared to which value).",
+  args: {
+    workflowId: {
+      type: "positional",
+      description: "Workflow id (from `baker hubspot workflows list`)",
+      required: true
+    },
+    full: {
+      type: "boolean",
+      description: "Include the raw HubSpot payload \u2014 the only place the branch filter criteria can be read",
+      required: false,
+      default: false
+    }
+  }
+});
 registerSchema({
   command: "hubspot.pipelines.list",
   description: "The account's deal pipelines and their stages, in the order they run. Use it to answer where a lead lands once captured and whether it moved \u2014 the 'have these leads been worked?' half of a form audit.",
@@ -30171,6 +30242,62 @@ var workflowsListCommand = defineCommand120({
     }
   }
 });
+function workflowViewHints(workflow) {
+  const hints = [];
+  if (!workflow.enabled) {
+    hints.push(
+      "This workflow is switched off, so nothing below it is running now \u2014 it may still have run while it was on. Say so before reporting on what it does."
+    );
+  }
+  const ordered = workflow.steps.filter((step) => step.type === "LIST_BRANCH" && (step.branches?.length ?? 0) > 1);
+  if (ordered.length > 0) {
+    hints.push(
+      "Branches are listed in evaluation order and the first match wins. Check that no broad branch sits above a narrower one \u2014 if it does, the narrow branch never runs and nothing in HubSpot reports it."
+    );
+  }
+  if (workflow.raw === void 0 && ordered.length > 0) {
+    hints.push(
+      "This view names the branches but not what they compare. Re-run with --full to read the filter criteria before judging whether a branch matches what it was meant to match."
+    );
+  }
+  if (workflow.enrollment.reEnrollment === false) {
+    hints.push(
+      "Re-enrolment is off: a record that meets the criteria a second time will not run through this again. That is a real choice, not necessarily a fault \u2014 but confirm it is the intended one."
+    );
+  } else if (workflow.enrollment.reEnrollment === null) {
+    hints.push(
+      "Whether this re-enrols is not reported for this kind of enrolment, so do not state it either way \u2014 read it in HubSpot if it matters."
+    );
+  }
+  return hints;
+}
+var workflowsViewCommand = defineCommand120({
+  meta: {
+    name: "view",
+    description: "Read one workflow's real configuration \u2014 enrolment, branches in order, and what each step writes. Example: baker hubspot workflows view 121183594 --full"
+  },
+  args: {
+    workflowId: {
+      type: "positional",
+      description: "Workflow id (from `baker hubspot workflows list`)",
+      required: true
+    },
+    full: { type: "boolean", description: "Include the raw HubSpot payload with the filter criteria", required: false }
+  },
+  run: async ({ args }) => {
+    try {
+      const response = await apiPost("/api/hubspot/workflows/view", {
+        workflowId: args.workflowId,
+        ...args.full ? { full: true } : {}
+      });
+      const { workflow } = response.data;
+      const hints = workflowViewHints(workflow);
+      writeJson({ ...response, meta: { count: workflow.steps.length }, ...hints.length > 0 ? { hints } : {} });
+    } catch (err) {
+      failNotConnected(err);
+    }
+  }
+});
 var pipelinesListCommand = defineCommand120({
   meta: {
     name: "list",
@@ -30292,7 +30419,7 @@ var formsCommand = defineCommand120({
 });
 var workflowsCommand = defineCommand120({
   meta: { name: "workflows", description: "HubSpot workflows on the connected account." },
-  subCommands: { list: workflowsListCommand }
+  subCommands: { list: workflowsListCommand, view: workflowsViewCommand }
 });
 var pipelinesCommand = defineCommand120({
   meta: { name: "pipelines", description: "HubSpot deal pipelines on the connected account." },
@@ -30315,6 +30442,7 @@ Examples:
   baker hubspot forms view <formId> --as-node     # the form.external blob -> write into the step
   baker hubspot forms submissions <formId>        # how many leads it got, and when
   baker hubspot workflows list --enabled-only     # what runs after a lead is captured
+  baker hubspot workflows view <workflowId>       # its real branches, in order, and what each step writes
   baker hubspot pipelines list                    # where a lead lands, and the stages after it
   baker hubspot contacts summary --days 30        # are recent leads being worked? (counts only)
   baker hubspot contacts lookup a@b.com           # was this one lead picked up?