@erdoai/cli 0.60.0 → 0.61.0

package/dist/index.js

@@ -310,6 +310,53 @@ var ErdoClient = class {
       { target_org: targetOrg }
     );
   }
+  // --- Email sending domains: the address outbound agent mail is sent FROM ---
+  // Registering one is DNS only: the response carries the records the customer
+  // creates at their own provider, and nothing leaves the domain until they exist
+  // and Erdo has verified them — sends keep falling back to Erdo's own address in
+  // the meantime, so status is the thing to read, not the fact of registration.
+  // An org has one sending domain; to move, remove the current one first.
+  listSendingDomains() {
+    return this.request("GET", "/v1/sending-domains");
+  }
+  getSendingDomain(domain) {
+    return this.request(
+      "GET",
+      `/v1/sending-domains/${encodeURIComponent(domain)}`
+    );
+  }
+  createSendingDomain(input) {
+    return this.request("POST", "/v1/sending-domains", input);
+  }
+  // Absent fields are left unchanged; a field passed empty is set empty. The
+  // domain rides in the path, so the body carries only what is changing.
+  updateSendingDomain(domain, input) {
+    return this.request(
+      "PATCH",
+      `/v1/sending-domains/${encodeURIComponent(domain)}`,
+      input
+    );
+  }
+  deleteSendingDomain(domain) {
+    return this.request(
+      "DELETE",
+      `/v1/sending-domains/${encodeURIComponent(domain)}`
+    );
+  }
+  // The mail that arrived AT the org's sending domain, newest first — the other
+  // half of the outreach the send path produces. `domain` can be left off: an org
+  // has one sending domain and the read resolves it. Needs only org membership,
+  // unlike the registration endpoints above.
+  listReceivedEmails(params) {
+    const q = new URLSearchParams();
+    if (params?.domain) q.set("domain", params.domain);
+    if (params?.limit) q.set("limit", String(params.limit));
+    const qs = q.toString();
+    return this.request(
+      "GET",
+      `/v1/received-emails${qs ? `?${qs}` : ""}`
+    );
+  }
   // Run a read-only HogQL query against the org's page-analytics events. Rows are
   // positional per columns; enabled:false means page analytics is off for the org
   // (not zero traffic). A rejected query surfaces PostHog's message as the error.
@@ -726,7 +773,12 @@ var ErdoClient = class {
     const qs = q.toString();
     return this.request("GET", `/v1/datasets${qs ? `?${qs}` : ""}`);
   }
-  // The endpoint's field is `question` (QueryDataNaturalLanguageInput). Sending
+  // The org's dataset vocabulary: every purpose in use, its description, and
+  // the dataset that established it (the canonical write target for that role).
+  listDatasetPurposes() {
+    return this.request("GET", `/v1/datasets-purposes`);
+  }
+  // The endpoint's field is `question` (QueryDataNaturalLanguageInput). Sending  // The endpoint's field is `question` (QueryDataNaturalLanguageInput). Sending
   // `query` made every `erdo datasets query` fail with "question is required".
   //
   // `rows` carries the values in `columns` order — the answer to the question —
@@ -3668,6 +3720,174 @@ domainsCmd.command("transfer <domain> <targetOrg>").description("Move a domain t
     fail(e);
   }
 });
