posthorn 0.2.3 → 0.2.5

package/README.md

@@ -1,22 +1,22 @@
 # Posthorn
 
-**Posthorn spins up cold-email infrastructure — sending domains, mailboxes,
-SPF/DKIM/DMARC, and inbox warmup — on accounts you own, drivable entirely by an
-AI agent.**
+**Posthorn spins up cold-email infrastructure: sending domains, mailboxes,
+SPF/DKIM/DMARC, and inbox warmup. It runs on accounts you own and is drivable
+entirely by an AI agent.**
 
 It's a pure orchestration layer: you own your Cloudflare account, your Google
 Workspace, your domains, and your mailboxes. Posthorn automates the setup and
-warmup on top of accounts you control — it never owns or bills for any of it.
+warmup on top of accounts you control. It never owns or bills for any of it.
 
 ## Quick start with an AI agent (recommended)
 
 Posthorn is built to be driven by an agent (Claude Code, Codex, Cursor, etc.).
 Paste this into your agent:
 
-> I want to set up cold-email infrastructure — sending domains, mailboxes, and
+> I want to set up cold-email infrastructure: sending domains, mailboxes, and
 > inbox warmup. Use the Posthorn CLI to do it. First run `npm install -g posthorn`
 > then `posthorn guide`, read the guide, and walk me through the whole setup
-> step by step — run the commands for me and tell me whenever I need to do
+> step by step. Run the commands for me and tell me whenever I need to do
 > something in my browser.
 
 The agent reads `posthorn guide` (which prints this document) and orchestrates
@@ -50,7 +50,7 @@ never owns or bills for any of it.
 4. Domain         → buy new OR connect existing OR managed DNS
 5. DKIM           → browser step (see below)
 6. Mailboxes      → `posthorn mailboxes create ...`
-7. Verify account → `posthorn auth verify` (unlocks sending/warmup — "verified" tier)
+7. Verify account → `posthorn auth verify` (unlocks sending/warmup, "verified" tier)
 8. Warmup         → `posthorn warmup start <mailbox-id>`
 
 Dependencies: you CANNOT create a mailbox until the domain status is `ready`.
@@ -70,7 +70,7 @@ click-by-click instructions.
   Zone>Zone>Edit, Zone>DNS>Edit. Resources: Include All.
 - Then: `posthorn accounts cloudflare <token>`
 - For domain PURCHASES, the user also needs a payment method on their Cloudflare
-  account (they pay Cloudflare directly — Posthorn never bills for domains).
+  account (they pay Cloudflare directly; Posthorn never bills for domains).
 
 ### Google Workspace domain-wide delegation (one-time per Workspace org)
 - admin.google.com → Security → Access and data control → API controls →
@@ -79,7 +79,7 @@ click-by-click instructions.
 - OAuth scopes (paste all, comma-separated):
   `https://mail.google.com/,https://www.googleapis.com/auth/admin.directory.user,https://www.googleapis.com/auth/admin.directory.domain,https://www.googleapis.com/auth/siteverification`
 - Then ask for their admin email and run: `posthorn accounts workspace <admin-email>`
-- This replaces OAuth entirely — no consent screen, no app verification, no test users.
+- This replaces OAuth entirely: no consent screen, no app verification, no test users.
 
 ### Nameservers (only for "managed DNS" or moving a domain to Cloudflare)
 - The CLI prints 2 nameservers. The user sets them at their domain REGISTRAR
@@ -87,10 +87,10 @@ click-by-click instructions.
 - Propagation takes minutes to 24h. Check with `posthorn domains activate <id>`
   (managed) or by polling `posthorn domains get <id>`.
 
-### DKIM (per domain — Google has no DKIM API)
+### DKIM (per domain, Google has no DKIM API)
 If you have browser-automation tools, do it for the user:
 - Navigate to https://admin.google.com/ac/apps/gmail/authenticateemail
