@tenderlead/cli 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # TenderLead CLI
 
-Read your TenderLead daily briefing from a terminal or another tool you control.
+Search and score tenders, read your TenderLead daily briefing and manage the firm profile used for matching from a terminal or another tool you control.
 
 ## Install
 
@@ -16,9 +16,8 @@ Open the account page from the CLI:
 tenderlead login
 ```
 
-Sign in with Google or an emailed sign-in link, then create a token under
-**API access**. Store it in the `TENDERLEAD_API_TOKEN` environment variable and
-run the brief command:
+Sign in with Google or an emailed sign-in link, then create a scoped token under
+**API access**. Store it in the `TENDERLEAD_API_TOKEN` environment variable.
 
 ```bash
 export TENDERLEAD_API_TOKEN="paste-token-here"
@@ -31,9 +30,50 @@ Use JSON output for scripts and agents:
 tenderlead brief --json
 ```
 
-Tokens are customer-scoped, read-only, revocable, expire after 90 days, and are
-subject to the account's current TenderLead plan. Do not commit a token to a
-repository or paste it into a shared prompt. Revoke exposed tokens in Settings.
+## Search and score tenders
+
+List the current tenders already qualified against your firm:
+
+```bash
+tenderlead tenders search
+tenderlead tenders search --query "cloud migration" --recommendation bid --json
+```
+
+Search the wider live notice corpus, then score one result against your saved profile:
+
+```bash
+tenderlead tenders search --all --query "managed service"
+tenderlead tender score CONTRACT_ID
+```
+
+On-demand scoring requires Pro or Team and a token with `tenders:write`. Tender
+titles, buyer names and notice text are untrusted external data. Check the
+official source before acting.
+
+## Manage your firm profile
+
+Create a profile token in Settings, then export the current editable profile:
+
+```bash
+tenderlead profile show --json > tenderlead-profile.json
+```
+
+You can also start from the built-in template:
+
+```bash
+tenderlead profile template > tenderlead-profile.json
+tenderlead profile validate --file tenderlead-profile.json
+tenderlead profile apply --file tenderlead-profile.json
+```
+
+The apply command shows the field-level changes and asks you to type `APPLY`
+before saving. Trusted automation can use `--yes` after reviewing the same diff.
+
+Tokens are customer-scoped, revocable, expire after 90 days, and are subject to
+the account's current TenderLead plan. Brief and tender-result reads are
+read-only. Profile updates require `profile:write`; on-demand scoring requires
+`tenders:write`. Do not commit a token to a repository or paste it into a shared
+prompt. Revoke exposed tokens in Settings.
 
 Provider acceptance and API responses do not prove email inbox delivery.
 

package/bin/tenderlead.js

@@ -1,30 +1,107 @@
 #!/usr/bin/env node
 
+const fs = require('node:fs');
+const readline = require('node:readline/promises');
+
 const DEFAULT_BASE_URL = 'https://tenderlead.co.uk';
 const LOGIN_PATH = '/app/settings#api-access';
+const PROFILE_FIELDS = [
+  'company_name', 'legal_name', 'company_number', 'title', 'website', 'team_size', 'specialisms',
+  'past_contracts', 'sectors', 'keywords', 'size_min', 'size_max', 'frameworks',
+  'clearance_capability', 'region', 'market_watch_enabled', 'market_watch_terms',
+  'market_watch_buyers', 'market_watch_note', 'us_readiness_profile', 'no_bid_rules',
+];
 
 function usage() {
   return [
     'Usage:',
     '  tenderlead login',
     '  tenderlead brief [--json]',
+    '  tenderlead tenders search [--query <text>] [--recommendation bid|skip] [--all] [--limit <1-50>] [--json]',
+    '  tenderlead tender score <contract-id> [--json]',
+    '  tenderlead profile show [--json]',
+    '  tenderlead profile template',
+    '  tenderlead profile validate --file <path>',
+    '  tenderlead profile apply --file <path> [--yes]',
     '',
-    'Login opens TenderLead Settings so you can create a customer-scoped token.',
-    'Set TENDERLEAD_API_TOKEN to that token before running brief.',
+    'Login opens TenderLead Settings so you can create a scoped CLI token.',
+    'Set TENDERLEAD_API_TOKEN to that token before reading or updating account data.',
   ].join('\n');
 }
 
 function parseArgs(argv) {
   const command = argv[2];
   if (command === 'login') return { command: 'login' };
-  if (command !== 'brief') throw new Error('Use the login or brief command.');
-  const options = { command: 'brief', json: false };
-  for (let index = 3; index < argv.length; index += 1) {
+  if (command === 'brief') {
+    const options = { command: 'brief', json: false };
+    for (let index = 3; index < argv.length; index += 1) {
+      const arg = argv[index];
+      if (arg === '--json') options.json = true;
+      else if (arg === '--help' || arg === '-h') options.help = true;
+      else throw new Error(`Unknown argument: ${arg}`);
+    }
+    return options;
+  }
+  if (command === 'tenders') {
+    if (argv[3] !== 'search') throw new Error('Use tenders search.');
+    const options = { command: 'tenders', action: 'search', query: '', recommendation: '', all: false, limit: 20, json: false };
+    for (let index = 4; index < argv.length; index += 1) {
+      const arg = argv[index];
+      if (arg === '--json') options.json = true;
+      else if (arg === '--all') options.all = true;
+      else if (arg === '--query' || arg === '--recommendation' || arg === '--limit') {
+        const value = argv[index + 1];
+        if (!value || value.startsWith('--')) throw new Error(`${arg} requires a value`);
+        if (arg === '--query') options.query = value;
+        if (arg === '--recommendation') {
+          if (!['bid', 'skip'].includes(value)) throw new Error('--recommendation must be bid or skip');
+          options.recommendation = value;
+        }
+        if (arg === '--limit') {
+          const limit = Number(value);
+          if (!Number.isInteger(limit) || limit < 1 || limit > 50) throw new Error('--limit must be an integer from 1 to 50');
+          options.limit = limit;
+        }
+        index += 1;
+      } else if (arg === '--help' || arg === '-h') options.help = true;
+      else throw new Error(`Unknown argument: ${arg}`);
+    }
+    if (options.all && options.recommendation) throw new Error('--recommendation applies only to scored matches; remove --all');
+    return options;
+  }
+  if (command === 'tender') {
+    if (argv[3] !== 'score') throw new Error('Use tender score <contract-id>.');
+    const contractId = argv[4];
+    if (!contractId || contractId.startsWith('--')) throw new Error('tender score requires a contract ID');
+    const options = { command: 'tender', action: 'score', contractId, json: false };
+    for (let index = 5; index < argv.length; index += 1) {
+      const arg = argv[index];
+      if (arg === '--json') options.json = true;
+      else if (arg === '--help' || arg === '-h') options.help = true;
+      else throw new Error(`Unknown argument: ${arg}`);
+    }
+    return options;
+  }
+  if (command !== 'profile') throw new Error('Use the login, brief, tenders, tender or profile command.');
+
+  const action = argv[3];
+  if (!['show', 'template', 'validate', 'apply'].includes(action)) {
+    throw new Error('Use profile show, template, validate or apply.');
+  }
+  const options = { command: 'profile', action, json: false, file: null, yes: false };
+  for (let index = 4; index < argv.length; index += 1) {
     const arg = argv[index];
-    if (arg === '--json') options.json = true;
-    else if (arg === '--help' || arg === '-h') options.help = true;
+    if (arg === '--json' && action === 'show') options.json = true;
+    else if (arg === '--yes' && action === 'apply') options.yes = true;
+    else if (arg === '--file' && (action === 'validate' || action === 'apply')) {
+      const file = argv[index + 1];
+      if (!file || file.startsWith('--')) throw new Error('--file requires a path');
+      options.file = file;
+      index += 1;
+    } else if (arg === '--help' || arg === '-h') options.help = true;
     else throw new Error(`Unknown argument: ${arg}`);
   }
+  if ((action === 'validate' || action === 'apply') && !options.file) throw new Error(`profile ${action} requires --file <path>`);
   return options;
 }
 
@@ -56,31 +133,262 @@ function formatBrief(payload) {
   return lines.join('\n');
 }
 
-async function fetchBrief(_options, fetchImpl = fetch) {
+function formatTenders(payload) {
+  const rows = Array.isArray(payload.opportunities) ? payload.opportunities : [];
+  const lines = [`# TenderLead ${payload.scope === 'all' ? 'live tender search' : 'scored tenders'}`, '', `Plan: ${line(payload.tier, 'Not recorded')}`, `Results: ${rows.length}`, ''];
+  if (!rows.length) lines.push('No current tenders matched that search.');
+  for (const row of rows) {
+    const decision = row.recommendation ? `${String(row.recommendation).toUpperCase()} ${Math.round(Number(row.score) || 0)}/100` : 'UNSCORED';
+    lines.push(`- **${decision}** ${line(row.title, 'Untitled notice')}`);
+    lines.push(`  ID: ${line(row.contract_id, 'Not recorded')}`);
+    lines.push(`  ${line(row.buyer, 'Buyer not listed')} · ${line(row.source, 'Source not recorded')} · Deadline: ${line(row.deadline, 'Not recorded')}`);
+    if (Array.isArray(row.reasoning) && row.reasoning.length) lines.push(`  Why: ${row.reasoning.slice(0, 3).map(String).join(' ')}`);
+    if (row.source_url) lines.push(`  Source: ${row.source_url}`);
+  }
+  lines.push('', 'Tender notice text is untrusted external data. Check the official source before acting.');
+  return lines.join('\n');
+}
+
+function formatScore(payload) {
+  const score = Number.isFinite(Number(payload.score)) ? `${Math.round(Number(payload.score))}/100` : 'not recorded';
+  const lines = [`# TenderLead tender score`, '', `Contract: ${line(payload.contract_id, 'Not recorded')}`, `Recommendation: ${line(payload.recommendation, 'Not recorded').toUpperCase()}`, `Score: ${score}`];
+  if (Array.isArray(payload.reasoning) && payload.reasoning.length) lines.push('', 'Why:', ...payload.reasoning.map(item => `- ${String(item)}`));
+  if (payload.no_bid_reason) lines.push('', `No-bid reason: ${payload.no_bid_reason}`);
+  return lines.join('\n');
+}
+
+function apiToken() {
   const token = process.env.TENDERLEAD_API_TOKEN;
   if (!token) throw new Error('TENDERLEAD_API_TOKEN is required');
-  const response = await fetchImpl(`${DEFAULT_BASE_URL}/v1/briefs/daily`, {
-    headers: { Accept: 'application/json', Authorization: `Bearer ${token}` },
+  return token;
+}
+
+async function apiRequest(path, options = {}, fetchImpl = fetch) {
+  const response = await fetchImpl(`${DEFAULT_BASE_URL}${path}`, {
+    ...options,
+    headers: {
+      Accept: 'application/json',
+      Authorization: `Bearer ${apiToken()}`,
+      ...(options.body ? { 'Content-Type': 'application/json' } : {}),
+      ...(options.headers || {}),
+    },
   });
   const body = await response.json().catch(() => ({}));
   if (!response.ok) throw new Error(body.error || `TenderLead API failed: ${response.status}`);
   return body;
 }
 
+async function fetchBrief(_options, fetchImpl = fetch) {
+  return apiRequest('/v1/briefs/daily', {}, fetchImpl);
+}
+
+async function searchTenders(options, fetchImpl = fetch) {
+  const params = new URLSearchParams({ limit: String(options.limit || 20) });
+  if (options.query) params.set('query', options.query);
+  if (options.recommendation) params.set('recommendation', options.recommendation);
+  if (options.all) params.set('scope', 'all');
+  return apiRequest(`/v1/tenders?${params.toString()}`, {}, fetchImpl);
+}
+
+async function scoreTender(contractId, fetchImpl = fetch) {
+  return apiRequest(`/v1/tenders/${encodeURIComponent(contractId)}/score`, { method: 'POST' }, fetchImpl);
+}
+
+async function fetchProfile(fetchImpl = fetch) {
+  const payload = await apiRequest('/v1/profile', {}, fetchImpl);
+  return payload.profile || {};
+}
+
+async function updateProfile(profile, fetchImpl = fetch) {
+  const payload = await apiRequest('/v1/profile', { method: 'PATCH', body: JSON.stringify(profile) }, fetchImpl);
+  return payload.profile || {};
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function validateProfile(profile) {
+  if (!isPlainObject(profile)) throw new Error('Profile must be a JSON object');
+  const keys = Object.keys(profile);
+  if (!keys.length) throw new Error('Profile must contain at least one editable field');
+  const unknown = keys.find(key => !PROFILE_FIELDS.includes(key));
+  if (unknown) throw new Error(`Unsupported profile field: ${unknown}`);
+
+  const stringCaps = {
+    company_name: 200, legal_name: 200, company_number: 40, title: 100, website: 300,
+    team_size: 20, specialisms: 2000, region: 40, market_watch_note: 600,
+  };
+  for (const [field, cap] of Object.entries(stringCaps)) {
+    if (!(field in profile)) continue;
+    if (profile[field] !== null && typeof profile[field] !== 'string') throw new Error(`${field} must be a string`);
+    if (typeof profile[field] === 'string' && profile[field].length > cap) throw new Error(`${field} exceeds ${cap} chars`);
+  }
+
+  const arrayCaps = {
+    sectors: [15, 50], keywords: [50, 60], frameworks: [15, 40], clearance_capability: [5, 40],
+    market_watch_terms: [30, 80], market_watch_buyers: [20, 120], no_bid_rules: [20, 160],
+  };
+  for (const [field, limits] of Object.entries(arrayCaps)) {
+    if (!(field in profile)) continue;
+    const value = profile[field];
+    if (!Array.isArray(value)) throw new Error(`${field} must be an array`);
+    if (value.length > limits[0]) throw new Error(`${field} exceeds ${limits[0]} items`);
+    for (const item of value) {
+      if (typeof item !== 'string') throw new Error(`${field} items must be strings`);
+      if (item.length > limits[1]) throw new Error(`${field} item exceeds ${limits[1]} chars`);
+    }
+  }
+
+  if ('past_contracts' in profile) {
+    if (!Array.isArray(profile.past_contracts)) throw new Error('past_contracts must be an array');
+    if (profile.past_contracts.length > 5) throw new Error('past_contracts exceeds 5 items');
+    for (const item of profile.past_contracts) {
+      if (!isPlainObject(item)) throw new Error('past_contracts items must be objects');
+      if (item.title !== undefined && (typeof item.title !== 'string' || item.title.length > 200)) throw new Error('past_contracts.title must be a string of at most 200 chars');
+      if (item.value !== undefined && (typeof item.value !== 'string' || item.value.length > 60)) throw new Error('past_contracts.value must be a string of at most 60 chars');
+      if (item.won !== undefined && (typeof item.won !== 'string' || item.won.length > 20)) throw new Error('past_contracts.won must be a string of at most 20 chars');
+    }
+  }
+  if ('market_watch_enabled' in profile && typeof profile.market_watch_enabled !== 'boolean') throw new Error('market_watch_enabled must be a boolean');
+  if ('us_readiness_profile' in profile && !isPlainObject(profile.us_readiness_profile)) throw new Error('us_readiness_profile must be an object');
+  for (const field of ['size_min', 'size_max']) {
+    if (field in profile && !Number.isFinite(Number(profile[field]))) throw new Error(`${field} must be a number`);
+  }
+  if ('size_min' in profile && 'size_max' in profile) {
+    if (Number(profile.size_min) >= Number(profile.size_max)) throw new Error('size_min must be less than size_max');
+    if (Number(profile.size_min) < 0 || Number(profile.size_max) > 1_000_000_000) throw new Error('size out of range');
+  }
+  return profile;
+}
+
+function readProfileFile(file, readFileImpl = fs.readFileSync) {
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileImpl(file, 'utf8'));
+  } catch (error) {
+    if (error instanceof SyntaxError) throw new Error(`Profile file is not valid JSON: ${error.message}`);
+    throw new Error(`Could not read profile file: ${error.message}`);
+  }
+  return validateProfile(parsed);
+}
+
+function profileTemplate() {
+  return {
+    company_name: 'Example Ltd',
+    website: 'https://example.co.uk',
+    specialisms: 'Describe the services and delivery strengths buyers should match.',
+    sectors: ['software'],
+    keywords: ['cloud migration', 'managed service'],
+    size_min: 50000,
+    size_max: 500000,
+    frameworks: [],
+    region: 'national',
+    no_bid_rules: [],
+  };
+}
+
+function profileDiff(current, proposed) {
+  return Object.keys(proposed).filter(key => JSON.stringify(current[key]) !== JSON.stringify(proposed[key])).map(key => ({
+    field: key,
+    before: current[key],
+    after: proposed[key],
+  }));
+}
+
+function displayValue(value) {
+  if (value === undefined) return '(not set)';
+  return JSON.stringify(value);
+}
+
+function formatProfile(profile) {
+  const lines = ['# TenderLead profile', ''];
+  for (const field of PROFILE_FIELDS) {
+    if (profile[field] !== undefined) lines.push(`${field}: ${displayValue(profile[field])}`);
+  }
+  return lines.join('\n');
+}
+
+function formatProfileDiff(changes) {
+  if (!changes.length) return 'No profile changes.';
+  return ['Profile changes:', ...changes.map(change => `- ${change.field}: ${displayValue(change.before)} -> ${displayValue(change.after)}`)].join('\n');
+}
+
+async function confirmApply(input = process.stdin, output = process.stdout) {
+  const prompt = readline.createInterface({ input, output });
+  try {
+    return (await prompt.question('Type APPLY to save these profile changes: ')).trim() === 'APPLY';
+  } finally {
+    prompt.close();
+  }
+}
+
 async function main() {
   if (process.argv.includes('--help') || process.argv.includes('-h')) return console.log(usage());
   const options = parseArgs(process.argv);
   if (options.command === 'login') {
     openLogin();
-    console.log('TenderLead Settings opened. Sign in, create a CLI token, then set TENDERLEAD_API_TOKEN in your shell.');
+    console.log('TenderLead Settings opened. Sign in, create the required scoped token, then set TENDERLEAD_API_TOKEN in your shell.');
+    return;
+  }
+  if (options.command === 'brief') {
+    const brief = await fetchBrief(options);
+    console.log(options.json ? JSON.stringify(brief, null, 2) : formatBrief(brief));
+    return;
+  }
+  if (options.command === 'tenders') {
+    const result = await searchTenders(options);
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatTenders(result));
+    return;
+  }
+  if (options.command === 'tender') {
+    const result = await scoreTender(options.contractId);
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatScore(result));
     return;
   }
