quoxcli 0.0.0-stage → 0.3.1

package/lib/commands/tg.js

@@ -0,0 +1,240 @@
+/**
+ * Telegram Pro commands (QTG-PRO P0 CLI parity): onboarding status, owner
+ * binding, session leases, and webhook admin.
+ *
+ * quox tg status [--bot <botId>]
+ * quox tg bind-owner <tg_chat_id> [--bot <botId>]
+ * quox tg leases
+ * quox tg webhook-info [--bot <botId>]
+ * quox tg setup <webhook_url> [--bot <botId>]
+ *
+ * Backend: services/collector/server.js (QTG-PRO P0 sections) — every route
+ * is collector-direct (no org segment in the URL), requireServiceOrUserAuth()
+ * gated. Onboarding handler bodies live in
+ * services/collector/lib/telegramPro/onboardingService.js (getOnboardingStatus,
+ * bindOwner); session leases in services/collector/lib/telegramPro/sessionLeaseStore.js;
+ * webhook admin reuses the existing /webhook/telegram/* routes shared with
+ * the original Telegram integration setup flow.
+ *
+ * bind-owner 409s when a primary owner binding already exists for the
+ * bot/chat/thread — mirrored on the quoxchat `reply` 409 convention
+ * (cli/lib/commands/quoxchat.js): catch, surface a plain-language error, and
+ * point the caller at `quox tg status` rather than trying to unpack response
+ * detail the generic client error path doesn't forward (QuoxApiError only
+ * carries `detail`/`details`, not arbitrary body fields like `binding`).
+ */
+
+import { formatOutput, formatDetail, printSuccess } from '../core/output.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+function yesNo(value) {
+  return value ? 'yes' : 'no';
+}
+
+function isoOrDash(value) {
+  if (value === null || value === undefined) return '-';
+  const d = new Date(value);
+  return Number.isNaN(d.getTime()) ? String(value) : d.toISOString();
+}
+
+function renderStatus(data, botId) {
+  const lines = [];
+  lines.push('');
+  lines.push(`Bot: ${botId || 'default'}`);
+  if (data.bot) {
+    lines.push(`  Username        ${data.bot.username || '-'}`);
+    lines.push(`  Name            ${data.bot.name || '-'}`);
+  } else {
+    lines.push('  (no bot token configured)');
+  }
+  lines.push(`  Webhook URL     ${data.webhook?.url || '-'}`);
+  lines.push(`  Webhook active  ${yesNo(!!data.webhook?.active)}`);
+  if (data.webhook?.last_error_message) {
+    lines.push(`  Last error      ${data.webhook.last_error_message}`);
+  }
+  if (data.owner_binding) {
+    lines.push(`  Owner chat      ${data.owner_binding.tg_chat_id}${data.owner_binding.title ? ` (${data.owner_binding.title})` : ''}`);
+  } else {
+    lines.push('  Owner chat      not bound');
+  }
+  return lines.join('\n');
+}
+
+export function registerTgCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  const tg = program
+    .command('tg')
+    .description('Manage Telegram Pro: onboarding status, owner binding, session leases, webhook admin');
+
+  // ── status ───────────────────────────────────────────────────────────────
+
+  tg
+    .command('status')
+    .description('Show Telegram Pro onboarding status: bot, webhook, seen chats, owner binding')
+    .option('--bot <botId>', 'target a specific bot ID instead of the default gateway bot')
+    .action(async (options) => {
+      auth.requireAuth();
+      const query = {};
+      if (options.bot) query.bot_id = options.bot;
+
+      const ep = resolveEndpoint('tg.status');
+      const data = await client.get(ep.path, { service: ep.service, query });
+
+      const format = program.opts().output;
+      if (format === 'json') {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+      }
+      if (format === 'quiet') {
+        console.log(data.bot?.username || '');
+        return;
+      }
+
+      console.log(renderStatus(data, options.bot));
+
+      formatOutput({
+        columns: ['tg_chat_id', 'title', 'is_forum', 'seen_at'],
+        headers: ['Chat ID', 'Title', 'Forum', 'Seen'],
+        rows: (data.chats_seen || []).map((c) => ({
+          tg_chat_id: c.tg_chat_id,
+          title: c.title || '-',
+          is_forum: yesNo(c.is_forum),
+          seen_at: c.seen_at || '-',
+        })),
+      }, { format, emptyMessage: 'No chats seen yet — message the bot from a chat first.' });
+
+      if (data.bots && data.bots.length) {
+        console.log('\nBots');
+        formatOutput({
+          columns: ['bot_id', 'username', 'kind', 'webhook_active', 'chats_bound'],
+          headers: ['Bot ID', 'Username', 'Kind', 'Webhook', 'Chats'],
+          rows: data.bots.map((b) => ({
+            bot_id: b.bot_id,
+            username: b.username || '-',
+            kind: b.kind,
+            webhook_active: yesNo(b.webhook_active),
+            chats_bound: b.chats_bound,
+          })),
+        }, { format, emptyMessage: 'No bots configured.' });
+      }
+    });
+
+  // ── bind-owner ───────────────────────────────────────────────────────────
+
+  tg
+    .command('bind-owner')
+    .description('Bind a Telegram chat as the owner target (the chat must have messaged the bot first)')
+    .argument('<tg_chat_id>', 'Telegram chat ID that has already messaged the bot')
+    .option('--bot <botId>', 'target a specific bot ID instead of the default gateway bot')
+    .action(async (tgChatId, options) => {
+      auth.requireAuth();
+      const body = { tg_chat_id: tgChatId };
+      if (options.bot) body.bot_id = options.bot;
+
+      const ep = resolveEndpoint('tg.bindOwner');
+      try {
+        const data = await client.post(ep.path, { service: ep.service, body });
+        if (program.opts().output === 'json') {
+          console.log(JSON.stringify(data, null, 2));
+          return;
+        }
+        printSuccess(`Owner bound to chat ${tgChatId}.`);
+        if (data.binding) {
+          formatDetail(data.binding, {
+            format: program.opts().output,
+            title: 'Owner Binding',
+          });
+        }
+      } catch (err) {
+        if (err.status === 409) {
+          throw new Error(
+            `A primary owner binding already exists for this bot. Run \`quox tg status${options.bot ? ` --bot ${options.bot}` : ''}\` to see the current owner binding before rebinding.`
+          );
+        }
+        throw err;
+      }
+    });
+
+  // ── leases ───────────────────────────────────────────────────────────────
+
+  tg
+    .command('leases')
+    .description('List session leases for parallel terminal identities (T1-T8)')
+    .action(async () => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('tg.leases.list');
+      const data = await client.get(ep.path, { service: ep.service });
+
+      formatOutput({
+        columns: ['terminal', 'session_id', 'stream', 'alive', 'expires_at'],
+        headers: ['Terminal', 'Session ID', 'Stream', 'Alive', 'Expires'],
+        rows: (data.leases || []).map((l) => ({
+          terminal: l.terminal,
+          session_id: l.session_id,
+          stream: l.stream || '-',
+          alive: yesNo(l.alive),
+          expires_at: isoOrDash(l.expires_at),
+        })),
+      }, { format: program.opts().output, emptyMessage: 'No active session leases.' });
+    });
+
+  // ── webhook-info ─────────────────────────────────────────────────────────
+
+  tg
+    .command('webhook-info')
+    .description('Show current Telegram webhook status (per-bot info is pending backend support; --bot is a no-op today)')
+    .option('--bot <botId>', 'target a specific bot ID (not yet honored server-side)')
+    .action(async (options) => {
+      auth.requireAuth();
+      const query = {};
+      if (options.bot) query.bot_id = options.bot;
+
+      const ep = resolveEndpoint('tg.webhook.info');
+      const data = await client.get(ep.path, { service: ep.service, query });
+
+      formatDetail({
+        active: data.active,
+        has_token: data.has_token,
+        bot_username: data.bot_username,
+        webhook_url: data.webhook_url,
+        pending_update_count: data.pending_update_count,
+        last_error_date: data.last_error_date,
+        last_error_message: data.last_error_message,
+      }, {
+        format: program.opts().output,
+        title: 'Telegram Webhook Info',
+        labels: {
+          active: 'Active',
+          has_token: 'Has token',
+          bot_username: 'Bot username',
+          webhook_url: 'Webhook URL',
+          pending_update_count: 'Pending updates',
+          last_error_date: 'Last error date',
+          last_error_message: 'Last error message',
+        },
+      });
+    });
+
+  // ── setup ────────────────────────────────────────────────────────────────
+
+  tg
+    .command('setup')
+    .description('Register the Telegram webhook URL for the bot')
+    .argument('<webhook_url>', 'HTTPS URL Telegram should POST updates to')
+    .option('--bot <botId>', 'target a specific bot ID instead of the default gateway bot')
+    .action(async (webhookUrl, options) => {
+      auth.requireAuth();
+      const body = { webhook_url: webhookUrl };
+      if (options.bot) body.bot_id = options.bot;
+
+      const ep = resolveEndpoint('tg.webhook.setup');
+      const data = await client.post(ep.path, { service: ep.service, body });
+
+      if (program.opts().output === 'json') {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+      }
+      printSuccess(`Webhook registered: ${data.webhook_url} (bot: ${data.bot_username || 'unknown'}).`);
+    });
+}

