posthorn 0.2.6 → 0.2.8

package/README.md

@@ -42,19 +42,63 @@ The platform is a pure orchestration layer: the USER owns their Cloudflare
 account, their Google Workspace, their domains, and their mailboxes. Posthorn
 never owns or bills for any of it.
 
-## The end-to-end flow (in order)
-
-1. Account        → `posthorn auth register` (anonymous API key, instant)
-2. Cloudflare     → user creates account + API token, then `posthorn accounts cloudflare <token>`
-3. Workspace      → user sets up domain-wide delegation, then `posthorn accounts workspace <admin-email>`
-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)
-8. Warmup         → `posthorn warmup start <mailbox-id>`
+## The flow: walk it like a setup wizard
+
+Go step by step. Ask one question at a time, only when the step needs it, and
+do as much as possible yourself. Don't front-load questions.
+
+Step 1. `posthorn auth register`. Instant API key; no email or signup info
+needed, and there are no account tiers. Nothing to ask.
+
+Step 2. Domain. Ask: "Do you need a new domain for your emails, or will you
+use an existing one for sending?"
+- NEW domain (the purchase always happens on the user's own Cloudflare account
+  and card; Posthorn never owns or bills for domains):
+  a. They need a Cloudflare account with a payment method (they pay Cloudflare
+     directly for the domain, ~$10/yr). Browser step: create the API token
+     (below), then `posthorn accounts cloudflare <token>`.
+  b. `posthorn domains check name1.com name2.io --cloudflare <id>` (availability
+     + price) → `posthorn domains reputation <pick>` (vets Spamhaus blocklist,
+     reputation score, and prior use; verdicts: clean / caution / avoid. Run it
+     before buying; you can't tell a tainted domain from its name.) →
+     `posthorn domains buy <pick> --cloudflare <id> --contact '{...}'`
+- EXISTING domain. If it runs their live website or real email, recommend a
+  dedicated sending domain instead. Two ways to connect it; either way the
+  domain stays registered where they bought it, only nameservers change:
+  a. Their own Cloudflare: they manage the domain's DNS in their own Cloudflare
+     account. Needs the API token (below); and if the domain isn't on their
+     Cloudflare yet, they add it at dash.cloudflare.com and point nameservers
+     there first. Then `posthorn domains connect <domain> --cloudflare <id>`.
+  b. Posthorn-managed DNS: no Cloudflare account to create or manage; Posthorn
+     hosts the domain's DNS for them (free). `posthorn domains managed <domain>`
+     → they set the 2 printed nameservers at their registrar →
+     `posthorn domains activate <id>`. Note: Posthorn then hosts ALL of the
+     domain's DNS records (website records included), so it fits domains
+     dedicated to email.
+
+Step 3. Google Workspace. Ask: "Do you have a Google Workspace you can add new
+domains and mailboxes to, or do you want to set up a new one?"
+- Existing Workspace: delegation browser step (below), then
+  `posthorn accounts workspace <admin-email>`.
+- New Workspace: they create one at workspace.google.com using the domain from
+  step 2, then delegation as above.
+(Delegation is per org, not per domain, so with an existing org this step can
+happen any time, even before the domain exists. The domain pipeline auto-adds
+and verifies the new domain inside their org.)
+
+Step 4. Wait for the domain: poll `posthorn domains get <id>` until status
+`ready` (minutes to 24h; poll every 30-60s, don't hammer). MX/SPF/DMARC are
+configured automatically. Statuses progress: pending_* → purchased →
+dns_configuring → dns_configured → dns_verified → workspace_verifying →
+workspace_verified → ready.
+
+Step 5. DKIM. Browser step below; once per domain, needs the domain `ready`.
+
+Step 6. `posthorn mailboxes create <domain-id> --email ... --first ... --last ...`
+
+Step 7. `posthorn warmup start <mailbox-id>`
 
 Dependencies: you CANNOT create a mailbox until the domain status is `ready`.
-You CANNOT send or start warmup until the account is "verified" tier.
 
 Run `posthorn auth status --json` any time to see where things stand. State is
 stored locally, so you can stop and continue any time.
@@ -62,15 +106,20 @@ stored locally, so you can stop and continue any time.
 ## The external/manual steps (things that happen OUTSIDE the CLI)
 
 These are the steps you must GUIDE THE USER through in their browser. Give exact
-click-by-click instructions. Tell the user up front that these are one-time
-setup steps; once done, they never repeat them. Future domains and mailboxes
-are fully automated (the only exceptions: DKIM is once per domain, delegation
-is once per Workspace org).
+click-by-click instructions. Before each browser step, share with the user that
+this is a one-time setup, e.g. "This is a one-time setup step; you won't need
+to do this again." The repetition model, so you can answer follow-ups:
+- Cloudflare API token: once ever
+- Workspace delegation: once per Workspace org
+- DKIM: once per domain
+- Everything else (domains, mailboxes, warmup): fully automated, no browser
 
 ### Cloudflare API token (one-time, for "buy new" or "own Cloudflare" domains)
 - dash.cloudflare.com/profile/api-tokens → Create Token → Custom Token
 - Permissions: Account>Account Settings>Read, Account>Registrar: Domains>Admin,
-  Zone>Zone>Edit, Zone>DNS>Edit. Resources: Include All.
+  Zone>Zone>Edit, Zone>DNS>Edit.
+- Account Resources: Include > All accounts
+- Zone Resources: Include > All zones
 - Do NOT add Billing permissions; they are not needed. Domain purchases charge
   the payment method already on the Cloudflare account, which is a dashboard
   setting, not a token permission.
@@ -87,7 +136,9 @@ is once per Workspace org).
 - Client ID: 110137377718772968374
 - 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>`
+- Must be done signed in as a SUPER-ADMIN of that Workspace org, and the email
+  passed to the CLI must be that super-admin's. Then run:
+  `posthorn accounts workspace <admin-email>`
 - This replaces OAuth entirely: no consent screen, no app verification, no test users.
 
 ### Nameservers (only for "managed DNS" or moving a domain to Cloudflare)
@@ -109,37 +160,6 @@ If you have browser-automation tools, do it for the user:
 If no browser tools: have the user do the above and paste you the TXT value,
 then add it to their DNS.
 
-## Domain options (3 paths)
-
-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
-     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
-     a quota, so it's a separate explicit call, not part of `check`.)
-   - `posthorn domains buy <domain> --cloudflare <id> --contact '{...}'`
-
-2. EXISTING domain, recommended → user's own Cloudflare account.
-   - `posthorn domains connect <domain> --cloudflare <account-id>`
-   - (If the domain isn't on Cloudflare yet, the user adds it at dash.cloudflare.com
-     and points nameservers to their account first.)
-
-3. EXISTING domain, optional → Posthorn-managed DNS (no Cloudflare account needed).
-   - `posthorn domains managed <domain>` → prints 2 nameservers
-   - 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.
-
-After any path, poll `posthorn domains get <id>` until status is `ready`. DNS
-records (MX, SPF, DMARC) are configured automatically. Statuses progress:
-pending_* → purchased → dns_configuring → dns_configured → dns_verified →
-workspace_verifying → workspace_verified → ready.
-
 ## Mailboxes & sending
 
 - Create: `posthorn mailboxes create <domain-id> --email john@dom.com --first John --last Smith`
@@ -147,19 +167,17 @@ workspace_verifying → workspace_verified → ready.
 - 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 "..."`
-  (requires "verified" tier)
 
-## Account verification (unlocks sending/warmup)
-
-Anonymous tier can do setup (accounts, domains). To send/warmup, verify:
-`posthorn auth verify` → choose admin email or a custom email → confirm the code.
+There is no email-verification step anywhere: connecting your own Cloudflare
+and Workspace IS the identity. Once a mailbox exists, sending and warmup work.
 
 ## 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 start <mailbox-id>` → joins the shared warmup pool and runs
+  continuously until paused
+  - Volume and reply behavior are platform-managed (ramps from 2/day up to
+    5/day, then holds; 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>`.
@@ -169,19 +187,17 @@ Anonymous tier can do setup (accounts, domains). To send/warmup, verify:
 `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
+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.
+(include the command you ran and what you expected).
+
+Whenever you or the user get stuck, file the issue with `posthorn feedback`.
 
 ## 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
   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.
-- 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

@@ -76,7 +76,6 @@ async function register(options) {
     spinner.succeed("Account created!");
     console.log();
     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, it won't be shown again."));
     console.log(chalk.dim(`  Config stored at: ${getConfigPath()}`));
@@ -581,7 +580,7 @@ function guide() {
 
 // src/index.ts
 var program = new Command();
-program.name("posthorn").description("Posthorn: domain setup, mailbox creation, and email warmup").version("0.2.6");
+program.name("posthorn").description("Posthorn: domain setup, mailbox creation, and email warmup").version("0.2.8");
 program.addHelpText("after", `
 Agents: run 'posthorn guide' first for the full workflow playbook.
 
@@ -593,7 +592,6 @@ Typical flow:
   posthorn domains connect <domain> --cloudflare <id>
   posthorn domains get <id> --json                poll until status: ready
   posthorn mailboxes create <domain-id> --email you@dom.com --first A --last B
-  posthorn auth verify                            unlock sending + warmup
   posthorn warmup start <mailbox-id>
 
 Output: read commands auto-detect. Agents (non-TTY) get JSON, humans get
@@ -634,7 +632,9 @@ program.parseAsync(process.argv).catch((err) => {
   if (err.statusCode === 401) {
     console.log(chalk7.red("\n  Authentication failed. Run: posthorn auth register\n"));
   } else if (err.statusCode === 403) {
-    console.log(chalk7.red("\n  Account not verified. Run: posthorn auth verify\n"));
+    console.log(chalk7.red(`
+  Not allowed: ${err.message}
+`));
   } else if (err.statusCode === 429) {
     console.log(chalk7.yellow("\n  Rate limit exceeded. Try again in a minute.\n"));
   } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "posthorn",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "Domain setup, mailbox creation, and email warmup from the command line",
   "type": "module",
   "bin": {