@myapihq/cli 2.6.1 → 2.7.0

package/dist/commands/container-deploy-safety.test.d.ts

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

package/dist/commands/container-deploy-safety.test.js

@@ -0,0 +1,60 @@
+// The deploy-safety surface: --smoke parsing, and the rules around
+// --no-promote.
+//
+// Context: a user shipped a build whose frontend was a placeholder. It bound
+// its port and answered every request with 200, so the platform called the
+// deploy healthy and sent it 100% of traffic. Fifteen minutes of dead
+// production followed, with no way back.
+//
+// The one assertion that would have caught it is content, not status —
+// "returns 200" was true of the broken build. That is why a smoke check with
+// no `contains` and no `status` is refused rather than accepted as a no-op.
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { _parseSmoke } from './container.js';
+import * as output from '../output.js';
+let errSpy;
+beforeEach(() => {
+    errSpy = vi.spyOn(output, 'error').mockImplementation(((m) => { throw new Error(m); }));
+});
+afterEach(() => errSpy.mockRestore());
+describe('_parseSmoke', () => {
+    it('parses the shape the reporting user proposed', () => {
+        expect(_parseSmoke('GET / contains assets/')).toEqual({
+            method: 'GET', path: '/', contains: 'assets/',
+        });
+    });
+    it('parses a status assertion', () => {
+        expect(_parseSmoke('GET /livez status 200')).toEqual({
+            method: 'GET', path: '/livez', status: 200,
+        });
+    });
+    it('parses both assertions together', () => {
+        const s = _parseSmoke('HEAD /health status 204 contains ok');
+        expect(s).toEqual({ method: 'HEAD', path: '/health', status: 204, contains: 'ok' });
+    });
+    it('defaults method and path when only an assertion is given', () => {
+        expect(_parseSmoke('contains assets/')).toEqual({ contains: 'assets/' });
+    });
+    it('strips quotes around the contains value', () => {
+        expect(_parseSmoke("GET / contains 'assets/'").contains).toBe('assets/');
+        expect(_parseSmoke('GET / contains "assets/"').contains).toBe('assets/');
+    });
+    it('keeps spaces inside the contains value', () => {
+        expect(_parseSmoke('GET / contains <div id="app">').contains).toBe('<div id="app">');
+    });
+    // The whole point. A check that asserts nothing passes on the placeholder
+    // page it exists to catch, which is worse than no check because it reads as
+    // verification.
+    it('REFUSES a check that asserts nothing', () => {
+        expect(() => _parseSmoke('GET /')).toThrow(/asserts nothing/);
+        expect(() => _parseSmoke('/')).toThrow(/asserts nothing/);
+        expect(() => _parseSmoke('')).toThrow(/asserts nothing/);
+    });
+    it('explains why, rather than just rejecting', () => {
+        expect(() => _parseSmoke('GET /')).toThrow(/placeholder/);
+    });
+    it('is case-insensitive on the keywords', () => {
+        const s = _parseSmoke('get / CONTAINS assets/');
+        expect(s.contains).toBe('assets/');
+    });
+});

package/dist/commands/container.d.ts

@@ -1,3 +1,4 @@
+import { container as sdkContainer } from '@myapihq/sdk';
 import type { FlagSchema } from '../flags.js';
 import { type Flags } from '../helpers.js';
 import type { Exposes } from '../exposes.js';
@@ -13,6 +14,9 @@ export declare function get(id: string, flags: Flags): Promise<void>;
 export declare function del(id: string, flags: Flags): Promise<void>;
 export declare function _isTarball(p: string): boolean;
 export declare function deploy(id: string, image: string, flags: Flags): Promise<void>;
