@zeegme/cli 0.2.0 → 0.3.0

package/README.md

@@ -78,7 +78,13 @@ zeeg crm upsert people --match emails --data '{"firstName":"Sophie","emails":["s
 
 ## JSON output
 
-In a terminal the CLI prints tables. When its output goes to a pipe or a file, or with `--json`, it prints the API's JSON unchanged, so you can hand it to `jq` or an agent:
+In a terminal the CLI prints tables. When its output goes to a pipe or a file, or with `--json`, it prints JSON you can hand to `jq` or an agent. Every command answers in one of these shapes:
+
+- **Lists** print `{ "collection": [...], "pagination": {...} }`. `pagination` is `null` when the command has no pages, as for `notes list`.
+- **One record** prints `{ "resource": {...} }`. That covers `get` commands and the record a write command created or changed. `resource` is `null` when the API returns no record, as for `bookings cancel`.
+- **Login and logout** print their own small status objects.
+
+For example:
 
 ```sh
 zeeg bookings list --status confirmed | jq -r '.collection[].uuid'

package/dist/commands/agents.js

@@ -1,5 +1,5 @@
 import { unwrap } from '../api/client.js';
-import { asJson, pageFooter, positiveInt } from './util.js';
+import { asJson, positiveInt } from './util.js';
 export function registerAgents(program, context) {
     const agents = program.command('agents').description('AI phone agents and their calls');
     agents
@@ -10,13 +10,13 @@ export function registerAgents(program, context) {
         .action(async (options) => {
         const ctx = context();
         const data = asJson(await unwrap((await ctx.api()).GET('/agents', { params: { query: options } })));
-        ctx.print.list(data, (data.data?.agents ?? []), [
+        ctx.print.list((data.data?.agents ?? []), [
             { header: 'id', value: (row) => row.id },
             { header: 'title', value: (row) => row.title },
             { header: 'active', value: (row) => (row.active ? 'yes' : 'no') },
             { header: 'phone', value: (row) => row.phoneNumber },
             { header: 'calls', value: (row) => row.totalCalls },
-        ], pageFooter(data.data?.pagination));
+        ], data.data?.pagination);
     });
     agents
         .command('calls <agentUuid>')
@@ -31,14 +31,14 @@ export function registerAgents(program, context) {
         const data = asJson(await unwrap((await ctx.api()).GET('/agents/{agentUuid}/calls', {
             params: { path: { agentUuid }, query: options },
         })));
-        ctx.print.list(data, (data.data?.calls ?? []), [
+        ctx.print.list((data.data?.calls ?? []), [
             { header: 'id', value: (row) => row.id },
             { header: 'started', value: (row) => row.startedAt },
             { header: 'direction', value: (row) => row.direction },
             { header: 'status', value: (row) => row.status },
             { header: 'seconds', value: (row) => row.durationSeconds },
             { header: 'summary', value: (row) => row.callSummaryTitle },
-        ], pageFooter(data.data?.pagination));
+        ], data.data?.pagination);
     });
     agents
         .command('call <callId>')
@@ -48,6 +48,6 @@ export function registerAgents(program, context) {
         const data = asJson(await unwrap((await ctx.api()).GET('/agent-calls/{callId}', {
             params: { path: { callId } },
         })));
-        ctx.print.record(data, asJson(data.call));
+        ctx.print.record(data.call);
     });
 }

package/dist/commands/auth.js

@@ -55,6 +55,6 @@ export function registerAuth(program, context) {
         const ctx = context();
         const me = await unwrap((await ctx.api()).GET('/whoami'));
         const tokens = await (await ctx.store()).load();
-        ctx.print.record({ email: me.email, baseUrl: ctx.baseUrl, scopes: tokens?.scopes ?? [] }, { email: me.email, api: ctx.baseUrl, scopes: tokens?.scopes ?? [] });
+        ctx.print.record({ email: me.email, baseUrl: ctx.baseUrl, scopes: tokens?.scopes ?? [] });
     });
 }

package/dist/commands/bookings.js

@@ -1,6 +1,6 @@
 import { unwrap } from '../api/client.js';
 import { UsageError } from '../errors.js';
-import { asJson, clockTime, collect, isoDate, localTimeZone, pageFooter, positiveInt } from './util.js';
+import { asJson, clockTime, collect, isoDate, localTimeZone, positiveInt } from './util.js';
 const inviteeNames = (row) => (row.invitees ?? []).map((invitee) => invitee.fullName ?? invitee.email);
 export function registerBookings(program, context) {
     const bookings = program.command('bookings').description('Scheduled events (bookings)');
@@ -38,13 +38,13 @@ export function registerBookings(program, context) {
                 },
             },
         })));
-        ctx.print.list(data, (data.collection ?? []), [
+        ctx.print.list((data.collection ?? []), [
             { header: 'uuid', value: (row) => row.uuid },
             { header: 'start', value: (row) => row.startTime },
             { header: 'title', value: (row) => row.title },
             { header: 'status', value: (row) => row.status },
             { header: 'invitees', value: inviteeNames },
-        ], pageFooter(data.pagination));
+        ], data.pagination);
     });
     bookings
         .command('get <uuid>')
@@ -52,7 +52,7 @@ export function registerBookings(program, context) {
         .action(async (uuid) => {
         const ctx = context();
         const data = asJson(await unwrap((await ctx.api()).GET('/scheduled-events/{uuid}', { params: { path: { uuid } } })));
-        ctx.print.record(data, asJson(data.resource));
+        ctx.print.record(data.resource);
     });
     bookings
         .command('create <eventTypeUuid>')
@@ -87,7 +87,7 @@ export function registerBookings(program, context) {
                 locationKey: options.locationKey,
             },
         })));
-        ctx.print.message(data, `Booked: ${data.title ?? 'meeting'} at ${data.startTime ?? `${options.date} ${options.time}`} (${data.uuid}).`);
+        ctx.print.record(data, `Booked: ${data.title ?? 'meeting'} at ${data.startTime ?? `${options.date} ${options.time}`} (${data.uuid}).`);
     });
     bookings
         .command('cancel <uuid>')
@@ -97,11 +97,11 @@ export function registerBookings(program, context) {
         .action(async (uuid, options) => {
         const ctx = context();
         await ctx.confirm(`Cancel booking ${uuid}? The invitees are notified.`, options.yes);
-        const data = await unwrap((await ctx.api()).PUT('/scheduled-events/{uuid}/cancel', {
+        await unwrap((await ctx.api()).PUT('/scheduled-events/{uuid}/cancel', {
             params: { path: { uuid } },
             body: { cancellationReason: options.reason },
         }));
-        ctx.print.message(data, `Cancelled ${uuid}.`);
+        ctx.print.record(null, `Cancelled ${uuid}.`);
     });
     bookings
         .command('reschedule <uuid>')
@@ -119,7 +119,7 @@ export function registerBookings(program, context) {
             params: { path: { uuid } },
             body: { date: options.date, start: options.time, timeZone: options.tz, duration: options.duration, reason: options.reason },
         })));
-        ctx.print.message(data, `Rescheduled ${uuid} to ${options.date} ${options.time}.`);
+        ctx.print.record(data.resource, `Rescheduled ${uuid} to ${options.date} ${options.time}.`);
     });
     bookings
         .command('no-show <inviteeUuid>')
@@ -131,12 +131,12 @@ export function registerBookings(program, context) {
         const params = { params: { path: { uuid: inviteeUuid } } };
         if (options.undo) {
             const data = asJson(await unwrap((await ctx.api()).DELETE('/scheduled-invitees/{uuid}/no-show', params)));
-            ctx.print.message(data, `${inviteeUuid} is no longer marked as a no-show.`);
+            ctx.print.record(data.resource, `${inviteeUuid} is no longer marked as a no-show.`);
             return;
         }
         await ctx.confirm(`Mark invitee ${inviteeUuid} as a no-show? Your no-show workflows may email them.`, options.yes);
         const data = asJson(await unwrap((await ctx.api()).POST('/scheduled-invitees/{uuid}/no-show', params)));
-        ctx.print.message(data, `Marked ${inviteeUuid} as a no-show.`);
+        ctx.print.record(data.resource, `Marked ${inviteeUuid} as a no-show.`);
     });
     bookings
         .command('hand-over <uuid>')
@@ -156,6 +156,6 @@ export function registerBookings(program, context) {
                 fallbackToReschedule: options.fallbackToReschedule,
             },
         }));
-        ctx.print.message(data, `Handed over ${uuid}.`);
+        ctx.print.record(asJson(data).resource, `Handed over ${uuid}.`);
     });
 }

package/dist/commands/calls.js

@@ -27,7 +27,7 @@ export function registerCalls(program, context) {
                 scheduledTime: options.at,
             },
         })));
-        ctx.print.message(data, `Call ${options.at ? 'scheduled' : 'started'} (${asJson(data.element).status ?? 'queued'}).`);
+        ctx.print.record(data.element, `Call ${options.at ? 'scheduled' : 'started'} (${asJson(data.element).status ?? 'queued'}).`);
     });
 }
 /** The API takes the agent's extra context as one string, so a file is sent as its text. */

package/dist/commands/crm.js

@@ -1,6 +1,6 @@
 import { unwrap } from '../api/client.js';
 import { UsageError } from '../errors.js';
-import { asJson, jsonArgument, pageFooter, positiveInt } from './util.js';
+import { asJson, jsonArgument, positiveInt } from './util.js';
 /** `people` and `companies` have their own endpoints; anything else is a custom object slug. */
 async function list(api, object, query) {
     if (object === 'people') {
@@ -66,12 +66,12 @@ export function registerCrm(program, context) {
         }
         const ctx = context();
         const { data, rows } = await list(await ctx.api(), object, options);
-        ctx.print.list(data, rows, [
+        ctx.print.list(rows, [
             { header: 'id', value: (row) => row.id },
             { header: 'name', value: displayName },
             { header: 'email', value: (row) => row.emails ?? row.domain },
             { header: 'updated', value: (row) => row.updatedAt },
-        ], pageFooter(data.data?.pagination));
+        ], data.data?.pagination);
     });
     crm
         .command('get <object> <id>')
@@ -79,7 +79,7 @@ export function registerCrm(program, context) {
         .action(async (object, id) => {
         const ctx = context();
         const data = await get(await ctx.api(), object, id);
-        ctx.print.record(data, recordOf(data));
+        ctx.print.record(recordOf(data));
     });
     crm
         .command('upsert <object>')
@@ -91,6 +91,6 @@ export function registerCrm(program, context) {
         const ctx = context();
         const data = await upsert(await ctx.api(), object, options.match, body);
         const record = recordOf(data);
-        ctx.print.message(data, `Saved ${object} record ${record.id ?? ''}.`.replace(' .', '.'));
+        ctx.print.record(record, `Saved ${object} record ${record.id ?? ''}.`.replace(' .', '.'));
     });
 }

package/dist/commands/eventTypes.js

@@ -1,5 +1,6 @@
 import { unwrap } from '../api/client.js';
-import { addDays, asJson, isoDate, localTimeZone, pageFooter, positiveInt } from './util.js';
+import { renderTable } from '../output.js';
+import { addDays, asJson, isoDate, localTimeZone, positiveInt } from './util.js';
 export function registerEventTypes(program, context) {
     const eventTypes = program.command('event-types').description('Scheduling pages (event types)');
     eventTypes
@@ -14,13 +15,13 @@ export function registerEventTypes(program, context) {
         const data = asJson(await unwrap((await ctx.api()).GET('/event-types', {
             params: { query: { userSlug: options.userSlug, email: options.email, page: options.page, count: options.count } },
         })));
-        ctx.print.list(data, (data.collection ?? []), [
+        ctx.print.list((data.collection ?? []), [
             { header: 'uuid', value: (row) => row.uuid },
             { header: 'title', value: (row) => row.title },
             { header: 'minutes', value: (row) => row.duration },
             { header: 'active', value: (row) => (row.isActive ? 'yes' : 'no') },
             { header: 'url', value: (row) => row.schedulingUrl },
-        ], pageFooter(data.pagination));
+        ], data.pagination);
     });
     eventTypes
         .command('get <uuid>')
@@ -28,7 +29,7 @@ export function registerEventTypes(program, context) {
         .action(async (uuid) => {
         const ctx = context();
         const data = asJson(await unwrap((await ctx.api()).GET('/event-types/{uuid}', { params: { path: { uuid } } })));
-        ctx.print.record(data, asJson(data.resource));
+        ctx.print.record(data.resource);
     });
     program
         .command('availability <eventTypeUuid>')
@@ -47,10 +48,11 @@ export function registerEventTypes(program, context) {
                 query: { startDate: from, endDate: to, timeZone: options.tz ?? localTimeZone(), duration: options.duration },
             },
         })));
+        // One record, since the time zone and date range belong with the days; a terminal shows only the days with free times.
         const days = (data.availability ?? []).filter((day) => Array.isArray(day.slots) && day.slots.length > 0);
-        ctx.print.list(data, days, [
+        ctx.print.record(data, days.length === 0 ? 'Nothing found.' : renderTable(days, [
             { header: 'date', value: (day) => day.date },
             { header: `times (${data.timeZone ?? options.tz ?? localTimeZone()})`, full: true, value: (day) => day.slots.map((slot) => (typeof slot === 'string' ? slot : asJson(slot).time)).join(' ') },
-        ]);
+        ]));
     });
 }

package/dist/commands/forms.js

@@ -1,5 +1,5 @@
 import { unwrap } from '../api/client.js';
-import { asJson, pageFooter, positiveInt } from './util.js';
+import { asJson, positiveInt } from './util.js';
 export function registerForms(program, context) {
     const forms = program.command('forms').description('Routing forms');
     forms
@@ -10,12 +10,12 @@ export function registerForms(program, context) {
         .action(async (options) => {
         const ctx = context();
         const data = asJson(await unwrap((await ctx.api()).GET('/routing-forms', { params: { query: options } })));
-        ctx.print.list(data, (data.data?.routingForms ?? []), [
+        ctx.print.list((data.data?.routingForms ?? []), [
             { header: 'id', value: (row) => row.id },
             { header: 'name', value: (row) => row.name },
             { header: 'active', value: (row) => (row.isActive ? 'yes' : 'no') },
             { header: 'updated', value: (row) => row.updatedAt },
-        ], pageFooter(data.data?.pagination));
+        ], data.data?.pagination);
     });
     forms
         .command('submissions')
@@ -39,11 +39,11 @@ export function registerForms(program, context) {
                 },
             },
         })));
-        ctx.print.list(data, (data.data?.submissions ?? []), [
+        ctx.print.list((data.data?.submissions ?? []), [
             { header: 'id', value: (row) => row.id },
             { header: 'created', value: (row) => row.createdAt },
             { header: 'form', value: (row) => row.routingForm?.name ?? row.routingFormId },
             { header: 'route', value: (row) => row.routeType ?? row.route?.type },
-        ], pageFooter(data.data?.pagination));
+        ], data.data?.pagination);
     });
 }

package/dist/commands/notes.js

@@ -8,7 +8,7 @@ export function registerNotes(program, context) {
         .action(async (uuid) => {
         const ctx = context();
         const data = asJson(await unwrap((await ctx.api()).GET('/notes/event/{uuid}', { params: { path: { uuid } } })));
-        ctx.print.list(data, (data.list ?? []), [
+        ctx.print.list((data.list ?? []), [
             { header: 'id', value: (row) => row.id },
             { header: 'created', value: (row) => row.createdAt },
             { header: 'by', value: (row) => row.creator?.fullName ?? row.creator?.email },
@@ -23,6 +23,6 @@ export function registerNotes(program, context) {
         const data = await unwrap((await ctx.api()).POST('/notes', {
             body: { relation: 'event', uuid, note: text.join(' ') },
         }));
-        ctx.print.message(data, `Note added to ${uuid}.`);
+        ctx.print.record(asJson(data).data, `Note added to ${uuid}.`);
     });
 }

package/dist/commands/schedules.js

@@ -1,6 +1,6 @@
 import { unwrap } from '../api/client.js';
 import { UsageError } from '../errors.js';
-import { asJson, collect, isoDate, pageFooter, positiveInt } from './util.js';
+import { asJson, collect, isoDate, positiveInt } from './util.js';
 async function ownEmail(api) {
     return (await unwrap(api.GET('/whoami'))).email;
 }
@@ -18,12 +18,12 @@ export function registerSchedules(program, context) {
         const data = asJson(await unwrap(api.GET('/schedules', {
             params: { query: { email: options.email ?? await ownEmail(api), page: options.page, count: options.count } },
         })));
-        ctx.print.list(data, (data.collection ?? []), [
+        ctx.print.list((data.collection ?? []), [
             { header: 'uuid', value: (row) => row.uuid },
             { header: 'title', value: (row) => row.title },
             { header: 'time zone', value: (row) => row.timezone },
             { header: 'default', value: (row) => (row.isDefault ? 'yes' : 'no') },
-        ], pageFooter(data.pagination));
+        ], data.pagination);
     });
     const timeOff = program.command('time-off').description('Time off (vacation, out of office)');
     timeOff
@@ -51,6 +51,6 @@ export function registerSchedules(program, context) {
                 note: options.note,
             },
         }));
-        ctx.print.message(data, `Time off added from ${options.start} to ${options.end}.`);
+        ctx.print.record(data, `Time off added from ${options.start} to ${options.end}.`);
     });
 }

package/dist/commands/util.js

@@ -55,14 +55,3 @@ export function addDays(date, days) {
     copy.setUTCDate(copy.getUTCDate() + days);
     return copy.toISOString().slice(0, 10);
 }
-/** "Page 2 of 5 (93 in total)" from either pagination shape the v2 API uses. */
-export function pageFooter(pagination) {
-    const p = asJson(pagination);
-    const current = p.currentPage;
-    const last = p.totalPages ?? p.lastPage;
-    const total = p.total ?? p.totalItems;
-    if (current === undefined || last === undefined) {
-        return undefined;
-    }
-    return `Page ${current} of ${last}${total !== undefined ? ` (${total} in total)` : ''}. Use --page to see more.`;
-}

package/dist/config.js

@@ -1,9 +1,6 @@
 import { UsageError } from './errors.js';
 export const DEFAULT_BASE_URL = 'https://api.zeeg.me';
-/**
- * The CLI's OAuth client. The backend inserts it with this id in every environment
- * (config('mcp.cli.client_id')), so one build reaches local, staging and production.
- */
+/** The CLI's public OAuth client, which has the same id on every Zeeg server it can sign in to. */
 export const DEFAULT_CLIENT_ID = '1000001';
 /** The v2 scopes the commands need. The server narrows them to what the plan allows. */
 export const SCOPES = [

package/dist/errors.js

@@ -43,15 +43,19 @@ export function exitCodeFor(error) {
     return ExitCode.Usage;
 }
 /**
- * The v2 API answers errors as `{ message, errors? }`; validation errors list messages per
- * field. A 401 means the token was revoked or expired server-side, so it asks for a new login.
+ * The API answers errors in two shapes: controllers and validation send `{ message, errors? }`,
+ * with validation messages listed per field, and the shared exception handler sends
+ * `{ error: { type, message } }` for not found, forbidden and similar. A 401 means the token was
+ * revoked or expired server-side, so it asks for a new login.
  */
 export function apiErrorFrom(status, body) {
     if (status === 401) {
         return new AuthError('Your Zeeg session is no longer valid. Run `zeeg login` to sign in again.');
     }
     const record = typeof body === 'object' && body !== null ? body : {};
-    const message = typeof record.message === 'string' && record.message !== '' ? record.message : `The Zeeg API answered HTTP ${status}.`;
+    const nested = typeof record.error === 'object' && record.error !== null ? record.error : {};
+    const text = [record.message, nested.message].find((value) => typeof value === 'string' && value !== '');
+    const message = text ?? `The Zeeg API answered HTTP ${status}.`;
     const details = record.errors && typeof record.errors === 'object'
         ? Object.values(record.errors).flat().filter((item) => typeof item === 'string')
         : [];

package/dist/output.js

@@ -38,23 +38,36 @@ export function renderRecord(record) {
     const width = Math.max(0, ...lines.map(([key]) => key.length));
     return lines.map(([key, value]) => `${key.padEnd(width)}  ${value}`).join('\n');
 }
+/** "Page 2 of 5 (93 in total)" from either pagination shape the API uses. */
+export function pageFooter(pagination) {
+    const p = pagination !== null && typeof pagination === 'object' ? pagination : {};
+    const current = p.currentPage;
+    const last = p.totalPages ?? p.lastPage;
+    const total = p.total ?? p.totalItems;
+    if (current === undefined || last === undefined) {
+        return undefined;
+    }
+    return `Page ${String(current)} of ${String(last)}${total !== undefined ? ` (${String(total)} in total)` : ''}. Use --page to see more.`;
+}
 export function createPrinter(mode, write = (text) => process.stdout.write(text)) {
     const json = (data) => write(`${JSON.stringify(data ?? null, null, 2)}\n`);
     return {
-        list(data, rows, columns, footer) {
+        list(rows, columns, pagination) {
             if (mode === 'json') {
-                return json(data);
+                return json({ collection: rows, pagination: pagination ?? null });
             }
             write(rows.length === 0 ? 'Nothing found.\n' : `${renderTable(rows, columns)}\n`);
+            const footer = pageFooter(pagination);
             if (footer) {
                 write(`${footer}\n`);
             }
         },
-        record(data, record) {
+        record(resource, text) {
             if (mode === 'json') {
-                return json(data);
+                return json({ resource: resource ?? null });
             }
-            write(`${renderRecord(record)}\n`);
+            const record = resource !== null && typeof resource === 'object' ? resource : {};
+            write(`${text ?? renderRecord(record)}\n`);
         },
         message(data, text) {
             if (mode === 'json') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeegme/cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "The Zeeg command line: bookings, availability, notes, CRM, routing forms and AI phone calls from your terminal.",
   "license": "MIT",
   "type": "module",
@@ -17,7 +17,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
     "prepublishOnly": "npm run build",
     "check-types": "tsc --noEmit",
     "generate:api": "openapi-typescript ../../apps/backend/tools/api-docs/openapi.yaml -o src/api/schema.d.ts",