@myapihq/cli 1.0.84 → 1.1.0-wip.1

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

@@ -0,0 +1,104 @@
+---
+name: my-email-api
+description: >
+  Send transactional and bulk email from your own domain. Create mailboxes, send/receive messages, generate AI templates, run drip campaigns, and manage warmup.
+---
+
+# MyEmailAPI
+
+Account-scoped email infrastructure tied to your registered domains. Mailboxes belong to domains; sending and receiving work without per-org plumbing. Templates and campaigns are org-scoped (one campaign belongs to one org).
+
+## How It Fits Together
+
+- Requires `api_key` from **myapihq** and a registered domain via **mydomainapi**.
+- Mailboxes live on a domain (e.g. `hello@yourdomain.com`).
+- Sending must be activated per-mailbox (`mailbox activate-sending`) before transactional sends or campaigns.
+- Templates and campaigns require `org_id` (set a default with `myapi auth config set-org`).
+
+## Quick Start
+
+```bash
+# 1. Create a mailbox on your registered domain
+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
+
+# 3. Send a transactional email
+myapi email message send \
+  --from hello@yourdomain.com \
+  --to recipient@example.com \
+  --subject "Hi" \
+  --body "Test message"
+
+# 4. Read inbox / outbox
+myapi email message inbox hello@yourdomain.com
+myapi email message outbox hello@yourdomain.com
+```
+
+## Command Map
+
+| Namespace | Subcommands | Purpose |
+|---|---|---|
+| `email mailbox` | `create`, `list`, `activate-sending` | Create and manage mailboxes on your domains |
+| `email message` | `send`, `status`, `sent`, `inbox`, `outbox`, `get` | Transactional send + read |
+| `email warmup` | `start`, `stats`, `pause`, `resume`, `stop` | IP/domain warmup for sending reputation |
+| `email template` | `generate`, `list`, `edit`, `send-test`, `delete` | AI-generated HTML templates (org-scoped) |
+| `email campaign` | `create`, `list`, `get`, `update`, `upload-contacts`, `start`, `pause`, `resume`, `stats` | Drip campaigns (org-scoped) |
+
+## Templates (AI-generated)
+
+```bash
+# Generate a template — polls the LLM job (up to 90s)
+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
+myapi email template edit <id> --prompt "Make the CTA larger and red"
+myapi email template send-test <id> --to me@yourdomain.com
+myapi email template delete <id>
+```
+
+## Campaigns
+
+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 "Welcome series" \
+  --template-id <template_id> \
+  --from hello@yourdomain.com \
+  --per-day 50
+
+# 2. Upload contacts
+myapi email campaign upload-contacts <campaign_id> \
+  --emails "alice@example.com,bob@example.com"
+
+# 3. Start (only after upload-contacts has finished processing)
+myapi email campaign start <campaign_id>
+
+# 4. Monitor
+myapi email campaign stats <campaign_id>
+myapi email campaign pause <campaign_id>
+myapi email campaign resume <campaign_id>
+```
+
+## Warmup
+
+Warmup gradually ramps mailbox sending to build reputation with inbox providers. Recommended before high-volume campaigns.
+
+```bash
+myapi email warmup start --address hello@yourdomain.com
+myapi email warmup stats --address hello@yourdomain.com
+myapi email warmup pause --address hello@yourdomain.com
+```
+
+## Notes
+
+- A single mailbox is uniquely identified by its address (`username@domain`).
+- Sending must be activated explicitly — newly-created mailboxes can receive but not send.
+- Templates and campaigns are org-scoped. Set a default org once: `myapi auth config set-org <id>`.
+- Domain assignment to org is enforced at unassign time: an active or paused campaign sending from a mailbox on the domain will block `domain unassign` with `DOMAIN_IN_USE`.
+
+Run `myapi email --help` or `myapi email <namespace> --help` for full flag reference.

package/dist/skills/my-email-api/claude/.claude-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "my-email-api",
+  "description": "Send transactional and bulk email from your own domain. Mailboxes, AI templates, drip campaigns, and warmup.",
+  "version": "1.0.0",
+  "published": true
+}

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

@@ -0,0 +1,40 @@
+---
+# my-webhook-api
+
+Inbound HTTP endpoints that receive POSTs from third-party services and store every delivery for inspection. Pair with my-workflow-api to react to incoming events.
+
+## What it does
+
+- Create per-org webhook endpoints with unique inbound URLs
+- Store every inbound delivery (body + headers)
+- Inspect individual deliveries by id
+- Bind webhooks to workflows for event-driven actions
+
+## Quickstart
+
+```bash
+# Create an endpoint
+myapi webhook create "stripe-events"
+# → prints: Inbound URL: https://api.myapihq.com/webhook/in/<slug>
+
+# POST to it from anywhere
+curl -X POST <inbound-url> -d '{"event":"x"}'
+
+# List + inspect
+myapi webhook list
+myapi webhook delivery <delivery_id>
+```
+
+## Authentication
+
+```bash
+export MYAPI_KEY=mak_...
+```
+
+Requires `api_key` and `org_id` from **myapihq**.
+
+## Documentation
+
+Full command reference and workflow integration: see `SKILL.md`.
+
+Run `myapi webhook --help` for inline reference.

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

@@ -0,0 +1,138 @@
+---
+name: my-webhook-api
+description: >
+  Inbound webhook endpoints. Receive HTTP POSTs from third parties (forms, Stripe, GitHub, etc.) and either inspect the deliveries directly or wire them to a workflow.
+---
+
+# MyWebhookAPI
+
+Per-org HTTP endpoints that accept inbound POSTs and durably store every delivery. A webhook on its own is a passive receiver — pair it with **myworkflowapi** to react to incoming events (send email, post to Slack, etc.).
+
+## How It Fits Together
+
+- Requires `api_key` and `org_id` from **myapihq**.
+- Each endpoint has a unique inbound URL (returned at create time).
+- Deliveries are stored verbatim — full request body + headers — for inspection.
+- `myworkflowapi` workflows bind to a webhook endpoint via its `id`.
+
+## Quick Start
+
+```bash
+# 1. Create a webhook endpoint
+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
+curl -X POST https://api.myapihq.com/webhook/in/<slug> \
+  -H "Content-Type: application/json" \
+  -d '{"event":"payment.succeeded"}'
+
+# 3. List endpoints / inspect a delivery
+myapi webhook list
+myapi webhook delivery <delivery_id>
+```
+
+## All Commands
+
+| Command | What it does |
+|---|---|
+| `myapi webhook create` | Create an endpoint, returns id + inbound URL |
+| `myapi webhook list` | List all endpoints in your org |
+| `myapi webhook delete <id>` | Delete an endpoint and all its deliveries |
+| `myapi webhook delivery <delivery_id>` | Get the full payload + headers for one delivery |
+
+## Wiring to a Workflow
+
+Webhooks become useful when a workflow fires on each inbound POST. See **myworkflowapi**:
+
+```bash
+# Create the webhook
+WID=$(myapi webhook create "leads" --json | jq -r .id)
+
+# Bind a workflow that sends an email each time the webhook fires
+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.
+- Deliveries are kept indefinitely. Delete the endpoint to purge them.
+- Failed workflow runs do not affect the delivery record — the inbound POST is always saved.
+
+Run `myapi webhook --help` for full flag reference.

