@velaro/cli 0.1.0

package/README.md

@@ -0,0 +1,138 @@
+# Velaro CLI
+
+Command-line interface for managing your Velaro account — bots, knowledge base ingestion, and MCP API keys.
+
+## Installation
+
+```bash
+npm install -g @velaro/cli
+```
+
+Or run without installing:
+
+```bash
+npx @velaro/cli login
+```
+
+> Requires Node.js 18 or later.
+
+## Authentication
+
+Velaro CLI uses your existing Velaro account — the same login you use in the admin portal. No separate API key or password required.
+
+```bash
+velaro login
+```
+
+This opens your browser to a short code page. Enter the code shown in the terminal, sign in with your Velaro account, and you're done. Your session is saved to `~/.velaro/config.json` and refreshes automatically — you won't need to log in again for months.
+
+```bash
+velaro logout     # clear saved credentials
+velaro whoami     # confirm who you're logged in as
+```
+
+## Commands
+
+### `velaro bot list`
+List all AI bots configured on your site.
+
+```
+[42] Support Bot    model=velaro-gpt-4o-mini  status=ready
+[43] Sales Bot      model=velaro-gpt-4o-mini  status=ready
+```
+
+### `velaro bot setup`
+Create or update an AI bot (upsert by name).
+
+```bash
+velaro bot setup \
+  --name "Support Bot" \
+  --prompt "You are a helpful support assistant for Acme Corp..." \
+  --tone Professional \
+  --reply-length Medium \
+  --urls "https://help.acme.com,https://acme.com/faq"
+```
+
+Options:
+| Flag | Description | Default |
+|---|---|---|
+| `--name` | Bot name (required) | — |
+| `--prompt` | System prompt | — |
+| `--model` | AI model | `velaro-gpt-4o-mini` |
+| `--tone` | `Professional`, `Friendly`, `Formal`, `Casual` | `Professional` |
+| `--reply-length` | `Short`, `Medium`, `Long` | `Medium` |
+| `--urls` | Comma-separated knowledge base URLs | — |
+
+### `velaro ingest --job-id <id>`
+Trigger knowledge base ingestion for a completed scraper job. The job runs in the background — embedding 50+ pages typically takes 1–2 minutes.
+
+```bash
+velaro ingest --job-id d2d93504
+```
+
+> Requires the **Knowledge Base** feature on your subscription.
+
+### `velaro mcp-key list`
+List MCP API keys for your site (used to connect AI tools like Claude).
+
+```
+[1] Claude Code    prefix=vel_live_aB4  active  last used=4/9/2026
+[2] Zapier         prefix=vel_live_xC7  active  last used=never
+```
+
+### `velaro mcp-key create --label <label>`
+Create a new MCP API key. The full key is shown **once** — copy it immediately.
+
+```bash
+velaro mcp-key create --label "Claude Code"
+velaro mcp-key create --label "Zapier" --expires 2027-01-01
+```
+
+### `velaro mcp-key revoke <id>`
+Revoke an MCP key by ID.
+
+```bash
+velaro mcp-key revoke 2
+```
+
+### `velaro status`
+Check that the Velaro API is reachable.
+
+```bash
+velaro status
+# Checking https://velaro-messaging-api-staging.azurewebsites.net/Status ... OK
+```
+
+## Environment variables
+
+| Variable | Description |
+|---|---|
+| `VELARO_API_BASE` | Override the API base URL (defaults to production) |
+| `VELARO_CLI_CLIENT_ID` | Override the Entra app ID (advanced) |
+
+## What the CLI can access
+
+The CLI operates under your Velaro account with the same permissions you have in the admin portal. It can only access **your own site's data** — it is not possible to read or modify another customer's account.
+
+Feature access is gated by your subscription plan:
+- **Bot setup** — requires the AI feature on your plan
+- **KB ingestion** — requires the Knowledge Base feature
+- **MCP keys** — requires the MCP API Access feature
+
+## Security
+
+- Login uses OAuth 2.0 device authorization (RFC 8628) — no password is ever stored
+- Credentials are saved to `~/.velaro/config.json` with owner-only permissions (`0600`)
+- Your Velaro JWT expires after 1 hour and is silently refreshed using a secure refresh token
+- All API calls go over HTTPS to `velaro-messaging-api.azurewebsites.net`
+
+## Publishing (internal)
+
+The CLI lives in `velaro-admin/cli/`. To publish to npm:
+
+```bash
+cd cli
+npm publish --access public
+```
+
+Requires `npm login` with the `@velaro` organization access.

