@dench.com/cli 3.11.6 → 3.11.7-staging.488

package/app-sdk.d.ts

@@ -80,6 +80,10 @@ export interface ApiRequests {
     name?: string;
     /** IANA timezone, e.g. America/Los_Angeles. Sets a Mon-Fri 9-18 send window in it; without one the draft has no send window. */
     timezone?: string;
+    /** Mailboxes to send from instead of your own running ones. Checked as the draft is created: one you can't use creates nothing. */
+    emailMailboxAccountIds?: string[];
+    /** LinkedIn accounts to send from instead of your own running ones. Checked as the draft is created. */
+    linkedinAccountIds?: string[];
   };
   /** Search people by filters without adding CRM records or campaign recipients. Search credits apply; this is not a free provider preview. — `dench campaign search` — POST /api/v1/campaigns/audience/search */
   "campaigns.audience.search": {
@@ -569,8 +573,10 @@ export interface ApiRequests {
     };
     steps?: Array<{
       type: "email" | "wait" | "linkedin_connection" | "linkedin_message";
+      /** Hours to wait, 1 to 1440. Required on a wait step. */
       waitHours?: number;
       emailSubject?: string;
+      /** Plain text only; draft steps keep no HTML body. */
       emailTextBody?: string;
       emailReplyToPrevious?: boolean;
       onlyIf?: "always" | "connected" | "not_connected";

package/campaign.ts

@@ -339,6 +339,14 @@ function unknownFlags(args: readonly string[], command: string): void {
     if (error instanceof CliArgError) throw new CampaignCliError(error.message);
     throw error;
   }
+  // Every caller reads its positionals first, so anything left is a typo or
+  // a value missing its flag; refuse it before a write.
+  const extra = args.find((token) => token !== "--");
+  if (extra !== undefined) {
+    throw new CampaignCliError(
+      `Unexpected argument for ${command}: ${JSON.stringify(extra)}. Quote a name with spaces, or check for a value missing its flag. Run \`dench campaign help\` for usage.`,
+    );
+  }
 }
 
 async function callQuery(
@@ -746,11 +754,13 @@ export function parseStepsJson(
 export { stepToInput };
 
 /**
- * A `--start`/`--end` value. A full timestamp is an instant already; a bare
- * date (`2026-09-03`) stays a date until the campaign's timezone is known,
- * because midnight in Los Angeles is not midnight in UTC.
+ * A `--start`/`--end` value. A timestamp with an offset is an instant
+ * already; a bare date (`2026-09-03`) or a date-time without an offset
+ * (`2026-09-03T09:00`) stays wall-clock time until the campaign's timezone
+ * is known, because 09:00 in Los Angeles is not 09:00 in UTC (nor wherever
+ * the CLI happens to run).
  */
-export type WhenFlag = number | { date: string };
+export type WhenFlag = number | { date: string; time?: string };
 
 export type ScheduleFlags = {
   timezone?: string;
@@ -761,28 +771,54 @@ export type ScheduleFlags = {
   windows: string[];
 };
 
-const DATE_ONLY = /^(\d{4})-(\d{2})-(\d{2})$/;
+/**
+ * ISO 8601 only: a date, optionally `T` + time, optionally an offset. Every
+ * part is checked, so February 30 or 25:00 is refused rather than rolled
+ * over by `Date.parse`, and other formats (09/03/2026) are refused outright.
+ */
+const ISO_WHEN =
+  /^(\d{4})-(\d{2})-(\d{2})(?:T(\d{2}):(\d{2})(?::(\d{2})(\.\d{1,3})?)?(Z|[+-]\d{2}:?\d{2})?)?$/;
+
+function isCalendarDate(year: number, month: number, day: number): boolean {
+  const utc = new Date(Date.UTC(year, month - 1, day));
+  return (
+    utc.getUTCFullYear() === year &&
+    utc.getUTCMonth() === month - 1 &&
+    utc.getUTCDate() === day
+  );
+}
 
 function parseWhenFlag(value: string, flag: string): WhenFlag {
   const trimmed = value.trim();
-  const dateOnly = trimmed.match(DATE_ONLY);
-  if (dateOnly) {
-    const [, year, month, day] = dateOnly.map(Number);
-    const utc = new Date(Date.UTC(year, month - 1, day));
-    if (
-      utc.getUTCFullYear() !== year ||
-      utc.getUTCMonth() !== month - 1 ||
-      utc.getUTCDate() !== day
-    ) {
-      throw new CampaignCliError(`${flag}: "${value}" is not a calendar date.`);
-    }
-    return { date: trimmed };
+  const match = trimmed.match(ISO_WHEN);
+  if (!match) {
+    throw new CampaignCliError(
+      `${flag} must be an ISO 8601 date or date-time, e.g. 2026-09-03, 2026-09-03T09:00 (in the campaign's timezone) or 2026-09-03T09:00:00-07:00 (got "${value}").`,
+    );
+  }
+  const [, year, month, day, hour, minute, second, , offset] = match;
+  if (!isCalendarDate(Number(year), Number(month), Number(day))) {
+    throw new CampaignCliError(`${flag}: "${value}" is not a calendar date.`);
+  }
+  const date = `${year}-${month}-${day}`;
+  if (hour === undefined) return { date };
+  if (
+    Number(hour) > 23 ||
+    Number(minute) > 59 ||
+    Number(second ?? 0) > 59 ||
+    (offset !== undefined &&
+      offset !== "Z" &&
+      (Number(offset.slice(1, 3)) > 14 || Number(offset.slice(-2)) > 59))
+  ) {
+    throw new CampaignCliError(`${flag}: "${value}" is not a valid time.`);
   }
+  const time = `${hour}:${minute}:${second ?? "00"}`;
+  // No offset: the campaign's timezone decides the instant, never the
+  // machine the CLI runs on.
+  if (offset === undefined) return { date, time };
   const parsed = Date.parse(trimmed);
   if (!Number.isFinite(parsed)) {
-    throw new CampaignCliError(
-      `${flag} must be an ISO 8601 date or date-time, e.g. 2026-09-03 or 2026-09-03T09:00:00-07:00 (got "${value}").`,
-    );
+    throw new CampaignCliError(`${flag}: "${value}" is not a valid date-time.`);
   }
   return parsed;
 }
@@ -812,26 +848,64 @@ function timezoneOffsetMs(ms: number, timeZone: string): number {
   return wallClockAsUtc - (ms - (ms % 1000));
 }
 
-/** Midnight at the start of `date` (YYYY-MM-DD) in `timezone`, as epoch ms. */
-export function zonedMidnight(date: string, timezone: string): number {
+const DAY_MS = 86_400_000;
+
+/**
+ * The instant a wall-clock time (`date` YYYY-MM-DD, `time` HH:MM[:SS]) has
+ * in `timezone`, as epoch ms. A time a DST change repeats takes its first
+ * instant; a time it skips (some zones skip midnight) takes the first instant
+ * after the gap, which is still on that date.
+ */
+export function zonedTime(
+  date: string,
+  timezone: string,
+  time = "00:00:00",
+): number {
   const timeZone = assertIanaTimezone(timezone);
   const [year, month, day] = date.split("-").map(Number);
-  const utcMidnight = Date.UTC(year, month - 1, day);
-  const offset = timezoneOffsetMs(utcMidnight, timeZone);
-  const guess = utcMidnight - offset;
-  // Around a DST change the offset in force at the guess differs from the
-  // one at UTC midnight; a second pass settles on the zone's own midnight.
-  const settled = timezoneOffsetMs(guess, timeZone);
-  return settled === offset ? guess : utcMidnight - settled;
+  const [hour = 0, minute = 0, second = 0] = time.split(":").map(Number);
+  const wall = Date.UTC(year, month - 1, day, hour, minute, second);
+  // The offsets in force around that wall time; each one that maps back to
+  // it is a reading of it.
+  const offsets = [
+    ...new Set(
+      [wall - DAY_MS, wall, wall + DAY_MS].map((ms) =>
+        timezoneOffsetMs(ms, timeZone),
+      ),
+    ),
+  ];
+  const readings = offsets
+    .map((offset) => wall - offset)
+    .filter((ms) => timezoneOffsetMs(ms, timeZone) === wall - ms);
+  if (readings.length) return Math.min(...readings);
+  // Skipped: the clock jumped from the smaller offset to the larger one
+  // somewhere in [wall - larger, wall - smaller]. The jump is the answer.
+  const before = Math.min(...offsets);
+  let lo = wall - Math.max(...offsets);
+  let hi = wall - before;
+  while (hi - lo > 1000) {
+    const mid = Math.floor((lo + hi) / 2);
+    if (timezoneOffsetMs(mid, timeZone) === before) lo = mid;
+    else hi = mid;
+  }
+  return hi - (hi % 1000);
+}
+
+/** Midnight at the start of `date` (YYYY-MM-DD) in `timezone`, as epoch ms. */
+export function zonedMidnight(date: string, timezone: string): number {
+  return zonedTime(date, timezone);
 }
 
 function resolveWhen(when: WhenFlag | null, timezone: string): number | null {
   if (when === null || typeof when === "number") return when;
-  return zonedMidnight(when.date, timezone);
+  return zonedTime(when.date, timezone, when.time);
 }
 
+/** Orders two values of the same kind (both instants, or both wall-clock). */
 function whenOrder(when: WhenFlag): number {
-  return typeof when === "number" ? when : Date.parse(when.date);
+  return typeof when === "number"
+    ? when
+    : Date.parse(`${when.date}T${when.time ?? "00:00:00"}Z`);
 }
 
 const END_BEFORE_START = "--end must be after --start.";
@@ -1460,10 +1534,32 @@ async function runCreate(ctx: CampaignCliContext): Promise<void> {
     ...senderPools,
   })) as { sequenceId: string; references?: unknown[] };
   if (hasScheduleChanges(patch)) {
-    await callMutation(ctx, `${OUTREACH}:updateDraft`, {
-      sequenceId: created.sequenceId,
-      ...patch,
-    });
+    try {
+      await callMutation(ctx, `${OUTREACH}:updateDraft`, {
+        sequenceId: created.sequenceId,
+        ...patch,
+      });
+    } catch (error) {
+      // The draft exists; say which one, so the schedule can be set on it
+      // rather than creating another.
+      const reason = error instanceof Error ? error.message : String(error);
+      if (ctx.jsonOutput) {
+        out(
+          ctx,
+          {
+            sequenceId: created.sequenceId,
+            name,
+            status: "draft",
+            scheduleSaved: false,
+            error: reason,
+          },
+          [],
+        );
+      }
+      throw new CampaignCliError(
+        `Created draft campaign "${name}" [${created.sequenceId}], but its schedule wasn't saved: ${reason}. Set it with: dench campaign set ${created.sequenceId} <the same schedule flags>`,
+      );
+    }
   }
   const schedules = patch.sendSchedules ?? [businessHoursSchedule(timezone)];
   const payload = {
@@ -1966,13 +2062,30 @@ async function runStepsEdit(
     return;
   }
   if (draft) {
-    await callMutation(ctx, `${OUTREACH}:replaceSteps`, {
-      sequenceId: row._id,
-      steps: plan.steps,
-      ...(workflow || plan.steps.some(hasWorkflowShape)
-        ? { stepModel: "workflow" }
-        : {}),
-    });
+    // The versions this edit was planned against: a step another editor
+    // saved since the read makes the replace fail rather than undo it.
+    const expectedSteps = sortedSteps(detail).map((step) => ({
+      id: String(step._id),
+      updatedAt: Number(step.updatedAt),
+    }));
+    try {
+      await callMutation(ctx, `${OUTREACH}:replaceSteps`, {
+        sequenceId: row._id,
+        steps: plan.steps,
+        expectedSteps,
+        ...(workflow || plan.steps.some(hasWorkflowShape)
+          ? { stepModel: "workflow" }
+          : {}),
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (/changed in another editor/.test(message)) {
+        throw new CampaignCliError(
+          `"${row.name}"'s steps changed since this edit read them, so nothing was saved. Read them again with dench campaign steps get ${row._id} --with-ids, redo the edit, and run it again.`,
+        );
+      }
+      throw error;
+    }
   } else {
     await callMutation(ctx, `${OUTREACH}:updateSteps`, {
       sequenceId: row._id,
@@ -4454,7 +4567,8 @@ Send window spec (--window, repeatable, all in --timezone):
   "Mon-Fri 9-18"  "Mon,Wed,Fri 10-16"  "Weekdays 9am-5pm"  "Sat-Sun 10-14"
 
 --start / --end take ISO 8601. A bare date (2026-10-01) is midnight at the start
-of that day in the campaign's timezone; add a time and offset to be exact.
+of that day in the campaign's timezone, and a time without an offset
+(2026-10-01T09:00) is that time there too; add an offset to pin the instant.
 
 steps.json: a JSON array of steps, in order. Types: email, wait, linkedin_visit,
 linkedin_connection, linkedin_message, linkedin_like_post, linkedin_inmail,

package/lib/api-schemas.ts

@@ -2310,22 +2310,48 @@ const composioToolRun = z.object({
  * One list-filter entry: a plain string includes the value; the object
  * form supports per-value `exclude` / `exactMatch`.
  */
-const searchFilterItem = z.union([
-  z.string(),
-  z.object({
-    value: z.string(),
-    exclude: z.boolean().optional(),
-    exactMatch: z.boolean().optional(),
-  }),
-]);
+const searchFilterItem = z.union(
+  [
+    z.string(),
+    // Strict: a misspelled control (`excluded`) must fail, not be stripped
+    // into an include.
+    z
+      .object({
+        value: z.string(),
+        exclude: z.boolean().optional(),
+        exactMatch: z.boolean().optional(),
+      })
+      .strict(),
+  ],
+  {
+    error: (issue) => {
+      // Name what was wrong with the object form ("Unrecognized key:
+      // excluded"); the default union message is only "Invalid input".
+      const branches = (issue as { errors?: { message: string }[][] }).errors;
+      const detail = branches?.[1]?.map((entry) => entry.message).join("; ");
+      return `Use a string or {"value": "…", "exclude": true, "exactMatch": true}${detail ? ` (${detail})` : ""}`;
+    },
+  },
+);
 
 const FILTER_OPTIONS_NOTE =
   "Accepted values: see `dench leads filters` or https://dench.com/references/find-filter-options.json.";
 
-const searchRange = z.object({
-  min: z.number().int().nonnegative().optional(),
-  max: z.number().int().nonnegative().optional(),
-});
+const searchRange = z
+  .object({
+    min: z.number().int().nonnegative().optional(),
+    max: z.number().int().nonnegative().optional(),
+  })
+  // A range has no exclude: an extra key would silently turn into a
+  // positive range.
+  .strict()
+  .refine(
+    (range) =>
+      range.min === undefined ||
+      range.max === undefined ||
+      range.min <= range.max,
+    { message: "Provide a range with min no greater than max." },
+  );
 
 const peopleSearch = z.object({
   linkedinUrl: z.string().optional(),
@@ -2508,34 +2534,43 @@ const campaignTargeting = z.object({
   companies: z.array(z.string()).optional(),
   companyTypes: z.array(z.string()).optional(),
 });
-const campaignSignalTerms = z.object({
-  post_engagement: z
-    .array(z.string())
-    .optional()
-    .describe(
-      'Post topics, phrased as what the buyer does ("using AI for outbound"), not bare product names.',
-    ),
-  keyword: z.array(z.string()).optional(),
-  hiring: z.array(z.string()).optional().describe("Roles being hired for."),
-  voice_engagement: z
-    .array(z.string())
-    .optional()
-    .describe("LinkedIn profile URLs of market voices whose posts to watch."),
-  company_engagement: z
-    .array(z.string())
-    .optional()
-    .describe("LinkedIn company page URLs of companies and competitors."),
-  brand_engagement: z
-    .array(z.string())
-    .optional()
-    .describe("The sender's own LinkedIn company page URL."),
-  exact: z
-    .array(z.enum(["post_engagement", "keyword"]))
-    .optional()
-    .describe(
-      "Topic signals searched by their exact keywords only (no drafted phrases).",
-    ),
-});
+/**
+ * Targeting a request sends. Strict: a key the builder can't represent
+ * (seniorities, companyHeadquarters, companyDomains…) is refused, not
+ * dropped, since dropping it would quietly widen the audience.
+ */
+const campaignTargetingInput = campaignTargeting.strict();
+const campaignSignalTerms = z
+  .object({
+    post_engagement: z
+      .array(z.string())
+      .optional()
+      .describe(
+        'Post topics, phrased as what the buyer does ("using AI for outbound"), not bare product names.',
+      ),
+    keyword: z.array(z.string()).optional(),
+    hiring: z.array(z.string()).optional().describe("Roles being hired for."),
+    voice_engagement: z
+      .array(z.string())
+      .optional()
+      .describe("LinkedIn profile URLs of market voices whose posts to watch."),
+    company_engagement: z
+      .array(z.string())
+      .optional()
+      .describe("LinkedIn company page URLs of companies and competitors."),
+    brand_engagement: z
+      .array(z.string())
+      .optional()
+      .describe("The sender's own LinkedIn company page URL."),
+    exact: z
+      .array(z.enum(["post_engagement", "keyword"]))
+      .optional()
+      .describe(
+        "Topic signals searched by their exact keywords only (no drafted phrases).",
+      ),
+  })
+  // A term list under a signal it doesn't recognize is refused, not dropped.
+  .strict();
 const campaignDraftSource = z
   .enum(["signals", "lookalike", "existing", "crm", "search"])
   .describe(
@@ -2575,19 +2610,40 @@ const campaignOutreachBrief = z.object({
   tone: z.enum(["conversational", "warm", "direct", "formal"]),
   channels: z.enum(["both", "email", "linkedin"]),
 });
-const campaignDraftStep = z.object({
-  type: z.enum(["email", "wait", "linkedin_connection", "linkedin_message"]),
-  waitHours: z.number().optional(),
-  emailSubject: z.string().optional(),
-  emailTextBody: z.string().optional(),
-  emailReplyToPrevious: z.boolean().optional(),
-  onlyIf: z.enum(["always", "connected", "not_connected"]).optional(),
-  linkedinMessageBody: z.string().optional(),
-  linkedinMessageMode: z
-    .enum(["skip_if_not_connected", "wait_until_connected"])
-    .optional(),
-  connectionTimeoutHours: z.number().optional(),
-});
+// Strict, with the bounds saving enforces: a field or value it can't keep
+// (an HTML body, a 13th step, a negative wait) is refused, not dropped.
+const campaignDraftStep = z
+  .object({
+    type: z.enum(["email", "wait", "linkedin_connection", "linkedin_message"]),
+    waitHours: z
+      .number()
+      .min(1)
+      .max(24 * 60)
+      .optional()
+      .describe("Hours to wait, 1 to 1440. Required on a wait step."),
+    emailSubject: z.string().max(200).optional(),
+    emailTextBody: z
+      .string()
+      .max(5000)
+      .optional()
+      .describe("Plain text only; draft steps keep no HTML body."),
+    emailReplyToPrevious: z.boolean().optional(),
+    onlyIf: z.enum(["always", "connected", "not_connected"]).optional(),
+    linkedinMessageBody: z.string().max(5000).optional(),
+    linkedinMessageMode: z
+      .enum(["skip_if_not_connected", "wait_until_connected"])
+      .optional(),
+    connectionTimeoutHours: z
+      .number()
+      .min(1)
+      .max(24 * 60)
+      .optional(),
+  })
+  .strict()
+  .refine((step) => step.type !== "wait" || step.waitHours !== undefined, {
+    message: "A wait step needs waitHours (1 to 1440).",
+    path: ["waitHours"],
+  });
 const campaignDraftSending = z.object({
   emailMailboxAccountIds: z.array(z.string()),
   linkedinAccountIds: z.array(z.string()),
@@ -3174,6 +3230,20 @@ export const requestSchemas: Record<string, ZodTypeAny> = {
         .describe(
           "IANA timezone, e.g. America/Los_Angeles. Sets a Mon-Fri 9-18 send window in it; without one the draft has no send window.",
         ),
+      emailMailboxAccountIds: z
+        .array(z.string().min(1))
+        .max(50)
+        .optional()
+        .describe(
+          "Mailboxes to send from instead of your own running ones. Checked as the draft is created: one you can't use creates nothing.",
+        ),
+      linkedinAccountIds: z
+        .array(z.string().min(1))
+        .max(50)
+        .optional()
+        .describe(
+          "LinkedIn accounts to send from instead of your own running ones. Checked as the draft is created.",
+        ),
     })
     .strict(),
   "campaigns.audience.search": z
@@ -3210,7 +3280,7 @@ export const requestSchemas: Record<string, ZodTypeAny> = {
       cadence: z.enum(["daily", "weekly", "monthly"]).optional(),
       findMoreMatching: z.boolean().optional(),
       approvalMode: campaignApprovalMode.optional(),
-      targeting: campaignTargeting.optional(),
+      targeting: campaignTargetingInput.optional(),
       signal: z
         .object({ signal: campaignSignal, enabled: z.boolean() })
         .optional(),
@@ -3244,7 +3314,7 @@ export const requestSchemas: Record<string, ZodTypeAny> = {
   "campaigns.builder.save": z
     .object({
       clientRequestId: campaignClientRequestId,
-      targeting: campaignTargeting,
+      targeting: campaignTargetingInput,
       signals: z.array(campaignSignal),
       signalTerms: campaignSignalTerms.optional(),
       findMoreMatching: z
@@ -3287,7 +3357,10 @@ export const requestSchemas: Record<string, ZodTypeAny> = {
           "ai: generate the sequence from the brief. manual: write steps.",
         ),
       brief: campaignOutreachBrief.optional(),
-      steps: z.array(campaignDraftStep).optional(),
+      steps: z
+        .array(campaignDraftStep)
+        .max(12, "A sequence can have up to 12 steps.")
+        .optional(),
       sending: campaignDraftSending.optional(),
       approvalMode: campaignApprovalMode.optional(),
     })
@@ -3332,7 +3405,7 @@ export const requestSchemas: Record<string, ZodTypeAny> = {
   "campaigns.builder.estimate": z
     .object({
       kind: z.enum(["people", "week"]),
-      targeting: campaignTargeting,
+      targeting: campaignTargetingInput,
       signals: z.array(campaignSignal).optional(),
       signalTerms: campaignSignalTerms.optional(),
     })