@tenderlead/cli 0.4.3 → 0.5.0

package/README.md

@@ -200,3 +200,100 @@ Provider acceptance and API responses do not prove email inbox delivery.
 ## Licence
 
 MIT
+
+## Multi-company pilot
+
+The 0.5.0 candidate adds explicit company commands for enabled portfolio pilot
+accounts. These commands require the shared company API to be deployed. Standard
+Pro remains one company profile; Team access is agreed separately. Existing
+single-profile commands keep their existing behaviour.
+
+Start with the saved company IDs. A company name is never a selector:
+
+```bash
+tenderlead companies list --json
+tenderlead companies show COMPANY_UUID --json
+tenderlead companies brief COMPANY_UUID --json
+tenderlead companies matches COMPANY_UUID --json
+tenderlead companies pipeline COMPANY_UUID --json
+tenderlead companies matches all --json
+```
+
+`list` returns company metadata; `show COMPANY_UUID` returns that company's
+full saved profile. `brief`, `matches` and `pipeline` return one page only:
+10 items by default, with `--page-size 1` to `--page-size 25` supported.
+Human output includes the total, whether more items exist, the next page and
+snapshot token, plus a continuation command. `--json` preserves the same
+`pagination` metadata unchanged. No command automatically fetches later pages.
+
+```bash
+tenderlead companies matches all --page-size 10 --json
+# Use the returned pagination.snapshot for the next page:
+tenderlead companies matches all --page 2 --page-size 10 --snapshot SNAPSHOT_TOKEN --json
+```
+
+`--page`, `--page-size` and `--snapshot` apply only to those three read commands.
+Page numbers start at 1. Pages after the first require the previous response's
+64-character snapshot token and the same company selector, operation and page
+size. If the server reports a changed snapshot (HTTP 409), restart at page 1
+without `--snapshot`; do not combine pages from different snapshots. The CLI
+reports the conflict and never retries or restarts automatically.
+
+`all` is allowed only for `brief`, `matches` and `pipeline` reads. Combined
+responses retain company IDs and names. Reads show saved results, revisions and
+source state; they do not start matching or send alerts. `brief` is a saved
+company brief, not proof of email delivery.
+
+Create a token with the explicit company scopes. Existing tokens gain no scopes
+automatically:
+
+| Command | Required scopes |
+| --- | --- |
+| `list`, `show` | `companies:read`, `profile:read` |
+| `brief` | `companies:read`, `briefs:read` |
+| `matches` | `companies:read`, `tenders:read` |
+| `pipeline` | `companies:read`, `pipeline:read` |
+| `apply` | `companies:write`, `profile:write` |
+| `save`, `update` | `companies:write`, `pipeline:write` |
+| `review` | `companies:write`, `feedback:write` |
+
+Writes first read the selected company for an identity check, so also retain
+`companies:read` and `profile:read`. Review the saved company, notice or pipeline
+record before preparing the JSON. Each write requires typed confirmation, or
+`--yes` after review:
+
+```bash
+tenderlead companies apply COMPANY_UUID --file company-changes.json
+tenderlead companies save COMPANY_UUID --file save-notice.json
+tenderlead companies update COMPANY_UUID ITEM_UUID --file pipeline-changes.json
+tenderlead companies review COMPANY_UUID --file notice-review.json
+```
+
+`apply` accepts a flat partial company profile with the saved UUID
+`expectedRevision`. Company fields follow the portfolio schema: `name`,
+`websites`, `capabilities`, `keywords`, `industries`, `exclusions`, `limitations`,
+`legal_name`, `company_number`, `team_size`, `specialisms`, `region`, `size_min`,
+`size_max`, `frameworks`, `clearances`, `no_bid_rules`, `past_work` and `geography`.
+This schema differs from the single-profile `profile apply` schema.
+
+`save` requires `noticeKey`, UUID `expectedProfileRevision` and the exact
+64-character `expectedSourceFingerprint` from the saved company notice. An
+optional `legacyId` must be a UUID for an existing legacy record. It does not
+create another company or run an assessment.
+
+`update` requires UUID `expectedRevision` from the saved pipeline item plus
+`stage` or `notes`. Stages are `watching`, `preparing`, `submitted`, `won` and
+`lost`. Notes accept up to 10,000 characters.
+
+`review` requires `noticeKey`, UUID `expectedProfileRevision`,
+`expectedSourceFingerprint`, `decision`, `rationale` and `expectedRevision`.
+Use `expectedRevision: null` for a first review, or the saved review UUID for an
+update. Optional canonical fields are `sourceQuote`, `capability`, `nextAction`
+and `gaps`; the server validates the decision and supporting source evidence.
+
+All writes use the company UUID in the command. JSON must not contain an owner,
+account or profile override, `notify`, `monitoring` or `archived`. Company
+creation, deletion, archiving, alert preferences and refreshing are not exposed
+by these commands. On a conflict or uncertain request outcome, reload the
+company and affected record before deciding whether to retry. The CLI never
+automatically retries a write.

