@myapihq/cli 1.2.6 → 1.2.8

package/dist/commands/billing.d.ts

@@ -6,6 +6,7 @@ export declare const EXPOSES: Exposes;
 export declare function run(subcommand: string | undefined, args: string[], flags: Flags): Promise<void>;
 export declare function balance(flags: Flags): Promise<void>;
 export declare function history(flags: Flags): Promise<void>;
+export declare function usage(flags: Flags): Promise<void>;
 export declare function topup(amountStr: string, flags: Flags): Promise<void>;
 export declare function setup(_flags: Flags): Promise<void>;
 export declare function spendCap(arg: string | undefined, flags: Flags): Promise<void>;

package/dist/commands/billing.js

@@ -9,6 +9,7 @@ export const SCHEMA = {
 export const EXPOSES = [
     'GET /hq/billing/balance',
     'GET /hq/billing/history',
+    'GET /hq/billing/usage',
     'POST /hq/billing/setup-payment',
     'POST /hq/billing/topup',
     'GET /hq/account/me',
@@ -17,6 +18,11 @@ export const EXPOSES = [
 const SUBCOMMAND_USAGE = {
     'balance': 'myapi billing balance [--json]',
     'history': 'myapi billing history [--json]',
+    'usage': `myapi billing usage [--period month|30d] [--json]
+
+Spend rolled up by service — the accurate "where is my money going" view.
+Aggregates every billing event, unlike the flat history log. Defaults to
+the current calendar month; --period 30d gives the trailing 30 days.`,
     'topup': `myapi billing topup <amount> [--yes]
 
 Amount is in whole dollars (e.g. "10" charges $10).
@@ -44,6 +50,7 @@ export async function run(subcommand, args, flags) {
 Subcommands:
   balance    Check balance, credits, and payment method status
   history    View recent transactions and top-ups
+  usage      Spend rolled up by service (this month, or --period 30d)
   topup      Top up your balance (whole dollars)
   setup      Open a checkout link to add or update payment method
   spend-cap  Set/show/clear the account-level spend ceiling (IAM Layer 2)`);
@@ -60,6 +67,7 @@ Subcommands:
     switch (subcommand) {
         case 'balance': return balance(flags);
         case 'history': return history(flags);
+        case 'usage': return usage(flags);
         case 'topup': return topup(args[0], flags);
         case 'setup': return setup(flags);
         case 'spend-cap': return spendCap(args[0], flags);
@@ -105,6 +113,31 @@ export async function history(flags) {
         empty: 'No transactions yet.',
     });
 }
+// Spend rolled up by service. Aggregates every billing event over the
+// window (current calendar month, or trailing 30 days with --period 30d) —
+// the accurate "where is my money going" view, distinct from `history`.
+export async function usage(flags) {
+    const config = requireConfig();
+    const period = flags.period || 'month';
+    if (period !== 'month' && period !== '30d') {
+        error(`Invalid --period "${period}". Use month or 30d.`);
+    }
+    const res = await hq.getBillingUsage(config.api_key, period);
+    if (flags.json) {
+        printJson(res);
+        return;
+    }
+    info(`Spend by service — ${res.period === '30d' ? 'last 30 days' : 'this month'} (since ${formatDate(res.since)})`);
+    printTable(res.services.map(s => ({
+        Service: s.service,
+        Requests: s.requests,
+        Cost: s.cost_display,
+    })), {
+        flags,
+        empty: 'No usage recorded in this window.',
+    });
+    info(`Total: ${res.total_display}`);
+}
 export async function topup(amountStr, flags) {
     const amount = Math.round(parseFloat(amountStr));
     if (!amountStr || isNaN(amount) || amount <= 0) {

package/dist/commands/container-validation.test.d.ts

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

package/dist/commands/container-validation.test.js

@@ -0,0 +1,45 @@
+// Unit tests for container.ts CLI's pure helpers — name validation
+// (mirrors the backend regex/reserved set) and the --env K=V parser.
+import { describe, it, expect } from 'vitest';
+import { _validateName, _parseEnv, NAME_RE, RESERVED_NAMES } from './container.js';
+describe('_validateName — pure helper', () => {
+    it.each(['a', 'api-server', 'worker-2', '0', 'a'.repeat(50)])('accepts %s', (name) => {
+        expect(_validateName(name)).toBeNull();
+    });
+    it.each([
+        ['empty', ''],
+        ['UPPERCASE', 'BAD'],
+        ['underscore', 'my_app'],
+        ['leading hyphen', '-app'],
+        ['too long', 'a'.repeat(51)],
+        ['space', 'my app'],
+    ])('rejects %s', (_label, name) => {
+        expect(_validateName(name)).toMatch(/Invalid --name/);
+    });
+    it.each([...RESERVED_NAMES])('rejects reserved name %s', (name) => {
+        expect(_validateName(name)).toMatch(/is reserved/);
+    });
+    it('matches the backend regex exactly', () => {
+        expect(NAME_RE.source).toBe('^[a-z0-9][a-z0-9-]{0,49}$');
+    });
+});
+describe('_parseEnv — pure helper', () => {
+    it('parses a single KEY=VALUE pair', () => {
+        expect(_parseEnv('FOO=bar')).toEqual({ FOO: 'bar' });
+    });
+    it('parses comma-separated pairs', () => {
+        expect(_parseEnv('FOO=bar,BAZ=qux')).toEqual({ FOO: 'bar', BAZ: 'qux' });
+    });
+    it('keeps = inside the value', () => {
+        expect(_parseEnv('URL=https://x?a=1')).toEqual({ URL: 'https://x?a=1' });
+    });
+    it('tolerates surrounding whitespace and empty segments', () => {
+        expect(_parseEnv(' FOO=bar , ')).toEqual({ FOO: 'bar' });
+    });
+    it.each([
+        ['no equals', 'FOObar'],
+        ['leading equals (empty key)', '=bar'],
+    ])('rejects %s', (_label, raw) => {
+        expect(_parseEnv(raw)).toMatch(/Invalid --env entry/);
+    });
+});

package/dist/commands/container.d.ts

@@ -0,0 +1,16 @@
+import type { FlagSchema } from '../flags.js';
+import { type Flags } from '../helpers.js';
+import type { Exposes } from '../exposes.js';
+export declare const EXPOSES: Exposes;
+export declare const SCHEMA: FlagSchema;
+export declare const NAME_RE: RegExp;
+export declare const RESERVED_NAMES: Set<string>;
+export declare function _validateName(name: string): string | null;
+export declare function _parseEnv(raw: string): Record<string, string> | string;
+export declare function create(flags: Flags): Promise<void>;
+export declare function list(flags: Flags): Promise<void>;
+export declare function get(id: string, flags: Flags): Promise<void>;
+export declare function del(id: string, flags: Flags): Promise<void>;
+export declare function deploy(id: string, image: string, flags: Flags): Promise<void>;
+export declare function logs(id: string, flags: Flags): Promise<void>;
+export declare function run(subcommand: string | undefined, args: string[], flags: Flags): Promise<void>;

package/dist/commands/container.js

@@ -0,0 +1,270 @@
+import { container as sdkContainer } from '@myapihq/sdk';
+import { requireConfig } from '../config.js';
+import { success, error, printTable, info, printJson, banner } from '../output.js';
+import { formatDate } from '../utils.js';
+import { requireOrg } from '../helpers.js';
+export const EXPOSES = [
+    'POST /container/orgs/{org_id}/containers',
+    'GET /container/orgs/{org_id}/containers',
+    'GET /container/orgs/{org_id}/containers/{id}',
+    'DELETE /container/orgs/{org_id}/containers/{id}',
+    'POST /container/orgs/{org_id}/containers/{id}/deploy',
+    'GET /container/orgs/{org_id}/containers/{id}/logs',
+];
+export const SCHEMA = {
+    name: 'string',
+    type: 'string',
+    cron: 'string',
+    cpu: 'string',
+    memory: 'string',
+    'min-instances': 'number',
+    'max-instances': 'number',
+    port: 'number',
+    env: 'string',
+    tail: 'number',
+};
+const CONTAINER_TYPES = ['service', 'worker', 'job'];
+// Mirrors validateName in myapi-hq/internal/routes/container/crud.go —
+// identical to functions. Client-side rejection so typos fail before the
+// network call; the backend runs the same regex as defence in depth.
+export const NAME_RE = /^[a-z0-9][a-z0-9-]{0,49}$/;
+export const RESERVED_NAMES = new Set(['www', 'api', 'admin', 'system', 'default']);
+// Returns an error message on failure, or null on success. Pure — no I/O,
+// no process.exit. Tests use this form; the caller wraps it in error().
+export function _validateName(name) {
+    if (!NAME_RE.test(name)) {
+        return `Invalid --name "${name}". Lowercase letters, digits, hyphens; 1-50 chars; starts with a letter or digit.`;
+    }
+    if (RESERVED_NAMES.has(name)) {
+        return `Name "${name}" is reserved. Pick a different one.`;
+    }
+    return null;
+}
+// Parses `--env K=V,K2=V2` into an object. Returns the map or an error
+// message string (pure form, for tests).
+export function _parseEnv(raw) {
+    const env = {};
+    for (const pair of raw.split(',').map(s => s.trim()).filter(Boolean)) {
+        const eq = pair.indexOf('=');
+        if (eq < 1) {
+            return `Invalid --env entry "${pair}". Use KEY=VALUE, comma-separated.`;
+        }
+        env[pair.slice(0, eq)] = pair.slice(eq + 1);
+    }
+    return env;
+}
+function summarizeContainer(c) {
+    return {
+        id: c.id,
+        name: c.name,
+        type: c.type,
+        status: c.status,
+        url: c.url || '(not deployed)',
+        updated_at: c.updated_at ? formatDate(c.updated_at) : '',
+    };
+}
+export async function create(flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi container create --name <name> [--type service|worker|job] [--org <id>]');
+    const name = flags.name;
+    if (!name) {
+        error('Missing --name.\nUsage: myapi container create --name <name> [--type service|worker|job] [--org <id>]\n\n→ Name is a kebab-case slug, 1-50 chars (e.g. "my-worker").');
+    }
+    const nameErr = _validateName(name);
+    if (nameErr)
+        error(nameErr);
+    const type = flags.type ?? 'service';
+    if (!CONTAINER_TYPES.includes(type)) {
+        error(`Invalid --type "${type}". Use one of: ${CONTAINER_TYPES.join(', ')}.`);
+    }
+    const cron = flags.cron;
+    if (cron && type !== 'job') {
+        error('--cron is only valid for --type job (services and workers are always-on).');
+    }
+    const payload = { name, type: type };
+    if (cron)
+        payload.cron_schedule = cron;
+    if (typeof flags.cpu === 'string')
+        payload.cpu = flags.cpu;
+    if (typeof flags.memory === 'string')
+        payload.memory = flags.memory;
+    if (typeof flags['min-instances'] === 'number')
+        payload.min_instances = flags['min-instances'];
+    if (typeof flags['max-instances'] === 'number')
+        payload.max_instances = flags['max-instances'];
+    if (typeof flags.port === 'number')
+        payload.port = flags.port;
+    if (typeof flags.env === 'string') {
+        const env = _parseEnv(flags.env);
+        if (typeof env === 'string')
+            error(env);
+        payload.env = env;
+    }
+    const result = await sdkContainer.createContainer(config.api_key, orgId, payload);
+    success(`Container created: ${result.container.id}`);
+    info(`Name:            ${result.container.name}`);
+    info(`Type:            ${result.container.type}${result.container.cron_schedule ? ` (${result.container.cron_schedule})` : ''}`);
+    info(`Resources:       ${result.container.cpu} CPU, ${result.container.memory}, instances ${result.container.min_instances}-${result.container.max_instances}`);
+    // The scoped key is returned ONCE — it's delivered to the running
+    // container as the MYAPI_KEY env var. Deploy rotates it.
+    info('');
+    info(`Scoped API key (returned once — save it if you need it):`);
+    info(`  ${result.scoped_api_key}`);
+    if (!result.container.url) {
+        info('');
+        banner(`Next: deploy an image with  myapi container deploy ${result.container.id} <image-ref>`);
+    }
+}
+export async function list(flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi container list [--org <id>]');
+    const containers = await sdkContainer.listContainers(config.api_key, orgId);
+    if (flags.json) {
+        printJson(containers);
+        return;
+    }
+    printTable(containers.map(summarizeContainer), {
+        flags,
+        empty: 'No containers yet. Create one with: myapi container create --name <name>',
+    });
+}
+export async function get(id, flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi container get <id> [--org <id>]');
+    if (!id)
+        error('Missing id.\nUsage: myapi container get <id>');
+    const c = await sdkContainer.getContainer(config.api_key, orgId, id);
+    if (flags.json) {
+        printJson(c);
+        return;
+    }
+    info(`ID:              ${c.id}`);
+    info(`Name:            ${c.name}`);
+    info(`Type:            ${c.type}${c.cron_schedule ? ` (${c.cron_schedule})` : ''}`);
+    info(`Status:          ${c.status}`);
+    info(`Resources:       ${c.cpu} CPU, ${c.memory}, instances ${c.min_instances}-${c.max_instances}`);
+    if (c.port)
+        info(`Port:            ${c.port}`);
+    info(`URL:             ${c.url || '(not deployed)'}`);
+    info(`Created:         ${c.created_at}`);
+    info(`Updated:         ${c.updated_at}`);
+}
+export async function del(id, flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi container delete <id> [--org <id>]');
+    if (!id)
+        error('Missing id.\nUsage: myapi container delete <id>');
+    await sdkContainer.deleteContainer(config.api_key, orgId, id);
+    success(`Deleted container ${id}`);
+}
+// deploy ships a pre-built image to Cloud Run. The scoped API key is
+// rotated on every deploy — the fresh value is shown once here.
+export async function deploy(id, image, flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi container deploy <id> <image-ref> [--org <id>]');
+    if (!id)
+        error('Missing id.\nUsage: myapi container deploy <id> <image-ref>');
+    if (!image)
+        error('Missing image ref.\nUsage: myapi container deploy <id> <image-ref>\n\n→ <image-ref> is a pre-built container image (e.g. a registry path).');
+    const result = await sdkContainer.deployContainer(config.api_key, orgId, id, image);
+    if (flags.json) {
+        printJson(result);
+        return;
+    }
+    success(`Deployed container ${id} (revision ${result.revision_id})`);
+    info(`Status:          ${result.status}`);
+    info(`URL:             ${result.url}`);
+    info('');
+    info(`Scoped API key was rotated. New value (returned once — save it if you need it):`);
+    info(`  ${result.scoped_api_key}`);
+}
+// logs prints the container's recent Cloud Run runtime logs, newest first.
+export async function logs(id, flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi container logs <id> [--tail <n>] [--org <id>]');
+    if (!id)
+        error('Missing id.\nUsage: myapi container logs <id> [--tail <n>]');
+    const tail = typeof flags.tail === 'number' ? flags.tail : undefined;
+    const entries = await sdkContainer.getContainerLogs(config.api_key, orgId, id, tail);
+    if (flags.json) {
+        printJson(entries);
+        return;
+    }
+    if (entries.length === 0) {
+        info('No logs — the container is not deployed yet, or has produced no output.');
+        return;
+    }
+    for (const e of entries) {
+        info(`${e.timestamp}  ${(e.severity || '').padEnd(8)} ${e.text}`);
+    }
+}
+// ── Dispatcher ───────────────────────────────────────────────────────────────
+const SUBCOMMAND_USAGE = {
+    'create': `myapi container create --name <name> [--type service|worker|job] [--cron <expr>]
+                       [--cpu <n>] [--memory <size>] [--min-instances <n>]
+                       [--max-instances <n>] [--port <n>] [--env K=V,...] [--org <id>]
+
+Persists a container record + issues a scoped API key. Deploy an image
+separately with "myapi container deploy".
+
+Types:
+  service   HTTP server (default) — scales to zero
+  worker    always-on background process (min 1 instance)
+  job       runs to completion — the only type that accepts --cron
+
+Examples:
+  myapi container create --name api --port 8080
+  myapi container create --name nightly --type job --cron "0 3 * * *"
+  myapi container create --name queue-worker --type worker --memory 1Gi`,
+    'deploy': `myapi container deploy <id> <image-ref> [--org <id>] [--json]
+
+Ships a pre-built container image to the runtime. The scoped API key is
+rotated on every deploy — the fresh value is printed once.
+
+Example:
+  myapi container deploy <id> registry.example.com/my-app:v2`,
+    'list': 'myapi container list [--org <id>] [--json]',
+    'get': 'myapi container get <id> [--org <id>] [--json]',
+    'logs': `myapi container logs <id> [--tail <n>] [--org <id>] [--json]
+
+Recent Cloud Run runtime logs, newest first. --tail caps the count
+(default 100, max 1000).`,
+    'delete': 'myapi container delete <id> [--org <id>]',
+};
+export async function run(subcommand, args, flags) {
+    if (!subcommand || (flags.help && !subcommand)) {
+        info(`Usage: myapi container <subcommand>
+
+Run containers — long-running services, background workers, and scheduled
+jobs. The heavier-duty sibling of edge functions (myapi fn), for native
+dependencies and long execution.
+
+Subcommands:
+  create               Register a container and get its scoped API key (returned once)
+  deploy <id> <image>  Ship a pre-built image and go live
+  list                 List containers in your org
+  get <id>             Inspect a container
+  logs <id>            Show recent runtime logs (--tail <n>)
+  delete <id>          Soft-delete and revoke its scoped API key
+
+All commands accept --org <id> (or set default: myapi config set-org <id>).`);
+        return;
+    }
+    if (flags.help) {
+        const usage = SUBCOMMAND_USAGE[subcommand];
+        if (usage)
+            info(`Usage: ${usage}`);
+        else
+            info(`Unknown subcommand: ${subcommand}. Run "myapi container --help" for the list.`);
+        return;
+    }
+    switch (subcommand) {
+        case 'create': return create(flags);
+        case 'deploy': return deploy(args[0], args[1], flags);
+        case 'list': return list(flags);
+        case 'get': return get(args[0], flags);
+        case 'logs': return logs(args[0], flags);
+        case 'delete': return del(args[0], flags);
+        default: error(`Unknown subcommand: ${subcommand}. Run "myapi container --help" for a list of valid subcommands.`);
+    }
+}

package/dist/commands/email/campaign.js

@@ -35,7 +35,22 @@ async function list(flags) {
     const config = requireConfig();
     const orgId = requireOrg(flags, config, 'myapi email campaign list [--org <id>]');
     const campaigns = await sdkEmail.listCampaigns(config.api_key, orgId);
-    printTable(campaigns, {
+    if (flags.json) {
+        printJson(campaigns);
+        return;
+    }
+    // Drops warmup_config — a nested object that renders as "[object Object]"
+    // in a table. The scalar fields below are what a listing needs; the full
+    // config is in `myapi email campaign get <id>` and `--json`.
+    printTable(campaigns.map(c => ({
+        id: c.id,
+        name: c.name,
+        status: c.status,
+        template_id: c.template_id,
+        from_address: c.from_address,
+        per_day_limit: c.per_day_limit,
+        created_at: c.created_at,
+    })), {
         flags,
         empty: 'No campaigns yet. Create one with: myapi email campaign create',
     });

package/dist/commands/email/message.js

@@ -9,6 +9,17 @@ export const EXPOSES = [
     'GET /email/outbox/{address}',
     'GET /email/message/{message_id}',
 ];
+// Table columns for a message listing. Drops `body` — the full message
+// content is large and belongs in `myapi email message get <id>`, not in a
+// list row. `--json` still returns the complete record.
+function summarizeMessage(m) {
+    return {
+        message_id: m.message_id,
+        from: m.from,
+        subject: m.subject,
+        received_at: m.received_at,
+    };
+}
 async function send(flags) {
     const config = requireConfig();
     if (!flags.from || !flags.to || !flags.subject) {
@@ -50,7 +61,11 @@ async function sent(flags) {
     const limit = flags.limit || 50;
     const offset = flags.offset || 0;
     const emails = await sdkEmail.getSentEmails(config.api_key, limit, offset);
-    printTable(emails, {
+    if (flags.json) {
+        printJson(emails);
+        return;
+    }
+    printTable(emails.map(summarizeMessage), {
         flags,
         empty: 'No sent emails yet.',
     });
@@ -60,7 +75,11 @@ async function inbox(address, flags) {
     if (!address)
         error('Missing required arguments.\nUsage: myapi email message inbox <address>');
     const messages = await sdkEmail.getInbox(config.api_key, address);
-    printTable(messages, {
+    if (flags.json) {
+        printJson(messages);
+        return;
+    }
+    printTable(messages.map(summarizeMessage), {
         flags,
         empty: `No messages in ${address}.`,
     });
@@ -70,7 +89,11 @@ async function outbox(address, flags) {
     if (!address)
         error('Missing required arguments.\nUsage: myapi email message outbox <address>');
     const messages = await sdkEmail.getOutbox(config.api_key, address);
-    printTable(messages, {
+    if (flags.json) {
+        printJson(messages);
+        return;
+    }
+    printTable(messages.map(summarizeMessage), {
         flags,
         empty: `No outbound messages from ${address}.`,
     });

package/dist/commands/email/template.js

@@ -44,7 +44,14 @@ async function list(flags) {
         printJson(templates);
         return;
     }
-    printTable(templates, {
+    // Drops preview_url (a long URL, available via `template get`) and
+    // created_at (updated_at is the field a listing cares about).
+    printTable(templates.map(t => ({
+        id: t.id,
+        name: t.name,
+        subject: t.subject,
+        updated_at: t.updated_at,
+    })), {
         flags,
         empty: 'No templates yet. Generate one with: myapi email template generate --prompt <p> --name <n>',
     });

package/dist/commands/pixel.js

@@ -75,7 +75,13 @@ export async function visits(flags) {
         printJson(res);
         return;
     }
-    printTable(res.visits);
+    // `type` is constant ('visit') across this list — omitted from the table.
+    printTable(res.visits.map(v => ({
+        pixel_id: v.pixel_id,
+        from_url: v.from_url,
+        to_url: v.to_url,
+        ts: v.ts,
+    })));
     info(`Total: ${res.total} | Showing: ${res.limit} | Offset: ${res.offset}`);
 }
 // Engagement events (open / click / page_visit / sent) — filterable by
@@ -106,7 +112,14 @@ export async function events(flags) {
         printJson(res);
         return;
     }
-    printTable(res.events);
+    // `type` is constant ('event') across this list — omitted from the table.
+    printTable(res.events.map(e => ({
+        pixel_id: e.pixel_id,
+        event_type: e.event_type,
+        url: e.url ?? '',
+        campaign_id: e.campaign_id ?? '',
+        ts: e.ts,
+    })));
     info(`Total: ${res.total} | Showing: ${res.limit} | Offset: ${res.offset}`);
 }
 // Geographic distribution sample of the org's pixel audience.

package/dist/commands/update.d.ts

@@ -1,7 +1,7 @@
 import type { Flags } from '../helpers.js';
 import type { Exposes } from '../exposes.js';
 export declare const EXPOSES: Exposes;
+export declare function cachedLatestVersion(): string | null;
 export declare function checkForUpdate(currentVersion: string): Promise<void>;
 export declare function update(flags?: Flags): Promise<void>;
-export declare function latestVersion(): Promise<string | null>;
 export declare function isNewer(latest: string, current: string): boolean;