@myapihq/cli 1.1.0-wip.0 → 1.1.0-wip.2

package/dist/helpers.js

@@ -1,16 +1,18 @@
 import { error } from './output.js';
-// Resolve org id from --org or the configured default. On miss, exit with a
-// usage-aware error that points the user at both the flag and the config command.
+// error() returns `never`, so after `if (!x) error(...)` TS narrows x to a
+// non-falsy value and the casts disappear.
 export function requireOrg(flags, config, usage) {
-    const orgId = flags.org || config.default_org;
-    if (!orgId || typeof orgId !== 'string') {
+    const orgId = (typeof flags.org === 'string' ? flags.org : '') || config.default_org;
+    if (!orgId) {
         error(`Missing required arguments.\nUsage: ${usage}\n(Or set default: myapi config set-org <id>)`);
     }
     return orgId;
 }
 export function requireDomain(arg, flags, config, usage) {
-    const domain = arg || flags.domain || config.default_domain;
-    if (!domain || typeof domain !== 'string') {
+    const fromFlag = typeof flags.domain === 'string' ? flags.domain : '';
+    const fromConfig = typeof config.default_domain === 'string' ? config.default_domain : '';
+    const domain = arg || fromFlag || fromConfig;
+    if (!domain) {
         error(`Missing required arguments.\nUsage: ${usage}\n(Or set default: myapi config set-domain <domain>)`);
     }
     return domain;

package/dist/index.js

@@ -15,7 +15,7 @@ import * as domainCmd from './commands/domain.js';
 import * as funnelCmd from './commands/funnel.js';
 import * as webhookCmd from './commands/webhook.js';
 import * as workflowCmd from './commands/workflow.js';
-import * as emailCmd from './commands/email.js';
+import * as emailCmd from './commands/email/index.js';
 import * as authCmd from './commands/auth.js';
 import * as configCmd from './commands/config.js';
 // Each command file declares the value flags it understands. We union them
@@ -58,6 +58,9 @@ const ERROR_MESSAGES = {
     RATE_LIMITED: 'Too many requests. Please wait a moment and try again.',
     INSUFFICIENT_BALANCE: 'Insufficient balance. Run: myapi billing topup <amount>',
     INVALID_AMOUNT: 'Amount out of range. Maximum single top-up is $100. Run: myapi billing topup <amount>',
+    // invalid_json_response intentionally absent — the SDK's MyApiError now
+    // builds a useful detailed message for that case (status + URL + body
+    // snippet), and friendlyError(err.code) would override it.
 };
 function friendlyError(code) {
     return ERROR_MESSAGES[code] || code;
@@ -161,7 +164,10 @@ async function main() {
                 error(friendlyError(err.code) || err.message);
         }
         else {
-            error(err.message || (typeof err === 'object' ? JSON.stringify(err) : String(err)));
+            // Don't JSON.stringify Error instances — that returns "{}" because
+            // Error's enumerable surface is empty. Prefer .message; fall back to
+            // String() which Errors stringify reasonably ("Error: ...").
+            error(err?.message ?? String(err));
         }
     }
 }
@@ -250,4 +256,4 @@ Run "myapi <command> --help" for subcommand help.
 
 ${quickStart}`);
 }
-main().catch(err => { error(err.message || (typeof err === 'object' ? JSON.stringify(err) : String(err))); });
+main().catch(err => { error(err?.message ?? String(err)); });

package/dist/output.d.ts

@@ -6,10 +6,12 @@ export declare function error(message: string): never;
 export declare function info(message: string): void;
 export declare function banner(message: string): void;
 export declare function printJson(data: unknown): void;
+export declare function spinnerFrame(i: number): string;
+export declare function clearLine(): void;
 export interface PrintTableOptions {
     /** Pass `flags` so `--json` (any truthy form) routes to JSON output. */
     flags?: TableFlags;
     /** Hint shown when the table is empty (instead of "No data found."). */
     empty?: string;
 }
-export declare function printTable(rows: Record<string, unknown>[], opts?: PrintTableOptions): void;
+export declare function printTable<T extends object>(rows: T[], opts?: PrintTableOptions): void;

package/dist/output.js

@@ -15,6 +15,18 @@ export function banner(message) {
 export function printJson(data) {
     console.log(JSON.stringify(data, null, 2));
 }
+// Spinner / line-clear primitives. Used by polling helpers (utils.pollJob)
+// and any handler that wants its own progress UI.
+const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+export function spinnerFrame(i) {
+    return SPINNER_FRAMES[i % SPINNER_FRAMES.length];
+}
+export function clearLine() {
+    process.stdout.write('\r\x1b[K');
+}
+// Generic so callers don't need `as unknown as Record<string, unknown>[]`.
+// Field names come from the first row; if SDK renames a field, the projector
+// (passed in by the caller) is where it'll fail at compile time.
 export function printTable(rows, opts = {}) {
     if (opts.flags && opts.flags.json) {
         printJson(rows);

package/dist/prompt.d.ts

@@ -0,0 +1,24 @@
+import * as readline from 'readline';
+/**
+ * Ask a free-form question on stdin. Returns the trimmed answer.
+ *
+ * Handles the readline lifecycle so callers don't open/close interfaces
+ * inline. Replaces five copies of the same boilerplate across commands.
+ */
+export declare function ask(question: string): Promise<string>;
+/**
+ * Yes/No confirm. `defaultYes` controls how Enter (no input) is interpreted.
+ *
+ * - `confirm('› Continue? (Y/n) ', true)` — Enter means yes.
+ * - `confirm('› Delete? (y/N) ', false)` — Enter means no.
+ *
+ * Accepted yes inputs: 'y', 'yes' (case-insensitive). Anything else is no
+ * when `defaultYes=false`; when `defaultYes=true`, only an explicit 'n' /
+ * 'no' counts as no, matching the existing Y/n convention in the CLI.
+ */
+export declare function confirm(question: string, defaultYes: boolean): Promise<boolean>;
+/**
+ * Lower-level escape hatch: get a readline.Interface, do something with it,
+ * close it on the way out (even if your callback throws).
+ */
+export declare function withReadline<T>(fn: (rl: readline.Interface) => Promise<T>): Promise<T>;

package/dist/prompt.js

@@ -0,0 +1,41 @@
+import * as readline from 'readline';
+/**
+ * Ask a free-form question on stdin. Returns the trimmed answer.
+ *
+ * Handles the readline lifecycle so callers don't open/close interfaces
+ * inline. Replaces five copies of the same boilerplate across commands.
+ */
+export async function ask(question) {
+    return withReadline(rl => new Promise(resolve => {
+        rl.question(question, ans => resolve(ans.trim()));
+    }));
+}
+/**
+ * Yes/No confirm. `defaultYes` controls how Enter (no input) is interpreted.
+ *
+ * - `confirm('› Continue? (Y/n) ', true)` — Enter means yes.
+ * - `confirm('› Delete? (y/N) ', false)` — Enter means no.
+ *
+ * Accepted yes inputs: 'y', 'yes' (case-insensitive). Anything else is no
+ * when `defaultYes=false`; when `defaultYes=true`, only an explicit 'n' /
+ * 'no' counts as no, matching the existing Y/n convention in the CLI.
+ */
+export async function confirm(question, defaultYes) {
+    const ans = (await ask(question)).toLowerCase();
+    if (defaultYes)
+        return ans !== 'n' && ans !== 'no';
+    return ans === 'y' || ans === 'yes';
+}
+/**
+ * Lower-level escape hatch: get a readline.Interface, do something with it,
+ * close it on the way out (even if your callback throws).
+ */
+export async function withReadline(fn) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return await fn(rl);
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/skills/my-email-api/README.md

@@ -16,7 +16,7 @@ Send transactional email and run drip campaigns from mailboxes on your own regis
 
 ```bash
 # Create a mailbox + activate sending
-myapi email mailbox create --domain yourdomain.com --username hello
+myapi email mailbox create hello@yourdomain.com
 myapi email mailbox activate-sending --address hello@yourdomain.com
 
 # Send

package/dist/skills/my-email-api/SKILL.md

@@ -19,7 +19,7 @@ Account-scoped email infrastructure tied to your registered domains. Mailboxes b
 
 ```bash
 # 1. Create a mailbox on your registered domain
-myapi email mailbox create --domain yourdomain.com --username hello --display-name "Hello"
+myapi email mailbox create hello@yourdomain.com --display-name "Hello"
 
 # 2. Activate sending (required before send/campaign)
 myapi email mailbox activate-sending --address hello@yourdomain.com
@@ -50,9 +50,8 @@ myapi email message outbox hello@yourdomain.com
 
 ```bash
 # Generate a template — polls the LLM job (up to 90s)
-myapi email template generate \
-  --prompt "A welcome email with our brand colors and a CTA to /onboarding" \
-  --name welcome-v1
+myapi email template generate welcome-v1 \
+  --prompt "A welcome email with our brand colors and a CTA to /onboarding"
 
 # List, edit, delete
 myapi email template list
@@ -67,8 +66,7 @@ Campaigns send a template to a contact list at a per-day rate.
 
 ```bash
 # 1. Create a campaign linked to an existing template + sender mailbox
-myapi email campaign create \
-  --name "Welcome series" \
+myapi email campaign create "Welcome series" \
   --template-id <template_id> \
   --from hello@yourdomain.com \
   --per-day 50

package/dist/skills/my-webhook-api/README.md

@@ -14,7 +14,7 @@ Inbound HTTP endpoints that receive POSTs from third-party services and store ev
 
 ```bash
 # Create an endpoint
-myapi webhook create --name "stripe-events"
+myapi webhook create "stripe-events"
 # → prints: Inbound URL: https://api.myapihq.com/webhook/in/<slug>
 
 # POST to it from anywhere

package/dist/skills/my-webhook-api/SKILL.md

@@ -19,7 +19,7 @@ Per-org HTTP endpoints that accept inbound POSTs and durably store every deliver
 
 ```bash
 # 1. Create a webhook endpoint
-myapi webhook create --name "stripe-events" --description "Stripe payment events"
+myapi webhook create "stripe-events" --description "Stripe payment events"
 # → prints: Inbound URL: https://api.myapihq.com/webhook/in/<slug>
 
 # 2. POST to the inbound URL from your service
@@ -47,15 +47,88 @@ Webhooks become useful when a workflow fires on each inbound POST. See **myworkf
 
 ```bash
 # Create the webhook
-WID=$(myapi webhook create --name "leads" --json | jq -r .id)
+WID=$(myapi webhook create "leads" --json | jq -r .id)
 
 # Bind a workflow that sends an email each time the webhook fires
-myapi workflow create \
-  --name "Notify on lead" \
+myapi workflow create "Notify on lead" \
   --endpoint-id $WID \
   --steps '[{"type":"send_email","to":"sales@yourdomain.com","subject":"New lead"}]'
 ```
 
+## Payload contract
+
+The inbound URL accepts **any JSON body** — there's no enforced schema, no
+required fields. Whatever you POST is stored verbatim alongside the headers
+and a timestamp. The shape is whatever the sender chooses to send.
+
+That has two consequences:
+
+1. **You decide the shape.** A form, a Stripe event, a custom payload — all
+   work. Be consistent within one webhook so downstream workflows can
+   reference fields reliably.
+2. **Workflows reference fields with `{{ payload.field }}` templating.**
+   If your form POSTs `{"email": "alice@x.com", "message": "hi"}`, a
+   workflow step can do `--to "{{ payload.email }}"` to send a reply to
+   whoever submitted.
+
+Inbound responses: 200 OK on success, 4xx if the endpoint is missing or
+the body isn't valid JSON.
+
+## End-to-end recipe — contact form on your website
+
+Goal: a contact form on yoursite.com. When someone submits, send a
+thank-you email to them and a Slack ping to your team.
+
+```bash
+# 1. Create a webhook to receive form submissions
+WID=$(myapi webhook create "contact-form" --json | jq -r .id)
+WURL=$(myapi webhook list --json | jq -r ".[] | select(.id==\"$WID\") | .url")
+
+# 2. Create the workflow that fires on every submission
+myapi workflow create "Contact form handler" \
+  --endpoint-id $WID \
+  --steps "$(cat <<'JSON'
+[
+  {
+    "type": "send_email",
+    "from": "hello@yoursite.com",
+    "to": "{{ payload.email }}",
+    "subject": "Thanks for reaching out, {{ payload.name }}!",
+    "body": "We got your message and will reply within 24 hours."
+  },
+  {
+    "type": "slack",
+    "webhook_url": "https://hooks.slack.com/services/T.../B.../xxx",
+    "text": "New contact form submission from {{ payload.name }} ({{ payload.email }}): {{ payload.message }}"
+  }
+]
+JSON
+)"
+
+# 3. Drop this form in your HTML — it POSTs JSON to the webhook
+echo "<form id='contact'>
+  <input name='name' required>
+  <input name='email' type='email' required>
+  <textarea name='message' required></textarea>
+  <button>Send</button>
+</form>
+<script>
+document.getElementById('contact').addEventListener('submit', async e => {
+  e.preventDefault();
+  const data = Object.fromEntries(new FormData(e.target));
+  await fetch('$WURL', {
+    method: 'POST',
+    headers: {'Content-Type': 'application/json'},
+    body: JSON.stringify(data),
+  });
+  alert('Thanks! Check your inbox.');
+});
+</script>"
+```
+
+The form sends `{"name": "...", "email": "...", "message": "..."}` →
+webhook stores it → workflow fires → email goes out → Slack gets pinged.
+
 ## Notes
 
 - The inbound URL is public — anyone with the URL can POST to it. Treat the slug as a secret.

package/dist/skills/my-workflow-api/README.md

@@ -6,7 +6,7 @@ Run a chain of actions (send email, post to Slack, call an HTTP endpoint) every
 ## What it does
 
 - Bind ordered step chains to webhook endpoints
-- Steps can: send transactional email, hit Slack, call any HTTP URL
+- Steps can: send transactional email, post to Slack
 - Template values from the inbound webhook payload (`{{ payload.field }}`)
 - Per-run status tracking (attempt, error, started/finished timestamps)
 - Enable/disable without losing config
@@ -15,9 +15,8 @@ Run a chain of actions (send email, post to Slack, call an HTTP endpoint) every
 
 ```bash
 # Create a webhook + workflow that sends Slack on every POST
-WID=$(myapi webhook create --name "leads" --json | jq -r .id)
-myapi workflow create \
-  --name "Slack on lead" \
+WID=$(myapi webhook create "leads" --json | jq -r .id)
+myapi workflow create "Slack on lead" \
   --endpoint-id $WID \
   --steps '[{"type":"slack","webhook_url":"..."}]'
 ```

package/dist/skills/my-workflow-api/SKILL.md

@@ -18,11 +18,10 @@ Workflows bind a list of steps to a webhook endpoint. Every time the webhook rec
 
 ```bash
 # 1. Create the webhook that will trigger the workflow
-WID=$(myapi webhook create --name "leads" --json | jq -r .id)
+WID=$(myapi webhook create "leads" --json | jq -r .id)
 
 # 2. Create a workflow bound to that webhook
-myapi workflow create \
-  --name "Slack on new lead" \
+myapi workflow create "Slack on new lead" \
   --endpoint-id $WID \
   --steps '[{"type":"slack","webhook_url":"https://hooks.slack.com/..."}]'
 
@@ -52,31 +51,101 @@ myapi workflow get-run <run_id>
 
 `--steps` is a JSON array of step objects. Each step has a `type` and type-specific fields.
 
+Supported step types (alias forms in parentheses):
+
+| `type` | Aliases | Required fields |
+|---|---|---|
+| `send_email` | `email` | `from`, `to`, `subject`, plus one of `body` / `html` / `template_id` |
+| `slack_message` | `slack` | `webhook_url`, `text` |
+
 ```json
 [
   {
-    "type": "send_email",
+    "type": "email",
     "from": "hello@yourdomain.com",
     "to": "{{ payload.email }}",
     "subject": "Welcome, {{ payload.name }}",
     "template_id": "<template_id>"
   },
   {
-    "type": "http",
-    "method": "POST",
-    "url": "https://crm.example.com/contacts",
-    "body": "{{ payload | json }}"
+    "type": "slack",
+    "webhook_url": "https://hooks.slack.com/services/T.../B.../xxx",
+    "text": "New submission from {{ payload.name }}"
+  }
+]
+```
+
+Unknown step types are rejected at workflow create time, so typos surface
+immediately instead of after 3 failed retries during execution.
+
+The webhook payload is available as `{{ payload }}` and individual fields
+as `{{ payload.fieldname }}`. Whitespace inside the braces is fine —
+both `{{ payload.email }}` and `{{payload.email}}` work.
+
+## End-to-end recipe — react to a contact form submission
+
+Goal: form on yoursite.com posts to a webhook → workflow sends a thank-you
+email and pings Slack. Full HTML + commands:
+
+```bash
+# 1. Create the webhook to receive submissions
+WID=$(myapi webhook create "contact-form" --json | jq -r .id)
+WURL=$(myapi webhook list --json | jq -r ".[] | select(.id==\"$WID\") | .url")
+
+# 2. Workflow that fires on each submission. Two steps: thank-you email
+#    + Slack ping. Both reference fields from the form payload via {{ }}.
+myapi workflow create "Contact form handler" \
+  --endpoint-id $WID \
+  --steps "$(cat <<'JSON'
+[
+  {
+    "type": "send_email",
+    "from": "hello@yoursite.com",
+    "to": "{{ payload.email }}",
+    "subject": "Thanks for reaching out, {{ payload.name }}!",
+    "body": "We got your message and will reply within 24 hours."
+  },
+  {
+    "type": "slack",
+    "webhook_url": "https://hooks.slack.com/services/T.../B.../xxx",
+    "text": "New submission from {{ payload.name }} ({{ payload.email }}): {{ payload.message }}"
   }
 ]
+JSON
+)"
+
+# 3. The HTML form on yoursite.com — POSTs JSON to the webhook
+echo "<form id='contact'>
+  <input name='name' required>
+  <input name='email' type='email' required>
+  <textarea name='message' required></textarea>
+  <button>Send</button>
+</form>
+<script>
+document.getElementById('contact').addEventListener('submit', async e => {
+  e.preventDefault();
+  const data = Object.fromEntries(new FormData(e.target));
+  await fetch('$WURL', {
+    method: 'POST',
+    headers: {'Content-Type': 'application/json'},
+    body: JSON.stringify(data),
+  });
+  alert('Thanks! Check your inbox.');
+});
+</script>"
 ```
 
-The webhook payload is available as `{{ payload }}` and individual fields as `{{ payload.fieldname }}`.
+The form sends `{"name": "...", "email": "...", "message": "..."}`. The
+webhook stores it. The workflow runs both steps in order: the user gets
+an email at the address they typed, your team gets a Slack ping with the
+message. Each invocation is recorded — `myapi workflow runs <id>` shows
+the history.
 
 ## Lifecycle
 
 ```bash
 # Create disabled, test, then enable
-myapi workflow create --name "X" --endpoint-id $WID --steps '...' --no-enable
+myapi workflow create "X" --endpoint-id $WID --steps '...' --no-enable
 
 # Trigger via webhook POST, inspect
 myapi workflow runs <id>

package/dist/utils.d.ts

@@ -4,3 +4,29 @@ export declare function sleep(ms: number): Promise<unknown>;
  * Strips Go's " +0000 UTC" suffix before parsing.
  */
 export declare function formatDate(str: string): string;
+export interface PollOptions<T> {
+    /** Fetch current state. Called once per interval. */
+    check: () => Promise<T>;
+    /** Inspect a state and decide if we should resolve with it. */
+    isDone: (state: T) => boolean;
+    /** Inspect a state and decide if the job has failed (calls error()). */
+    isFailed?: (state: T) => boolean;
+    /** Label shown next to the spinner (e.g. "Importing"). */
+    label: string;
+    /** Total wall-clock budget. Defaults to 90s. */
+    timeoutMs?: number;
+    /** Delay between checks. Defaults to 3s. */
+    intervalMs?: number;
+    /** Message shown via error() on timeout. Defaults to a generic phrase. */
+    timeoutMessage?: string;
+    /** Message shown via error() when isFailed returns true. */
+    failedMessage?: string;
+}
+/**
+ * Generic spinner+poll helper. Used wherever the CLI kicks off a long-running
+ * server-side job and needs to wait for it (template generate, sync-brand).
+ *
+ * Returns the final `T` from `check()` once `isDone(state)` is true.
+ * Calls error() (which exits with code 1) on timeout or `isFailed`.
+ */
+export declare function pollJob<T>(opts: PollOptions<T>): Promise<T>;

package/dist/utils.js

@@ -1,3 +1,4 @@
+import { spinnerFrame, clearLine, error } from './output.js';
 export function sleep(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }
@@ -12,3 +13,34 @@ export function formatDate(str) {
         return str;
     return date.toISOString().replace('T', ' ').slice(0, 16) + ' UTC';
 }
+/**
+ * Generic spinner+poll helper. Used wherever the CLI kicks off a long-running
+ * server-side job and needs to wait for it (template generate, sync-brand).
+ *
+ * Returns the final `T` from `check()` once `isDone(state)` is true.
+ * Calls error() (which exits with code 1) on timeout or `isFailed`.
+ */
+export async function pollJob(opts) {
+    const timeoutMs = opts.timeoutMs ?? 90_000;
+    const intervalMs = opts.intervalMs ?? 3_000;
+    process.stdout.write(`${opts.label} `);
+    let i = 0;
+    let elapsed = 0;
+    while (elapsed < timeoutMs) {
+        const state = await opts.check();
+        if (opts.isDone(state)) {
+            clearLine();
+            return state;
+        }
+        if (opts.isFailed && opts.isFailed(state)) {
+            clearLine();
+            error(opts.failedMessage ?? `${opts.label} failed`);
+        }
+        process.stdout.write(`\r${opts.label} ${spinnerFrame(i++)}`);
+        await sleep(intervalMs);
+        elapsed += intervalMs;
+    }
+    clearLine();
+    error(opts.timeoutMessage ??
+        `${opts.label} timed out after ${Math.round(timeoutMs / 1000)}s. The job may still complete in the background — re-run to retry.`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myapihq/cli",
-  "version": "1.1.0-wip.0",
+  "version": "1.1.0-wip.2",
   "description": "MyAPI command-line interface",
   "type": "module",
   "files": [