@dench.com/cli 2.2.7 → 2.3.0

package/cron.ts

@@ -34,10 +34,15 @@
  *   disable <jobId>                      Soft-pause without delete.
  *   run <jobId> [--wait]                 Manual fire; --wait blocks.
  *   secret <jobId>                       Mint/rotate a signing secret (any type).
+ *   events <toolkit>                     List a connected app's event types.
  *   runs <jobId> [--limit N] [--status]  Run history per trigger.
  *   history [--limit N]                  Flat history across all crons.
  *   help                                 Print this help.
  *
+ * Trigger types accepted by `create --type`:
+ *   schedule (default) | webhook | composio (app event) | crm (CRM event).
+ *   composio/crm POST to /api/cron/jobs; the others use the Convex mutation.
+ *
  * Schedule flags accepted by `create` and `update`:
  *   --every <duration>   30s | 5m | 2h | 1d | 12h…
  *   --every-ms <number>  Same, raw milliseconds.
@@ -139,6 +144,28 @@ async function postJson(
   return json;
 }
 
+async function getJson(
+  url: string,
+  headers: Record<string, string>,
+): Promise<unknown> {
+  const response = await fetch(url, { method: "GET", headers });
+  const text = await response.text();
+  let json: unknown;
+  try {
+    json = text ? JSON.parse(text) : null;
+  } catch {
+    json = { raw: text };
+  }
+  if (!response.ok) {
+    const detail =
+      json && typeof json === "object" && "error" in json
+        ? String((json as Record<string, unknown>).error)
+        : JSON.stringify(json);
+    throw new CronCliError(`${url} failed (${response.status}): ${detail}`);
+  }
+  return json;
+}
+
 async function callQuery(
   ctx: CronCliContext,
   fn: Parameters<ConvexHttpClient["query"]>[0],
@@ -367,12 +394,32 @@ async function runCreate(ctx: CronCliContext): Promise<void> {
   }
   const triggerType = (getFlag(ctx.args, "--type") ?? "schedule") as
     | "schedule"
-    | "webhook";
-  if (triggerType !== "schedule" && triggerType !== "webhook") {
+    | "webhook"
+    | "composio"
+    | "crm";
+  if (!["schedule", "webhook", "composio", "crm"].includes(triggerType)) {
     throw new CronCliError(
-      `--type must be schedule|webhook (got "${triggerType}"). app-event / CRM automations are created from the dashboard.`,
+      `--type must be schedule|webhook|composio|crm (got "${triggerType}").`,
     );
   }
+
+  // App-event (composio) and CRM-event automations are created through the
+  // REST `/api/cron/jobs` POST: composio needs the upstream subscribe +
+  // connection-ownership flow (Node runtime, project Composio key), and CRM
+  // rides the same path for one create surface. schedule + webhook keep the
+  // direct Convex mutation below.
+  if (triggerType === "composio" || triggerType === "crm") {
+    return await runCreateAppOrCrm(ctx, {
+      triggerType,
+      name,
+      prompt,
+      description,
+      overlapPolicy,
+      disabled,
+      deleteAfterRun,
+      target,
+    });
+  }
   const isWebhook = triggerType === "webhook";
 
   let schedule: CronScheduleSpec | undefined;
@@ -447,6 +494,185 @@ async function runSecret(ctx: CronCliContext): Promise<void> {
   });
 }
 