package/bin/velaro.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+
+import yargs                                    from 'yargs';
+import { hideBin }                              from 'yargs/helpers';
+import { loginCommand, logoutCommand }          from '../lib/commands/login.js';
+import { whoamiCommand }                        from '../lib/commands/whoami.js';
+import { botCommand }                           from '../lib/commands/bot.js';
+import { ingestCommand }                        from '../lib/commands/ingest.js';
+import { mcpKeyCommand }                        from '../lib/commands/mcp-key.js';
+import { statusCommand }                        from '../lib/commands/status.js';
+
+yargs(hideBin(process.argv))
+  .scriptName('velaro')
+  .usage('$0 <command> [options]')
+  .command(loginCommand)
+  .command(logoutCommand)
+  .command(whoamiCommand)
+  .command(botCommand)
+  .command(ingestCommand)
+  .command(mcpKeyCommand)
+  .command(statusCommand)
+  .demandCommand(1, 'Specify a command. Run velaro --help for a list.')
+  .strict()
+  .help()
+  .alias('h', 'help')
+  .alias('v', 'version')
+  .wrap(Math.min(100, process.stdout.columns || 100))
+  .argv;

package/lib/api.js

@@ -0,0 +1,48 @@
+import { readConfig, writeConfig } from './config.js';
+import { refreshVelaroToken }       from './oauth.js';
+
+const REFRESH_BUFFER_MS = 5 * 60 * 1000;
+
+export async function getCredentials() {
+  let creds = readConfig();
+
+  if (!creds?.velaroToken) {
+    throw new Error('Not logged in. Run: velaro login');
+  }
+
+  if (Date.now() + REFRESH_BUFFER_MS >= new Date(creds.velaroExpires).getTime()) {
+    if (!creds.entraRefreshToken) {
+      throw new Error('Session expired. Run: velaro login');
+    }
+    creds = await refreshVelaroToken(creds);
+    writeConfig(creds);
+  }
+
+  return creds;
+}
+
+export async function request(method, path, body) {
+  const creds = await getCredentials();
+
+  const res = await fetch(`${creds.apiBase}${path}`, {
+    method,
+    headers: {
+      Authorization:  `Bearer ${creds.velaroToken}`,
+      'Content-Type': 'application/json',
+    },
+    body: body !== undefined ? JSON.stringify(body) : undefined,
+  });
+
+  if (!res.ok) {
+    let msg = `${method} ${path} → ${res.status}`;
+    try { const t = await res.text(); if (t) msg += `: ${t}`; } catch { /* body unreadable — status already captured */ }
+    throw new Error(msg);
+  }
+
+  const text = await res.text();
+  return text ? JSON.parse(text) : null;
+}
+
+export const get  = (path)       => request('GET',    path);
+export const post = (path, body) => request('POST',   path, body);
+export const del  = (path)       => request('DELETE', path);

package/lib/commands/bot.js