+var emailCmd = program.command("email").description("The domain Erdo sends your outbound agent email from, and the mail that comes back");
+var sendingDomainsCmd = emailCmd.command("domains").description("Sending domains \u2014 the verified domain outreach is sent from (one per org)");
+function printSendingDomain(d) {
+  console.log(`${d.domain}	${d.status}${d.error_reason ? `	${d.error_reason}` : ""}`);
+  console.log(`from: ${d.from_email}${d.from_name ? ` (${d.from_name})` : ""}`);
+  console.log(
+    `receiving: ${d.receiving_enabled ? "on" : "off"}${d.forward_to_email ? `, forwards to ${d.forward_to_email}` : ""}`
+  );
+  if (d.status !== "active") {
+    console.error(
+      "Not active yet \u2014 sends still go out from Erdo's own address until every record below is live and verified (re-checked about every ten minutes)."
+    );
+  }
+  if (d.existing_mx_detected) {
+    console.error(
+      "This domain already routes mail to a mailbox provider, so it was registered sending-only and no MX record was issued \u2014 your existing email is untouched. To receive replies through Erdo, remove it and register a subdomain instead."
+    );
+  } else if (!d.registered_receiving) {
+    console.error(
+      "Registered sending-only: receiving cannot be turned on here. Remove the domain and register it (or a subdomain) again to receive replies."
+    );
+  }
+  const records = d.dns_records ?? [];
+  if (records.length > 0) {
+    console.error("Create these records at the domain's DNS provider:");
+    for (const r of records) {
+      console.log(`${r.type}	${r.name}	${r.value}`);
+    }
+  }
+}
+sendingDomainsCmd.command("list").description("List the org's sending domains with their verification status").option("--json", "print the raw JSON result instead of a table").action(async (opts) => {
+  try {
+    const res = await new ErdoClient().listSendingDomains();
+    if (opts.json) {
+      print(res);
+      return;
+    }
+    const domains = res.sending_domains ?? [];
+    if (domains.length === 0) {
+      console.log(
+        "No sending domain \u2014 this org's agent email is sent from Erdo's own address, which is a working default rather than a misconfiguration. Register one with: erdo email domains add <domain>"
+      );
+      return;
+    }
+    printAlignedTable(
+      ["domain", "status", "from", "receiving", "forwards to", "checked"],
+      domains.map((d) => [
+        d.domain,
+        d.status,
+        d.from_name ? `${d.from_email} (${d.from_name})` : d.from_email,
+        d.receiving_enabled ? "on" : "off",
+        d.forward_to_email ?? "",
+        d.last_checked_at ?? "never"
+      ])
+    );
+  } catch (e) {
+    fail(e);
+  }
+});
+sendingDomainsCmd.command("get <domain>").description(
+  "Read one sending domain \u2014 its status, the address it sends as, and the DNS records that must exist. The command to run while waiting for DNS to propagate: error_reason names the record that did not check out."
+).option("--json", "print the raw JSON result instead of the status and records").action(async (domain, opts) => {
+  try {
+    const d = await new ErdoClient().getSendingDomain(domain);
+    if (opts.json) {
+      print(d);
+      return;
+    }
+    printSendingDomain(d);
+  } catch (e) {
+    fail(e);
+  }
+});
+sendingDomainsCmd.command("add <domain>").description(
+  "Register the domain outbound agent email should be sent from (an apex, acme.com, or a subdomain, hello.acme.com) and print the DNS records to create. Nothing sends from it until those records exist and verify."
+).option("--from-name <name>", "display name on the From header, e.g. 'Acme Sales'").option("--from-local-part <part>", "the part before the @ (default: hello)").option(
+  "--receiving <bool>",
+  "accept replies back into Erdo (true/false; defaults on). Needs an MX record, which a name already routing mail elsewhere cannot have"
+).option(
+  "--forward-to <email>",
+  "a real mailbox each received reply is copied to, e.g. sales@acme.com \u2014 required when the domain is sending-only"
+).action(
+  async (domain, opts) => {
+    try {
+      const d = await new ErdoClient().createSendingDomain({
+        domain,
+        from_name: opts.fromName,
+        from_local_part: opts.fromLocalPart,
+        receiving_enabled: opts.receiving === void 0 ? void 0 : parseStrictBoolean(opts.receiving),
+        forward_to_email: opts.forwardTo
+      });
+      printSendingDomain(d);
+    } catch (e) {
+      fail(e);
+    }
+  }
+);
+sendingDomainsCmd.command("update <domain>").description(
+  "Edit a sending domain's identity \u2014 only the flags you pass change, and they take effect on the next send"
+).option("--from-name <name>", "new display name on the From header").option("--from-local-part <part>", "new part before the @, e.g. 'sales'").option(
+  "--forward-to <email>",
+  'new mailbox received replies are copied to (pass "" to clear, which a sending-only domain refuses)'
+).option(
+  "--receiving <bool>",
+  "accept replies back into Erdo (true/false). Can only be turned on for a domain REGISTERED with receiving"
+).action(
+  async (domain, opts) => {
+    try {
+      const body = {
+        from_name: opts.fromName,
+        from_local_part: opts.fromLocalPart,
+        forward_to_email: opts.forwardTo,
+        receiving_enabled: opts.receiving === void 0 ? void 0 : parseStrictBoolean(opts.receiving)
+      };
+      if (Object.values(body).every((v) => v === void 0)) {
+        fail(new Error("nothing to update \u2014 pass at least one field to change"));
+        return;
+      }
+      printSendingDomain(await new ErdoClient().updateSendingDomain(domain, body));
+    } catch (e) {
+      fail(e);
+    }
+  }
+);
+sendingDomainsCmd.command("remove <domain>").description(
+  "Remove a sending-domain registration \u2014 outbound agent email reverts to Erdo's own address on the next send and replies to the old address stop reaching Erdo. The DNS records are in your own DNS and are left alone."
+).action(async (domain) => {
+  try {
+    const res = await new ErdoClient().deleteSendingDomain(domain);
+    console.log(`removed: ${res.domain}`);
+  } catch (e) {
+    fail(e);
+  }
+});
+emailCmd.command("received").description(
+  "Read the mail that arrived at the org's sending domain, newest first \u2014 usually leads replying to outreach an agent sent. Omit --domain: an org has one sending domain and the read resolves it."
+).option("--domain <domain>", "the sending domain to read (only needed if the org has more than one)").option("--limit <n>", "maximum messages to return, newest first").option("--json", "print the raw JSON result instead of the message list").action(async (opts) => {
+  try {
+    const res = await new ErdoClient().listReceivedEmails({
+      domain: opts.domain,
+      limit: opts.limit ? Number(opts.limit) : void 0
+    });
+    if (opts.json) {
+      print(res);
+      return;
+    }
+    const emails = res.emails ?? [];
+    if (emails.length === 0) {
+      console.log(
+        `No mail has arrived at ${res.domain}. Replies only come back for a domain registered with receiving on and verified active \u2014 a sending-only domain sends them straight to its nominated mailbox, which is the configuration working rather than a fault.`
+      );
+      return;
+    }
+    process.stderr.write(`${res.domain} \u2014 ${emails.length} message(s), newest first
+`);
+    for (const m of emails) {
+      const who = m.from_name ? `${m.from_name} <${m.from_email}>` : m.from_email;
+      console.log(`${m.received_at}	${who}	${m.subject || "(no subject)"}`);
+      const preview = (m.text_preview || "").replace(/\s+/g, " ").trim();
+      if (preview) console.log(`    ${preview.length > 160 ? `${preview.slice(0, 160)}\u2026` : preview}`);
+      console.log(
+        m.forwarded_at ? `    forwarded ${m.forwarded_at}` : "    not forwarded \u2014 this one is in Erdo only, so nobody on your side has necessarily seen it"
+      );
+    }
+  } catch (e) {
+    fail(e);
+  }
+});
 var datasetsCmd = program.command("datasets").description("Datasets");
 datasetsCmd.command("list").description("List datasets").option(
   "--class <class>",
@@ -3695,6 +3915,23 @@ datasetsCmd.command("list").description("List datasets").option(
     fail(e);
   }
 });