-  (the URL may need /u/N/ for the right account slot — verify the "Selected
+  (the URL may need /u/N/ for the right account slot, verify the "Selected
   domain" on the page matches).
 - If status is "Authenticating email with DKIM" → already done, skip.
 - Otherwise click GENERATE NEW RECORD → GENERATE (defaults: 2048-bit, "google"
@@ -106,11 +106,11 @@ PRINCIPLE: domain purchase ALWAYS happens on the user's own Cloudflare account
 and card. Posthorn never owns or bills for domains.
 
 1. NEW domain → requires the user's own Cloudflare account (+ payment method).
-   - `posthorn domains check name1.com name2.io --cloudflare <id>` — fast availability + price
-   - `posthorn domains reputation <domain>` — VET it before buying (Spamhaus
+   - `posthorn domains check name1.com name2.io --cloudflare <id>`, fast availability + price
+   - `posthorn domains reputation <domain>`, VET it before buying (Spamhaus
      blocklist/score + archive.org prior-use). Verdicts: clean / caution (used
      before) / avoid (blocklisted or poor reputation). Run this on the candidate
-     before `buy` — you can't tell a tainted domain from its name. (Slower + uses
+     before `buy`; you can't tell a tainted domain from its name. (Slower + uses
      a quota, so it's a separate explicit call, not part of `check`.)
    - `posthorn domains buy <domain> --cloudflare <id> --contact '{...}'`
 
@@ -124,7 +124,7 @@ and card. Posthorn never owns or bills for domains.
    - user sets them at their registrar
    - `posthorn domains activate <domain-id>` → checks propagation, starts DNS setup
    - Best for DEDICATED email-only domains. Don't use on a domain running a live
-     website — Posthorn becomes authoritative for ALL its DNS.
+     website; Posthorn becomes authoritative for ALL its DNS.
 
 After any path, poll `posthorn domains get <id>` until status is `ready`. DNS
 records (MX, SPF, DMARC) are configured automatically. Statuses progress:
@@ -134,7 +134,7 @@ workspace_verifying → workspace_verified → ready.
 ## Mailboxes & sending
 
 - Create: `posthorn mailboxes create <domain-id> --email john@dom.com --first John --last Smith`
-  Returns a one-time password (Google Workspace login). Save it — not shown again.
+  Returns a one-time password (Google Workspace login). Save it (not shown again).
 - Credentials for IMAP/SMTP are auto-provisioned via the service account
   (domain-wide delegation). Google mailboxes need no per-mailbox setup.
 - Send: `posthorn send <mailbox-id> --to x@y.com --subject "Hi" --body "..."`
@@ -148,18 +148,31 @@ Anonymous tier can do setup (accounts, domains). To send/warmup, verify:
 ## Warmup
 
 - `posthorn warmup start <mailbox-id>` → joins the shared warmup pool, ramps over ~30 days
+  - Volume and reply behavior are platform-managed (ramps from 2/day to 5/day;
+    peers reply to ~30% of warmup mail). Not configurable: the pool is shared,
+    so settings are tuned for everyone's deliverability.
 - `posthorn warmup stats <campaign-id>` → placement rate, reputation, daily breakdown
 - `posthorn warmup list` → all campaigns
-- Warmup never fully stops on its own — pause with `posthorn warmup pause <id>`.
+- Warmup never fully stops on its own, pause with `posthorn warmup pause <id>`.
+
+## Feedback (bugs, feature requests)
+
+`posthorn feedback --type bug|feature|question|other "<message>"`
+
+If you hit a bug, missing capability, or rough edge while driving this CLI,
+report it, it goes straight to the Posthorn team. Agents: you are encouraged
+to file feedback yourself when something doesn't work the way you expected
+(include the command you ran and what you expected). Works on any tier, no
+verification needed.
 
 ## Tips for agents
 
 - Read commands auto-detect output: when stdout isn't a TTY (i.e. you're an agent
-  capturing output), they emit JSON automatically — no flag needed. Humans in a
+  capturing output), they emit JSON automatically, no flag needed. Humans in a
   terminal get formatted text. Force either way with `--json` / `--pretty`.
 - Async steps (domain provisioning, nameserver propagation) need polling, not blocking.
 - Every command stores state locally (~/.config), so the user doesn't re-enter keys.
 - Translate everything into plain English for the user. Never show them raw JSON
-  or ask them to run curl — you run the CLI on their behalf.
+  or ask them to run curl, you run the CLI on their behalf.
 - When a step needs the user's browser (Cloudflare token, delegation, nameservers,
   DKIM), give exact click-by-click instructions and wait for confirmation.

package/dist/index.js

@@ -2,7 +2,7 @@
 
 // src/index.ts
 import { Command } from "commander";
-import chalk6 from "chalk";
+import chalk7 from "chalk";
 
 // src/commands/auth.ts
 import chalk from "chalk";
@@ -78,7 +78,7 @@ async function register(options) {
     console.log(`  API Key: ${chalk.cyan(data.api_key)}`);
     console.log(`  Tier:    ${chalk.yellow(data.user.tier)}`);
     console.log();
-    console.log(chalk.dim("  Save this API key \u2014 it won't be shown again."));
+    console.log(chalk.dim("  Save this API key, it won't be shown again."));
     console.log(chalk.dim(`  Config stored at: ${getConfigPath()}`));
   } catch (err) {
     spinner.fail(`Could not reach ${apiUrl}`);
@@ -158,6 +158,21 @@ async function api(path, options = {}) {
 }
 
 // src/commands/accounts.ts
+var SERVICE_ACCOUNT_CLIENT_ID = "110137377718772968374";
+var DELEGATION_SCOPES = "https://mail.google.com/,https://www.googleapis.com/auth/admin.directory.user,https://www.googleapis.com/auth/admin.directory.domain,https://www.googleapis.com/auth/siteverification";
+function printDelegationHelp(adminEmail) {
+  const domain = adminEmail.includes("@") ? adminEmail.split("@")[1] : "your-domain.com";
+  console.log();
+  console.log(chalk2.bold("  Set up domain-wide delegation first (one-time per Workspace org):"));
+  console.log(`  1. Go to ${chalk2.cyan("admin.google.com")} signed in as a ${chalk2.bold("super-admin")} of ${chalk2.bold(domain)}`);
+  console.log("  2. Security \u2192 Access and data control \u2192 API controls \u2192 Domain-wide delegation \u2192 Add new");
+  console.log(`  3. Client ID:  ${chalk2.bold(SERVICE_ACCOUNT_CLIENT_ID)}`);
+  console.log("  4. OAuth scopes (paste all, comma-separated):");
+  console.log(`     ${chalk2.green(DELEGATION_SCOPES)}`);
+  console.log("  5. Authorize, then re-run this command.");
+  console.log(chalk2.dim(`     The admin email you pass must be a super-admin of ${domain}'s own org.`));
+  console.log();
+}
 async function connectCloudflare(token, options) {
   const spinner = ora2("Connecting Cloudflare...").start();
   const data = await api("/api/accounts", {
@@ -183,10 +198,21 @@ async function connectCloudflare(token, options) {
 }
 async function connectWorkspace(adminEmail) {
   const spinner = ora2("Connecting Google Workspace...").start();
-  const data = await api("/api/accounts/workspace", {
-    method: "POST",
-    body: { adminEmail }
-  });
+  let data;
+  try {
+    data = await api("/api/accounts/workspace", {
+      method: "POST",
+      body: { adminEmail }
+    });
+  } catch (err) {
+    spinner.fail("Could not connect Google Workspace.");
+    if (err instanceof ApiError) {
+      console.log(chalk2.red(`  ${err.message}`));
+    }
+    printDelegationHelp(adminEmail);
+    process.exitCode = 1;
+    return;
+  }
   setConfig({
     workspaceConnected: true,
     workspaceAccountId: data.account.id
@@ -312,7 +338,7 @@ async function getDomain(domainId, options = {}) {
 function verdictText(rep) {
   switch (rep.verdict) {
     case "avoid":
-      return chalk3.red(`\u26A0 ${rep.verdictLabel} \u2014 avoid`);
+      return chalk3.red(`\u26A0 ${rep.verdictLabel}, avoid`);
     case "caution":
       return chalk3.yellow(rep.verdictLabel);
     case "clean":
@@ -393,7 +419,7 @@ async function createMailbox(domainId, options) {
   console.log(`  ${chalk4.bold("Email:")}    ${data.credentials.email}`);
   console.log(`  ${chalk4.bold("Password:")} ${chalk4.yellow(data.credentials.password)}`);
   console.log();
-  console.log(chalk4.red("  Save this password now \u2014 it will not be shown again."));
+  console.log(chalk4.red("  Save this password now, it will not be shown again."));
   console.log(chalk4.dim("  Login at: https://mail.google.com"));
 }
 async function sendEmail(mailboxId, options) {
@@ -421,7 +447,7 @@ async function provisionCredentials(mailboxId, options) {
     body: { authType: options.type ?? "xoauth2" }
   });
   if (data.connectivity.send && data.connectivity.imap) {
-    spinner.succeed(`Credentials provisioned \u2014 sending (${data.connectivity.sendMethod}) and IMAP connected!`);
+    spinner.succeed(`Credentials provisioned, sending (${data.connectivity.sendMethod}) and IMAP connected!`);
   } else {
     spinner.warn("Credentials provisioned but connectivity issues:");
     for (const err of data.connectivity.errors) {
@@ -435,14 +461,19 @@ import chalk5 from "chalk";
 import ora5 from "ora";
 async function startWarmup(mailboxId) {
   const spinner = ora5("Starting warmup...").start();
-  const data = await api("/api/warmup/campaigns", {
-    method: "POST",
-    body: { mailboxId, autoStart: true }
-  });
+  const data = await api(
+    "/api/warmup/campaigns",
+    {
+      method: "POST",
+      body: { mailboxId, autoStart: true }
+    }
+  );
+  const effective = data.campaign.config ?? {};
   spinner.succeed("Warmup started!");
   console.log(`  Campaign ID: ${chalk5.dim(data.campaign.id)}`);
   console.log(`  Status:      ${chalk5.green("active")}`);
-  console.log(chalk5.dim("  Emails will ramp up gradually over 30 days."));
+  console.log(`  Daily cap:   ${effective.daily_limit ?? 5}/day (ramps up from 2)`);
+  console.log(`  Reply rate:  ${Math.round((effective.reply_rate ?? 0.3) * 100)}%`);
 }
 async function pauseWarmup(campaignId) {
   await api(`/api/warmup/campaigns/${campaignId}`, {
@@ -493,25 +524,64 @@ async function listCampaigns() {
   }
 }
 
-// src/commands/guide.ts
+// src/commands/feedback.ts
 import { readFileSync } from "fs";
 import { fileURLToPath } from "url";
 import { dirname, join } from "path";
-function guide() {
+import chalk6 from "chalk";
+function cliVersion() {
   try {
     const here = dirname(fileURLToPath(import.meta.url));
-    const readme = readFileSync(join(here, "..", "README.md"), "utf8");
+    return JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8")).version;
+  } catch {
+    return "unknown";
+  }
+}
+async function sendFeedback(messageWords, options) {
+  const message = messageWords.join(" ").trim();
+  if (!message) {
+    console.error(chalk6.red("Feedback message is required."));
+    console.error(chalk6.dim('  Example: posthorn feedback --type feature "bulk domain checks would save me round trips"'));
+    process.exitCode = 1;
+    return;
+  }
+  const data = await api("/api/feedback", {
+    method: "POST",
+    body: {
+      message,
+      type: options.type ?? "other",
+      metadata: {
+        cliVersion: cliVersion(),
+        platform: process.platform,
+        agent: !process.stdout.isTTY
+        // non-TTY usually means an agent is driving
+      }
+    }
+  });
+  console.log(chalk6.green("Feedback recorded, thank you!"));
+  console.log(`  id:   ${chalk6.dim(data.feedback.id)}`);
+  console.log(`  type: ${chalk6.dim(data.feedback.type)}`);
+}
+
+// src/commands/guide.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { dirname as dirname2, join as join2 } from "path";
+function guide() {
+  try {
+    const here = dirname2(fileURLToPath2(import.meta.url));
+    const readme = readFileSync2(join2(here, "..", "README.md"), "utf8");
     console.log(readme);
   } catch {
     console.log(
-      "Posthorn \u2014 see the full guide at https://www.npmjs.com/package/posthorn\nQuick start: posthorn auth register, then posthorn accounts cloudflare <token>, posthorn accounts workspace <admin-email>, posthorn domains connect <domain> --cloudflare <id>."
+      "Posthorn, see the full guide at https://www.npmjs.com/package/posthorn\nQuick start: posthorn auth register, then posthorn accounts cloudflare <token>, posthorn accounts workspace <admin-email>, posthorn domains connect <domain> --cloudflare <id>."
     );
   }
 }
 
 // src/index.ts
 var program = new Command();
-program.name("posthorn").description("Posthorn \u2014 domain setup, mailbox creation, and email warmup").version("0.1.0");
+program.name("posthorn").description("Posthorn: domain setup, mailbox creation, and email warmup").version("0.2.5");
 program.addHelpText("after", `
 Agents: run 'posthorn guide' first for the full workflow playbook.
 
@@ -526,10 +596,10 @@ Typical flow:
   posthorn auth verify                            unlock sending + warmup
   posthorn warmup start <mailbox-id>
 
-Output: read commands auto-detect \u2014 agents (non-TTY) get JSON, humans get
+Output: read commands auto-detect. Agents (non-TTY) get JSON, humans get
 formatted text. Force either with --json or --pretty.
 `);
-program.command("guide").description("Print the full agent playbook \u2014 workflow, external steps, and how to drive the CLI. Run this first.").action(guide);
+program.command("guide").description("Print the full agent playbook: workflow, external steps, and how to drive the CLI. Run this first.").action(guide);
 var auth = program.command("auth").description("Account management");
 auth.command("register").description("Create a new account and get an API key").option("--url <url>", "API server URL", "https://api-production-08f2.up.railway.app").action(register);
 auth.command("status").description("Show current account info and setup progress").option("--json", "Force JSON output").option("--pretty", "Force human-readable output").action(status);
@@ -542,7 +612,7 @@ var domains = program.command("domains").description("Domain management");
 domains.command("list").description("List all domains").option("--json", "Force JSON output").option("--pretty", "Force human-readable output").action(listDomains);
 domains.command("get <domain-id>").description("Get domain details (poll this until status is 'ready')").option("--json", "Force JSON output").option("--pretty", "Force human-readable output").action(getDomain);
 domains.command("check <domains...>").description("Check domain availability + pricing (fast)").requiredOption("--cloudflare <account-id>", "Cloudflare account ID").option("--json", "Force JSON output").option("--pretty", "Force human-readable output").action(checkDomains);
-domains.command("reputation <domains...>").description("Vet a domain before buying \u2014 blocklist + reputation + prior-use history").option("--json", "Force JSON output").option("--pretty", "Force human-readable output").action(domainReputation);
+domains.command("reputation <domains...>").description("Vet a domain before buying, blocklist + reputation + prior-use history").option("--json", "Force JSON output").option("--pretty", "Force human-readable output").action(domainReputation);
 domains.command("buy <domain>").description("Purchase a domain").requiredOption("--cloudflare <account-id>", "Cloudflare account ID").option("--contact <json>", "Registrant contact info as JSON").action(buyDomain);
 domains.command("connect <domain>").description("Connect an existing domain on your own Cloudflare account").requiredOption("--cloudflare <account-id>", "Cloudflare account ID").option("--workspace <account-id>", "Workspace account ID").action(connectDomain);
 domains.command("managed <domain>").description("Add an existing domain to Posthorn-managed DNS (returns nameservers to set at your registrar)").option("--workspace <account-id>", "Workspace account ID").action(managedDomain);
@@ -557,17 +627,18 @@ warmup.command("list").description("List warmup campaigns").action(listCampaigns
 warmup.command("start <mailbox-id>").description("Start warming a mailbox").action(startWarmup);
 warmup.command("pause <campaign-id>").description("Pause a warmup campaign").action(pauseWarmup);
 warmup.command("stats <campaign-id>").description("Show warmup stats and daily breakdown").option("--json", "Force JSON output").option("--pretty", "Force human-readable output").action(warmupStats);
+program.command("feedback <message...>").description("Send feedback to the Posthorn team: bug reports, feature requests, anything").option("-t, --type <type>", "bug | feature | question | other", "other").action(sendFeedback);
 program.hook("preAction", () => {
 });
 program.parseAsync(process.argv).catch((err) => {
   if (err.statusCode === 401) {
-    console.log(chalk6.red("\n  Authentication failed. Run: posthorn auth register\n"));
+    console.log(chalk7.red("\n  Authentication failed. Run: posthorn auth register\n"));
   } else if (err.statusCode === 403) {
-    console.log(chalk6.red("\n  Account not verified. Run: posthorn auth verify\n"));
+    console.log(chalk7.red("\n  Account not verified. Run: posthorn auth verify\n"));
   } else if (err.statusCode === 429) {
-    console.log(chalk6.yellow("\n  Rate limit exceeded. Try again in a minute.\n"));
+    console.log(chalk7.yellow("\n  Rate limit exceeded. Try again in a minute.\n"));
   } else {
-    console.error(chalk6.red(`
+    console.error(chalk7.red(`
   Error: ${err.message}
 `));
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "posthorn",
-  "version": "0.2.3",
-  "description": "Posthorn — domain setup, mailbox creation, and email warmup from the command line",
+  "version": "0.2.5",
+  "description": "Domain setup, mailbox creation, and email warmup from the command line",
   "type": "module",
   "bin": {
     "posthorn": "dist/index.js"