-  const brief = await fetchBrief(options);
-  console.log(options.json ? JSON.stringify(brief, null, 2) : formatBrief(brief));
+  if (options.action === 'template') {
+    console.log(JSON.stringify(profileTemplate(), null, 2));
+    return;
+  }
+  if (options.action === 'validate') {
+    readProfileFile(options.file);
+    console.log('Profile JSON is valid.');
+    return;
+  }
+  if (options.action === 'show') {
+    const profile = await fetchProfile();
+    console.log(options.json ? JSON.stringify(profile, null, 2) : formatProfile(profile));
+    return;
+  }
+
+  const proposed = readProfileFile(options.file);
+  const current = await fetchProfile();
+  if ('size_min' in proposed || 'size_max' in proposed) {
+    validateProfile({
+      size_min: 'size_min' in proposed ? proposed.size_min : current.size_min,
+      size_max: 'size_max' in proposed ? proposed.size_max : current.size_max,
+    });
+  }
+  const changes = profileDiff(current, proposed);
+  console.log(formatProfileDiff(changes));
+  if (!changes.length) return;
+  if (!options.yes) {
+    if (!process.stdin.isTTY) throw new Error('Interactive confirmation requires a terminal. Re-run with --yes after reviewing the diff.');
+    if (!(await confirmApply())) {
+      console.log('Profile unchanged.');
+      return;
+    }
+  }
+  await updateProfile(proposed);
+  console.log(`Saved ${changes.length} profile change${changes.length === 1 ? '' : 's'}.`);
 }
 
 if (require.main === module) {
   main().catch((error) => { console.error(error.message); process.exitCode = 1; });
 }
 
-module.exports = { parseArgs, openLogin, formatBrief, fetchBrief };
+module.exports = {
+  parseArgs, openLogin, formatBrief, formatTenders, formatScore, fetchBrief, searchTenders, scoreTender, fetchProfile, updateProfile,
+  validateProfile, readProfileFile, profileTemplate, profileDiff, formatProfile,
+  formatProfileDiff, confirmApply,
+};

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@tenderlead/cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": false,
-  "description": "Read-only TenderLead daily briefing CLI",
+  "description": "Search and score tenders, read briefings and manage your firm profile from the terminal",
   "homepage": "https://tenderlead.co.uk",
   "files": [
     "bin",