+datasetsCmd.command("purposes").description(
+  "List the org's dataset purposes \u2014 the vocabulary of dataset roles in use (e.g. leads, page events). The established_by slug is the canonical dataset for that role: write there rather than creating a sibling (one purpose = one dataset per org)."
+).action(async () => {
+  try {
+    const { purposes } = await new ErdoClient().listDatasetPurposes();
+    if (purposes.length === 0) {
+      console.error("(no dataset purposes established yet)");
+      return;
+    }
+    for (const p of purposes)
+      console.log(
+        `${p.purpose}	${p.established_by_dataset_slug ?? p.established_by_dataset_id}	${p.dataset_count} dataset${p.dataset_count === 1 ? "" : "s"}	${p.description}`
+      );
+  } catch (e) {
+    fail(e);
+  }
+});
 datasetsCmd.command("query <slug> <question>").description(
   "Ask a natural-language question of a dataset \u2014 Erdo writes and runs the SQL, and answers with that SQL alongside the values. It runs an agent, so it is slower and two identical questions can produce two different queries: for a deterministic or scripted read, write the SQL yourself with `datasets fetch --sql`."
 ).action(async (slug, question) => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erdoai/cli",
-  "version": "0.60.0",
-  "description": "Erdo CLI — drive datasets, pages, and evals from the terminal or CI",
+  "version": "0.61.0",
+  "description": "Erdo CLI \u2014 drive datasets, pages, and evals from the terminal or CI",
   "type": "module",
   "bin": {
     "erdo": "dist/index.js"
@@ -52,4 +52,4 @@
   "overrides": {
     "esbuild": "^0.28.1"
   }
-}
+}