@dench.com/cli 3.5.5 → 3.5.6-staging.344

package/README.md

@@ -334,8 +334,9 @@ dench campaign pause|resume|archive <campaign>
 dench campaign stop <campaign> --person <enrollmentId>
 ```
 
-Steps lock at launch (`steps set` works on drafts only); the schedule, daily
-cap and stop-on-reply stay editable with `dench campaign set`. A campaign
+`steps set` works on drafts only; after launch, edit a step's text or wait
+time in the Dench app. The schedule, daily cap and stop-on-reply stay
+editable with `dench campaign set`. A campaign
 holds at most 300 people. Every command takes `--json`. The full guide,
 including the `steps.json` shape and the `--window` spec, is
 `references/CAMPAIGNS.md` (`dench campaign help` for the flag list).
@@ -355,7 +356,7 @@ returned. LinkedIn summaries expose `linkedinAccountId`, display/owner labels,
 availability, `remainingToday` (invites/messages/profiles) and
 `remainingInvitesThisWeek`. Capacity is an account-local usage snapshot before
 queued work and campaign limits; today's invites also respect the weekly cap.
-The API equivalent is `GET /v1/campaigns/accounts/linkedin`.
+The API equivalent is `GET $DENCH_API_BASE/campaigns/accounts/linkedin`.
 
 Outreach needs a workspace member's credentials (a `dench signin` session, a
 member-bound `DENCH_API_KEY`, or an agent session); an organization-only key

package/app-sdk.d.ts

@@ -1824,9 +1824,20 @@ export interface ApiRequests {
     campaignId: string;
   };
   /** List managed email campaigns (paginated, optional status filter). — `dench email campaign list` — GET /api/v1/email/campaigns */
-  "email.campaign.list": Record<string, unknown>;
+  "email.campaign.list": {
+    limit?: number;
+    cursor?: string;
+    status?: string;
+  };
   /** List a campaign's recipients (paginated, optional status filter). — `dench email campaign recipients list` — GET /api/v1/email/campaigns/{campaignId}/recipients */
-  "email.campaign.recipients.list": Record<string, unknown>;
+  "email.campaign.recipients.list": {
+    campaignId: string;
+    limit?: number;
+    cursor?: string;
+    status?: string;
+    /** Default true: attach each recipient's CRM record. */
+    includePeople?: boolean;
+  };
   /** Add campaign recipients from a CRM object: pick the object, the email field, and the entry ids. — `dench email campaign recipients add-from-object` — POST /api/v1/email/campaigns/{campaignId}/recipients/from-object */
   "email.campaign.recipients.addFromObject": Record<string, unknown>;
   /** Create a follow-up sequence from a connected inbox or verified sender. — `dench email sequence create` — POST /api/v1/email/sequences */
@@ -1856,7 +1867,12 @@ export interface ApiRequests {
   /** Enroll people from a CRM object: pick the object, the email field, and the entry ids. — `dench email sequence enroll-from-object` — POST /api/v1/email/sequences/{sequenceId}/enroll/from-object */
   "email.sequence.enrollFromObject": Record<string, unknown>;
   /** List a sequence's enrollments (paginated, optional status filter). — `dench email sequence enrollments list` — GET /api/v1/email/sequences/{sequenceId}/enrollments */
-  "email.sequence.enrollments.list": Record<string, unknown>;
+  "email.sequence.enrollments.list": {
+    sequenceId: string;
+    limit?: number;
+    cursor?: string;
+    status?: string;
+  };
   /** Pause one enrollment. — `dench email sequence enrollment pause` — POST /api/v1/email/sequences/enrollments/{enrollmentId}/pause */
   "email.sequence.enrollment.pause": Record<string, unknown>;
   /** Resume one paused enrollment. — `dench email sequence enrollment resume` — POST /api/v1/email/sequences/enrollments/{enrollmentId}/resume */
@@ -1918,6 +1934,14 @@ export interface ApiRequests {
       /** Days sends may go out: 0 = Sunday ... 6 = Saturday. */
       weekdays: number[];
     }[];
+    /** Legacy single-window timezone. Prefer sendSchedules. */
+    timezone?: string;
+    /** Legacy single-window start hour. Prefer sendSchedules. */
+    sendWindowStartHour?: number;
+    /** Legacy single-window end hour. Prefer sendSchedules. */
+    sendWindowEndHour?: number;
+    /** Legacy single-window weekdays, 0 = Sunday. Prefer sendSchedules. */
+    sendWeekdays?: number[];
     /** Cold emails per day, 1-100. */
     dailySendCap?: number;
   };
@@ -1976,6 +2000,11 @@ export interface ApiRequests {
     entryId?: string;
     sourceEntryId?: string;
     sourceObjectName?: string;
+    emailIdentityId?: string;
+    linkedinIdentityId?: string;
+    linkedinProviderUserId?: string;
+    /** CRM object a new record is created in when none matches. */
+    newRecordsObject?: "lead" | "people";
     personalization?: Record<string, unknown>;
     checkDuplicatesAcrossWorkspace?: boolean;
   };

package/campaign.ts

@@ -249,7 +249,7 @@ function shift(args: string[], expected: string): string {
     if (error instanceof CliArgError) throw new CampaignCliError(error.message);
     throw error;
   }
-  if (value.startsWith("--")) {
+  if (isFlagToken(value)) {
     throw new CampaignCliError(
       `Missing ${expected}: it is positional, so write it before or after the flags, e.g. dench campaign get "Founder outreach" --json`,
     );
@@ -257,7 +257,17 @@ function shift(args: string[], expected: string): string {
   return value;
 }
 
+function isFlagToken(value: string): boolean {
+  return value.startsWith("--") || /^-[A-Za-z]/.test(value);
+}
+
 function unknownFlags(args: readonly string[], command: string): void {
+  const short = args.find((token) => /^-[A-Za-z]/.test(token));
+  if (short) {
+    throw new CampaignCliError(
+      `Unknown flag for ${command}: ${short}. Run \`dench campaign help\` for the full flag list.`,
+    );
+  }
   try {
     assertNoUnknownFlags(args, command);
   } catch (error) {
@@ -1298,11 +1308,17 @@ async function runGet(ctx: CampaignCliContext): Promise<void> {
   unknownFlags(ctx.args, "campaign get");
   const row = await resolveCampaign(ctx, reference);
   const sequenceId = String(row._id);
+  let analyticsError: string | undefined;
   const [detail, analytics, live] = await Promise.all([
     loadDetail(ctx, sequenceId),
-    callAction(ctx, `${OUTREACH}:computeSequenceAnalytics`, {
-      sequenceId,
-    }) as Promise<CampaignAnalytics>,
+    (
+      callAction(ctx, `${OUTREACH}:computeSequenceAnalytics`, {
+        sequenceId,
+      }) as Promise<CampaignAnalytics>
+    ).catch((error: unknown) => {
+      analyticsError = error instanceof Error ? error.message : String(error);
+      return null;
+    }),
     callQuery(ctx, `${OUTREACH}:getSequenceLive`, {
       sequenceId,
     }) as Promise<CampaignLive>,
@@ -1324,6 +1340,11 @@ async function runGet(ctx: CampaignCliContext): Promise<void> {
   if (sequence.lastError) lines.push(`Last error: ${sequence.lastError}`);
 
   lines.push("", "Funnel");
+  if (analyticsError) {
+    lines.push(
+      `  Funnel numbers are unavailable right now (${analyticsError}). Run dench campaign get again in a minute.`,
+    );
+  }
   const a = analytics ?? {};
   const audience = a.audience ?? detail.enrollments.length;
   lines.push(`  Enrolled    ${audience}`);
@@ -1418,7 +1439,11 @@ async function runGet(ctx: CampaignCliContext): Promise<void> {
       `  … ${enrollments.length - shown.length} more: dench campaign people <campaign>`,
     );
   }
-  out(ctx, { detail, analytics, live }, lines);
+  out(
+    ctx,
+    { detail, analytics, live, ...(analyticsError ? { analyticsError } : {}) },
+    lines,
+  );
 }
 
 async function runSet(ctx: CampaignCliContext): Promise<void> {
@@ -1513,7 +1538,7 @@ async function runSteps(ctx: CampaignCliContext): Promise<void> {
   }
   if (row.status !== "draft") {
     throw new CampaignCliError(
-      "Steps can only change while a campaign is a draft. Duplicate it to edit steps.",
+      "steps set only works while a campaign is a draft. After launch, edit a step's text or wait time in the Dench app (the step types and order stay fixed).",
     );
   }
   const raw = await readFile(file, "utf8").catch(() => {
@@ -1729,7 +1754,7 @@ async function runAdd(ctx: CampaignCliContext): Promise<void> {
   unknownFlags(ctx.args, "campaign add");
 
   const usage =
-    'Usage: dench campaign add <campaign> --object <name> --view "<view>" | --object <name> --entries id1,id2 | --name "Ada" [--email ada@x.com] [--linkedin-url https://linkedin.com/in/ada]';
+    'Usage: dench campaign add <campaign> --object <name> --view "<view>" | --object <name> --entries id1,id2 | [--name "Ada"] --email ada@x.com and/or --linkedin-url https://linkedin.com/in/ada';
   const row = await resolveCampaign(ctx, reference);
   if (row.status === "archived") {
     throw new CampaignCliError(
@@ -1738,6 +1763,11 @@ async function runAdd(ctx: CampaignCliContext): Promise<void> {
   }
 
   if (objectName) {
+    if (displayName) {
+      throw new CampaignCliError(
+        `--name adds one person and can't be combined with --object. Use --name-field <column> to pick the name column. ${usage}`,
+      );
+    }
     if (viewName && entriesRaw) {
       throw new CampaignCliError(
         `Pass either --view or --entries, not both. ${usage}`,
@@ -1782,7 +1812,7 @@ async function runAdd(ctx: CampaignCliContext): Promise<void> {
       if (collected.truncated) {
         warn(
           ctx,
-          `the view "${viewName}" has more rows than one read can list; only the first ${entryIds.length} were considered.`,
+          `the view "${viewName}" could not be read in full; ${entryIds.length} of ${collected.totalCount} rows were considered. Split it into smaller views to add the rest.`,
         );
       }
     } else {
@@ -1979,14 +2009,32 @@ async function runLifecycle(
   ]);
 }
 
+const ENROLLMENT_STATUSES = [
+  "draft",
+  "active",
+  "paused",
+  "finished",
+  "replied",
+  "stopped",
+  "bounced",
+  "complained",
+  "unsubscribed",
+  "failed",
+];
+
 async function runPeople(ctx: CampaignCliContext): Promise<void> {
-  const status = valueFlag(ctx.args, "--status");
+  const status = valueFlag(ctx.args, "--status")?.trim().toLowerCase();
   const reference = shift(ctx.args, "campaign id or name");
   unknownFlags(ctx.args, "campaign people");
+  if (status !== undefined && !ENROLLMENT_STATUSES.includes(status)) {
+    throw new CampaignCliError(
+      `Unknown --status "${status}". Use one of: ${ENROLLMENT_STATUSES.join(", ")}.`,
+    );
+  }
   const row = await resolveCampaign(ctx, reference);
   const detail = await loadDetail(ctx, String(row._id));
   const enrollments = status
-    ? detail.enrollments.filter((e) => e.status === status.trim().toLowerCase())
+    ? detail.enrollments.filter((e) => e.status === status)
     : detail.enrollments;
   const people = enrollments.map((enrollment) =>
     describePerson(enrollment, detail),
@@ -2307,8 +2355,45 @@ async function runAccounts(ctx: CampaignCliContext): Promise<void> {
 
 // ─── Help ─────────────────────────────────────────────────────────────────
 
-export function campaignHelp(): void {
-  console.log(`Usage: dench campaign <subcommand> [--json]
+const SUBCOMMAND_ALIASES: Record<string, string> = {
+  ls: "list",
+  new: "create",
+  status: "get",
+  show: "get",
+  update: "set",
+  configure: "set",
+  enroll: "add",
+  start: "launch",
+  activity: "events",
+  senders: "accounts",
+};
+
+export function campaignHelp(subcommand?: string): void {
+  const text = campaignHelpText();
+  const name = subcommand
+    ? (SUBCOMMAND_ALIASES[subcommand] ?? subcommand)
+    : undefined;
+  const lines = text.split("\n");
+  const usage: string[] = [];
+  lines.forEach((line, index) => {
+    if (!name || !line.startsWith(`  dench campaign ${name} `)) return;
+    usage.push(line);
+    for (const next of lines.slice(index + 1)) {
+      if (!next.startsWith("      ")) break;
+      usage.push(next);
+    }
+  });
+  if (!usage.length) {
+    console.log(text);
+    return;
+  }
+  console.log(
+    `Usage:\n${usage.join("\n")}\n\n<campaign> is an id or an exact (case-insensitive) name. Run 'dench campaign help' for everything.`,
+  );
+}
+
+function campaignHelpText(): string {
+  return `Usage: dench campaign <subcommand> [--json]
 
 Outreach campaigns send email and LinkedIn steps to a list of people on one
 schedule. <campaign> is an id or an exact (case-insensitive) name.
@@ -2316,7 +2401,7 @@ schedule. <campaign> is an id or an exact (case-insensitive) name.
 Browse:
   dench campaign list [--all]                       # live campaigns; --all includes archived
   dench campaign get <campaign>                     # status, schedule, funnel, Now/Next, holds, people
-  dench campaign people <campaign> [--status active|paused|finished|replied|stopped|bounced|failed]
+  dench campaign people <campaign> [--status active|paused|finished|replied|stopped|bounced|failed|draft|complained|unsubscribed]
   dench campaign events <campaign> [--limit 50] [--max-pages 1]   # activity log, newest first
   dench campaign accounts                           # email + LinkedIn sender ids, availability and capacity
 
@@ -2332,9 +2417,10 @@ Create and configure:
   dench campaign steps set <campaign> --file steps.json      # replaces every step; drafts only
 
 Fill it:
-  dench campaign add <campaign> --object lead --view "Q3 targets" [--email-field Email] [--linkedin-field "POC LinkedIn URL"] [--allow-duplicates]
+  dench campaign add <campaign> --object lead --view "Q3 targets" [--email-field Email] [--linkedin-field "POC LinkedIn URL"] \\
+      [--name-field Name] [--allow-duplicates]
   dench campaign add <campaign> --object people --entries id1,id2 [--relation-field Contact] [--reverse]
-  dench campaign add <campaign> --name "Ada Lovelace" [--email ada@x.com] [--linkedin-url https://linkedin.com/in/ada]
+  dench campaign add <campaign> [--name "Ada Lovelace"] --email ada@x.com and/or --linkedin-url https://linkedin.com/in/ada
 
 Run it:
   dench campaign launch <campaign> [--ack-linkedin-risk]     # checks readiness first; prints blockers
@@ -2360,13 +2446,14 @@ leave that channel unchanged. Only your accounts and accounts shared with you
 can be selected. Launch checks availability. A person's sender stays fixed for
 their conversation. Legacy step senders are preserved until a pool is configured.
 
-A campaign holds at most ${MAX_CAMPAIGN_PEOPLE} people. Steps lock at launch; the schedule,
-daily cap and stop-on-reply stay editable. Leads move New → Contacted → Replied
+A campaign holds at most ${MAX_CAMPAIGN_PEOPLE} people. steps set only works on drafts. After
+launch, edit a step's text or wait time in the Dench app; the schedule,
+daily cap and stop-on-reply stay editable here. Leads move New → Contacted → Replied
 on their own as steps go out.
 
 Auth: a workspace member's credentials (dench signin, a member DENCH_API_KEY, or
 an agent session). An organization-only key cannot run outreach.
-`);
+`;
 }
 
 // ─── Entry point ──────────────────────────────────────────────────────────
@@ -2395,6 +2482,10 @@ export async function runCampaignCommand(opts: {
     campaignHelp();
     return;
   }
+  if (args.some((token) => token === "--help" || token === "-h")) {
+    campaignHelp(subcommand);
+    return;
+  }
   switch (subcommand) {
     case "list":
     case "ls":

package/dench.ts

@@ -373,7 +373,7 @@ function normalizeCliError(error: unknown): CliError {
       ],
     });
   }
-  if (message.includes("Sign in as a workspace member to run outreach")) {
+  if (message.includes("Sign in as a workspace member to")) {
     return new CliError(
       "Outreach needs a workspace member's credentials — sending accounts belong to a person, not the workspace",
       {
@@ -4905,6 +4905,11 @@ async function main() {
       await runToolCommand({ args: filteredSubArgs, jsonOutput: json });
       return;
     }
+    if (sub === "run") {
+      const { parseJson } = await import("./lib/cli-args");
+      const argsIndex = filteredSubArgs.indexOf("--args");
+      if (argsIndex !== -1) parseJson(filteredSubArgs[argsIndex + 1]);
+    }
     const runtime = await getRuntime();
     const isSlackConnect =
       sub === "connect" &&
@@ -5105,7 +5110,11 @@ async function main() {
   if (command === "campaign" || command === "campaigns") {
     const subArgs = stripRuntimeFlags(args.slice(args.indexOf(command) + 1));
     const sub = subArgs[0];
-    if (!sub || sub === "help" || sub === "--help" || sub === "-h") {
+    if (
+      !sub ||
+      sub === "help" ||
+      subArgs.some((token) => token === "--help" || token === "-h")
+    ) {
       const { runCampaignCommand } = await import("./campaign");
       // biome-ignore lint/suspicious/noExplicitAny: help-only stub, never queries
       await runCampaignCommand({ convex: {} as any, args: subArgs });

package/lib/api-schemas.ts

@@ -2382,6 +2382,31 @@ export const requestSchemas: Record<string, ZodTypeAny> = {
       .optional()
       .describe("Epoch ms; null clears the end."),
     sendSchedules: z.array(campaignSendSchedule).min(1).max(8).optional(),
+    timezone: z
+      .string()
+      .optional()
+      .describe("Legacy single-window timezone. Prefer sendSchedules."),
+    sendWindowStartHour: z
+      .number()
+      .int()
+      .min(0)
+      .max(23)
+      .optional()
+      .describe("Legacy single-window start hour. Prefer sendSchedules."),
+    sendWindowEndHour: z
+      .number()
+      .int()
+      .min(1)
+      .max(24)
+      .optional()
+      .describe("Legacy single-window end hour. Prefer sendSchedules."),
+    sendWeekdays: z
+      .array(z.number().int().min(0).max(6))
+      .min(1)
+      .optional()
+      .describe(
+        "Legacy single-window weekdays, 0 = Sunday. Prefer sendSchedules.",
+      ),
     dailySendCap: z
       .number()
       .int()
@@ -2430,6 +2455,13 @@ export const requestSchemas: Record<string, ZodTypeAny> = {
       .describe("Existing CRM people entry to link."),
     sourceEntryId: z.string().optional(),
     sourceObjectName: z.string().optional(),
+    emailIdentityId: z.string().optional(),
+    linkedinIdentityId: z.string().optional(),
+    linkedinProviderUserId: z.string().optional(),
+    newRecordsObject: z
+      .enum(["lead", "people"])
+      .optional()
+      .describe("CRM object a new record is created in when none matches."),
     personalization: z.record(z.string(), z.unknown()).optional(),
     checkDuplicatesAcrossWorkspace: z.boolean().optional(),
   }),
@@ -3591,6 +3623,27 @@ export const requestSchemas: Record<string, ZodTypeAny> = {
   "email.campaign.pause": z.object({ campaignId: z.string() }),
   "email.campaign.resume": z.object({ campaignId: z.string() }),
   "email.campaign.cancel": z.object({ campaignId: z.string() }),
+  "email.campaign.list": z.object({
+    limit: z.coerce.number().int().min(1).max(100).optional(),
+    cursor: z.coerce.string().optional(),
+    status: z.string().optional(),
+  }),
+  "email.campaign.recipients.list": z.object({
+    campaignId: z.string(),
+    limit: z.coerce.number().int().min(1).max(100).optional(),
+    cursor: z.coerce.string().optional(),
+    status: z.string().optional(),
+    includePeople: z
+      .boolean()
+      .optional()
+      .describe("Default true: attach each recipient's CRM record."),
+  }),
+  "email.sequence.enrollments.list": z.object({
+    sequenceId: z.string(),
+    limit: z.coerce.number().int().min(1).max(100).optional(),
+    cursor: z.coerce.string().optional(),
+    status: z.string().optional(),
+  }),
 
   // Routines
   "cron.list": z.object({ enabledOnly: z.coerce.boolean().optional() }),
@@ -5174,6 +5227,12 @@ export const requestExamples: Record<string, unknown> = {
     objectName: "lead",
     entryIds: ["<entryId1>", "<entryId2>"],
   },
+  "campaigns.people.add": {
+    sequenceId: "<sequenceId>",
+    displayName: "Ada Lovelace",
+    email: "ada@example.com",
+    linkedinProfileUrl: "https://linkedin.com/in/ada",
+  },
   "campaigns.launch": {
     sequenceId: "<sequenceId>",
     fingerprint: "<fingerprint from the launch preview>",

package/lib/command-registry.ts

@@ -3254,7 +3254,13 @@ const rawApiOperations = [
     path: "/email/campaigns",
     requestSchema: anyObject,
     responseSchema: anyResponse,
-    backend: convex("query", "functions/emailCampaigns:listCampaigns"),
+    backend: {
+      ...convex("query", "functions/emailCampaigns:listCampaigns"),
+      transformArgs: (input) => ({
+        status: input.status,
+        paginationOpts: paginationOptsFrom(input, 25),
+      }),
+    },
   }),
   op({
     id: "email.campaign.recipients.list",
@@ -3266,7 +3272,15 @@ const rawApiOperations = [
     path: "/email/campaigns/{campaignId}/recipients",
     requestSchema: anyObject,
     responseSchema: anyResponse,
-    backend: convex("query", "functions/emailCampaigns:listRecipients"),
+    backend: {
+      ...convex("query", "functions/emailCampaigns:listRecipients"),
+      transformArgs: (input) => ({
+        campaignId: input.campaignId,
+        status: input.status,
+        includePeople: input.includePeople,
+        paginationOpts: paginationOptsFrom(input, 50),
+      }),
+    },
   }),
   op({
     id: "email.campaign.recipients.addFromObject",
@@ -3446,7 +3460,14 @@ const rawApiOperations = [
     path: "/email/sequences/{sequenceId}/enrollments",
     requestSchema: anyObject,
     responseSchema: anyResponse,
-    backend: convex("query", "functions/emailSequences:listEnrollments"),
+    backend: {
+      ...convex("query", "functions/emailSequences:listEnrollments"),
+      transformArgs: (input) => ({
+        sequenceId: input.sequenceId,
+        status: input.status,
+        paginationOpts: paginationOptsFrom(input, 50),
+      }),
+    },
   }),
   op({
     id: "email.sequence.enrollment.pause",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dench.com/cli",
-  "version": "3.5.5",
+  "version": "3.5.6-staging.344",
   "description": "Dench agent workspace CLI.",
   "type": "module",
   "bin": {