package/bin/tenderlead.js

@@ -17,6 +17,11 @@ function usage() {
   return [
     'Usage:',
     '  tenderlead login',
+    '  tenderlead companies list [--json]',
+    '  tenderlead companies show <company-id> [--json]',
+    '  tenderlead companies brief|matches|pipeline <company-id|all> [--page <N>] [--page-size <1-25>] [--snapshot <token>] [--json]',
+    '  tenderlead companies apply|save|review <company-id> --file <path> [--yes] [--json]',
+    '  tenderlead companies update <company-id> <item-id> --file <path> [--yes] [--json]',
     '  tenderlead whoami [--json]',
     '  tenderlead account status [--json]',
     '  tenderlead brief [--json]',
@@ -118,6 +123,7 @@ function parseArgs(argv) {
     }
     return options;
   }
+  if (command === 'companies') return parseCompanyArgs(argv);
   if (command === 'pipeline') return parsePipelineArgs(argv);
   if (command === 'insights') return parseJsonOnlyArgs(argv, 3, { command: 'insights', json: false });
   if (command === 'feedback') return parseFeedbackArgs(argv);
@@ -150,6 +156,124 @@ function parseArgs(argv) {
   return options;
 }
 
+const COMPANY_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const COMPANY_PAGED_READS = ['brief', 'matches', 'pipeline'];
+const COMPANY_WRITES = ['apply', 'save', 'update', 'review'];
+function companyId(id, allowAll = false) {
+  if ((allowAll && id === 'all') || (typeof id === 'string' && COMPANY_UUID.test(id))) return id;
+  throw new Error(`Use an explicit company UUID${allowAll ? ' or all for this read' : ''}. Run companies list for IDs.`);
+}
+function parseCompanyArgs(argv) {
+  const action = argv[3];
+  if (!['list', 'show', 'brief', 'matches', 'pipeline', ...COMPANY_WRITES].includes(action)) throw new Error('Use companies list, show, brief, matches, pipeline, apply, save, update or review.');
+  const write = COMPANY_WRITES.includes(action);
+  const paged = COMPANY_PAGED_READS.includes(action);
+  const options = { command: 'companies', action, json: false, yes: false, file: null };
+  let start = 4;
+  if (action !== 'list') { options.id = companyId(argv[start++], ['brief', 'matches', 'pipeline'].includes(action)); }
+  if (action === 'update') { options.itemId = companyId(argv[start++]); }
+  for (let index = start; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--json') options.json = true;
+    else if (paged && ['--page', '--page-size', '--snapshot'].includes(arg)) {
+      const key = { '--page': 'page', '--page-size': 'pageSize', '--snapshot': 'snapshot' }[arg];
+      if (options[key] !== undefined) throw new Error(`Duplicate argument: ${arg}`);
+      options[key] = optionValue(argv, index, arg); index += 1;
+    }
+    else if (write && arg === '--yes') options.yes = true;
+    else if (write && arg === '--file' && !options.file) { options.file = optionValue(argv, index, arg); index += 1; }
+    else throw new Error(`Unknown argument: ${arg}`);
+  }
+  if (paged) Object.assign(options, companyPagination(options));
+  if (write && !options.file) throw new Error(`companies ${action} requires --file <path>`);
+  return options;
+}
+function companyPagination(options) {
+  const pageText = String(options.page ?? 1), sizeText = String(options.pageSize ?? 10);
+  if (!/^[1-9][0-9]*$/.test(pageText) || !Number.isSafeInteger(Number(pageText))) throw new Error('--page must be a positive integer.');
+  if (!/^[1-9][0-9]*$/.test(sizeText) || Number(sizeText) > 25) throw new Error('--page-size must be an integer from 1 to 25.');
+  const snapshot = options.snapshot;
+  if (snapshot !== undefined && (typeof snapshot !== 'string' || !/^[0-9a-f]{64}$/.test(snapshot))) throw new Error('--snapshot must be the saved 64-character snapshot token.');
+  if (Number(pageText) > 1 && !snapshot) throw new Error('--page greater than 1 requires --snapshot from the previous response.');
+  return { page: Number(pageText), pageSize: Number(sizeText), ...(snapshot ? { snapshot } : {}) };
+}
+function validateCompanyBody(action, body) {
+  if (!isPlainObject(body)) throw new Error('Company JSON must be an object.');
+  const fields = {
+    apply: ['expectedRevision', 'name', 'websites', 'capabilities', 'keywords', 'industries', 'exclusions', 'limitations', 'legal_name', 'company_number', 'team_size', 'specialisms', 'region', 'size_min', 'size_max', 'frameworks', 'clearances', 'no_bid_rules', 'past_work', 'geography'],
+    save: ['noticeKey', 'expectedProfileRevision', 'expectedSourceFingerprint', 'legacyId'],
+    update: ['expectedRevision', 'stage', 'notes'],
+    review: ['noticeKey', 'expectedProfileRevision', 'expectedSourceFingerprint', 'expectedRevision', 'decision', 'rationale', 'sourceQuote', 'capability', 'nextAction', 'gaps'],
+  }[action];
+  if (!fields || Object.keys(body).some(key => !fields.includes(key))) throw new Error('Unsupported company field. Account/profile overrides, alerts and monitoring changes are not accepted.');
+  const uuid = key => { if (typeof body[key] !== 'string' || !COMPANY_UUID.test(body[key])) throw new Error(`${key} must be the saved UUID revision.`); };
+  if (['apply', 'update'].includes(action)) uuid('expectedRevision');
+  if (['save', 'review'].includes(action)) {
+    uuid('expectedProfileRevision');
+    if (typeof body.noticeKey !== 'string' || !body.noticeKey || body.noticeKey.length > 1000) throw new Error('noticeKey must identify a saved company notice.');
+    if (typeof body.expectedSourceFingerprint !== 'string' || !/^[0-9a-f]{64}$/.test(body.expectedSourceFingerprint)) throw new Error('expectedSourceFingerprint must be the saved source fingerprint.');
+  }
+  if (action === 'save' && body.legacyId !== undefined) uuid('legacyId');
+  if (action === 'review' && body.expectedRevision !== null) uuid('expectedRevision');
+  if (action === 'update') {
+    if (!('stage' in body) && !('notes' in body)) throw new Error('Include stage or notes.');
+    if ('stage' in body && !['watching', 'preparing', 'submitted', 'won', 'lost'].includes(body.stage)) throw new Error('Use a valid pipeline stage.');
+    if ('notes' in body && (typeof body.notes !== 'string' || body.notes.length > 10000)) throw new Error('notes must be text of at most 10,000 characters.');
+  }
+  return body;
+}
+async function companyRequest(options, body, fetchImpl = fetch) {
+  const { action } = options;
+  const id = action === 'list' ? null : companyId(options.id, ['brief', 'matches', 'pipeline'].includes(action));
+  const base = '/v1/companies' + (id ? `/${encodeURIComponent(id)}` : '');
+  if (!COMPANY_WRITES.includes(action)) {
+    const paged = COMPANY_PAGED_READS.includes(action);
+    const params = paged ? companyPagination(options) : null;
+    const query = params ? new URLSearchParams({ page: String(params.page), page_size: String(params.pageSize), ...(params.snapshot ? { snapshot: params.snapshot } : {}) }) : null;
+    try { return await apiRequest(base + (['list', 'show'].includes(action) ? '' : `/${action}`) + (query ? `?${query}` : ''), {}, fetchImpl); }
+    catch (error) {
+      if (paged && error.status === 409) throw new Error(`${error.message} Restart at --page 1 without --snapshot; do not reuse the previous pages.`);
+      throw error;
+    }
+  }
+  validateCompanyBody(action, body);
+  const suffix = action === 'apply' ? '' : action === 'review' ? '/reviews' : '/pipeline' + (action === 'update' ? `/${companyId(options.itemId)}` : '');
+  return apiRequest(base + suffix, { method: ['apply', 'update'].includes(action) ? 'PATCH' : 'POST', body: JSON.stringify(body) }, fetchImpl);
+}
+function companyText(value, fallback = '') {
+  return line(String(value ?? '').replace(/[\u0000-\u001f\u007f-\u009f]/g, ' '), fallback);
+}
+function formatCompanies(payload, options) {
+  const profiles = payload.profiles || (payload.profile ? [payload.profile] : []);
+  const heading = options.action === 'list' ? '# TenderLead companies' : `# Company ${companyText(options.id)} · ${companyText(options.action)}`;
+  const lines = [heading];
+  for (const profile of profiles) lines.push(`Company: ${companyText(profile.name, 'Unnamed')} · ${companyText(profile.id, 'unknown')} · revision ${companyText(profile.revision, 'unknown')}`);
+  // Retain every saved field, source check and company label in text output too.
+  lines.push(JSON.stringify(payload, null, 2));
+  if (payload.pagination) {
+    const page = payload.pagination;
+    lines.push(`Page: ${companyText(page.page)} · Total: ${companyText(page.total_count)} · Has more: ${Boolean(page.has_more)} · Next page: ${companyText(page.next_page, 'none')} · Snapshot: ${companyText(page.snapshot)}`);
+    if (page.has_more && Number.isSafeInteger(page.next_page) && page.next_page > 1 && /^[0-9a-f]{64}$/.test(page.snapshot) && COMPANY_PAGED_READS.includes(options.action)) {
+      lines.push(`Continue: tenderlead companies ${options.action} ${companyId(options.id, true)} --page ${page.next_page} --page-size ${companyPagination({ pageSize: page.page_size }).pageSize} --snapshot ${page.snapshot}`);
+    }
+  }
+  return lines.join('\n');
+}
+async function runCompanyCommand(options, dependencies = {}) {
+  const fetchImpl = dependencies.fetch || fetch;
+  if (!COMPANY_WRITES.includes(options.action)) return companyRequest(options, undefined, fetchImpl);
+  companyId(options.id);
+  if (options.action === 'update') companyId(options.itemId);
+  const body = validateCompanyBody(options.action, (dependencies.read || readJsonFile)(options.file));
+  apiToken();
+  const current = await companyRequest({ action: 'show', id: options.id }, undefined, fetchImpl);
+  const profile = current.profile;
+  if (!profile || profile.id !== options.id) throw new Error('Company identity could not be confirmed. Reload companies list.');
+  const message = `${options.action} for company ${companyText(profile.name, 'Unnamed')} (${options.id})${options.itemId ? `, pipeline item ${options.itemId}` : ''}.`;
+  if (!(await (dependencies.confirm || requireWriteConfirmation)(options, options.action.toUpperCase(), message))) return { unchanged: true, profileId: options.id, companyName: profile.name };
+  return companyRequest(options, body, fetchImpl);
+}
+
 function optionValue(argv, index, flag) {
   const value = argv[index + 1];
   if (!value || value.startsWith('--')) throw new Error(`${flag} requires a value`);
@@ -444,7 +568,11 @@ async function apiRequest(path, options = {}, fetchImpl = fetch) {
     },
   });
   const body = await response.json().catch(() => ({}));
