@myapihq/cli 1.3.2 → 1.3.5

package/dist/commands/doctor.js

@@ -4,15 +4,29 @@
 // checks across slots and returns a structured report. The CLI's job is:
 //   1. fetch the report,
 //   2. augment with *customer-perspective* probes the backend structurally
-//      can't run (today: DNS resolution from the user's network),
+//      can't run from its own egress: DNS resolution and HTTP reachability
+//      from the user's network,
 //   3. render with section grouping, color, and exit codes for CI.
+//
+// Division of labour (a contract, not an accident): the backend owns
+// configuration / reference-integrity / orphan checks; the client owns
+// liveness probes (DNS, HTTP). The backend must NOT HTTP-probe — it has no
+// customer-vantage egress — and the client must not re-derive config state.
+// Augmented sections are therefore appended *last*: client-observed checks
+// are a distinct epistemic class (observed now, from here) and shouldn't
+// interleave with the backend's findings.
 import { promises as dns } from 'node:dns';
-import { hq as sdkHq } from '@myapihq/sdk';
+import { createHash } from 'node:crypto';
+import { hq as sdkHq, container as sdkContainer, funnel as sdkFunnel } from '@myapihq/sdk';
 import { requireConfig } from '../config.js';
 import { info, error, printJson } from '../output.js';
 import { requireOrg } from '../helpers.js';
 export const EXPOSES = [
     'GET /hq/orgs/{org_id}/doctor',
+    // Read-only enumeration for the HTTP reachability augmentation pass.
+    'GET /container/orgs/{org_id}/containers',
+    'GET /funnel/orgs/{org_id}/funnels',
+    'GET /funnel/orgs/{org_id}/funnels/{funnel_id}/pages',
 ];
 export const SCHEMA = {};
 const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