@@ -0,0 +1,54 @@
+import { get, post }  from '../api.js';
+import { runCommand } from '../run.js';
+
+export const botCommand = {
+  command:  'bot <subcommand>',
+  describe: 'Manage AI bots',
+  builder:  (yargs) =>
+    yargs
+      .command(botListCommand)
+      .command(botSetupCommand)
+      .demandCommand(1, 'Specify a subcommand: list, setup'),
+  handler: () => {},
+};
+
+const botListCommand = {
+  command:  'list',
+  describe: 'List AI bots on your site',
+  handler:  runCommand(async () => {
+    const bots = await get('/AIConfiguration/list');
+    if (!bots?.length) { console.log('No bots found.'); return; }
+    console.log(`Found ${bots.length} bot(s):\n`);
+    for (const b of bots) {
+      console.log(`  [${b.id}] ${b.name}  model=${b.aiModel ?? '(default)'}  status=${b.status ?? 'ready'}`);
+    }
+  }),
+};
+
+const botSetupCommand = {
+  command:  'setup',
+  describe: 'Create or update an AI bot (upsert by name)',
+  builder:  (y) =>
+    y
+      .option('name',         { describe: 'Bot name',                                                       type: 'string', demandOption: true })
+      .option('prompt',       { describe: 'System prompt text',                                              type: 'string' })
+      .option('model',        { describe: 'AI model override',                                               type: 'string', default: 'velaro-gpt-4o-mini' })
+      .option('tone',         { describe: 'Response tone',   choices: ['Professional','Friendly','Formal','Casual'], default: 'Professional' })
+      .option('reply-length', { describe: 'Response length', choices: ['Short','Medium','Long'],                     default: 'Medium' })
+      .option('urls',         { describe: 'Comma-separated data source URLs',                                type: 'string' }),
+
+  handler: runCommand(async (argv) => {
+    const payload = {
+      name:        argv.name,
+      aiModel:     argv.model,
+      tone:        argv.tone,
+      replyLength: argv['reply-length'],
+    };
+
+    if (argv.prompt) payload.prompt    = argv.prompt;
+    if (argv.urls)   payload.dataUrls  = argv.urls.split(',').map((u) => u.trim()).filter(Boolean);
+
+    const result = await post('/AIConfiguration', payload);
+    console.log(`Saved: [${result.id}] ${result.name}`);
+  }),
+};

package/lib/commands/ingest.js

@@ -0,0 +1,31 @@
+import { getCredentials, post } from '../api.js';
+import { runCommand }           from '../run.js';
+
+export const ingestCommand = {
+  command:  'ingest',
+  describe: 'Trigger knowledge base ingestion for a completed scraper job',
+  builder:  (y) =>
+    y.option('job-id', {
+      describe:     'Scraper job ID to ingest',
+      type:         'string',
+      demandOption: true,
+    }),
+
+  handler: runCommand(async (argv) => {
+    // Single credential resolution — avoids double readConfig() from calling readConfig()
+    // here and again inside post() → getCredentials().
+    const creds = await getCredentials();
+
+    console.log(`Triggering ingestion for job ${argv['job-id']} on site ${creds.siteId}...`);
+
+    const result = await post('/AzureIndexes/IngestJobDirect', {
+      siteId: creds.siteId,
+      jobId:  argv['job-id'],
+    });
+
+    console.log('Ingestion started.');
+    console.log(`  Job ID: ${result.jobId}`);
+    console.log(`  Index:  ${result.physicalIndex}`);
+    console.log('\nEmbedding runs in the background. Check logs for completion.');
+  }),
+};

package/lib/commands/login.js

@@ -0,0 +1,53 @@
+import { requestDeviceCode, pollForToken, exchangeForVelaroToken } from '../oauth.js';
+import { readConfig, writeConfig, DEFAULT_API_BASE }               from '../config.js';
+import { runCommand }                                               from '../run.js';
+
+export const loginCommand = {
+  command:  'login',
+  describe: 'Authenticate with Velaro using your browser',
+  builder:  (y) =>
+    y.option('api', {
+      describe: 'Velaro Messaging API base URL',
+      default:  DEFAULT_API_BASE,
+      type:     'string',
+    }),
+
+  handler: runCommand(async (argv) => {
+    const apiBase = argv.api;
+
+    console.log('Starting Velaro login...\n');
+
+    const deviceData = await requestDeviceCode();
+
+    console.log(`  Open:  ${deviceData.verification_uri}`);
+    console.log(`  Enter: ${deviceData.user_code}\n`);
+    console.log('Waiting for you to complete login in your browser...');
+
+    const entraTokens  = await pollForToken(deviceData.device_code, deviceData.interval ?? 5);
+    const velaroResult = await exchangeForVelaroToken(entraTokens.access_token, apiBase);
+
+    writeConfig({
+      ...readConfig(),
+      apiBase,
+      velaroToken:       velaroResult.token.token,
+      velaroExpires:     velaroResult.token.expires,
+      entraRefreshToken: entraTokens.refresh_token,
+      siteId:            velaroResult.profile?.SiteId,
+      userName:          velaroResult.profile?.Name,
+    });
+
+    console.log(`\nLogged in as ${velaroResult.profile?.Name ?? velaroResult.profile?.UserName}`);
+    console.log(`Site ID: ${velaroResult.profile?.SiteId}`);
+    console.log('Credentials saved to ~/.velaro/config.json');
+  }),
+};
+
+export const logoutCommand = {
+  command:  'logout',
+  describe: 'Clear stored credentials',
+  handler:  runCommand(async () => {
+    const { clearConfig } = await import('../config.js');
+    clearConfig();
+    console.log('Logged out. Credentials removed from ~/.velaro/config.json');
+  }),
+};