-  if (!response.ok) throw new Error(body.error || `TenderLead API failed: ${response.status}`);
+  if (!response.ok) {
+    const error = new Error(body.error || `TenderLead API failed: ${response.status}`);
+    error.status = response.status;
+    throw error;
+  }
   return body;
 }
 
@@ -735,6 +863,7 @@ async function main() {
     console.log('TenderLead Settings opened. Sign in, create the required scoped token, then set TENDERLEAD_API_TOKEN in your shell.');
     return;
   }
+  if (options.command === 'companies') return printPayload(await runCompanyCommand(options), options.json, payload => formatCompanies(payload, options));
   if (options.command === 'whoami') return printPayload(await fetchWhoami(), options.json, formatWhoami);
   if (options.command === 'account') return printPayload(await fetchAccountStatus(), options.json, formatAccountStatus);
   if (options.command === 'brief') {
@@ -870,6 +999,7 @@ if (require.main === module) {
 }
 
 module.exports = {
+  parseCompanyArgs, validateCompanyBody, companyRequest, formatCompanies, runCompanyCommand,
   parseArgs, openLogin, fetchWhoami, fetchAccountStatus, formatWhoami, formatAccountStatus, formatBrief, formatTenders, formatScore, fetchBrief, searchTenders, scoreTender, fetchProfile, updateProfile,
   validateProfile, readProfileFile, profileTemplate, profileDiff, formatProfile,
   formatProfileDiff, confirmApply, confirmWord, readJsonFile, contentTypeForFile, appendFiles,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenderlead/cli",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "private": false,
   "description": "Run TenderLead tender, profile, pipeline, insight and bid-workspace workflows from the terminal",
   "homepage": "https://tenderlead.co.uk",