package/dist/skills/my-webhook-api/claude/.claude-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "my-webhook-api",
+  "description": "Receive inbound HTTP webhooks. Per-org endpoints with full delivery history.",
+  "version": "1.0.0",
+  "published": true
+}

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

@@ -0,0 +1,36 @@
+---
+# my-workflow-api
+
+Run a chain of actions (send email, post to Slack, call an HTTP endpoint) every time an inbound webhook fires. No backend required.
+
+## What it does
+
+- Bind ordered step chains to webhook endpoints
+- Steps can: send transactional email, hit Slack, call any HTTP URL
+- Template values from the inbound webhook payload (`{{ payload.field }}`)
+- Per-run status tracking (attempt, error, started/finished timestamps)
+- Enable/disable without losing config
+
+## Quickstart
+
+```bash
+# Create a webhook + workflow that sends Slack on every POST
+WID=$(myapi webhook create "leads" --json | jq -r .id)
+myapi workflow create "Slack on lead" \
+  --endpoint-id $WID \
+  --steps '[{"type":"slack","webhook_url":"..."}]'
+```
+
+## Authentication
+
+```bash
+export MYAPI_KEY=mak_...
+```
+
+Requires `api_key` + `org_id` from **myapihq**, and a webhook endpoint id from **mywebhookapi**.
+
+## Documentation
+
+Full command reference, step types, and templating: see `SKILL.md`.
+
+Run `myapi workflow --help` for inline reference.

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

