@standchat/cli 0.0.0-stage → 0.1.1

package/dist/commands.js

@@ -0,0 +1,385 @@
+import { randomUUID } from 'node:crypto';
+import { CliError, isObject, usage } from './errors.js';
+import { BUNDLED_SCHEMA } from './contract.js';
+const COMMAND_DEFINITIONS = [
+    { "command": "org plan", "args": [], "description": "Read the current plan.", "scope": "org:read", "method": "GET", "path": "/v1/org/plan", "options": [], "confirmation": false, "bodyRequired": false },
+    { "command": "org usage", "args": [], "description": "Read current plan usage.", "scope": "org:read", "method": "GET", "path": "/v1/org/usage", "options": [], "confirmation": false, "bodyRequired": false },
+    { "command": "standins status", "args": [], "description": "Read the account-wide Stand-in switch.", "scope": "standins:read", "method": "GET", "path": "/v1/reps/me/standin/status", "options": [], "confirmation": false, "bodyRequired": false },
+    { "command": "knowledge list", "args": [], "description": "List knowledge bases and capabilities.", "scope": "knowledge:read", "method": "GET", "path": "/v1/knowledge-bases", "options": [], "confirmation": false, "bodyRequired": false },
+    { "command": "knowledge create", "args": [], "description": "Create a knowledge base.", "scope": "knowledge:write", "method": "POST", "path": "/v1/knowledge-bases", "options": ["body-file"], "confirmation": true, "bodyRequired": true },
+    { "command": "knowledge crawl", "args": ["knowledgeBaseId"], "description": "Crawl approved public website content.", "scope": "knowledge:write", "method": "POST", "path": "/v1/knowledge-bases/{knowledgeBaseId}/crawls", "options": ["body-file"], "confirmation": true, "bodyRequired": true },
+    { "command": "knowledge sources", "args": ["knowledgeBaseId"], "description": "Read knowledge sources.", "scope": "knowledge:read", "method": "GET", "path": "/v1/knowledge-bases/{knowledgeBaseId}/sources", "options": [], "confirmation": false, "bodyRequired": false },
+    { "command": "knowledge tasks", "args": ["knowledgeBaseId"], "description": "Read ingestion tasks.", "scope": "knowledge:read", "method": "GET", "path": "/v1/knowledge-bases/{knowledgeBaseId}/tasks", "options": [], "confirmation": false, "bodyRequired": false },
+    { "command": "knowledge documents", "args": ["knowledgeBaseId"], "description": "Read indexed documents.", "scope": "knowledge:read", "method": "GET", "path": "/v1/knowledge-bases/{knowledgeBaseId}/documents", "options": [], "confirmation": false, "bodyRequired": false },
+    { "command": "standins knowledge get", "args": ["standinProfileId"], "description": "Read knowledge attachments.", "scope": "knowledge:read", "method": "GET", "path": "/v1/reps/me/standins/{standinProfileId}/knowledge-bases", "options": [], "confirmation": false, "bodyRequired": false },
+    { "command": "standins knowledge set", "args": ["standinProfileId"], "description": "Replace the complete approved attachment list.", "scope": "knowledge:write", "method": "PUT", "path": "/v1/reps/me/standins/{standinProfileId}/knowledge-bases", "options": ["body-file"], "confirmation": true, "bodyRequired": true },
+    { command: 'standins master', args: [], description: 'Change the account-wide switch; affects other enabled Stand-ins.', scope: 'standins:write', method: 'POST', path: '/v1/reps/me/standin/toggle', options: ['enabled'], confirmation: true },
+    { command: 'whoami', args: [], description: 'Get the authenticated user.', scope: 'profile:read', method: 'GET', path: '/v1/reps/me', options: [] },
+    { command: 'profile get', args: [], description: 'Get your representative profile.', scope: 'profile:read', method: 'GET', path: '/v1/reps/profile', options: [] },
+    { command: 'team list', args: [], description: 'List the current team.', scope: 'team:read', method: 'GET', path: '/v1/team', options: [] },
+    { command: 'sites list', args: [], description: 'List sites in your organization.', scope: 'sites:read', method: 'GET', path: '/v1/sites', options: [] },
+    { command: 'sites get', args: ['siteId'], description: 'Read one authorized site directly.', scope: 'sites:read', method: 'GET', path: '/v1/sites/{siteId}', options: [] },
+    { command: 'sites create', args: [], description: 'Create a site.', scope: 'sites:write', method: 'POST', path: '/v1/sites', options: ['domain', 'name', 'body-file'], confirmation: true },
+    { command: 'sites update', args: ['siteId'], description: 'Update supplied site settings; requires organization ownership. Legacy embedOptions replaces behavior rules and resets experimentation consent; use complete behaviorConfig to retain behavior.', scope: 'sites:write', method: 'PUT', path: '/v1/sites/{siteId}', options: ['name', 'enabled', 'language', 'body-file'], confirmation: true },
+    { command: 'sites delete', args: ['siteId'], description: 'Delete a site; requires organization ownership.', scope: 'sites:write', method: 'DELETE', path: '/v1/sites/{siteId}', options: [], confirmation: true },
+    { command: 'sessions list', args: [], description: 'List active session identifiers. Does not change rep availability.', scope: 'sessions:read', method: 'GET', path: '/v1/sessions', options: ['watch', 'interval', 'count'] },
+    { command: 'sessions get', args: ['sessionId'], description: 'Read a session and up to 500 messages.', scope: 'sessions:read', method: 'GET', path: '/v1/sessions/{sessionId}?messageLimit=500', options: ['watch', 'interval', 'count'] },
+    { command: 'sessions send', args: ['sessionId'], description: 'Send a message after verifying your identity (also requires profile:read). Adds clientMessageId when absent; errors after dispatch include reconciliation IDs.', scope: 'sessions:write', additionalScopes: ['profile:read'], method: 'POST', path: '/v1/sessions/{sessionId}/messages', options: ['body-file'], confirmation: true },
+    { command: 'sessions close', args: ['sessionId'], description: 'Close a session as the authenticated user.', scope: 'sessions:write', method: 'DELETE', path: '/v1/sessions/{sessionId}', options: [], confirmation: true },
+    { command: 'history search', args: [], description: 'Search archived sessions; dates are explicit instants and closed-to is exclusive.', scope: 'sessions:read', method: 'GET', path: '/v1/sessions/archived', options: ['query', 'page', 'size', 'type', 'scope', 'site', 'contact', 'label', 'closed-from', 'closed-to', 'sort-by', 'sort-dir', 'all', 'max-pages'] },
+    { command: 'history export', args: [], description: 'Stream a history export into a new private file; never overwrites an existing file.', scope: 'sessions:read', method: 'GET', path: '/v1/sessions/archived/export', options: ['output', 'max-bytes', 'query', 'type', 'scope', 'site', 'contact', 'label', 'closed-from', 'closed-to', 'sort-by', 'sort-dir'] },
+    ...([
+        ['profile update', [], 'Update an already-completed profile; initial onboarding remains in the browser.', 'profile:write', 'PUT', '/v1/reps/profile', true],
+        ['sites matches', [], 'List responder matches for installed sites.', 'sites:read', 'GET', '/v1/sites/matches'],
+        ['sites preferences get', [], 'Get the sites selected for your representative profile.', 'sites:read', 'GET', '/v1/reps/profile/sites'],
+        ['sites preferences set', [], 'Set the sites selected for your representative profile.', 'sites:write', 'PUT', '/v1/reps/profile/sites', true],
+        ['sites prompt get', ['siteId'], 'Get site instructions.', 'sites:read', 'GET', '/v1/sites/{siteId}/prompt'],
+        ['sites prompt set', ['siteId'], 'Replace site instructions.', 'sites:write', 'PUT', '/v1/sites/{siteId}/prompt', true],
+        ['sites prompt delete', ['siteId'], 'Delete site instructions.', 'sites:write', 'DELETE', '/v1/sites/{siteId}/prompt'],
+        ['sites prompt history', ['siteId'], 'Read site instruction history.', 'sites:read', 'GET', '/v1/sites/{siteId}/prompt/history'],
+        ['org prompt get', ['orgId'], 'Get organization instructions.', 'org:read', 'GET', '/v1/orgs/{orgId}/prompt'],
+        ['org prompt set', ['orgId'], 'Replace organization instructions.', 'org:write', 'PUT', '/v1/orgs/{orgId}/prompt', true],
+        ['org prompt delete', ['orgId'], 'Delete organization instructions.', 'org:write', 'DELETE', '/v1/orgs/{orgId}/prompt'],
+        ['org prompt history', ['orgId'], 'Read organization instruction history.', 'org:read', 'GET', '/v1/orgs/{orgId}/prompt/history'],
+        ['org privacy get', ['orgId'], 'Read organization privacy preferences.', 'org:read', 'GET', '/v1/orgs/{orgId}/privacy-settings'],
+        ['org privacy set', ['orgId'], 'Update organization privacy preferences.', 'org:write', 'PUT', '/v1/orgs/{orgId}/privacy-settings', true],
+        ['sessions seen', ['sessionId'], 'Mark a session as seen.', 'sessions:write', 'PUT', '/v1/sessions/{sessionId}/seen'],
+        ['sessions take-over', ['sessionId'], 'Take over a session from its Stand-in.', 'sessions:write', 'POST', '/v1/sessions/{sessionId}/handoff'],
+        ['sessions offer-handoff', ['sessionId'], 'Offer a session handoff.', 'sessions:write', 'POST', '/v1/sessions/{sessionId}/handoff/offer'],
+        ['greetings list', [], 'List greeting variants.', 'profile:read', 'GET', '/v1/reps/me/greeting-variants'],
+        ['greetings set', [], 'Replace greeting variants.', 'profile:write', 'PUT', '/v1/reps/me/greeting-variants', true],
+        ['digest preferences get', [], 'Read digest delivery preferences.', 'digest:read', 'GET', '/v1/digest/preferences'],
+        ['digest preferences set', [], 'Update digest delivery preferences.', 'digest:write', 'PUT', '/v1/digest/preferences', true],
+        ['digest ai-preferences get', [], 'Read AI digest preferences.', 'digest:read', 'GET', '/v1/digest/ai-preferences'],
+        ['digest ai-preferences set', [], 'Update AI digest preferences.', 'digest:write', 'PUT', '/v1/digest/ai-preferences', true],
+        ['digest send', [], 'Send the configured digest now.', 'digest:write', 'POST', '/v1/digest/send-now'],
+        ['standins list', [], 'List your Stand-ins.', 'standins:read', 'GET', '/v1/reps/me/standins'],
+        ['standins create', [], 'Create a Stand-in.', 'standins:write', 'POST', '/v1/reps/me/standins', true],
+        ['standins get', ['id'], 'Read a Stand-in.', 'standins:read', 'GET', '/v1/reps/me/standins/{id}'],
+        ['standins update', ['id'], 'Save Stand-in settings. Chat history is preserved by creating a replacement version when needed; use the returned standinProfileId for later calls. Read and preserve existing fields before saving.', 'standins:write', 'PUT', '/v1/reps/me/standins/{id}', true],
+        ['standins delete', ['id'], 'Delete a Stand-in.', 'standins:write', 'DELETE', '/v1/reps/me/standins/{id}'],
+        ['standins clone', ['id'], 'Clone a Stand-in as an independent, initially disabled copy.', 'standins:write', 'POST', '/v1/reps/me/standins/{id}/clone'],
+    ]).map(([command, args, description, scope, method, path, bodyRequired]) => ({
+        command, args, description, scope, method, path, bodyRequired,
+        options: bodyRequired ? ['body-file'] : [], confirmation: method !== 'GET',
+    })),
+    { command: 'team provider-default', args: [], description: 'Resolve the required provider for a prospective invitation.', scope: 'team:read', method: 'GET', path: '/v1/team/invite-provider-default', options: ['email'] },
+    { command: 'standins set-enabled', args: ['id'], description: 'Enable or disable a Stand-in.', scope: 'standins:write', method: 'POST', path: '/v1/reps/me/standins/{id}/enabled', options: ['enabled'], confirmation: true },
+    { command: 'sites preferences update', args: ['siteId'], description: 'Change your chat selection for one site, retaining the other selected sites.', scope: 'sites:write', method: 'PUT', path: '/v1/reps/profile/sites/{siteId}', options: ['enabled'], confirmation: true },
+];
+// Only operations present in the bundled public contract are available. The
+// private definition catalog may include wrappers for routes excluded by policy.
+export const COMMANDS = COMMAND_DEFINITIONS.flatMap(command => {
+    const paths = isObject(BUNDLED_SCHEMA) && isObject(BUNDLED_SCHEMA.paths) ? BUNDLED_SCHEMA.paths : {};
+    const item = paths[command.path.split('?')[0]];
+    const operation = isObject(item) ? item[command.method.toLowerCase()] : undefined;
+    if (!isObject(operation))
+        return [];
+    if (typeof operation.operationId !== 'string' || typeof operation['x-required-scope'] !== 'string') {
+        throw new Error('Public API operation is missing its identifier or required scope.');
+    }
+    return [{
+            ...command,
+            options: command.options,
+            operationId: operation.operationId,
+            scope: operation['x-required-scope'],
+        }];
+});
+export function stringFlag(flags, key) { const value = flags[key]; return typeof value === 'string' ? value : undefined; }
+export function integerFlag(flags, key, defaultValue, min, max) {
+    const raw = stringFlag(flags, key);
+    if (raw === undefined)
+        return defaultValue;
+    if (!/^\d+$/.test(raw))
+        usage(`--${key} must be an integer from ${min} to ${max}.`);
+    const value = Number(raw);
+    if (!Number.isSafeInteger(value) || value < min || value > max)
+        usage(`--${key} must be an integer from ${min} to ${max}.`);
+    return value;
+}
+export async function readInput(stream, maxBytes = 1024 * 1024, signal) {
+    const cancelled = () => new CliError('CANCELLED', 'Input cancelled. No request was sent.', 130);
+    if (signal?.aborted)
+        throw cancelled();
+    const cancel = () => {
+        if ('destroy' in stream && typeof stream.destroy === 'function')
+            stream.destroy(cancelled());
+    };
+    signal?.addEventListener('abort', cancel, { once: true });
+    const chunks = [];
+    let total = 0;
+    try {
+        for await (const chunk of stream) {
+            const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+            total += buffer.length;
+            if (total > maxBytes)
+                throw new CliError('INPUT_TOO_LARGE', `Input exceeds the ${maxBytes}-byte limit.`, 2);
+            chunks.push(buffer);
+        }
+        if (signal?.aborted)
+            throw cancelled();
+        return Buffer.concat(chunks).toString('utf8');
+    }
+    finally {
+        signal?.removeEventListener('abort', cancel);
+    }
+}
+export async function requestBody(flags, stdin, signal) {
+    const file = stringFlag(flags, 'body-file');
+    if (!file)
+        return undefined;
+    let text;
+    try {
+        if (file === '-')
+            text = await readInput(stdin, undefined, signal);
+        else {
+            // Stream files too, so a mistaken large path does not exhaust memory.
+            const { createReadStream } = await import('node:fs');
+            text = await readInput(createReadStream(file), undefined, signal);
+        }
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+        throw new CliError('INPUT_READ_FAILED', 'Cannot read the request body file.', 2);
+    }
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        return usage('Request body must be valid JSON.');
+    }
+    if (!isObject(body))
+        usage('Request body must be a JSON object.');
+    return body;
+}
+export function findCommand(words) {
+    const definition = COMMANDS.find(item => item.command.split(' ').every((word, i) => words[i] === word));
+    if (!definition)
+        return undefined;
+    const args = words.slice(definition.command.split(' ').length);
+    if (args.length !== definition.args.length)
+        usage(`Usage: stand ${definition.command}${definition.args.map(arg => ` <${arg}>`).join(' ')}.`);
+    if (args.some(value => !value || value === '.' || value === '..' || /[\x00-\x20\x7f/\\]/.test(value)))
+        usage('Resource identifiers must be nonempty path segments.');
+    return { definition, args };
+}
+export function resolvePath(command, args) {
+    return command.args.reduce((path, name, index) => path.replace(`{${name}}`, encodeURIComponent(args[index])), command.path);
+}
+function enumFlag(flags, key, values, fallback) {
+    const value = stringFlag(flags, key) ?? fallback;
+    if (!values.includes(value))
+        usage(`--${key} must be one of: ${values.join(', ')}.`);
+    return value;
+}
+function validTimestamp(value) {
+    const match = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?:Z|[+-](\d{2}):(\d{2}))$/.exec(value);
+    if (!match || !Number.isFinite(Date.parse(value)))
+        return false;
+    const [year, month, day, hour, minute, second] = match.slice(1, 7).map(Number);
+    if (month < 1 || month > 12 || hour > 23 || minute > 59 || second > 59 || Number(match[7] ?? 0) > 23 || Number(match[8] ?? 0) > 59)
+        return false;
+    const calendar = new Date(`${match[1]}-${match[2]}-01T00:00:00Z`);
+    calendar.setUTCMonth(month);
+    calendar.setUTCDate(0);
+    return calendar.getUTCFullYear() === year && day >= 1 && day <= calendar.getUTCDate();
+}
+export function historyParams(flags) {
+    const page = integerFlag(flags, 'page', 0, 0, 2_147_483_647);
+    const size = integerFlag(flags, 'size', 20, 1, 100);
+    if (page * size > 2_147_483_647)
+        usage('--page and --size exceed the maximum history offset.');
+    // Match Java String.trim() and String.length(), including its UTF-16 counting.
+    const rawQuery = stringFlag(flags, 'query');
+    let start = 0, end = rawQuery?.length ?? 0;
+    while (start < end && rawQuery.charCodeAt(start) <= 0x20)
+        start++;
+    while (end > start && rawQuery.charCodeAt(end - 1) <= 0x20)
+        end--;
+    const query = rawQuery?.slice(start, end);
+    if (query && query.length > 200)
+        usage('--query must contain at most 200 UTF-16 code units after removing leading and trailing U+0000 through U+0020 characters.');
+    const params = new URLSearchParams({
+        page: String(page), size: String(size),
+        type: enumFlag(flags, 'type', ['all', 'rep', 'agent'], 'all'),
+        scope: enumFlag(flags, 'scope', ['myself', 'org'], 'myself'),
+        contact: enumFlag(flags, 'contact', ['all', 'email', 'phone', 'any'], 'all'),
+        sortBy: enumFlag(flags, 'sort-by', ['closedAt', 'createdAt', 'page', 'messageCount'], 'closedAt'),
+        sortDir: enumFlag(flags, 'sort-dir', ['asc', 'desc'], 'desc'),
+    });
+    for (const key of ['site', 'label']) {
+        const value = stringFlag(flags, key);
+        if (value)
+            params.set(key, value);
+    }
+    if (query)
+        params.set('q', query);
+    for (const [flag, key] of [['closed-from', 'closedFrom'], ['closed-to', 'closedTo']]) {
+        const value = stringFlag(flags, flag);
+        if (value !== undefined) {
+            if (!validTimestamp(value))
+                usage(`--${flag} must be an ISO 8601 timestamp with timezone (for example 2026-10-15T00:00:00Z).`);
+            params.set(key, new Date(value).toISOString());
+        }
+    }
+    const from = params.get('closedFrom');
+    const to = params.get('closedTo');
+    if (from && to && from >= to)
+        usage('--closed-from must be earlier than --closed-to.');
+    return params;
+}
+export async function executeCommand(client, command, args, flags, stdin, options, preparedBody) {
+    const body = preparedBody ?? await requestBody(flags, stdin, options.signal);
+    if (command.bodyRequired && !body)
+        usage('This command requires --body-file FILE (or - for stdin). Run stand schema OPERATION_ID for its request schema.');
+    if (command.command === 'history export') {
+        const file = stringFlag(flags, 'output');
+        if (!file || file === '-')
+            usage('History export requires --output FILE. Use a new file; existing files are never overwritten.');
+        const params = historyParams(flags);
+        params.delete('page');
+        params.delete('size');
+        return client.download(`${command.path}?${params}`, file, integerFlag(flags, 'max-bytes', 100 * 1024 * 1024, 1, 1024 * 1024 * 1024), options);
+    }
+    if (command.command === 'history search') {
+        if (flags['max-pages'] !== undefined && !flags.all)
+            usage('--max-pages requires --all.');
+        const params = historyParams(flags);
+        const startPage = Number(params.get('page'));
+        if (!flags.all)
+            return client.request(`${command.path}?${params}`, options);
+        const maxPages = integerFlag(flags, 'max-pages', 20, 1, 1000);
+        const sessions = [];
+        let accumulatedBytes = 0;
+        let totalPages = 0;
+        let totalElements = 0;
+        let fetched = 0;
+        for (; fetched < maxPages; fetched++) {
+            params.set('page', String(startPage + fetched));
+            const response = await client.request(`${command.path}?${params}`, options);
+            if (!isObject(response) || !Array.isArray(response.sessions) || !Number.isInteger(response.totalPages)
+                || typeof response.totalPages !== 'number' || response.totalPages < 0 || typeof response.totalElements !== 'number'
+                || response.page !== startPage + fetched)
+                throw new CliError('INVALID_RESPONSE', 'History response has invalid pagination metadata.', 5);
+            accumulatedBytes += Buffer.byteLength(JSON.stringify(response.sessions));
+            if (accumulatedBytes > 32 * 1024 * 1024)
+                throw new CliError('RESPONSE_TOO_LARGE', 'Combined history exceeds 32 MiB. Request smaller page ranges or narrower filters.', 2);
+            sessions.push(...response.sessions);
+            totalPages = response.totalPages;
+            totalElements = response.totalElements;
+            if (startPage + fetched + 1 >= totalPages) {
+                fetched++;
+                break;
+            }
+        }
+        const nextPage = startPage + fetched < totalPages ? startPage + fetched : null;
+        return { sessions, startPage, pagesFetched: fetched, totalElements, complete: nextPage === null, nextPage,
+            consistency: 'Live offset pagination; concurrent changes can affect page boundaries.' };
+    }
+    let payload = body;
+    if (command.command === 'team provider-default') {
+        const email = stringFlag(flags, 'email');
+        if (!email || !/^[^\s@]+@[^\s@]+$/.test(email))
+            usage('--email must contain an email address.');
+        return client.request(`${command.path}?${new URLSearchParams({ email })}`, options);
+    }
+    if (['standins set-enabled', 'standins master'].includes(command.command) || command.command === 'sites preferences update') {
+        const enabled = stringFlag(flags, 'enabled');
+        if (enabled !== 'true' && enabled !== 'false')
+            usage('--enabled must be true or false.');
+        payload = { enabled: enabled === 'true' };
+    }
+    if (command.command === 'sites create' || command.command === 'sites update') {
+        const fieldFlags = ['domain', 'name', 'enabled', 'language'].filter(key => flags[key] !== undefined);
+        if (body && fieldFlags.length)
+            usage('Use --body-file or field flags, not both.');
+        payload ??= {};
+        for (const key of ['domain', 'name']) {
+            const value = stringFlag(flags, key);
+            if (value !== undefined)
+                payload[key] = value;
+        }
+        const enabled = stringFlag(flags, 'enabled');
+        if (enabled !== undefined) {
+            if (enabled !== 'true' && enabled !== 'false')
+                usage('--enabled must be true or false.');
+            payload.enabled = enabled === 'true';
+        }
+        const language = stringFlag(flags, 'language');
+        if (language !== undefined)
+            payload.defaultLanguageCode = language === 'auto' ? null : language;
+        if (command.command === 'sites create' && (typeof payload.domain !== 'string' || !payload.domain.trim()))
+            usage('Provide --domain or a JSON body with a nonempty domain.');
+        if (command.command === 'sites update' && !Object.keys(payload).length)
+            usage('Provide at least one site setting.');
+    }
+    if (command.command === 'sessions send') {
+        if (!payload || typeof payload.body !== 'string' || !payload.body.trim())
+            usage('Provide --body-file with a nonempty body string.');
+        payload.type ??= 'text';
+        payload.clientMessageId ??= randomUUID();
+        if (typeof payload.clientMessageId !== 'string' || !payload.clientMessageId.length
+            || payload.clientMessageId.length > 256 || payload.clientMessageId.trim() !== payload.clientMessageId
+            || /[\x00-\x1f\x7f-\x9f]/.test(payload.clientMessageId)) {
+            usage('clientMessageId must be a nonblank string of at most 256 characters, without control characters or surrounding whitespace. A UUID is recommended.');
+        }
+        if (args[0].length > 256)
+            usage('Session identifiers must contain at most 256 characters.');
+        const reconciliation = { sessionId: args[0], clientMessageId: payload.clientMessageId };
+        // The server deduplicates by clientMessageId and can return someone else's
+        // earlier message. Obtain the authenticated identity before making a write.
+        const user = await client.request('/v1/reps/me', options);
+        if (!isObject(user) || typeof user.userId !== 'string' || !user.userId.trim()) {
+            throw new CliError('INVALID_RESPONSE', 'Could not verify your identity. No reply was sent.', 5);
+        }
+        let dispatched = false;
+        try {
+            const result = await client.request(resolvePath(command, args), {
+                ...options, method: command.method, body: payload,
+                onDispatch: () => { options.onDispatch?.(); dispatched = true; },
+            });
+            if (!isObject(result) || typeof result.messageId !== 'string' || !result.messageId.trim()
+                || ['sessionId', 'senderId', 'senderType', 'type', 'body', 'clientMessageId'].some(key => typeof result[key] !== 'string')) {
+                throw new CliError('INVALID_RESPONSE', 'The server did not return a complete reply. Its outcome is unconfirmed.', 5);
+            }
+            if (result.sessionId !== args[0] || result.clientMessageId !== payload.clientMessageId || result.body !== payload.body
+                || result.senderType !== 'rep' || result.senderId !== user.userId || result.type !== 'text') {
+                throw new CliError('REPLY_CONFLICT', 'The returned message does not match the approved reply and authenticated sender. It does not confirm that your reply was sent.', 1);
+            }
+            return result;
+        }
+        catch (error) {
+            if (!dispatched)
+                throw error;
+            const failure = error instanceof CliError ? error : new CliError('NETWORK', 'Reply outcome could not be confirmed.', 5);
+            throw new CliError(failure.code, `${failure.message} Before retrying, read the conversation and check the reply identity, sender, type and body. Reuse this clientMessageId for an intentional retry. The responder may already have changed.`, failure.exitCode, failure.status, failure.retryAfter, reconciliation);
+        }
+    }
+    try {
+        return await client.request(resolvePath(command, args), { ...options, method: command.method, body: payload });
+    }
+    catch (error) {
+        // Preserve the named site lookup's established not-found exit status.
+        if (command.command === 'sites get' && error instanceof CliError && error.status === 404)
+            throw new CliError(error.code, error.message, 3, error.status, error.retryAfter);
+        throw error;
+    }
+}
+export async function readSchema(operation) {
+    const schema = BUNDLED_SCHEMA;
+    if (!operation)
+        return schema;
+    if (isObject(schema) && isObject(schema.paths)) {
+        for (const [path, raw] of Object.entries(schema.paths)) {
+            if (!isObject(raw))
+                continue;
+            for (const [method, detail] of Object.entries(raw)) {
+                if (isObject(detail) && detail.operationId === operation)
+                    return { path, method: method.toUpperCase(), ...detail, components: schema.components };
+            }
+        }
+    }
+    throw new CliError('NOT_FOUND', 'Operation was not found in the bundled API contract.', 3);
+}