package/lib/commands/mcp-key.js

@@ -0,0 +1,63 @@
+import { get, post, del } from '../api.js';
+import { runCommand }      from '../run.js';
+
+export const mcpKeyCommand = {
+  command:  'mcp-key <subcommand>',
+  describe: 'Manage MCP API keys (vel_live_* keys for AI skill access)',
+  builder:  (yargs) =>
+    yargs
+      .command(mcpKeyListCommand)
+      .command(mcpKeyCreateCommand)
+      .command(mcpKeyRevokeCommand)
+      .demandCommand(1, 'Specify a subcommand: list, create, revoke'),
+  handler: () => {},
+};
+
+const mcpKeyListCommand = {
+  command:  'list',
+  describe: 'List MCP API keys for your site',
+  handler:  runCommand(async () => {
+    const keys = await get('/McpApiKeys');
+    if (!keys?.length) { console.log('No MCP keys found.'); return; }
+    console.log(`Found ${keys.length} key(s):\n`);
+    for (const k of keys) {
+      const used = k.lastUsedAt ? new Date(k.lastUsedAt).toLocaleDateString() : 'never';
+      console.log(`  [${k.id}] ${k.label}  prefix=${k.keyPrefix}  ${k.isActive ? 'active' : 'revoked'}  last used=${used}`);
+    }
+  }),
+};
+
+const mcpKeyCreateCommand = {
+  command:  'create',
+  describe: 'Create a new MCP API key',
+  builder:  (y) =>
+    y
+      .option('label', {
+        describe:     'Human-readable label (e.g. "Claude Code")',
+        type:         'string',
+        demandOption: true,
+      })
+      .option('expires', {
+        describe: 'Expiry date in ISO 8601 format (e.g. 2027-01-01)',
+        type:     'string',
+      }),
+
+  handler: runCommand(async (argv) => {
+    const payload = { label: argv.label };
+    if (argv.expires) payload.expiresAt = new Date(argv.expires).toISOString();
+
+    const result = await post('/McpApiKeys', payload);
+    console.log(`MCP key created for: ${result.label}`);
+    console.log(`\n  Key: ${result.rawKey}`);
+    console.log(`\n  ${result.warning ?? 'Copy this key now — it will not be shown again.'}`);
+  }),
+};
+
+const mcpKeyRevokeCommand = {
+  command:  'revoke <id>',
+  describe: 'Revoke an MCP API key by ID',
+  handler:  runCommand(async (argv) => {
+    await del(`/McpApiKeys/${argv.id}`);
+    console.log(`Key ${argv.id} revoked.`);
+  }),
+};

package/lib/commands/status.js

@@ -0,0 +1,22 @@
+import { readConfig, DEFAULT_API_BASE } from '../config.js';
+
+export const statusCommand = {
+  command:  'status',
+  describe: 'Check Velaro API health',
+  handler:  async () => {
+    const apiBase = readConfig()?.apiBase ?? DEFAULT_API_BASE;
+    process.stdout.write(`Checking ${apiBase}/Status ... `);
+    try {
+      const res = await fetch(`${apiBase}/Status`);
+      if (res.ok) {
+        console.log('OK');
+      } else {
+        console.log(`DEGRADED (HTTP ${res.status})`);
+        process.exit(1);
+      }
+    } catch (err) {
+      console.log(`UNREACHABLE: ${err.message}`);
+      process.exit(1);
+    }
+  },
+};

