@myapihq/cli 2.31.4 → 2.31.6

package/dist/commands/domain.js

@@ -51,6 +51,9 @@ export const SCHEMA = {
     'registrant-state': 'string',
     'registrant-postal-code': 'string',
     'registrant-country': 'string',
+    // Alias for --registrant-country, kept because account declared this
+    // spelling for the same field. See fromFlags in registrant.ts.
+    'registrant-country-code': 'string',
     'registrant-organization': 'string',
     // DNS records sub-surface
     type: 'string',

package/dist/commands/email/message-textpart.test.d.ts

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

package/dist/commands/email/message-textpart.test.js

@@ -0,0 +1,64 @@
+// An html-only `email message send` arrived with an EMPTY text/plain part.
+//
+// The backend adds the multipart alternative but does not fill it (filed
+// 2026-08-23, still open backend-side). Found live by the deep probe's email
+// journey on its FIRST run with a real fixture, 2026-08-25 — the exact defect
+// the step was written for, invisible to everything that does not read a
+// delivered message. The CLI now derives the plain part from the HTML, so the
+// customer-facing defect is closed regardless of when the backend fills its
+// half.
+import { describe, it, expect, vi } from 'vitest';
+const sdk = vi.hoisted(() => ({
+    email: { sendEmail: vi.fn(async () => ({ message_id: 'm-1' })) },
+    MyApiError: class MyApiError extends Error {
+        code = '';
+        status = 0;
+    },
+    // retryFunds in utils.js wraps sends with the 402 auto-recharge loop.
+    withFundsRetry: (fn) => fn(),
+    isInsufficientFunds: () => false,
+    autoRechargeState: () => undefined,
+}));
+vi.mock('@myapihq/sdk', () => sdk);
+vi.mock('../../config.js', () => ({
+    requireConfig: () => ({ api_key: 'hq_live_test' }),
+    loadConfig: () => ({ api_key: 'hq_live_test' }),
+    CONFIG_DIR: '/tmp/nowhere',
+}));
+import { run, plainTextFromHtml } from './message.js';
+import { withSink } from '../../output.js';
+const SINK = { out: () => { }, err: () => { }, fail: (m) => { throw new Error(m); } };
+describe('html-only send carries a derived text part', () => {
+    it('fills text from the html when --body is absent', async () => {
+        await withSink(SINK, () => run('send', [], {
+            from: 'a@x.co', to: 'b@x.co', subject: 's',
+            html: '<h1>Hello</h1><p>Two &amp; two.</p>',
+        }));
+        const payload = sdk.email.sendEmail.mock.calls.at(-1)[1];
+        expect(payload.text).toBe('Hello\nTwo & two.');
+        expect(payload.html).toContain('<h1>');
+    });
+    it('never overwrites an explicit --body', async () => {
+        await withSink(SINK, () => run('send', [], {
+            from: 'a@x.co', to: 'b@x.co', subject: 's',
+            html: '<p>rich</p>', body: 'my own words',
+        }));
+        expect(sdk.email.sendEmail.mock.calls.at(-1)[1].text).toBe('my own words');
+    });
+    it('text-only send is untouched', async () => {
+        await withSink(SINK, () => run('send', [], {
+            from: 'a@x.co', to: 'b@x.co', subject: 's', body: 'plain',
+        }));
+        const payload = sdk.email.sendEmail.mock.calls.at(-1)[1];
+        expect(payload.text).toBe('plain');
+        expect(payload.html).toBeUndefined();
+    });
+});
+describe('plainTextFromHtml', () => {
+    it('turns block boundaries into line breaks and strips the rest', () => {
+        expect(plainTextFromHtml('<div>a</div><div>b<br>c</div>')).toBe('a\nb\nc');
+    });
+    it('unescapes the common entities', () => {
+        expect(plainTextFromHtml('<p>&lt;tag&gt; &quot;q&quot; &amp; more&nbsp;here</p>')).toBe('<tag> "q" & more here');
+    });
+});

package/dist/commands/email/message.d.ts

@@ -1,5 +1,6 @@
 import type { Flags } from '../../helpers.js';
 import type { Exposes } from '../../exposes.js';
 export declare const EXPOSES: Exposes;
+export declare function plainTextFromHtml(html: string): string;
 export declare const SUBCOMMAND_USAGE: Record<string, string>;
 export declare function run(sub: string | undefined, args: string[], flags: Flags): Promise<void>;

package/dist/commands/email/message.js

@@ -21,6 +21,21 @@ function summarizeMessage(m) {
         received_at: m.received_at,
     };
 }