package/lib/commands/tiktok.js

@@ -0,0 +1,218 @@
+/**
+ * `quox tiktok` — TikTok plugin verbs, TT-4 (instagram CLI parity).
+ *
+ * quox tiktok publish "<title>" --file <path-in-media-root> [--privacy SELF_ONLY|MUTUAL_FOLLOW_FRIENDS|PUBLIC_TO_EVERYONE] [--no-duet] [--no-comment] [--no-stitch]
+ * quox tiktok draft "<title>" --file <path-in-media-root>
+ * quox tiktok profile
+ * quox tiktok videos [--limit <n>]
+ * quox tiktok stats --ids <id,id,...>
+ * quox tiktok status --publish-id <id>
+ *
+ * The write verbs (publish, draft) execute the tiktok connector tool through
+ * the governed collector endpoint (POST /api/v1/tools/execute -> connector
+ * bridge). The bridge gates both on requiresApproval: it files an owner
+ * approval card and returns immediately with { pending:true,
+ * status:'awaiting_approval', approvalId, inbox_item_id }. The actual TikTok
+ * API write (video/init -> upload -> publish, or the inbox/draft init ->
+ * upload) only happens once the owner approves via the dashboard inbox or
+ * `quox inbox respond <id> --action approve`.
+ *
+ * TikTok has its OWN dedicated vaulted credential; there is no shared
+ * credential with any other plugin. Two hard truths this CLI states
+ * honestly: an unaudited TikTok app is restricted to posting private
+ * (SELF_ONLY) content regardless of the privacy level requested, until
+ * TikTok approves the app audit; and access tokens live 24 hours with no
+ * automatic refresh built yet.
+ */
+
+import { formatDetail, printSuccess, printInfo, printWarning } from '../core/output.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+import { resolveOrgId } from './helpers.js';
+
+const PRIVACY_LEVELS = ['SELF_ONLY', 'MUTUAL_FOLLOW_FRIENDS', 'PUBLIC_TO_EVERYONE'];
+
+/**
+ * Execute one tiktok connector tool via the governed collector endpoint.
+ * A pending-approval response is a SUCCESS shape here (the card was filed);
+ * only a non-pending success:false is an error.
+ */
+async function executeTikTokTool({ client, auth, program }, toolName, input) {
+  auth.requireAuth();
+  const orgId = resolveOrgId(auth, program);
+  const ep = resolveEndpoint('v1.tools.execute');
+  const body = { tool_name: toolName, input, org_id: orgId };
+  const data = await client.post(ep.path, { service: ep.service, body });
+  if (data && data.success === false && !data.pending) {
+    throw new Error(`${toolName} via POST ${ep.path} returned success:false: ${data.error || 'unknown error'}`);
+  }
+  return data;
+}
+
+function printAwaitingApproval(action, data) {
+  const itemRef = data.inbox_item_id || data.approvalId || 'unknown';
+  printSuccess(`${action} filed for owner approval - inbox item ${itemRef} (awaiting approval). Nothing publishes until an approver says yes.`);
+  if (data.inbox_item_id) {
+    printInfo(`Review and approve: quox inbox get ${data.inbox_item_id}  (or: quox inbox respond ${data.inbox_item_id} --action approve)`);
+  }
+}
+
+export function registerTikTokCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  const tiktok = program
+    .command('tiktok')
+    .description('TikTok video publishing and draft uploads: governed, HITL-approved via HITL Inbox, on your own dedicated TikTok credential');
+
+  // ── tiktok publish ────────────────────────────────────────────────────
+
+  tiktok
+    .command('publish')
+    .description('Publish a video from a file under the org TikTok media root. Files an owner approval card and returns immediately; never publishes directly.')
+    .argument('<title>', 'video title/caption')
+    .requiredOption('--file <path>', 'video file path, relative to the org TikTok media root')
+    .option('--privacy <level>', `privacy level: ${PRIVACY_LEVELS.join('|')} (default SELF_ONLY)`, 'SELF_ONLY')
+    .option('--no-duet', 'disable duets on this video')
+    .option('--no-comment', 'disable comments on this video')
+    .option('--no-stitch', 'disable stitching on this video')
+    .action(async (title, options) => {
+      const privacy = options.privacy || 'SELF_ONLY';
+      if (!PRIVACY_LEVELS.includes(privacy)) {
+        throw new Error(`--privacy must be one of ${PRIVACY_LEVELS.join(', ')} (got ${privacy})`);
+      }
+
+      const input = {
+        title,
+        video_path: options.file,
+        privacy_level: privacy,
+        disable_duet: !options.duet,
+        disable_comment: !options.comment,
+        disable_stitch: !options.stitch,
+      };
+
+      const data = await executeTikTokTool({ client, auth, program }, 'tiktok_publish_video', input);
+
+      if (program.opts().output === 'json') {
+        formatDetail(data, { format: 'json' });
+        return;
+      }
+      printAwaitingApproval('Publish', data);
+      if (privacy !== 'SELF_ONLY') {
+        printWarning(`Requested privacy_level=${privacy} is sent to TikTok exactly as asked, but an unaudited TikTok app is restricted to private (SELF_ONLY) viewing until TikTok approves the app audit. Check the outcome with: quox tiktok status --publish-id <id>`);
+      }
+    });
+
+  // ── tiktok draft ──────────────────────────────────────────────────────
+
+  tiktok
+    .command('draft')
+    .description('Upload a video to the account\'s TikTok inbox as a draft, finished manually in the TikTok app. Files an owner approval card and returns immediately; never uploads directly.')
+    .argument('<title>', 'working title for the draft (display only)')
+    .requiredOption('--file <path>', 'video file path, relative to the org TikTok media root')
+    .action(async (title, options) => {
+      const input = { title, video_path: options.file };
+      const data = await executeTikTokTool({ client, auth, program }, 'tiktok_upload_draft', input);
+
+      if (program.opts().output === 'json') {
+        formatDetail(data, { format: 'json' });
+        return;
+      }
+      printAwaitingApproval('Draft upload', data);
+    });
+
+  // ── tiktok profile (read; cheapest live credential check) ──────────────
+
+  tiktok
+    .command('profile')
+    .description('Show the connected TikTok profile (also the cheapest live credential check).')
+    .action(async () => {
+      const data = await executeTikTokTool({ client, auth, program }, 'tiktok_get_profile', {});
+
+      if (program.opts().output === 'json') {
+        formatDetail(data, { format: 'json' });
+        return;
+      }
+      const result = data.result || {};
+      if (!result.open_id && !result.display_name) {
+        printInfo('No profile returned.');
+        return;
+      }
+      console.log(`${result.display_name || 'unknown'}  (${result.open_id || 'unknown'})`);
+      console.log(`  followers: ${result.followers ?? 'unknown'}  following: ${result.following ?? 'unknown'}  likes: ${result.likes ?? 'unknown'}  videos: ${result.videos ?? 'unknown'}`);
+    });
+
+  // ── tiktok videos (read) ────────────────────────────────────────────────
+
+  tiktok
+    .command('videos')
+    .description('List the connected account\'s recent videos (read-only, no approval needed).')
+    .option('--limit <n>', 'max videos to return (max 20)', '10')
+    .action(async (options) => {
+      const maxCount = Math.min(parseInt(options.limit, 10) || 10, 20);
+      const data = await executeTikTokTool({ client, auth, program }, 'tiktok_list_videos', { max_count: maxCount });
+
+      if (program.opts().output === 'json') {
+        formatDetail(data, { format: 'json' });
+        return;
+      }
+      const videos = data.result?.videos || [];
+      if (videos.length === 0) {
+        printInfo('No videos returned.');
+        return;
+      }
+      for (const v of videos) {
+        console.log(`${v.id}  ${v.title || '(no title)'}`);
+        console.log(`  views: ${v.views ?? 0}  likes: ${v.likes ?? 0}  comments: ${v.comments ?? 0}  shares: ${v.shares ?? 0}`);
+      }
+    });
+
+  // ── tiktok stats (read) ──────────────────────────────────────────────────
+
+  tiktok
+    .command('stats')
+    .description('Show engagement stats for specific videos by id.')
+    .requiredOption('--ids <ids>', 'comma-separated TikTok video IDs')
+    .action(async (options) => {
+      const videoIds = options.ids.split(',').map((s) => s.trim()).filter(Boolean);
+      if (videoIds.length === 0) {
+        throw new Error('tiktok stats requires at least one id in --ids');
+      }
+      const data = await executeTikTokTool({ client, auth, program }, 'tiktok_get_video_stats', { video_ids: videoIds });
+
+      if (program.opts().output === 'json') {
+        formatDetail(data, { format: 'json' });
+        return;
+      }
+      const videos = data.result || [];
+      if (videos.length === 0) {
+        printInfo('No stats returned.');
+        return;
+      }
+      for (const v of videos) {
+        console.log(`${v.id}  ${v.title || '(no title)'}`);
+        console.log(`  views: ${v.views ?? 0}  likes: ${v.likes ?? 0}  comments: ${v.comments ?? 0}  shares: ${v.shares ?? 0}`);
+      }
+    });
+
+  // ── tiktok status (read) ─────────────────────────────────────────────────
+
+  tiktok
+    .command('status')
+    .description('Check the status of a video publish or draft upload by publish_id.')
+    .requiredOption('--publish-id <id>', 'the publish_id returned by publish or draft')
+    .action(async (options) => {
+      const data = await executeTikTokTool({ client, auth, program }, 'tiktok_get_publish_status', { publish_id: options.publishId });
+
+      if (program.opts().output === 'json') {
+        formatDetail(data, { format: 'json' });
+        return;
+      }
+      const result = data.result || {};
+      if (!result.status) {
+        printInfo('No status returned.');
+        return;
+      }
+      console.log(`${result.publish_id}  status: ${result.status}`);
+      if (result.fail_reason) console.log(`  fail_reason: ${result.fail_reason}`);
+      if (result.publicly_available_post_ids) console.log(`  publicly_available_post_ids: ${result.publicly_available_post_ids}`);
+    });
+}

