@dench.com/cli 3.8.0-staging.389 → 3.8.2-staging.391

package/lib/api-schemas.ts

@@ -20,15 +20,23 @@
  */
 import { type ZodTypeAny, z } from "zod";
 import {
+  CONDITION_CHECKS,
+  CONDITION_OPERATORS,
   checkCampaignSteps,
   checkStepEdits,
+  hasWorkflowShape,
   LINKEDIN_REACTIONS,
+  MAX_ACCEPTANCE_WAIT_HOURS,
   MAX_CAMPAIGN_STEPS,
   MAX_INMAIL_BODY_CHARS,
   MAX_INMAIL_SUBJECT_CHARS,
   MAX_LIKE_POST_AGE_DAYS,
+  MAX_LIKE_POST_COUNT,
   MAX_WAIT_HOURS,
+  MIN_ACCEPTANCE_WAIT_HOURS,
   MIN_WITHDRAW_AFTER_HOURS,
+  STEP_TYPES,
+  WORKFLOW_END,
 } from "./campaign-steps";
 
 const nativeEmailRecipient = z.object({
@@ -667,16 +675,25 @@ const campaignSendSchedule = z
   );
 
 const campaignStepType = z
-  .enum([
-    "email",
-    "wait",
-    "linkedin_visit",
-    "linkedin_connection",
-    "linkedin_message",
-    "linkedin_like_post",
-    "linkedin_inmail",
-  ])
-  .describe("Step type.");
+  .enum(STEP_TYPES)
+  .describe(
+    "Step type. condition (If / else) and wait_for_connection (Wait for them to accept) send nothing; they continue on yesNext or noNext and make the campaign a workflow.",
+  );
+
+const workflowTarget = (exit: string) =>
+  z
+    .string()
+    .min(1)
+    .optional()
+    .describe(
+      `Workflow steps: ${exit}: another step's key, or "${WORKFLOW_END}" to stop there. Fixed once the campaign launches.`,
+    );
+
+const campaignStepModel = z
+  .enum(["linear", "workflow"])
+  .describe(
+    "linear: steps run in order. workflow: steps have keys and paths (next, yesNext, noNext) and may include condition and wait_for_connection. Left out, a workflow stays one and steps with keys, paths or those types make one; nothing turns a workflow back into a list.",
+  );
 
 const campaignStepInput = z
   .object({
@@ -723,7 +740,7 @@ const campaignStepInput = z
       .string()
       .optional()
       .describe(
-        "Legacy LinkedIn step sender. Pool campaigns use the campaign's linkedinAccountIds instead.",
+        "Legacy LinkedIn step sender (also on wait_for_connection, and on a condition that checks linkedin_connected). Pool campaigns use the campaign's linkedinAccountIds instead.",
       ),
     linkedinMessageBody: z
       .string()
@@ -743,7 +760,7 @@ const campaignStepInput = z
       .max(MAX_WAIT_HOURS)
       .optional()
       .describe(
-        `linkedin_message with linkedinMessageMode=wait_until_connected: wait 1-${MAX_WAIT_HOURS} hours for acceptance (default 720). After a connection step this mode is the default.`,
+        `linkedin_message with linkedinMessageMode=wait_until_connected: wait 1-${MAX_WAIT_HOURS} hours for acceptance (default 720); after a connection step this mode is the default in a linear campaign. wait_for_connection: wait ${MIN_ACCEPTANCE_WAIT_HOURS}-${MAX_ACCEPTANCE_WAIT_HOURS} hours (1-90 days, default 720) before taking the Not accepted path.`,
       ),
     likeReaction: z
       .enum(LINKEDIN_REACTIONS)
@@ -760,12 +777,27 @@ const campaignStepInput = z
       .describe(
         `linkedin_like_post only: select the newest eligible original post from the last 1-${MAX_LIKE_POST_AGE_DAYS} days (default 30).`,
       ),
+    likeSkipPreviousWait: z
+      .boolean()
+      .optional()
+      .describe(
+        "linkedin_like_post only: before the immediately preceding wait starts, check for eligible posts. If none exist, skip that wait and the like step, keeping following waits. Defaults to false when omitted.",
+      ),
     likeSkipNextWait: z
       .boolean()
       .optional()
       .describe(
         "linkedin_like_post only: skip consecutive following wait steps whenever the reaction step is skipped (default true). False keeps those waits.",
       ),
+    likeCount: z
+      .number()
+      .int()
+      .min(1)
+      .max(MAX_LIKE_POST_COUNT)
+      .optional()
+      .describe(
+        `linkedin_like_post only: how many recent posts to react to, 1-${MAX_LIKE_POST_COUNT} (default 1).`,
+      ),
     inmailSubject: z
       .string()
       .optional()
@@ -781,6 +813,46 @@ const campaignStepInput = z
       .describe(
         `linkedin_connection only: withdraw a still-pending invitation sent by this campaign after ${MIN_WITHDRAW_AFTER_HOURS}-${MAX_WAIT_HOURS} hours (7-90 days). Omitted means off on creation; null turns it off on edit.`,
       ),
+    key: z
+      .string()
+      .min(1)
+      .optional()
+      .describe(
+        `Workflow steps: this step's id, unique in the campaign, which next, yesNext and noNext point at (not "${WORKFLOW_END}"). Left out, one is made.`,
+      ),
+    next: workflowTarget(
+      "where a step that isn't a condition or wait_for_connection goes; left out, the following step",
+    ),
+    yesNext: workflowTarget(
+      "condition and wait_for_connection only, required: where the Yes (Accepted) path goes",
+    ),
+    noNext: workflowTarget(
+      "condition and wait_for_connection only, required: where the No (Not accepted) path goes",
+    ),
+    check: z
+      .enum(CONDITION_CHECKS)
+      .optional()
+      .describe(
+        "condition only, required: linkedin_connected, has_email, opened_last_email (needs an email before it on every path) or field_value. Fixed once the campaign launches.",
+      ),
+    conditionField: z
+      .string()
+      .optional()
+      .describe(
+        'condition with check=field_value: the lead field to check, like "Job Title" or "Source" (the campaign itself changes Status, Last touch and LinkedIn connection). Fixed once the campaign launches.',
+      ),
+    conditionOperator: z
+      .enum(CONDITION_OPERATORS)
+      .optional()
+      .describe(
+        "condition with check=field_value: is, is_not, contains, is_empty or is_not_empty (all case-insensitive). Fixed once the campaign launches.",
+      ),
+    conditionValue: z
+      .string()
+      .optional()
+      .describe(
+        "condition with check=field_value and is, is_not or contains: the text to compare with. Editable after launch.",
+      ),
   })
   .describe("One campaign step, in order.");
 
@@ -814,10 +886,16 @@ const campaignTimelineRun = z
       .optional()
       .describe("The email this run sent, in emailMessages[]."),
     lastError: z.string().optional(),
+    timeoutAt: z
+      .number()
+      .optional()
+      .describe("wait_for_connection: when it stops waiting for the accept."),
     result: z
       .unknown()
       .optional()
-      .describe("For a skipped step, { reason } says why."),
+      .describe(
+        'For a skipped step, { reason } says why. A finished condition or wait_for_connection has { branch: "yes" | "no" } (Yes / Accepted or No / Not accepted), and { reason } for some No paths.',
+      ),
   })
   .passthrough();
 