+export declare function _parseSmoke(raw: string): sdkContainer.SmokeCheck;
+export declare function revisions(id: string, flags: Flags): Promise<void>;
+export declare function promote(id: string, revision: string | undefined, flags: Flags): Promise<void>;
 export declare function logs(id: string, flags: Flags): Promise<void>;
 export declare function domain(id: string, domainArg: string | undefined, flags: Flags): Promise<void>;
 export declare function buildLogs(id: string | undefined, flags: Flags): Promise<void>;

package/dist/commands/container.js

@@ -13,6 +13,8 @@ export const EXPOSES = [
     'DELETE /container/orgs/{org_id}/containers/{id}',
     'POST /container/orgs/{org_id}/containers/{id}/deploy',
     'GET /container/orgs/{org_id}/containers/{id}/logs',
+    'GET /container/orgs/{org_id}/containers/{id}/revisions',
+    'POST /container/orgs/{org_id}/containers/{id}/promote',
     'POST /container/orgs/{org_id}/containers/{id}/domain',
     'DELETE /container/orgs/{org_id}/containers/{id}/domain',
 ];
@@ -28,6 +30,9 @@ export const SCHEMA = {
     env: 'string',
     tail: 'number',
     scope: 'string',
+    'no-promote': 'boolean',
+    'health-check': 'string',
+    smoke: 'string',
     remove: 'boolean',
     source: 'string',
     image: 'string',
@@ -106,6 +111,17 @@ export async function create(nameArg, flags) {
         payload.max_instances = flags['max-instances'];
     if (typeof flags.port === 'number')
         payload.port = flags.port;
+    if (typeof flags['health-check'] === 'string') {
+        const hc = flags['health-check'];
+        // The API refuses /healthz, but say so here rather than round-tripping:
+        // the reason is specific and worth stating where the user typed it.
+        if (/^\/?healthz\/?$/i.test(hc)) {
+            error('The runtime intercepts /healthz, so a probe against it never reaches your container —\nit would report healthy no matter what your code does. Use /livez, or any other path.');
+        }
+        if (!hc.startsWith('/'))
+            error(`--health-check must be a path starting with "/" — got "${hc}".`);
+        payload.health_check = hc;
+    }
     if (typeof flags.env === 'string') {
         const env = _parseEnv(flags.env);
         if (typeof env === 'string')
@@ -198,7 +214,7 @@ async function tarDirectory(dir) {
     return res.stdout;
 }
 // deploy ships either a pre-built image (--image / positional ref, synchronous)
-// or a source build context (--source <dir-or-tar>, asynchronous Cloud Build).
+// or a source build context (--source <dir-or-tar>, built server-side, async).
 // The scoped API key is rotated on every (image) deploy and shown once.
 export async function deploy(id, image, flags) {
     const config = requireConfig();
@@ -242,7 +258,7 @@ export async function deploy(id, image, flags) {
         }
         // Async: poll the container until it leaves the building state.
         if (start.status === 'building') {
-            info(`Build started (revision ${start.revision_id}). Building from source via Cloud Build…`);
+            info(`Build started (revision ${start.revision_id}). Building from source — typically ~4 minutes…`);
             const final = await pollJob({
                 label: 'Building & deploying',
                 check: () => sdkContainer.getContainer(config.api_key, orgId, id),
@@ -274,11 +290,30 @@ export async function deploy(id, image, flags) {
     // ── Pre-built image path (sync) ─────────────────────────────────────────
     if (!image)
         error('Missing image ref.\nUsage: myapi container deploy <id> <image-ref>\n   or: myapi container deploy <id> --source <dir|tar>\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);
+    const opts = {};
+    if (flags['no-promote'] === true)
+        opts.promote = false;
+    if (typeof flags.smoke === 'string')
+        opts.smoke = _parseSmoke(flags.smoke);
+    if (opts.promote === false && opts.smoke) {
+        error('--smoke already withholds traffic until the check passes, then promotes.\nUse one or the other: --smoke to verify-and-promote, --no-promote to hold the revision back.');
+    }
+    const result = await sdkContainer.deployContainer(config.api_key, orgId, id, image, opts);
     if (flags.json) {
         printJson(result);
         return;
     }
+    // An unpromoted revision must NOT read like a completed deploy. A response
+    // that looked the same either way is how an agent concludes it has shipped
+    // when it has not — the original outage in miniature.
+    if (result.promoted === false) {
+        success(`Revision ${result.revision_id} built — NOT serving traffic`);
+        info(`Test it:         ${result.revision_url ?? '(no revision URL returned)'}`);
+        info(`Still live:      ${result.url || '(previous revision)'}`);
+        info('');
+        banner(`When it looks right:  myapi container promote ${id} ${result.revision_id}`);
+        return;
+    }
     success(`Deployed container ${id} (revision ${result.revision_id})`);
     info(`Status:          ${result.status}`);
     info(`URL:             ${result.url}`);
@@ -286,6 +321,113 @@ export async function deploy(id, image, flags) {
     info(`Scoped API key was rotated. New value (returned once — save it if you need it):`);
     info(`  ${result.scoped_api_key}`);
 }
+// Parses `--smoke 'GET / contains assets/'` into the API's structured check.
+//
+// The shape is the one the reporting user proposed, because it reads like a
+// sentence under incident pressure. Grammar:
+//
+//   [METHOD] [PATH] [status N] [contains TEXT]
+//
+// Everything is optional except that something must be asserted — a smoke
+// check that asserts nothing would pass on the broken build it exists to
+// catch. Returns the object or calls error().
+export function _parseSmoke(raw) {
+    const out = {};
+    let rest = raw.trim();
+    const m = /^(GET|HEAD)\s+/i.exec(rest);
+    if (m) {
+        out.method = m[1].toUpperCase();
+        rest = rest.slice(m[0].length);
+    }
+    const p = /^(\/\S*)\s*/.exec(rest);
+    if (p) {
+        out.path = p[1];
+        rest = rest.slice(p[0].length);
+    }
+    const st = /\bstatus\s+(\d{3})\b/i.exec(rest);
+    if (st) {
+        out.status = Number(st[1]);
+        rest = rest.replace(st[0], ' ');
+    }
+    const c = /\bcontains\s+(.+)$/i.exec(rest.trim());
+    if (c)
+        out.contains = c[1].trim().replace(/^['"]|['"]$/g, '');
+    if (out.status === undefined && out.contains === undefined) {
+        error(`--smoke "${raw}" asserts nothing.\n\n` +
+            'Add `contains <text>` or `status <code>`. A check that only requests a path\n' +
+            'passes on any response, including the placeholder page this flag exists to catch.\n\n' +
+            "Example: --smoke 'GET / contains assets/'");
+    }
+    return out;
+}
+// revisions lists what the runtime actually has, newest first.
+export async function revisions(id, flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi container revisions <id> [--org <id>]');
+    if (!id)
+        error('Missing id.\nUsage: myapi container revisions <id>');
+    const [revs, container] = await Promise.all([
+        sdkContainer.listRevisions(config.api_key, orgId, id),
+        sdkContainer.getContainer(config.api_key, orgId, id).catch(() => undefined),
+    ]);
+    if (flags.json) {
+        printJson(revs);
+        return;
+    }
+    printTable(revs.map(r => ({
+        revision: r.revision,
+        ready: r.ready ? '✓' : '',
+        traffic: `${r.traffic_percent}%`,
+        serving: r.serving ? '✓' : '',
+        created: r.created_at ? formatDate(r.created_at) : '',
+    })), { flags, empty: 'No revisions — this container has never been deployed.' });
+    // Verified 2026-07-28 across every service container in two orgs: the API
+    // reports 0% traffic on every revision while the containers demonstrably
+    // serve. The backend's own note explains it — Traffic was never set on the
+    // service, so the runtime applies an implicit "latest takes 100%" that this
+    // endpoint cannot see. Containers deployed before that fix are all in this
+    // state.
+    //
+    // Say so rather than render a table that reads as "nothing is live".
+    if (revs.length > 0 && revs.every(r => !r.serving && !r.traffic_percent) && container?.status === 'active') {
+        info('');
+        info('Note: every revision reports 0% traffic while this container is active and serving.');
+        info('That is a known reporting bug for containers deployed before 2026-07-28, not an outage.');
+        info('Rollback depends on this data, so it is unreliable here until the container is redeployed.');
+    }
+}
+// promote moves all traffic to one revision. Omitting the revision rolls back
+// to the previous ready one — the API models promote and rollback as a single
+// operation with a different target.
+export async function promote(id, revision, flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi container promote <id> <revision> [--org <id>]');
+    if (!id)
+        error('Missing id.\nUsage: myapi container promote <id> <revision>');
+    if (!revision) {
+        error('Missing revision.\nUsage: myapi container promote <id> <revision>\n\n' +
+            'List them with: myapi container revisions ' + id);
+    }
+    const res = await sdkContainer.promoteRevision(config.api_key, orgId, id, revision);
+    if (flags.json) {
+        printJson(res);
+        return;
+    }
+    success(`Traffic moved to ${revision}`);
+    if (res.message)
+        info(res.message);
+}
+// Not a command — guidance for a word that is not one. See the dispatch note.
+function rollbackGuidance(id) {
+    const ref = id || '<id>';
+    error('There is no `rollback` subcommand — rolling back is promoting an older revision.\n\n' +
+        `  myapi container revisions ${ref}          # find the last good revision\n` +
+        `  myapi container promote ${ref} <revision> # traffic moves in seconds\n\n` +
+        'Heads up: the platform currently reports 0% traffic on every revision of any\n' +
+        'container deployed before 2026-07-28, and its own roll-back-to-previous path\n' +
+        'returns a gateway error. Promoting a revision BY NAME works and is unaffected —\n' +
+        'use that. Reported upstream.');
+}
 // logs prints the container's recent runtime logs, newest first. By default
 // this is the container's own stdout/stderr; --scope all adds the platform
 // audit records that share the stream.
@@ -389,13 +531,38 @@ Two ways to deploy:
   image    Ship a pre-built image (positional ref or --image). Synchronous;
            the scoped API key is rotated and printed once.
   source   Upload a build context with --source <dir> (tarred locally) or a
-           pre-built --source <archive.tar.gz>. MyAPI builds it via Cloud
-           Build, then deploys. Asynchronous — the CLI polls until it's live.
+           pre-built --source <archive.tar.gz>. The context is
+           built server-side (typically ~4 minutes), then deployed.
+           Asynchronous — the CLI polls until it's live.
+
+Options:
+  --no-promote          Build the revision without giving it traffic. Test it at
+                        the returned URL, then: myapi container promote <id> <rev>
+  --smoke '<assertion>' Deploy, assert against the new revision, and promote it
+                        ONLY if the assertion holds. A failure leaves the
+                        previous revision serving.
+
+                        Grammar: [GET|HEAD] [/path] [status N] [contains TEXT]
+                        Assert on content, not just status — "returns 200" is
+                        true of a placeholder page too.
 
 Examples:
   myapi container deploy <id> registry.example.com/my-app:v2
   myapi container deploy <id> --source ./my-app
-  myapi container deploy <id> --source ./context.tar.gz`,
+  myapi container deploy <id> --source ./context.tar.gz
+  myapi container deploy <id> <image> --no-promote
+  myapi container deploy <id> <image> --smoke 'GET / contains assets/'`,
+    'revisions': `myapi container revisions <id> [--org <id>] [--json]
+
+Every revision the runtime currently holds, newest first, with the traffic
+each takes. Read from the runtime rather than our records, so a revision
+missing here genuinely no longer exists and cannot be promoted.`,
+    'promote': `myapi container promote <id> <revision> [--org <id>] [--json]
+
+Move all traffic to one revision. A traffic shift only — no build, no new
+revision — so it completes in seconds.
+
+List candidates with: myapi container revisions <id>`,
     'list': 'myapi container list [--org <id>] [--json]',
     'get': 'myapi container get <id> [--org <id>] [--json]',
     'logs': `myapi container logs <id> [--tail <n>] [--scope all] [--org <id>] [--json]
@@ -409,9 +576,9 @@ same stream and share the --tail budget, so raise --tail when you use it.`,
     'domain': `myapi container domain <id> <domain> [--org <id>] [--json]
        myapi container domain <id> --remove [--org <id>]
 
-Binds a custom domain to a deployed container, served over HTTPS via
-Cloudflare. The domain's MyAPI-managed parent domain must already be
-registered. --remove unbinds it.
+Binds a custom domain to a deployed container, served over HTTPS. The
+domain's MyAPI-managed parent domain must already be registered.
+--remove unbinds it.
 
 Example:
   myapi container domain <id> app.synthesisdaily.com`,
@@ -428,12 +595,16 @@ dependencies and long execution.
 Subcommands:
   build-logs <id>      Why the last --source build failed (--tail N; default 100)
   create               Register a container and get its scoped API key (returned once)
+                       (--health-check /livez to probe with HTTP, not a bare TCP connect)
   delete <id>          Soft-delete and revoke its scoped API key
   deploy <id> <image>  Ship a pre-built image (or --source <dir|tar> to build) and go live
+                       (--no-promote to hold it back; --smoke to verify before promoting)
   domain <id> <domain> Bind a custom domain (--remove to unbind)
   get <id>             Inspect a container
   list                 List containers in your org
   logs <id>            Show recent runtime logs (--tail <n>, --scope all) — see build-logs for build failures
+  promote <id> <rev>   Move all traffic to a revision (seconds, no rebuild)
+  revisions <id>       List revisions and the traffic each takes
 
 All commands accept --org <id> (or set default: myapi config set-org <id>).`);
         return;
@@ -453,8 +624,16 @@ All commands accept --org <id> (or set default: myapi config set-org <id>).`);
         case 'list': return list(flags);
         case 'get': return get(args[0], flags);
         case 'logs': return logs(args[0], flags);
+        case 'revisions': return revisions(args[0], flags);
+        case 'promote': return promote(args[0], args[1], flags);
         case 'domain': return domain(args[0], args[1], flags);
         case 'delete': return del(args[0], flags);
+        // `rollback` is the word people reach for during an incident, and it is
+        // NOT a verb here — the API models rollback as `promote` with no revision.
+        // A bare "unknown subcommand" would cost minutes at the worst possible
+        // moment, so say what to do instead, and be honest that the underlying
+        // call is currently broken rather than let someone discover that live.
+        case 'rollback': return rollbackGuidance(args[0]);
         default: error(`Unknown subcommand: ${subcommand}. Run "myapi container --help" for a list of valid subcommands.`);
     }
 }

package/dist/commands/crm/companies.js

@@ -3,7 +3,7 @@ import { crm } from '@myapihq/sdk';
 import { requireConfig } from '../../config.js';
 import { success, error, info, printTable, printJson } from '../../output.js';
 import { requireOrg, requireArg } from '../../helpers.js';
-import { rejectOffset, warnIfTruncated, countLine } from './pagination.js';
+import { pageLine } from './pagination.js';
 export const EXPOSES = [
     'POST /crm/orgs/{org_id}/companies',
     'POST /crm/orgs/{org_id}/companies/promote',
@@ -36,6 +36,7 @@ function buildSearchFilter(flags) {
         domain: typeof flags.domain === 'string' ? flags.domain : undefined,
         include_deleted: flags['include-deleted'] === true || undefined,
         limit: typeof flags.limit === 'number' ? flags.limit : undefined,
+        offset: typeof flags.offset === 'number' ? flags.offset : undefined,
     };
 }
 function renderCompanies(res, flags) {
@@ -43,8 +44,7 @@ function renderCompanies(res, flags) {
         printJson(res);
         return;
     }
-    // NOT `N of res.total` — total is the page size, not the match count.
-    info(countLine(res.companies.length, 'company', 'companies'));
+    info(pageLine(res.companies.length, res.total, res.has_more, 'company', 'companies'));
     printTable(res.companies.map(c => ({
         id: c.id,
         domain: c.domain ?? '',
@@ -58,22 +58,17 @@ function renderCompanies(res, flags) {
 async function search(flags) {
     const config = requireConfig();
     const orgId = requireOrg(flags, config, 'myapi crm companies search [filters...] [--org <id>]');
-    rejectOffset(flags, 'myapi crm companies search [filters...] [--limit N] [--org <id>]');
     const res = await crm.searchCompanies(config.api_key, orgId, buildSearchFilter(flags));
     renderCompanies(res, flags);
-    if (!flags.json)
-        warnIfTruncated(res.companies.length, flags);
 }
 async function list(flags) {
     const config = requireConfig();
     const orgId = requireOrg(flags, config, 'myapi crm companies list [--limit N] [--org <id>]');
-    rejectOffset(flags, 'myapi crm companies list [--limit N] [--org <id>]');
     const res = await crm.searchCompanies(config.api_key, orgId, {
         limit: typeof flags.limit === 'number' ? flags.limit : undefined,
+        offset: typeof flags.offset === 'number' ? flags.offset : undefined,
     });
     renderCompanies(res, flags);
-    if (!flags.json)
-        warnIfTruncated(res.companies.length, flags);
 }
 async function create(domainArg, flags) {
     const config = requireConfig();
@@ -148,9 +143,9 @@ async function promote(domain, flags) {
 }
 // ── Dispatcher ──────────────────────────────────────────────────────────
 const SUBCOMMAND_USAGE = {
-    list: 'myapi crm companies list [--limit N] [--org <id>] [--json]',
+    list: 'myapi crm companies list [--limit N] [--offset N] [--org <id>] [--json]',
     search: `myapi crm companies search [--stage <csv>] [--source <csv>] [--domain <d>]
-       [--include-deleted] [--limit N] [--org <id>] [--json]
+       [--include-deleted] [--limit N] [--offset N] [--org <id>] [--json]
 
   --stage   cold, warm, qualified, customer, churned
   --source  goldfox, email, pixel, webhook, manual`,

package/dist/commands/crm/contacts.js

@@ -3,7 +3,7 @@ import { crm } from '@myapihq/sdk';
 import { requireConfig } from '../../config.js';
 import { success, error, info, printTable, printJson } from '../../output.js';
 import { requireOrg, requireArg } from '../../helpers.js';
-import { rejectOffset, warnIfTruncated, countLine } from './pagination.js';
+import { pageLine } from './pagination.js';
 export const EXPOSES = [
     'POST /crm/orgs/{org_id}/contacts',
     'POST /crm/orgs/{org_id}/contacts/promote',
@@ -42,6 +42,7 @@ function buildSearchFilter(flags) {
         max_last_engagement_days: typeof flags['max-last-engagement-days'] === 'number' ? flags['max-last-engagement-days'] : undefined,
         include_deleted: flags['include-deleted'] === true || undefined,
         limit: typeof flags.limit === 'number' ? flags.limit : undefined,
+        offset: typeof flags.offset === 'number' ? flags.offset : undefined,
     };
 }
 function renderContacts(res, flags) {
@@ -49,8 +50,7 @@ function renderContacts(res, flags) {
         printJson(res);
         return;
     }
-    // NOT `N of res.total` — total is the page size, not the match count.
-    info(countLine(res.contacts.length, 'contact', 'contacts'));
+    info(pageLine(res.contacts.length, res.total, res.has_more, 'contact', 'contacts'));
     printTable(res.contacts.map(c => ({
         id: c.id,
         email: c.email ?? '',
@@ -65,23 +65,18 @@ function renderContacts(res, flags) {
 async function search(flags) {
     const config = requireConfig();
     const orgId = requireOrg(flags, config, 'myapi crm contacts search [filters...] [--org <id>]');
-    rejectOffset(flags, 'myapi crm contacts search [filters...] [--limit N] [--org <id>]');
     const res = await crm.searchContacts(config.api_key, orgId, buildSearchFilter(flags));
     renderContacts(res, flags);
-    if (!flags.json)
-        warnIfTruncated(res.contacts.length, flags);
 }
 // `list` is `search` with no filters — separate verb for discoverability.
 async function list(flags) {
     const config = requireConfig();
     const orgId = requireOrg(flags, config, 'myapi crm contacts list [--limit N] [--org <id>]');
-    rejectOffset(flags, 'myapi crm contacts list [--limit N] [--org <id>]');
     const res = await crm.searchContacts(config.api_key, orgId, {
         limit: typeof flags.limit === 'number' ? flags.limit : undefined,
+        offset: typeof flags.offset === 'number' ? flags.offset : undefined,
     });
     renderContacts(res, flags);
-    if (!flags.json)
-        warnIfTruncated(res.contacts.length, flags);
 }
 async function create(emailArg, flags) {
     const config = requireConfig();
@@ -183,10 +178,10 @@ async function events(id, flags) {
 }
 // ── Dispatcher ──────────────────────────────────────────────────────────
 const SUBCOMMAND_USAGE = {
-    list: 'myapi crm contacts list [--limit N] [--org <id>] [--json]',
+    list: 'myapi crm contacts list [--limit N] [--offset N] [--org <id>] [--json]',
     search: `myapi crm contacts search [--stage <csv>] [--source <csv>] [--email <e>]
        [--company-id <id>] [--min-last-engagement-days N] [--max-last-engagement-days N]
-       [--include-deleted] [--limit N] [--org <id>] [--json]
+       [--include-deleted] [--limit N] [--offset N] [--org <id>] [--json]
 
   --stage     cold, warm, qualified, customer, churned
   --source    goldfox, email, pixel, webhook, manual

package/dist/commands/crm/pagination.d.ts

@@ -1,6 +1,3 @@
-import { type Flags } from '../../helpers.js';
 import type { Exposes } from '../../exposes.js';
 export declare const EXPOSES: Exposes;
-export declare function rejectOffset(flags: Flags, usage: string): void;
-export declare function warnIfTruncated(returned: number, flags: Flags): void;
-export declare function countLine(returned: number, singular: string, plural: string): string;
+export declare function pageLine(returned: number, total: number | undefined, hasMore: boolean | undefined, singular: string, plural: string): string;

package/dist/commands/crm/pagination.js

@@ -1,60 +1,32 @@
-// CRM search/list pagination — what the API actually does, verified against
-// production on 2026-07-27 (build c8b30009).
+// CRM search/list pagination.
 //
-// Two facts, both discovered by lint-request-fields.js flagging that the SDK
-// sends an `offset` the OpenAPI schema does not declare:
+// HISTORY, because it is short and the lesson outlived the bug. For one day
+// this file did the opposite of what it does now: it REFUSED `--offset`,
+// because the API accepted the parameter and silently ignored it, and `total`
+// was `len(rows)` rather than the match count. An agent asking for 100 of 500
+// contacts received 100 records and a `total` of 100 — a complete-looking
+// answer that was short by 400, with nothing in the response to say so.
 //
-//   1. `offset` is ACCEPTED AND IGNORED. Against an org with three contacts,
-//      {limit:1, offset:0}, {limit:1, offset:1} and {limit:1, offset:2} all
-//      return the same first contact. This holds for contacts and companies,
-//      on both the POST /search and GET /contacts paths. There is no cursor
-//      parameter either.
+// Fixed backend-side on 2026-07-28 and re-verified here against an org with
+// three contacts: offsets 0/1/2 at limit 1 return three different records,
+// `total` reads 3 throughout, and `has_more` goes true, true, false.
 //
-//   2. `total` is the SIZE OF THE PAGE, not the number of matches. With three
-//      contacts in the org: limit=1 → total=1, limit=2 → total=2, limit=3 →
-//      total=3, limit=10 → total=3.
-//
-// Together those make the result set silently lossy. An agent with 500
-// contacts running `--limit 100` receives 100 records and a `total` of 100,
-// and has no signal that 400 more exist. This is the worst shape a data bug
-// can take for an unattended caller: it looks like a complete answer.
-//
-// Filed upstream. Until it is fixed the CLI refuses `--offset` rather than
-// sending a parameter that does nothing, and never prints `total` as though
-// it were a match count.
-import { error, info } from '../../output.js';
+// So the guard is gone and this file is now just honest rendering. Prefer
+// `has_more` over arithmetic against `total`: it stays correct even if the
+// meaning of `total` moves again, which is exactly what went wrong before.
 // A helper, not a command: it calls nothing. Declared empty rather than
 // exempted, so the coverage gate's "every module states its surface" rule
 // stays absolute.
 export const EXPOSES = [];
-// Server-side default page size when no --limit is given. The API applies
-// this; we only need it to know whether a result may have been truncated.
-const DEFAULT_LIMIT = 50;
-// Rejects --offset outright. Silently dropping it would reproduce the bug we
-// are protecting against, and passing it through means duplicate pages.
-export function rejectOffset(flags, usage) {
-    if (flags.offset === undefined)
-        return;
-    error('The CRM API accepts --offset and ignores it, so every page would return the same records.\n' +
-        'Verified against production: with --limit 1, offsets 0, 1 and 2 all return the first match.\n\n' +
-        'There is no cursor parameter either, so the CRM has no working pagination today.\n' +
-        'Raise --limit to fetch more in one call, and narrow the result set with filters\n' +
-        '(--stage, --source, --company-id, --email) rather than paging through it.\n\n' +
-        `Usage: ${usage}`);
-}
-// A page that came back exactly full is indistinguishable from a truncated
-// one, and `total` cannot tell them apart. Say so, rather than letting the
-// caller assume the answer is complete.
-export function warnIfTruncated(returned, flags) {
-    const limit = typeof flags.limit === 'number' ? flags.limit : DEFAULT_LIMIT;
-    if (returned < limit)
-        return;
-    info(`Note: exactly ${returned} record${returned === 1 ? '' : 's'} came back, which is the page limit. ` +
-        'There may be more, and the API reports no match count and offers no way to fetch the next page. ' +
-        'Raise --limit or add filters.');
-}
-// The API returns `total`, but it equals the page size, so rendering "N of
-// total" states something false. Callers use this instead.
-export function countLine(returned, singular, plural) {
-    return `${returned} ${returned === 1 ? singular : plural}`;
+// "3 contacts" · "3 of 128 contacts" · "3 of 128 contacts (more available)".
+//
+// `total` is only rendered when the API supplied it, and the more-available
+// note comes from `has_more` rather than from comparing lengths — a comparison
+// is what silently agreed with a wrong `total` before.
+export function pageLine(returned, total, hasMore, singular, plural) {
+    const noun = returned === 1 ? singular : plural;
+    const head = (typeof total === 'number' && total !== returned)
+        ? `${returned} of ${total} ${total === 1 ? singular : plural}`
+        : `${returned} ${noun}`;
+    return hasMore ? `${head} (more available — raise --limit or pass --offset)` : head;
 }