+// Block-level tags become line breaks, everything else is stripped, entities
+// beyond the common five are left alone. Exported for the test.
+export function plainTextFromHtml(html) {
+    return html
+        .replace(/<\s*(br|\/p|\/div|\/h[1-6]|\/li|\/tr)[^>]*>/gi, '\n')
+        .replace(/<[^>]+>/g, '')
+        .replace(/&nbsp;/g, ' ')
+        .replace(/&amp;/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/[ \t]+\n/g, '\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
 async function send(flags) {
     const config = requireConfig();
     // typeof check (not truthiness): a bare `--to` whose value got swallowed by
@@ -41,12 +56,22 @@ async function send(flags) {
             error('--template-vars must be valid JSON');
         }
     }
+    // An html-only send used to arrive with an EMPTY text/plain part: the
+    // backend adds the alternative but does not fill it (filed 2026-08-23,
+    // still open), so text-only clients and some spam filters saw a blank
+    // message. The API accepts `text`, so derive one instead of waiting.
+    // The stripper is deliberately crude — the plain part's job is to carry the
+    // words, not the layout.
+    const html = flags.html;
+    let text = flags.body;
+    if (html && !text)
+        text = plainTextFromHtml(html);
     const res = await retryFunds(() => sdkEmail.sendEmail(config.api_key, {
         from: flags.from,
         to: [flags.to],
         subject: flags.subject,
-        text: flags.body,
-        html: flags.html,
+        text,
+        html,
         template_id: flags['template-id'],
         template_vars: templateVars,
     }));

package/dist/commands/fn-create-json.test.d.ts

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

package/dist/commands/fn-create-json.test.js

@@ -0,0 +1,49 @@
+// `fn create --json` printed the human text, JSON nowhere.
+//
+// The scoped API key is returned exactly ONCE, at create. A script running
+// under --json got the prose rendering instead of a parseable object, so the
+// one-shot key was lost to anything that was not a human reading a terminal —
+// the same ignored---json class as `storage upload` and `mailbox create`.
+// Found by examples/a-to-z/run.mjs on its first real run, 2026-08-25.
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+const sdk = vi.hoisted(() => ({
+    fn: { createFunction: vi.fn() },
+    MyApiError: class MyApiError extends Error {
+        code = '';
+        status = 0;
+    },
+}));
+vi.mock('@myapihq/sdk', () => sdk);
+vi.mock('../config.js', () => ({
+    requireConfig: () => ({ api_key: 'hq_live_test', default_org: 'o-1' }),
+    loadConfig: () => ({ api_key: 'hq_live_test', default_org: 'o-1' }),
+    CONFIG_DIR: '/tmp/nowhere',
+}));
+import { create } from './fn.js';
+import { withSink } from '../output.js';
+const RESULT = {
+    function: { id: 'fn-1', name: 'demo', trigger_type: 'http', invocation_url: null },
+    scoped_api_key: 'hq_live_once',
+    scoped_api_key_id: 'key-1',
+};
+describe('fn create honours --json', () => {
+    // stdout and stderr are separate contracts: JSON rides stdout, the
+    // org-context banner rides stderr. Mixing them here would re-create the
+    // parse bug this file exists to prevent.
+    const out = [];
+    const err = [];
+    const SINK = { out: (m) => out.push(m), err: (m) => err.push(m), fail: (m) => { throw new Error(m); } };
+    beforeEach(() => { out.length = 0; err.length = 0; sdk.fn.createFunction.mockResolvedValue(RESULT); });
+    it('emits the full result as parseable JSON, including the one-shot key', async () => {
+        await withSink(SINK, () => create('demo', { json: true, org: 'o-1' }));
+        const parsed = JSON.parse(out.join('\n'));
+        expect(parsed.scoped_api_key).toBe('hq_live_once');
+        expect(parsed.function.id).toBe('fn-1');
+    });
+    it('without --json, keeps the human rendering', async () => {
+        await withSink(SINK, () => create('demo', { org: 'o-1' }));
+        const text = [...out, ...err].join('\n');
+        expect(text).toContain('Function created: fn-1');
+        expect(() => JSON.parse(text)).toThrow();
+    });
+});

package/dist/commands/fn.js

@@ -94,6 +94,15 @@ export async function create(nameArg, flags) {
             payload.scopes = scopes;
     }
     const result = await sdkFn.createFunction(config.api_key, orgId, payload);
+    // --json must carry the whole result — including the scoped key, which is
+    // returned exactly once. A script that created a function under --json got
+    // the human text instead (found by examples/a-to-z/run.mjs, the same
+    // ignored---json class as storage upload and mailbox create), and the
+    // one-shot key was lost to anything that wasn't a human reading a terminal.
+    if (flags.json) {
+        printJson(result);
+        return;
+    }
     success(`Function created: ${result.function.id}`);
     info(`Name:            ${result.function.name}`);
     info(`Trigger:         ${result.function.trigger_type}${result.function.cron_schedule ? ` (${result.function.cron_schedule})` : ''}`);

package/dist/commands/pixel.js

@@ -26,7 +26,7 @@ export async function interactions(flags) {
     const config = requireConfig();
     const orgId = flags.org || config.default_org;
     if (!orgId) {
-        error("Missing required arguments.\nUsage: myapi pixel interactions --org <id> [--website <domain>] [--campaign-id <id>] [--domain <domain>]\n(Or set defaults via: myapi config set-org <id>)");
+        error("Missing required arguments.\nUsage: myapi pixel interactions (--website <host> | --campaign-id <id> | --domain <domain>) [--org <id>]\n  --website: a site YOU own, where your pixel runs · --domain: a domain your visitors went to\n(Or set defaults via: myapi config set-org <id>)");
     }
     const params = {};
     if (flags.website)
@@ -44,7 +44,7 @@ export async function interactions(flags) {
     if (flags.offset)
         params.offset = parseInt(flags.offset, 10);
     if (!params.website && !params.campaign_id && !params.domain) {
-        error("You must provide at least one filter: --website, --campaign-id, or --domain");
+        error("You must provide at least one filter.\n  --website <host>     a site you own (where your pixel runs)\n  --campaign-id <id>   one email campaign\n  --domain <domain>    a domain your visitors went to");
     }
     const res = await sdkPixel.getInteractions(config.api_key, orgId, params);
     if (flags.json) {
@@ -195,7 +195,7 @@ Subcommands:
   identify       Link a known email/user id to an anonymous pixel visitor
   identity       Resolve the identity graph (emails, IPs, profiles) for a pixel ID
   interactions   Get a unified timeline of visits and events
-                 (requires at least one filter: --website, --campaign-id, or --domain)
+                 (requires one of: --website = a site you own · --campaign-id · --domain = a visited domain)
   visits         Page-visit timeline scoped to a website host
 
 All commands accept --org <id> (or set default: myapi config set-org <id>).`);

package/dist/commands/status.js

@@ -113,8 +113,13 @@ export async function run(_subcommand, _args, flags = {}) {
             info(`Recharge: ${summary}`);
     }
     if (Array.isArray(freeTier) && freeTier.length > 0) {
+        // A zero allowance rendered as "domain 0/0" reads like an error and says
+        // nothing a user can act on — there is no free tier for that slot, which
+        // is the platform's default, not this account's state. Show a slot only
+        // when there is an allowance to consume or usage to explain.
         const parts = freeTier
             .filter((e) => e && typeof e.service === 'string')
+            .filter((e) => (e.allowance ?? 0) > 0 || (e.used ?? 0) > 0)
             .map((e) => `${e.service} ${e.used ?? 0}/${e.allowance ?? '?'}`);
         if (parts.length > 0)
             info(`FreeTier: ${parts.join(' · ')}`);

package/dist/errors.js

@@ -3,6 +3,9 @@ import { currentOrg } from './helpers.js';
 // index.ts) so it can be unit-tested without importing the CLI entrypoint,
 // which runs main() on import.
 export const ERROR_MESSAGES = {
+    // 402, but not about money: the mailbox exists and the wallet is fine —
+    // outbound sending was never switched on for this address.
+    SENDING_NOT_ACTIVATED: 'This address cannot send yet — sending was never activated (this is not a billing problem). Run: myapi email mailbox activate-sending --address <email>',
     DOMAIN_NOT_FOUND: 'Domain not found.',
     INVALID_DOMAIN: 'Invalid domain name.',
     ORG_NOT_FOUND: 'Organization not found.',

package/dist/errors.test.js

@@ -165,3 +165,16 @@ describe('5xx advice distinguishes a read from a write', () => {
         expect(friendlyError(err())).toContain('went through');
     });
 });
+// SENDING_NOT_ACTIVATED arrives as HTTP 402, and the 402 handler's fallback
+// assumed any unrecognized 402 was an empty wallet — so a user with $92 of
+// credits was told "Insufficient balance. Top up". Money pointed at a problem
+// money cannot fix. Found live by the deep probe's email journey, 2026-08-25.
+describe('402 that is not about money', () => {
+    it('SENDING_NOT_ACTIVATED names the activation command, not a top-up', () => {
+        const e = new MyApiError('SENDING_NOT_ACTIVATED', 402, 'Activate sending for this address via POST /email/sending/activate');
+        const msg = friendlyError(e);
+        expect(msg).toContain('activate-sending');
+        expect(msg).toContain('not a billing problem');
+        expect(msg).not.toContain('topup');
+    });
+});

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { error, info, success, banner, setResolvedContextSource } from './output.js';
 import { loadConfig } from './config.js';
-import { MyApiError, setUserAgent, hq } from '@myapihq/sdk';
+import { MyApiError, setUserAgent, hq, isInsufficientFunds } from '@myapihq/sdk';
 import { friendlyError } from './errors.js';
 import { currentOrg, adoptSoleOrg } from './helpers.js';
 import * as fs from 'fs';
@@ -412,8 +412,16 @@ async function main() {
                     // Anonymous accounts can't top up (no payment surface) — link to unlock.
                     else if (cfg?.is_anonymous)
                         error('Insufficient balance. Anonymous accounts have no free credit — link an email to unlock $5: myapi account link <email>');
-                    else
+                    else if (!err.code || isInsufficientFunds(err)) {
                         error('Insufficient balance. Top up: myapi billing topup <amount> — or keep it funded automatically: myapi billing auto-recharge set');
+                    }
+                    // A 402 whose code is NOT about money. SENDING_NOT_ACTIVATED arrives
+                    // as 402 and landed in the branch above, so a user with $92 of
+                    // credits was told to top up — money pointed at a problem money
+                    // cannot fix, the same shape as "Invalid API key → run setup" on the
+                    // wrong-host bug. Show what the platform actually said.
+                    else
+                        error(friendlyError(err));
                 }
             }
             else

package/dist/registrant.js

@@ -21,6 +21,21 @@ import { saveConfig } from './config.js';
 // whether the partial is "complete enough" (we require all six base
 // fields plus country_code; state is optional).
 function fromFlags(flags) {
+    // Two spellings exist in the wild: account's schema declared
+    // `registrant-country-code` while this reader only ever read
+    // `registrant-country` — so the -code spelling was typed, swallowed a value,
+    // and did nothing. A scripted `account registrant set` then failed with
+    // "country_code missing" while the country sat in argv. Accept both;
+    // `registrant-country` is canonical (matching the rest of the family, which
+    // carries no type suffixes). Both-with-different-values is refused rather
+    // than resolved by precedence.
+    const country = flags['registrant-country'];
+    const countryAlias = flags['registrant-country-code'];
+    if (typeof country === 'string' && typeof countryAlias === 'string' && country !== countryAlias) {
+        error(`--registrant-country ("${country}") and --registrant-country-code ("${countryAlias}") disagree — they are the same field. Pass one.`);
+    }
+    const countryCode = typeof country === 'string' ? country
+        : typeof countryAlias === 'string' ? countryAlias : undefined;
     return {
         name: typeof flags['registrant-name'] === 'string' ? flags['registrant-name'] : undefined,
         email: typeof flags['registrant-email'] === 'string' ? flags['registrant-email'] : undefined,
@@ -29,7 +44,7 @@ function fromFlags(flags) {
         city: typeof flags['registrant-city'] === 'string' ? flags['registrant-city'] : undefined,
         state: typeof flags['registrant-state'] === 'string' ? flags['registrant-state'] : undefined,
         postal_code: typeof flags['registrant-postal-code'] === 'string' ? flags['registrant-postal-code'] : undefined,
-        country_code: typeof flags['registrant-country'] === 'string' ? flags['registrant-country'] : undefined,
+        country_code: countryCode,
         organization: typeof flags['registrant-organization'] === 'string' ? flags['registrant-organization'] : undefined,
     };
 }

package/dist/registrant.test.d.ts

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

package/dist/registrant.test.js

@@ -0,0 +1,39 @@
+import { describe, it, expect } from 'vitest';
+import { resolveRegistrantForRegister } from './registrant.js';
+import { withSink, CommandFailed } from './output.js';
+// error() exits the process unless a sink captures it — same pattern as
+// dispatch-in-process.test.ts.
+const SINK = { out: () => { }, err: () => { }, fail: (m) => { throw new CommandFailed(m); } };
+// `--registrant-country-code` was declared in account's SCHEMA but read by
+// nothing: fromFlags only ever looked at `registrant-country`. The -code
+// spelling consumed a value and discarded it, so a scripted registrant set
+// failed with "country_code missing" while the country sat in argv. Found
+// 2026-08-24 by dumping every SCHEMA key and asking which have no consumer.
+// Both spellings are read now; these tests pin that to behaviour, not to a
+// schema entry a lint could satisfy without a consumer.
+const BASE = {
+    'registrant-name': 'Ada Lovelace',
+    'registrant-email': 'ada@example.com',
+    'registrant-phone': '+44.2071234567',
+    'registrant-street': '12 Analytical Way',
+    'registrant-city': 'London',
+    'registrant-postal-code': 'EC1A 1AA',
+};
+const CONFIG = {};
+describe('registrant country spellings', () => {
+    it('canonical --registrant-country reaches country_code', async () => {
+        const r = await resolveRegistrantForRegister({ ...BASE, 'registrant-country': 'GB' }, CONFIG);
+        expect(r.country_code).toBe('GB');
+    });
+    it('the alias --registrant-country-code reaches country_code too', async () => {
+        const r = await resolveRegistrantForRegister({ ...BASE, 'registrant-country-code': 'GB' }, CONFIG);
+        expect(r.country_code).toBe('GB');
+    });
+    it('both spellings with different values are refused, not resolved by precedence', async () => {
+        await expect(withSink(SINK, () => resolveRegistrantForRegister({ ...BASE, 'registrant-country': 'GB', 'registrant-country-code': 'DE' }, CONFIG))).rejects.toThrow(/disagree/);
+    });
+    it('both spellings agreeing is fine', async () => {
+        const r = await resolveRegistrantForRegister({ ...BASE, 'registrant-country': 'GB', 'registrant-country-code': 'GB' }, CONFIG);
+        expect(r.country_code).toBe('GB');
+    });
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@myapihq/cli",
   "license": "Apache-2.0",
-  "version": "2.31.4",
+  "version": "2.31.6",
   "description": "MyAPI command-line interface",
   "repository": {
     "type": "git",
@@ -35,6 +35,8 @@
     "lint:help-order": "node scripts/lint-help-order.js",
     "lint:exposes": "node scripts/lint-exposes.js",
     "lint:query-params": "node scripts/lint-query-params.js",
+    "lint:flag-lexicon": "node scripts/lint-flag-lexicon.js",
+    "lint:verb-symmetry": "node scripts/lint-verb-symmetry.js",
     "lint:request-fields": "node scripts/lint-request-fields.js",
     "audit:doctor": "npm run build && node scripts/audit-doctor.js",
     "lint:docs": "node scripts/lint-docs.js",
@@ -47,7 +49,7 @@
     "lint:skills:strict": "node scripts/copy-skills.js && node scripts/lint-skills.js --strict"
   },
   "dependencies": {
-    "@myapihq/sdk": "^2.31.4"
+    "@myapihq/sdk": "^2.31.6"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",