package/lib/commands/tips.js

@@ -0,0 +1,23 @@
+/**
+ * quox tips [--json]
+ *
+ * The canned "did you know" tips behind the terminal's /tip (QUOXON-TIPS). Offline: this prints the registry
+ * (cli/lib/quoxon/tips.js), not what is ready on your install; the terminal applies the honesty gate
+ * (shipped maturity, capabilities contract, /tip-settings) when it shows one. --json (or -o json) is the
+ * shape the dashboard and cli.quox.ai reuse.
+ */
+
+import { TIPS, tipsJson, tipsReply } from '../quoxon/tips.js';
+
+export function registerTipsCommands(program) {
+  program
+    .command('tips')
+    .description('List the "did you know" tips the terminal shows (/tip); --json for the registry as data')
+    .argument('[query...]', 'search the tips by topic or words (like /tips); bare lists every tip')
+    .option('--json', 'print the registry as JSON')
+    .action((query, opts) => {
+      if (opts.json || program.opts().output === 'json') { console.log(JSON.stringify(tipsJson(), null, 2)); return; }
+      if (query?.length) { for (const l of tipsReply(query.join(' ')).lines) console.log(l); return; }
+      for (const t of TIPS) console.log(`${t.id}  [${t.product} · ${t.tier} · ${t.maturity}]  ${t.text}  Try: ${t.try}`);
+    });
+}