+export type AppOrCrmCreateBase = {
+  triggerType: "composio" | "crm";
+  name: string;
+  prompt: string;
+  description?: string;
+  overlapPolicy?: "skip" | "queue" | "kill_old";
+  disabled: boolean;
+  deleteAfterRun: boolean;
+  target?: "chat_turn";
+};
+
+/**
+ * Build the `/api/cron/jobs` POST body for an app-event (composio) or
+ * CRM-event automation from the create flags. Pure (no network) so the flag
+ * parsing + validation + payload shape can be unit-tested directly. Consumes
+ * the type-specific flags off `args` (composio: --connection/--event/--toolkit/
+ * --trigger-config; crm: --object/--event/--where/--where-logic) and throws a
+ * `CronCliError` with discovery hints when a required input is missing.
+ */
+export function buildAppOrCrmCreateBody(
+  args: string[],
+  base: AppOrCrmCreateBase,
+): Record<string, unknown> {
+  // Neither type takes a schedule — reject one early instead of silently
+  // dropping it server-side.
+  if (consumeScheduleFlags(args)) {
+    throw new CronCliError(
+      `${base.triggerType} automations don't take a schedule. Omit --every/--cron/--at.`,
+    );
+  }
+
+  const body: Record<string, unknown> = {
+    name: base.name,
+    prompt: base.prompt,
+    triggerType: base.triggerType,
+    description: base.description,
+    overlapPolicy: base.overlapPolicy,
+    enabled: base.disabled ? false : undefined,
+    deleteAfterRun: base.deleteAfterRun ? true : undefined,
+    target: base.target,
+  };
+
+  if (base.triggerType === "composio") {
+    const connection = getFlag(args, "--connection");
+    const event = getFlag(args, "--event");
+    if (!connection?.trim() || !event?.trim()) {
+      throw new CronCliError(
+        "app-event automations need --connection <connectedAccountId> and --event <triggerSlug>.\n" +
+          "  Discover apps:   dench apps --json              (use connectedAccountId + toolkit)\n" +
+          "  Discover events: dench cron events <toolkit>    (use the event slug)\n" +
+          "Example:\n" +
+          '  dench cron create "New GitHub star" --prompt "Thank the new stargazer" \\\n' +
+          "    --type composio --connection ca_123 --event GITHUB_STAR_ADDED_EVENT --toolkit github",
+      );
+    }
+    const toolkit = getFlag(args, "--toolkit");
+    const triggerConfigRaw = getFlag(args, "--trigger-config");
+    let triggerConfig: unknown;
+    if (triggerConfigRaw) {
+      try {
+        triggerConfig = JSON.parse(triggerConfigRaw);
+      } catch {
+        throw new CronCliError(
+          `--trigger-config must be valid JSON (got ${triggerConfigRaw})`,
+        );
+      }
+    }
+    body.composioConnectionId = connection.trim();
+    body.composioTriggerSlug = event.trim();
+    if (toolkit?.trim()) body.composioToolkitSlug = toolkit.trim();
+    if (triggerConfig !== undefined) body.triggerConfig = triggerConfig;
+  } else {
+    const object = getFlag(args, "--object");
+    const event = getFlag(args, "--event");
+    if (!object?.trim() || !event?.trim()) {
+      throw new CronCliError(
+        "CRM-event automations need --object <objectId> and --event create|update|delete.\n" +
+          "  Discover objects: dench crm objects list\n" +
+          "  Discover fields:  dench crm fields list <object>   (filter on field _id via --where)\n" +
+          "Example:\n" +
+          '  dench cron create "New company" --prompt "Research the new company" \\\n' +
+          "    --type crm --object <objectId> --event create",
+      );
+    }
+    if (!["create", "update", "delete"].includes(event)) {
+      throw new CronCliError(
+        `--event must be create|update|delete for CRM automations (got "${event}")`,
+      );
+    }
+    const whereRaw = getFlag(args, "--where");
+    const whereLogic = (getFlag(args, "--where-logic") ?? "AND") as
+      | "AND"
+      | "OR";
+    if (!["AND", "OR"].includes(whereLogic)) {
+      throw new CronCliError(
+        `--where-logic must be AND|OR (got "${whereLogic}")`,
+      );
+    }
+    const crmTriggerConfig: Record<string, unknown> = {
+      eventType: event,
+      objectId: object.trim(),
+    };
+    if (whereRaw) {
+      let whereGroups: unknown;
+      try {
+        whereGroups = JSON.parse(whereRaw);
+      } catch {
+        throw new CronCliError(
+          "--where must be valid JSON: an array of groups like " +
+            '\'[{"logic":"AND","conditions":[{"fieldId":"<id>","operator":"equals","value":"x"}]}]\'',
+        );
+      }
+      if (!Array.isArray(whereGroups)) {
+        throw new CronCliError(
+          "--where must be a JSON array of where-groups (each { logic, conditions }).",
+        );
+      }
+      crmTriggerConfig.whereGroups = whereGroups;
+      crmTriggerConfig.whereLogic = whereLogic;
+    }
+    body.crmTriggerConfig = crmTriggerConfig;
+  }
+
+  return body;
+}
+
+/**
+ * Create an app-event (composio) or CRM-event automation via the REST
+ * `/api/cron/jobs` POST. composio creation also subscribes the trigger
+ * instance upstream + verifies the org owns the connection (handled
+ * server-side in the Node route); CRM creation validates the object +
+ * filter field ids in the mutation.
+ */
+async function runCreateAppOrCrm(
+  ctx: CronCliContext,
+  base: AppOrCrmCreateBase,
+): Promise<void> {
+  const body = buildAppOrCrmCreateBody(ctx.args, base);
+  const url = `${getApiBase()}/api/cron/jobs`;
+  const created = await postJson(
+    url,
+    apiKeyHeaders(ctx.sessionToken ?? ""),
+    body,
+  );
+  out(ctx, created);
+}
+
+/**
+ * List the app-event types a connected app publishes, so the caller can pick
+ * a `--event <triggerSlug>` for `dench cron create --type composio`. Backed by
+ * `GET /api/cron/trigger-types` (project-level Composio catalogue).
+ */
+async function runEvents(ctx: CronCliContext): Promise<void> {
+  const toolkit = shift(
+    ctx.args,
+    "toolkit slug (e.g. github — run `dench apps --json` to see each app's slug)",
+  );
+  const url = `${getApiBase()}/api/cron/trigger-types?toolkit=${encodeURIComponent(toolkit)}`;
+  const result = (await getJson(
+    url,
+    apiKeyHeaders(ctx.sessionToken ?? ""),
+  )) as {
+    items?: Array<{ slug?: string; name?: string; description?: string }>;
+  };
+  if (ctx.jsonOutput) {
+    out(ctx, result);
+    return;
+  }
+  const items = result.items ?? [];
+  if (items.length === 0) {
+    console.log(`(no app events found for "${toolkit}")`);
+    return;
+  }
+  for (const item of items) {
+    console.log(`${item.slug ?? "?"}  —  ${item.name ?? ""}`);
+    if (item.description) console.log(`    ${item.description}`);
+  }
+}
+
 async function runUpdate(ctx: CronCliContext): Promise<void> {
   const jobId = shift(ctx.args, "job id");
   const name = getFlag(ctx.args, "--name");
@@ -578,11 +804,12 @@ Browse:
   dench cron get <jobId> [--json]
   dench cron history [--limit 50] [--status ok|error|skipped] [--json]
   dench cron runs <jobId> [--limit 50] [--status ok|error|skipped] [--json]
+  dench cron events <toolkit> [--json]            # app-event types for a connected app
 
 Create / update:
   dench cron create "Daily standup digest" \\
       --prompt "Pull yesterday's commits + Slack #standup msgs and post a summary…" \\
-      --type schedule                     # default; or --type webhook (no schedule)
+      --type schedule                     # default. also: webhook | composio | crm (see below)
       --every 1d                          # or --cron "0 9 * * 1-5"  or --at 2026-05-04T09:00:00Z
       [--description "..."]               # human-readable note shown in dashboard / list
       [--overlap skip|queue|kill_old]     # default: skip
@@ -595,6 +822,21 @@ Create / update:
   # signing secret unless --no-secret. The secret is shown ONCE.
   dench cron create "Inbound lead triage" --prompt "Triage the lead…" --type webhook
 
+  # App-event automation (fires when something happens in a connected app).
+  #   1. dench apps --json                    → connectedAccountId + toolkit
+  #   2. dench cron events <toolkit>          → event slug
+  dench cron create "New GitHub star" --prompt "Thank the new stargazer" \\
+      --type composio --connection <connectedAccountId> --event <triggerSlug> \\
+      [--toolkit <slug>] [--trigger-config '<json>']
+
+  # CRM-event automation (fires on a CRM object create/update/delete).
+  #   1. dench crm objects list               → objectId
+  #   2. dench crm fields list <object>       → field _id (for --where filters)
+  dench cron create "New company added" --prompt "Research the new company" \\
+      --type crm --object <objectId> --event create|update|delete \\
+      [--where '[{"logic":"AND","conditions":[{"fieldId":"<id>","operator":"equals","value":"x"}]}]'] \\
+      [--where-logic AND|OR]
+
   dench cron update <jobId> [--name N] [--prompt P] [--description D] \\
       [--every X | --cron EXPR | --at ISO] [--enabled true|false] [--overlap …]
 
@@ -676,6 +918,8 @@ export async function runCronCommand(opts: {
       return await runRunNow(ctx);
     case "secret":
       return await runSecret(ctx);
+    case "events":
+      return await runEvents(ctx);
     case "runs":
       return await runRuns(ctx);
     case "history":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dench.com/cli",
-  "version": "2.2.7",
+  "version": "2.3.0",
   "description": "Dench agent workspace CLI. v2 unifies auth behind `dench signin`; the legacy `dench login` / `dench onboard` / `dench setup` / `dench what-can-i-do` / `dench register` commands now error with a redirect.",
   "type": "module",
   "bin": {