@@ -28,8 +42,20 @@ const MARK = {
 function rule(width = 60) {
     return `${C.dim}${'─'.repeat(width)}${C.reset}`;
 }
+// Stable, dedupable id for a client-generated issue, matching the backend's
+// opaque `kind/<hash>` shape. The human-readable form lives in scope/message;
+// the id stays a single-slash key so consumers can split it the same way
+// they split backend ids (a raw URL in the id would break that).
+function localIssueId(kind, key) {
+    return `${kind}/${createHash('sha256').update(key).digest('hex').slice(0, 16)}`;
+}
 function fmtIssue(i) {
-    const head = `  ${MARK[i.severity] ?? '·'} ${i.message}`;
+    // Prefix the entity name so sibling issues with identical messages
+    // (e.g. four "domain is active" rows) are distinguishable. Skip it when
+    // the message already names the entity — the local DNS section does.
+    const name = i.entity?.name;
+    const label = name && !i.message.includes(name) ? `${C.bold}${name}${C.reset} — ` : '';
+    const head = `  ${MARK[i.severity] ?? '·'} ${label}${i.message}`;
     return i.hint ? `${head}\n    ${C.dim}→ ${i.hint}${C.reset}` : head;
 }
 // Local DNS-resolution probe for every distinct domain the report names.
@@ -51,7 +77,7 @@ async function dnsProbeSection(report) {
         try {
             const ips = await dns.resolve4(name);
             issues.push({
-                id: `dns_local_ok/${name}`,
+                id: localIssueId('dns_local_ok', name),
                 severity: 'ok',
                 scope: `local/${name}`,
                 entity: { slot: 'domain', id: '', name },
@@ -61,7 +87,7 @@ async function dnsProbeSection(report) {
         }
         catch (e) {
             issues.push({
-                id: `dns_local_fail/${name}`,
+                id: localIssueId('dns_local_fail', name),
                 severity: 'warn',
                 scope: `local/${name}`,
                 entity: { slot: 'domain', id: '', name },
@@ -78,6 +104,91 @@ async function dnsProbeSection(report) {
         issues,
     };
 }
+// One HTTP GET with an 8s ceiling. Returns the final status code (after
+// redirects) or, on a network/timeout failure, a null status + error string.
+async function fetchStatus(url) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), 8000);
+    try {
+        const res = await fetch(url, { method: 'GET', redirect: 'follow', signal: ctrl.signal });
+        // Drain the body so the socket can be released — we only want the status.
+        await res.body?.cancel().catch(() => { });
+        return { status: res.status };
+    }
+    catch (e) {
+        const error = e?.name === 'AbortError'
+            ? 'timed out after 8s'
+            : (e?.cause?.code || e?.code || e?.message || String(e));
+        return { status: null, error };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+// Customer-perspective HTTP reachability probe. The backend reports whether a
+// funnel/container is *configured* consistently; it can't tell from its own
+// egress whether the published URL actually answers. This fetches every
+// container URL and funnel page the org exposes and surfaces the status.
+//
+// Like the DNS probe, a failed fetch is `warn`, never `crit`: a single
+// request from one machine at one instant isn't authoritative enough to fail
+// CI — it's a signal to act on, layered over the backend's config view.
+async function httpProbeSection(apiKey, orgId) {
+    const targets = [];
+    // Containers: probe the bound custom domain when set (what customers hit),
+    // else the Cloud Run URL. An undeployed container has neither — skip it.
+    try {
+        const containers = await sdkContainer.listContainers(apiKey, orgId);
+        for (const c of containers) {
+            const url = c.custom_domain ? `https://${c.custom_domain}` : c.url;
+            if (url)
+                targets.push({ url, entity: { slot: 'container', id: c.id, name: c.name } });
+        }
+    }
+    catch { /* augmentation is best-effort — skip the slot if enumeration fails */ }
+    // Funnels: probe every published page URL.
+    try {
+        const funnels = await sdkFunnel.listFunnels(apiKey, orgId);
+        await Promise.all(funnels.map(async (f) => {
+            try {
+                const pages = await sdkFunnel.listFunnelPages(apiKey, orgId, f.id);
+                for (const p of pages) {
+                    if (p.url)
+                        targets.push({ url: p.url, entity: { slot: 'funnel', id: f.id, name: f.name || f.id } });
+                }
+            }
+            catch { /* skip this funnel */ }
+        }));
+    }
+    catch { /* skip the slot */ }
+    if (targets.length === 0)
+        return null;
+    const issues = [];
+    await Promise.all(targets.map(async ({ url, entity }) => {
+        const probe = await fetchStatus(url);
+        // 2xx/3xx = reachable. 4xx, 5xx and network failures are all `warn`.
+        const ok = probe.status != null && probe.status < 400;
+        issues.push({
+            id: localIssueId(ok ? 'http_ok' : 'http_unreachable', `${entity.slot}/${entity.id}/${url}`),
+            severity: ok ? 'ok' : 'warn',
+            scope: `local/${url}`,
+            entity,
+            category: 'network',
+            message: ok
+                ? `${url} responded ${probe.status}`
+                : `${url} ${probe.status != null ? `returned ${probe.status}` : 'is unreachable'}`,
+            hint: ok ? undefined : (probe.error || `customers may not be able to reach ${entity.slot} "${entity.name}"`),
+        });
+    }));
+    const warns = issues.filter(i => i.severity === 'warn').length;
+    return {
+        name: 'reachability',
+        summary: warns
+            ? `${warns} of ${issues.length} URL${issues.length === 1 ? '' : 's'} unreachable`
+            : `${issues.length} URL${issues.length === 1 ? '' : 's'} reachable`,
+        issues,
+    };
+}
 export async function run(_subcommand, _args, flags) {
     if (flags.help) {
         info(HELP);
@@ -95,14 +206,28 @@ export async function run(_subcommand, _args, flags) {
     catch (e) {
         error(`doctor endpoint failed: ${e?.message ?? String(e)}`);
     }
+    // Local augmentation, appended after the backend's sections by design —
+    // see the file header on why client-observed checks stay grouped at the end.
     const localSection = await dnsProbeSection(report);
     if (localSection)
         report.sections.push(localSection);
+    const reachSection = await httpProbeSection(apiKey, orgId);
+    if (reachSection)
+        report.sections.push(reachSection);
     // Re-tally totals after local augmentation.
     const totals = { ok: 0, warn: 0, crit: 0 };
-    for (const s of report.sections)
-        for (const i of s.issues)
-            totals[i.severity]++;
+    for (const s of report.sections) {
+        for (const i of s.issues) {
+            // Ignore any severity the backend invents that we don't model — better
+            // a missed count than a NaN poisoning the whole tally.
+            if (i.severity in totals)
+                totals[i.severity]++;
+        }
+    }
+    // Set the exit code before any output branch — CI relies on it in both
+    // the human and the --json path.
+    if (totals.crit)
+        process.exitCode = 1;
     if (wantJson) {
         printJson({ ...report, totals });
         return;
@@ -121,7 +246,6 @@ export async function run(_subcommand, _args, flags) {
     info(rule(60));
     if (totals.crit) {
         info(`${MARK.crit} ${totals.crit} critical, ${MARK.warn} ${totals.warn} warning${totals.warn === 1 ? '' : 's'}`);
-        process.exitCode = 1;
     }
     else if (totals.warn) {
         info(`${MARK.warn} ${totals.warn} warning${totals.warn === 1 ? '' : 's'}, no critical issues`);
@@ -136,13 +260,16 @@ const HELP = `Usage: myapi doctor [--verbose] [--json] [--org <id>]
 
 Org-wide consistency check. Fetches the structured report from the backend
 (GET /hq/orgs/{org_id}/doctor) and augments it with customer-perspective
-probes (DNS resolution from this machine's network).
+probes run from this machine's network.
 
 Sections returned by the backend today:
   funnels, webhooks, workflows, domains, containers, emails, payments
 
 Local additions:
-  network    — DNS resolution from your egress for each domain mentioned.
+  local network — DNS resolution from your egress for each domain mentioned.
+  reachability  — HTTP GET to every container URL and funnel page; surfaces
+                  the status code. Failures are warnings, never critical —
+                  a single fetch isn't authoritative enough to fail CI.
 
 Exit codes:
   0  no critical issues (warnings allowed)

package/dist/commands/domain.js

@@ -114,23 +114,44 @@ export async function importCmd(domainArg, flags) {
     }
     success(`Imported ${res.domain} (status: ${res.status})`);
     info('');
-    info(`Nameservers (set these at your current registrar):`);
-    for (const ns of res.nameservers)
-        info(`  ${ns}`);
-    info('');
-    if (res.preserved_records.length > 0) {
-        info(`Preserved DNS records (${res.preserved_count} found — verify before the NS change):`);
-        printTable(res.preserved_records.map(r => ({ type: r.type, name: r.name, content: r.content, ttl: r.ttl })), { flags });
+    // Defensive — the backend has shipped this response with a non-array
+    // `nameservers` (the domain_id string mis-serialized into the field) and
+    // missing `preserved_records` in some states. JS iterating a string
+    // prints char-per-line and reading .length on undefined crashes; see
+    // docs/cross-repo-prompts/backend-domain-import-response-shape.md. Never
+    // trust the shape blindly — degrade to pointing at `domain status`,
+    // which is queryable for the real values.
+    if (Array.isArray(res.nameservers) && res.nameservers.length > 0) {
+        info(`Nameservers (set these at your current registrar):`);
+        for (const ns of res.nameservers)
+            info(`  ${ns}`);
+        info('');
+    }
+    else {
+        info(`⚠ Backend returned an unexpected nameservers shape (got ${typeof res.nameservers}).`);
+        info(`  The domain is imported — fetch the real nameservers with:`);
+        info(`    myapi domain status ${res.domain} --json`);
+        info('');
+    }
+    const preserved = Array.isArray(res.preserved_records) ? res.preserved_records : [];
+    const preservedCount = typeof res.preserved_count === 'number' ? res.preserved_count : preserved.length;
+    if (preserved.length > 0) {
+        info(`Preserved DNS records (${preservedCount} found — verify before the NS change):`);
+        printTable(preserved.map(r => ({ type: r.type, name: r.name, content: r.content, ttl: r.ttl })), { flags });
         info('');
     }
     else {
         info(`No DNS records detected via public probe — verify directly with your registrar before the NS change.`);
         info('');
     }
-    info(res.probe_warning);
-    info('');
-    info(res.next_step);
-    info('');
+    if (res.probe_warning) {
+        info(res.probe_warning);
+        info('');
+    }
+    if (res.next_step) {
+        info(res.next_step);
+        info('');
+    }
     info(`After changing nameservers, watch activation with:`);
     info(`  myapi domain status ${res.domain} --watch`);
 }

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

@@ -50,7 +50,7 @@ pixel_visit | webhook_received
 
 Agents cannot write events directly — the closed enum is intentional. If you need custom state, use **mydatabaseapi** (KV) keyed on the contact id; the curated timeline stays authoritative for engagement.
 
-**Engagement-event kinds bump `last_engagement_at`**: email_sent/opened/clicked/replied, pixel_visit, webhook_received. Admin kinds (created, promoted, stage_changed) don't. That's the right semantics — promoting a Goldfox lead into the CRM is not engagement.
+**Engagement-event kinds bump `last_engagement_at`**: email_sent/opened/clicked/replied, pixel_visit, webhook_received. Admin kinds (created, promoted, stage_changed) don't — promoting a Goldfox lead isn't engagement.
 
 ### Auto-ingest
 
@@ -157,8 +157,7 @@ myapi crm contacts events <id> --kind webhook_received
 ## Notes
 
 - **Reserved event kinds — no custom events in v1.** If an agent needs custom state per contact, use `myapi database` keyed by contact id. The curated timeline stays the authoritative engagement record.
-- **Event payloads carry an `external_id`** field used by the backend's idempotency index — same value as the natural id of the underlying action (`goldfox_person_id` for `promoted`, `delivery_id` for `webhook_received`, future `message_id` for `email_sent`). Read the semantic field (e.g. `goldfox_person_id`); `external_id` is a backend-internal duplicate. Old rows may still carry a legacy `message_id` field — same value as `external_id`; safe to ignore.
-- **Goldfox enrichment field deferred** — the live join lands once the BQ get-by-id helper is wired backend-side. CLI treats it as optional today.
+- **Event payloads carry an `external_id`** — the backend's idempotency key, equal to the underlying action's natural id (`goldfox_person_id` for `promoted`, `delivery_id` for `webhook_received`). Read the semantic field; `external_id` is a backend-internal duplicate. A legacy `message_id` on old rows holds the same value — safe to ignore.
 - **Email + Pixel auto-ingest not yet wired**. Only `webhook_received` events fire today. Email and pixel ingest are coming — the CLI surface stays unchanged when they land.
 - **Free in v1.** Metered later if usage shows a need.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@myapihq/cli",
   "license": "Apache-2.0",
-  "version": "1.3.2",
+  "version": "1.3.5",
   "description": "MyAPI command-line interface",
   "type": "module",
   "files": [
@@ -29,7 +29,7 @@
     "lint:changelog": "node ../../scripts/lint-changelog.js"
   },
   "dependencies": {
-    "@myapihq/sdk": "^1.3.2"
+    "@myapihq/sdk": "^1.3.5"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",