@@ -863,6 +941,7 @@ const campaignRow = z
     sendSchedules: z.array(campaignSendSchedule).optional(),
     dailySendCap: z.number().optional(),
     stepCount: z.number(),
+    stepModel: campaignStepModel.optional(),
     totalEnrolled: z.number(),
     activeCount: z.number(),
     pausedCount: z.number(),
@@ -3110,7 +3189,12 @@ export const requestSchemas: Record<string, ZodTypeAny> = {
         .min(1)
         .max(MAX_CAMPAIGN_STEPS)
         .describe(
-          "Every step, in send order. Rejected, not trimmed: a field the step type would drop (onlyIf off email/post-like steps, a body on a visit, reply-in-thread on the first email), a missing subject or required body, an overlength note/message/InMail subject, out-of-range wait/withdrawal/post-age values, and {TOKEN} single braces, which would be sent as typed.",
+          "Every step, in send order (a workflow may list them in any order; they are stored in path order). Rejected, not trimmed: a field the step type would drop (onlyIf off email/post-like steps, a body on a visit, reply-in-thread on the first email, condition fields its check ignores), a missing subject or required body, an overlength note/message/InMail subject, out-of-range wait/withdrawal/post-age/acceptance values, {TOKEN} single braces, which would be sent as typed, and workflow paths that don't hold together (duplicate keys, a target that isn't a key or end, a condition or wait_for_connection without both yesNext and noNext, or any other step with them).",
+        ),
+      stepModel: campaignStepModel
+        .optional()
+        .describe(
+          "linear: steps run in order. workflow: steps have keys and paths (next, yesNext, noNext) and may include condition and wait_for_connection. Left out, a workflow stays one and steps with keys, paths or those types make one; nothing turns a workflow back into a list. When replacing a workflow's steps, send workflow, so steps without keys or paths are checked here the way they will be saved.",
         ),
       allowSingleBraces: z
         .boolean()
@@ -3121,8 +3205,20 @@ export const requestSchemas: Record<string, ZodTypeAny> = {
     })
     .strict()
     .superRefine((input, ctx) => {
+      if (input.stepModel === "linear") {
+        const shaped = input.steps.findIndex(hasWorkflowShape);
+        if (shaped >= 0)
+          ctx.addIssue({
+            code: "custom",
+            message: `Step ${shaped + 1}: condition, wait_for_connection, key, next, yesNext and noNext only work in a workflow. Send stepModel "workflow", or leave it out.`,
+            path: ["steps", shaped],
+          });
+      }
       for (const issue of checkCampaignSteps(input.steps, {
         allowSingleBraces: input.allowSingleBraces,
+        ...(input.stepModel
+          ? { workflow: input.stepModel === "workflow" }
+          : {}),
       }).errors)
         ctx.addIssue({
           code: "custom",
@@ -3154,13 +3250,13 @@ export const requestSchemas: Record<string, ZodTypeAny> = {
             })
             .strict()
             .describe(
-              "One step edit: only the fields given change. Clear text with an empty string, onlyIf with always, emailReplyToPrevious with false and withdrawAfterHours with null. Like settings are optional; omitted values stay unchanged.",
+              "One step edit: only the fields given change. Clear text with an empty string, onlyIf with always, emailReplyToPrevious with false and withdrawAfterHours with null. Like settings are optional; omitted values stay unchanged. A workflow step's key, next, yesNext, noNext, check, conditionField and conditionOperator can't change after launch (send them unchanged or leave them out); conditionValue and a wait_for_connection's connectionTimeoutHours can.",
             ),
         )
         .min(1)
         .max(MAX_CAMPAIGN_STEPS)
         .describe(
-          "The steps to change. Rejected, not trimmed: a field the step type would drop, an overlength note/message/InMail subject, out-of-range wait/withdrawal/post-age values, and {TOKEN} single braces.",
+          "The steps to change. Rejected, not trimmed: a field the step type would drop, an overlength note/message/InMail subject, out-of-range wait/withdrawal/post-age/acceptance values, {TOKEN} single braces, and a changed path or If / else check.",
         ),
       allowSingleBraces: z
         .boolean()
@@ -5039,7 +5135,11 @@ export const responseSchemas: Record<string, ZodTypeAny> = {
   "campaigns.get": z
     .object({
       sequence: campaignRow,
-      steps: z.array(campaignStepInput.passthrough()),
+      steps: z
+        .array(campaignStepInput.passthrough())
+        .describe(
+          "The steps in order, each with its _id. condition and wait_for_connection steps also carry a readable label.",
+        ),
       enrollments: z.array(z.record(z.string(), z.unknown())),
       currentRuns: z
         .record(z.string(), z.unknown())
@@ -5079,6 +5179,22 @@ export const responseSchemas: Record<string, ZodTypeAny> = {
       replyRate: z.number(),
       openRate: z.number(),
       clickRate: z.number(),
+      branchStats: z
+        .array(
+          z.object({
+            stepId: z.string(),
+            yes: z
+              .number()
+              .describe("People who took the Yes (Accepted) path."),
+            no: z
+              .number()
+              .describe("People who took the No (Not accepted) path."),
+          }),
+        )
+        .optional()
+        .describe(
+          "Workflows only: each condition and wait_for_connection step, in step order, with how many people took each path.",
+        ),
       truncated: z.boolean(),
     })
     .passthrough(),
@@ -5091,7 +5207,28 @@ export const responseSchemas: Record<string, ZodTypeAny> = {
       dailySendCap: z.number().nullable(),
       nextEmailAt: z.number().nullable(),
       now: z.record(z.string(), z.unknown()).nullable(),
-      next: z.record(z.string(), z.unknown()).nullable(),
+      next: z
+        .object({
+          kind: z
+            .string()
+            .describe(
+              "profile, visit, invite, message, like, inmail, withdraw, email, wait or check (an If / else).",
+            ),
+          acceptanceDeadline: z
+            .number()
+            .optional()
+            .describe(
+              "Waiting for them to accept: when the wait ends either way.",
+            ),
+          label: z
+            .string()
+            .optional()
+            .describe(
+              'kind check: what the If / else checks, e.g. "Has an email address".',
+            ),
+        })
+        .passthrough()
+        .nullable(),
       paused: z.record(z.string(), z.unknown()).nullable(),
       senders: z.array(z.record(z.string(), z.unknown())),
     })
@@ -6387,18 +6524,41 @@ export const requestExamples: Record<string, unknown> = {
   },
   "campaigns.steps.replace": {
     sequenceId: "<sequenceId>",
+    stepModel: "workflow",
     steps: [
-      { type: "linkedin_visit" },
       {
+        key: "connected",
+        type: "condition",
+        check: "linkedin_connected",
+        yesNext: "message",
+        noNext: "invite",
+      },
+      {
+        key: "invite",
         type: "linkedin_connection",
         linkedinMessageBody:
           "Hi {{First name}}, enjoyed your post on {{Topic}}.",
+        next: "accept",
+      },
+      {
+        key: "accept",
+        type: "wait_for_connection",
+        connectionTimeoutHours: 240,
+        yesNext: "message",
+        noNext: "email",
       },
-      { type: "wait", waitHours: 48 },
       {
+        key: "email",
         type: "email",
         emailSubject: "Quick question, {{First name}}",
         emailTextBody: "Hi {{First name}}, ...",
+        next: "end",
+      },
+      {
+        key: "message",
+        type: "linkedin_message",
+        linkedinMessageBody: "Thanks for connecting, {{First name}}. ...",
+        next: "end",
       },
     ],
   },
@@ -6417,6 +6577,12 @@ export const requestExamples: Record<string, unknown> = {
         type: "wait",
         waitHours: 96,
       },
+      {
+        stepId: "<waitForConnectionStepId>",
+        expectedUpdatedAt: 1765526400000,
+        type: "wait_for_connection",
+        connectionTimeoutHours: 336,
+      },
     ],
   },
   "campaigns.personalization.set": {

package/lib/app-sdk-catalog.generated.ts

@@ -381,12 +381,12 @@ export const APP_SDK_OPERATIONS: readonly AppSdkOperationInfo[] = [
   {"id":"campaigns.create","group":"campaigns","summary":"Create a draft outreach campaign with email and LinkedIn sender pools and a business-hours send window in the given timezone.","cli":"dench campaign create","method":"POST","path":"/campaigns","permission":"campaigns:write","pathParams":[]},
   {"id":"campaigns.duplicate","group":"campaigns","summary":"Copy a campaign into a new draft named \"<name> copy\": the same steps, schedule, sender pools and personalized lines, its lead source paused, and no people. To reach more than 300 people, duplicate and add the next page of the search to the copy.","cli":"dench campaign duplicate","method":"POST","path":"/campaigns/{sequenceId}/duplicate","permission":"campaigns:write","pathParams":["sequenceId"]},
   {"id":"campaigns.get","group":"campaigns","summary":"Read a campaign: settings, steps, people, their current step and hold, last touches, linked leads.","cli":"dench campaign get","method":"GET","path":"/campaigns/{sequenceId}","permission":"campaigns:read","pathParams":["sequenceId"]},
-  {"id":"campaigns.analytics","group":"campaigns","summary":"Campaign funnel: enrolled, contacted, invited, accepted, messaged, replied, opens and clicks.","cli":"dench campaign get","method":"GET","path":"/campaigns/{sequenceId}/analytics","permission":"campaigns:read","pathParams":["sequenceId"]},
+  {"id":"campaigns.analytics","group":"campaigns","summary":"Campaign funnel: enrolled, contacted, invited, accepted, messaged, replied, opens and clicks, and for a workflow how many people took each If / else and Wait for them to accept path (branchStats).","cli":"dench campaign get","method":"GET","path":"/campaigns/{sequenceId}/analytics","permission":"campaigns:read","pathParams":["sequenceId"]},
   {"id":"campaigns.live","group":"campaigns","summary":"What the campaign is doing now, what comes next and when, and why it is holding.","cli":"dench campaign get","method":"GET","path":"/campaigns/{sequenceId}/live","permission":"campaigns:read","pathParams":["sequenceId"]},
   {"id":"campaigns.pipeline","group":"campaigns","summary":"Where a campaign's people sit in the workspace's lead pipeline right now: each lead Status in order with how many enrolled leads are at it, and how many have no lead or a status outside the pipeline.","cli":"dench campaign pipeline","method":"GET","path":"/campaigns/{sequenceId}/pipeline","permission":"campaigns:read","pathParams":["sequenceId"]},
   {"id":"campaigns.update","group":"campaigns","summary":"Change a campaign's name, sender pools, send windows, daily email cap, stop-on-reply, start or end. Works until archived; existing conversations keep their assigned sender.","cli":"dench campaign set","method":"PATCH","path":"/campaigns/{sequenceId}","permission":"campaigns:write","pathParams":["sequenceId"]},
-  {"id":"campaigns.steps.replace","group":"campaigns","summary":"Replace every step of a draft campaign (email, wait, LinkedIn visit, connection request, message, post reaction, InMail). Steps are checked first: a field the step type would drop, missing text or {TOKEN} single braces are rejected, not saved. Configure sender pools on the campaign; step sender ids are legacy-only.","cli":"dench campaign steps set","method":"PUT","path":"/campaigns/{sequenceId}/steps","permission":"campaigns:write","pathParams":["sequenceId"]},
-  {"id":"campaigns.steps.update","group":"campaigns","summary":"Edit the text, waits and conditions of a launched (or paused) campaign's steps in place. Each step keeps its id, type and place; pass the stepId and the updatedAt you read, and only the fields you change. Messages already sent or being prepared keep their text; drafts use campaigns.steps.replace.","cli":"dench campaign steps edit","method":"PATCH","path":"/campaigns/{sequenceId}/steps","permission":"campaigns:write","pathParams":["sequenceId"]},
+  {"id":"campaigns.steps.replace","group":"campaigns","summary":"Replace every step of a draft campaign (email, wait, LinkedIn visit, connection request, message, post reaction, InMail, If / else, Wait for them to accept). A workflow (stepModel workflow, or steps with key, next, yesNext or noNext) branches: condition and wait_for_connection steps continue on yesNext or noNext, other steps on next; each points at another step's key or end. Steps are checked first: a field the step type would drop, missing text, {TOKEN} single braces or paths that don't hold together are rejected, not saved. Configure sender pools on the campaign; step sender ids are legacy-only.","cli":"dench campaign steps set","method":"PUT","path":"/campaigns/{sequenceId}/steps","permission":"campaigns:write","pathParams":["sequenceId"]},
+  {"id":"campaigns.steps.update","group":"campaigns","summary":"Edit the text, waits and conditions of a launched (or paused) campaign's steps in place. Each step keeps its id, type and place; pass the stepId and the updatedAt you read, and only the fields you change. A workflow keeps its paths and what each If / else checks (key, next, yesNext, noNext, check, conditionField, conditionOperator); conditionValue and acceptance waits stay editable. Messages already sent or being prepared keep their text; drafts use campaigns.steps.replace.","cli":"dench campaign steps edit","method":"PATCH","path":"/campaigns/{sequenceId}/steps","permission":"campaigns:write","pathParams":["sequenceId"]},
   {"id":"campaigns.personalization.get","group":"campaigns","summary":"Read a campaign's personalized lines (written for each person): their {{keys}} for steps, instructions and fallbacks, how many people have them, and the cost per person.","cli":"dench campaign personalize get","method":"GET","path":"/campaigns/{sequenceId}/personalization","permission":"campaigns:read","pathParams":["sequenceId"]},
   {"id":"campaigns.personalization.set","group":"campaigns","summary":"Define up to 5 personalized lines (each used as {{key}} in steps) and what you sell. Saving starts writing missing lines for up to 100 people, about 3 cents a person; for more it returns needsConfirm and writes nothing until campaigns.personalization.write is confirmed.","cli":"dench campaign personalize set","method":"PUT","path":"/campaigns/{sequenceId}/personalization","permission":"campaigns:write","pathParams":["sequenceId"]},
   {"id":"campaigns.personalization.clear","group":"campaigns","summary":"Turn off a campaign's personalized lines and cancel the ones not yet written. Refused while a step still uses one of the {{keys}}.","cli":"dench campaign personalize clear","method":"DELETE","path":"/campaigns/{sequenceId}/personalization","permission":"campaigns:write","pathParams":["sequenceId"]},