package/lib/commands/whoami.js

@@ -0,0 +1,22 @@
+import { readConfig } from '../config.js';
+
+export const whoamiCommand = {
+  command:  'whoami',
+  describe: 'Show current login and site info',
+  handler:  () => {
+    const cfg = readConfig();
+
+    if (!cfg?.velaroToken) {
+      console.error('Not logged in. Run: velaro login');
+      process.exit(1);
+    }
+
+    const expires = new Date(cfg.velaroExpires);
+    const minLeft = Math.round((expires - Date.now()) / 60000);
+
+    console.log(`User:    ${cfg.userName ?? '(unknown)'}`);
+    console.log(`Site ID: ${cfg.siteId   ?? '(unknown)'}`);
+    console.log(`API:     ${cfg.apiBase}`);
+    console.log(`Token:   ${expires > new Date() ? `valid (expires in ${minLeft}m)` : 'EXPIRED — run velaro login'}`);
+  },
+};

package/lib/config.js

@@ -0,0 +1,25 @@
+import { homedir } from 'os';
+import { join }    from 'path';
+import { readFileSync, writeFileSync, mkdirSync } from 'fs';
+
+const CONFIG_DIR  = join(homedir(), '.velaro');
+const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+
+export const DEFAULT_API_BASE = 'https://velaro-messaging-api.azurewebsites.net';
+
+export function readConfig() {
+  try {
+    return JSON.parse(readFileSync(CONFIG_FILE, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+export function writeConfig(data) {
+  mkdirSync(CONFIG_DIR, { recursive: true }); // no-op if already exists
+  writeFileSync(CONFIG_FILE, JSON.stringify(data, null, 2), { mode: 0o600 });
+}
+
+export function clearConfig() {
+  writeConfig({});
+}

package/lib/oauth.js

@@ -0,0 +1,134 @@
+/**
+ * OAuth 2.0 device authorization flow (RFC 8628) against the Velaro Entra CIAM tenant.
+ *
+ * Flow:
+ *   1. POST /devicecode  → get user_code + verification_uri
+ *   2. Show the user the code; poll /token until granted
+ *   3. Exchange the Entra access_token for a Velaro JWT via /auth/entra/token
+ *   4. Store { velaroToken, velaroExpires, entraRefreshToken } in ~/.velaro/config.json
+ *
+ * Refresh:
+ *   When the Velaro JWT is within 5 minutes of expiring, silently use the stored
+ *   Entra refresh_token to get a new access_token and re-exchange for a new Velaro JWT.
+ *
+ * One-time setup (run once in the Velaro CIAM tenant):
+ *   az login --tenant 61de45b3-458d-49a5-913c-501247a6fe4f --allow-no-subscriptions
+ *   az ad app create --display-name "Velaro CLI" --sign-in-audience AzureADMyOrg \
+ *     --public-client-redirect-uris "https://login.microsoftonline.com/common/oauth2/nativeclient"
+ *   az ad app update --id <appId> --set isFallbackPublicClient=true
+ *   # Grant admin consent in Azure Portal:
+ *   #   api://89bd2fb7-7020-4cfe-a153-1c1ee37903c2/access_as_user (Delegated)
+ *   # Then set VELARO_CLI_CLIENT_ID=<appId> or update the constant below.
+ */
+
+const TENANT_ID  = '61de45b3-458d-49a5-913c-501247a6fe4f';
+const AUTHORITY  = `https://login.microsoftonline.com/${TENANT_ID}`;
+const CLIENT_ID  = process.env.VELARO_CLI_CLIENT_ID || 'c0fdce54-e9b4-4427-a021-b2605855ff8b';
+
+const SCOPE = [
+  'api://89bd2fb7-7020-4cfe-a153-1c1ee37903c2/access_as_user',
+  'offline_access',
+  'openid',
+  'profile',
+  'email',
+].join(' ');
+
+const DEVICE_CODE_URL = `${AUTHORITY}/oauth2/v2.0/devicecode`;
+const TOKEN_URL       = `${AUTHORITY}/oauth2/v2.0/token`;
+const FETCH_TIMEOUT   = 10_000;
+
+export async function requestDeviceCode() {
+  const res = await fetch(DEVICE_CODE_URL, {
+    method:  'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body:    new URLSearchParams({ client_id: CLIENT_ID, scope: SCOPE }),
+    signal:  AbortSignal.timeout(FETCH_TIMEOUT),
+  });
+
+  const data = await res.json();
+  if (data.error) throw new Error(`Device code request failed: ${data.error_description || data.error}`);
+  return data; // { device_code, user_code, verification_uri, expires_in, interval, message }
+}
+
+export async function pollForToken(deviceCode, intervalSeconds) {
+  let interval = intervalSeconds;
+
+  while (true) {
+    const res = await fetch(TOKEN_URL, {
+      method:  'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body:    new URLSearchParams({
+        grant_type:  'urn:ietf:params:oauth:grant-type:device_code',
+        client_id:   CLIENT_ID,
+        device_code: deviceCode,
+      }),
+      signal: AbortSignal.timeout(FETCH_TIMEOUT),
+    });
+
+    const data = await res.json();
+
+    if (data.access_token) return data; // { access_token, refresh_token, expires_in }
+
+    if (data.error === 'authorization_pending') {
+      // normal — keep waiting
+    } else if (data.error === 'slow_down') {
+      interval += 5 + Math.random() * 2; // RFC 8628 §3.5 — add jitter to avoid lockstep
+    } else if (data.error === 'expired_token') {
+      throw new Error('Login timed out — please run velaro login again.');
+    } else if (data.error === 'access_denied') {
+      throw new Error('Login cancelled.');
+    } else {
+      throw new Error(data.error_description || data.error);
+    }
+
+    await sleep(interval * 1000); // sleep at end so first attempt fires immediately
+  }
+}
+
+export async function exchangeForVelaroToken(entraAccessToken, apiBase) {
+  const res = await fetch(`${apiBase}/auth/entra/token`, {
+    method:  'POST',
+    headers: { Authorization: `Bearer ${entraAccessToken}` },
+    signal:  AbortSignal.timeout(FETCH_TIMEOUT),
+  });
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => res.status.toString());
+    throw new Error(`Velaro token exchange failed (${res.status}): ${body}`);
+  }
+
+  return res.json(); // { token: { token, expires }, profile: { SiteId, Name, UserName, ... } }
+}
+
+export async function refreshVelaroToken(credentials) {
+  const res = await fetch(TOKEN_URL, {
+    method:  'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body:    new URLSearchParams({
+      grant_type:    'refresh_token',
+      client_id:     CLIENT_ID,
+      refresh_token: credentials.entraRefreshToken,
+    }),
+    signal: AbortSignal.timeout(FETCH_TIMEOUT),
+  });
+
+  const data = await res.json();
+  if (!data.access_token) {
+    throw new Error(`Token refresh failed: ${data.error_description || data.error}`);
+  }
+
+  const velaro = await exchangeForVelaroToken(data.access_token, credentials.apiBase);
+
+  return {
+    ...credentials,
+    velaroToken:       velaro.token.token,
+    velaroExpires:     velaro.token.expires,
+    entraRefreshToken: data.refresh_token || credentials.entraRefreshToken,
+    siteId:            velaro.profile?.SiteId ?? credentials.siteId,
+    userName:          velaro.profile?.Name   ?? credentials.userName,
+  };
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/lib/run.js

@@ -0,0 +1,11 @@
+/** Wraps a yargs command handler with consistent error reporting. */
+export function runCommand(fn) {
+  return async (argv) => {
+    try {
+      await fn(argv);
+    } catch (err) {
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
+    }
+  };
+}

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@velaro/cli",
+  "version": "0.1.0",
+  "description": "Velaro Workspace v20 — command-line interface for managing bots, knowledge base ingestion, and MCP API keys.",
+  "type": "module",
+  "bin": {
+    "velaro": "bin/velaro.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "yargs": "^17.7.2"
+  },
+  "files": [
+    "bin/",
+    "lib/"
+  ]
+}