@@ -0,0 +1,156 @@
+---
+name: my-workflow-api
+description: >
+  Run actions when a webhook fires. Trigger emails, Slack notifications, or HTTP calls in response to inbound webhook deliveries — without writing a backend.
+---
+
+# MyWorkflowAPI
+
+Workflows bind a list of steps to a webhook endpoint. Every time the webhook receives a POST, the workflow runs its steps in order. Each run is recorded with its status, attempt count, and any error.
+
+## How It Fits Together
+
+- Requires `api_key` and `org_id` from **myapihq**.
+- Requires a webhook endpoint id from **mywebhookapi** as the trigger.
+- Steps can reference other services — e.g. send an email via **myemailapi**.
+
+## Quick Start
+
+```bash
+# 1. Create the webhook that will trigger the workflow
+WID=$(myapi webhook create "leads" --json | jq -r .id)
+
+# 2. Create a workflow bound to that webhook
+myapi workflow create "Slack on new lead" \
+  --endpoint-id $WID \
+  --steps '[{"type":"slack","webhook_url":"https://hooks.slack.com/..."}]'
+
+# 3. POST to the webhook → workflow fires
+curl -X POST <webhook-inbound-url> -d '{"name":"Alice"}'
+
+# 4. Inspect runs
+myapi workflow runs <workflow_id>
+myapi workflow get-run <run_id>
+```
+
+## All Commands
+
+| Command | What it does |
+|---|---|
+| `myapi workflow create` | Create a new workflow (`--name --endpoint-id --steps`) |
+| `myapi workflow list` | List workflows in your org |
+| `myapi workflow get <id>` | Inspect a workflow's steps + trigger config |
+| `myapi workflow update <id>` | Change name, endpoint, or steps |
+| `myapi workflow enable <id>` | Enable firing |
+| `myapi workflow disable <id>` | Stop firing without deleting |
+| `myapi workflow delete <id>` | Permanently remove workflow + run history |
+| `myapi workflow runs <id>` | List recent runs (status, attempt, errors) |
+| `myapi workflow get-run <run_id>` | Get full run details + step output |
+
+## Steps
+
+`--steps` is a JSON array of step objects. Each step has a `type` and type-specific fields.
+
+```json
+[
+  {
+    "type": "send_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 }}"
+  }
+]
+```
+
+The webhook payload is available as `{{ payload }}` and individual fields as `{{ payload.fieldname }}`.
+
+## 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 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 "X" --endpoint-id $WID --steps '...' --no-enable
+
+# Trigger via webhook POST, inspect
+myapi workflow runs <id>
+
+# When ready
+myapi workflow enable <id>
+
+# To temporarily stop
+myapi workflow disable <id>
+```
+
+## Notes
+
+- Workflows fire on every webhook delivery. Failed runs don't block subsequent runs.
+- Each run records its attempt number, started_at/finished_at, and any error.
+- A workflow can be disabled to stop firing without losing the configuration.
+- Deleting a workflow purges its run history; the webhook endpoint remains.
+
+Run `myapi workflow --help` for full flag reference.

package/dist/skills/my-workflow-api/claude/.claude-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "my-workflow-api",
+  "description": "React to inbound webhooks with step chains: send email, post to Slack, call HTTP URLs.",
+  "version": "1.0.0",
+  "published": true
+}

package/dist/utils.d.ts

@@ -1,10 +1,32 @@
-export declare function parseArgs(argv: string[]): {
-    args: string[];
-    flags: Record<string, string | boolean>;
-};
 export declare function sleep(ms: number): Promise<unknown>;
 /**
  * Formats an ISO/Go timestamp string to "YYYY-MM-DD HH:mm" (UTC).
  * 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,36 +1,4 @@
-export function parseArgs(argv) {
-    const args = [];
-    const flags = {};
-    for (let i = 0; i < argv.length; i++) {
-        const arg = argv[i];
-        if (arg === '-h') {
-            flags['help'] = true;
-        }
-        else if (arg === '-v') {
-            flags['version'] = true;
-        }
-        else if (arg.startsWith('--')) {
-            if (arg.includes('=')) {
-                const [key, value] = arg.slice(2).split('=', 2);
-                flags[key] = value;
-            }
-            else {
-                const next = argv[i + 1];
-                if (next && !next.startsWith('--')) {
-                    flags[arg.slice(2)] = next;
-                    i++;
-                }
-                else {
-                    flags[arg.slice(2)] = true;
-                }
-            }
-        }
-        else {
-            args.push(arg);
-        }
-    }
-    return { args, flags };
-}
+import { spinnerFrame, clearLine, error } from './output.js';
 export function sleep(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }
@@ -45,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/dist/utils.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils.test.js

@@ -0,0 +1,48 @@
+import { describe, it, expect } from 'vitest';
+import { parseArgs } from './utils.js';
+describe('parseArgs', () => {
+    it('treats unknown flags as boolean', () => {
+        const { args, flags } = parseArgs(['funnel', 'get', '--json', 'abc-123']);
+        expect(flags.json).toBe(true);
+        expect(args).toEqual(['funnel', 'get', 'abc-123']);
+    });
+    it('treats --yes, --help, --verbose as boolean', () => {
+        const { flags } = parseArgs(['--yes', '--help', '--verbose']);
+        expect(flags.yes).toBe(true);
+        expect(flags.help).toBe(true);
+        expect(flags.verbose).toBe(true);
+    });
+    it('consumes next token for value flags', () => {
+        const { args, flags } = parseArgs(['org', 'create', '--name', 'Acme Inc', '--yes']);
+        expect(flags.name).toBe('Acme Inc');
+        expect(flags.yes).toBe(true);
+        expect(args).toEqual(['org', 'create']);
+    });
+    it('supports --key=value syntax for any flag', () => {
+        const { flags } = parseArgs(['--org=abc-123', '--json']);
+        expect(flags.org).toBe('abc-123');
+        expect(flags.json).toBe(true);
+    });
+    it('value flag with no next token becomes boolean true', () => {
+        const { flags } = parseArgs(['--name']);
+        expect(flags.name).toBe(true);
+    });
+    it('value flag followed by another flag does not consume it', () => {
+        const { flags } = parseArgs(['--org', '--json']);
+        expect(flags.org).toBe(true);
+        expect(flags.json).toBe(true);
+    });
+    it('-h maps to help', () => {
+        const { flags } = parseArgs(['-h']);
+        expect(flags.help).toBe(true);
+    });
+    it('-v maps to version', () => {
+        const { flags } = parseArgs(['-v']);
+        expect(flags.version).toBe(true);
+    });
+    it('collects positional args correctly', () => {
+        const { args, flags } = parseArgs(['domain', 'register', 'example.com', '--org', 'uuid-here']);
+        expect(args).toEqual(['domain', 'register', 'example.com']);
+        expect(flags.org).toBe('uuid-here');
+    });
+});