insightfulpipe 0.1.0

package/src/cli/commands/discovery.js

@@ -0,0 +1,353 @@
+import { getConfigSnapshot, getToken } from '../../config.js';
+import { apiGet } from '../../api.js';
+import { printJson, printTable, wantsJson } from '../../output.js';
+import {
+  buildQueryString,
+  parseIdList,
+  parseIntegerOption,
+  toPromptDataSource,
+} from '../options.js';
+import { fail, handleApiError } from '../errors.js';
+import {
+  fetchBrandMetadata,
+  fetchConnectedSources,
+  fetchHelperPayload,
+  runQueryContexts,
+  sourceDisplayName,
+  sourceIdentifier,
+} from '../query-contexts.js';
+
+export function registerDiscoveryCommands(program) {
+  program
+    .command('whoami')
+    .description('Show the authenticated user')
+    .action(async (opts, command) => {
+      const data = handleApiError(await apiGet('/user-info/'));
+
+      if (wantsJson(command)) {
+        printJson(data);
+        return;
+      }
+
+      console.log(`User:        ${data.user.email}`);
+      console.log(`Name:        ${data.user.full_name || '-'}`);
+      console.log(`Workspaces:  ${data.total_workspaces}`);
+      for (const workspace of data.workspaces || []) {
+        const subscription = workspace.subscription || {};
+        const planName = subscription.plan_name || '-';
+        const planStatus = subscription.status || (subscription.is_active ? 'active' : '-');
+        console.log(`  - ${workspace.name} (${workspace.role}; ${planName}; ${planStatus})`);
+      }
+    });
+
+  program
+    .command('platforms')
+    .description('List available platforms')
+    .option('--prod', 'Only show production-ready platforms')
+    .action(async (opts, command) => {
+      const suffix = buildQueryString({ prod: opts.prod ? 'true' : undefined });
+      const data = handleApiError(await apiGet(`/available-platforms/${suffix}`));
+
+      if (wantsJson(command)) {
+        printJson(data);
+        return;
+      }
+
+      printTable(data.platforms || [], [
+        { key: 'slug', label: 'Platform' },
+        { key: 'name', label: 'Name' },
+        { key: 'category', label: 'Category' },
+      ]);
+    });
+
+  program
+    .command('query_contexts')
+    .argument('[request]', 'One of: accounts, brands, available_actions, actions_details')
+    .description('Retrieve accounts, brands, and action schemas')
+    .option('-r, --request <request>', 'Request type if you prefer flags over the positional argument')
+    .option('-p, --platform <platform>', 'Platform slug')
+    .option('--workspace-id <id>', 'Workspace ID')
+    .option('--brand-id <id>', 'Brand ID')
+    .option('-a, --actions <actions>', 'Comma-separated action names')
+    .action(async (requestArg, opts) => {
+      const requestName = (requestArg || opts.request || '').trim();
+      if (!requestName) {
+        fail(
+          'query_contexts requires a request.',
+          'Use one of: accounts, brands, available_actions, actions_details.'
+        );
+      }
+
+      const data = await runQueryContexts(requestName, opts);
+      printJson(data);
+    });
+
+  program
+    .command('workspaces')
+    .description('List accessible workspaces')
+    .action(async (opts, command) => {
+      const data = handleApiError(await apiGet('/workspaces/'));
+
+      if (wantsJson(command)) {
+        printJson(data);
+        return;
+      }
+
+      printTable(data.workspaces || [], [
+        { key: 'id', label: 'ID' },
+        { key: 'slug', label: 'Slug' },
+        { key: 'name', label: 'Name' },
+        { key: 'role', label: 'Role' },
+      ]);
+    });
+
+  program
+    .command('brands')
+    .description('List brand metadata for a workspace')
+    .requiredOption('-w, --workspace <id>', 'Workspace ID')
+    .option('--brand-ids <ids>', 'Comma-separated brand IDs')
+    .action(async (opts, command) => {
+      const workspaceId = parseIntegerOption('workspace', opts.workspace);
+      const brandIds = opts.brandIds ? parseIdList(opts.brandIds, 'brand ID') : undefined;
+      const data = await fetchBrandMetadata(workspaceId, brandIds);
+      const brands = Array.isArray(data.brands) ? data.brands : [];
+
+      if (wantsJson(command)) {
+        printJson(data);
+        return;
+      }
+
+      if (brands.length === 1 || brandIds) {
+        printJson(brands.length === 1 ? brands[0] : brands);
+        return;
+      }
+
+      printTable(brands, [
+        { key: 'id', label: 'ID' },
+        { key: 'name', label: 'Name' },
+        { key: 'website_url', label: 'Website' },
+      ]);
+    });
+
+  program
+    .command('accounts')
+    .description('List connected accounts')
+    .option('-p, --platform <platform>', 'Filter by platform')
+    .option('--prod', 'Only include production-ready sources')
+    .action(async (opts, command) => {
+      const data = await fetchConnectedSources(opts.platform, opts.prod);
+      const sources = Array.isArray(data.sources) ? data.sources : [];
+
+      if (wantsJson(command)) {
+        printJson(data);
+        return;
+      }
+
+      if (sources.length === 0) {
+        console.log('No connected accounts.');
+        return;
+      }
+
+      const rows = sources.map((source) => ({
+        platform: source.platform || '-',
+        account: sourceDisplayName(source),
+        workspace: source.workspace_name || '-',
+        access: source.access_level || '-',
+      }));
+
+      printTable(rows, [
+        { key: 'platform', label: 'Platform' },
+        { key: 'account', label: 'Account' },
+        { key: 'workspace', label: 'Workspace' },
+        { key: 'access', label: 'Access' },
+      ]);
+    });
+
+  program
+    .command('sources')
+    .description('List connected data sources with IDs')
+    .option('-p, --platform <platform>', 'Filter by platform')
+    .option('--prod', 'Only include production-ready sources')
+    .action(async (opts, command) => {
+      const data = await fetchConnectedSources(opts.platform, opts.prod);
+      const sources = Array.isArray(data.sources) ? data.sources : [];
+
+      if (wantsJson(command)) {
+        printJson(data);
+        return;
+      }
+
+      const rows = sources.map((source) => ({
+        platform: source.platform || '-',
+        name: sourceDisplayName(source),
+        id: sourceIdentifier(source),
+        workspace: source.workspace_name || '-',
+        brand: source.brand_name || '-',
+        access: source.access_level || '-',
+      }));
+
+      printTable(rows, [
+        { key: 'platform', label: 'Platform' },
+        { key: 'name', label: 'Name' },
+        { key: 'id', label: 'ID' },
+        { key: 'workspace', label: 'Workspace' },
+        { key: 'brand', label: 'Brand' },
+        { key: 'access', label: 'Access' },
+      ]);
+    });
+
+  program
+    .command('helper')
+    .argument('<platform>', 'Platform slug (e.g., google-analytics)')
+    .description('Show available actions and schema for a platform')
+    .option('-a, --actions <actions>', 'Comma-separated action names')
+    .action(async (platform, opts) => {
+      const actions = opts.actions ? opts.actions.split(',').map((value) => value.trim()).filter(Boolean) : undefined;
+      const data = await fetchHelperPayload(platform, actions);
+      printJson(data);
+    });
+
+  program
+    .command('prompts')
+    .argument('<platform>', 'Platform slug (e.g., google-ads)')
+    .description('List prompt templates or fetch prompt details')
+    .option('--workspace <id>', 'Workspace ID for custom prompts')
+    .option('--type <type>', 'Prompt type filter')
+    .option('--id <id>', 'Prompt ID to fetch details')
+    .option('--custom', 'Fetch a custom prompt detail (requires --workspace and --id)')
+    .action(async (platform, opts, command) => {
+      const dataSource = toPromptDataSource(platform);
+
+      if (opts.id) {
+        const promptId = parseIntegerOption('prompt ID', opts.id);
+
+        if (opts.custom) {
+          if (!opts.workspace) {
+            fail('--workspace is required with --custom and --id.');
+          }
+
+          const data = handleApiError(
+            await apiGet(
+              `/prompts/custom/details/${buildQueryString({
+                prompt_id: promptId,
+                workspace_id: parseIntegerOption('workspace', opts.workspace),
+              })}`
+            )
+          );
+          if (wantsJson(command)) {
+            printJson(data);
+            return;
+          }
+          console.log(data.prompt_detail || '');
+          return;
+        }
+
+        const data = handleApiError(
+          await apiGet(
+            `/prompts/details/${buildQueryString({
+              prompt_id: promptId,
+              type: opts.type,
+            })}`
+          )
+        );
+        if (wantsJson(command)) {
+          printJson(data);
+          return;
+        }
+        console.log(data.prompt_detail || '');
+        return;
+      }
+
+      const data = handleApiError(
+        await apiGet(
+          `/prompts/menu/${buildQueryString({
+            data_source: dataSource,
+            workspace_id: opts.workspace ? parseIntegerOption('workspace', opts.workspace) : undefined,
+            type: opts.type,
+          })}`
+        )
+      );
+
+      if (wantsJson(command)) {
+        printJson(data);
+        return;
+      }
+
+      printTable(data.prompts || [], [
+        { key: 'id', label: 'ID' },
+        { key: 'prompt_name', label: 'Prompt' },
+        { key: 'is_custom', label: 'Custom' },
+        { key: 'data_source', label: 'Data Source' },
+      ]);
+    });
+
+  program
+    .command('doctor')
+    .description('Check configuration and API connectivity')
+    .action(async (opts, command) => {
+      const snapshot = getConfigSnapshot();
+      const token = getToken();
+      const checks = [
+        {
+          name: 'api_url',
+          status: 'ok',
+          details: snapshot.values.api_url,
+          source: snapshot.sources.api_url,
+        },
+        {
+          name: 'token',
+          status: token ? 'ok' : 'error',
+          details: token ? 'Configured' : 'Missing',
+          source: snapshot.sources.token,
+        },
+        {
+          name: 'timeout',
+          status: 'ok',
+          details: `${snapshot.values.timeout_ms} ms`,
+          source: snapshot.sources.timeout_ms,
+        },
+      ];
+
+      let connectivity = {
+        status: 'skipped',
+        details: 'Skipped because no token is configured.',
+      };
+
+      if (token) {
+        const data = await apiGet('/user-info/');
+        if (data?.error) {
+          connectivity = {
+            status: 'error',
+            details: data.message || data.details || 'Request failed',
+          };
+        } else {
+          connectivity = {
+            status: 'ok',
+            details: data.user?.email || 'Authenticated',
+          };
+        }
+      }
+
+      const status = [...checks, connectivity].some((item) => item.status === 'error') ? 'error' : 'ok';
+      const payload = {
+        status,
+        config_file: snapshot.configFile,
+        checks,
+        connectivity,
+      };
+
+      if (wantsJson(command)) {
+        printJson(payload);
+      } else {
+        console.log(`Config file: ${payload.config_file}`);
+        for (const item of payload.checks) {
+          console.log(`${item.name}: ${item.status} (${item.details}; ${item.source})`);
+        }
+        console.log(`connectivity: ${payload.connectivity.status} (${payload.connectivity.details})`);
+      }
+
+      if (status === 'error') {
+        process.exitCode = 1;
+      }
+    });
+}

package/src/cli/commands/execution.js

@@ -0,0 +1,50 @@
+import { apiPost } from '../../api.js';
+import { printJson } from '../../output.js';
+import {
+  confirmWriteAction,
+  ensureJsonObject,
+  readJsonInput,
+} from '../input.js';
+import { handleApiError } from '../errors.js';
+import { withPlatform } from '../options.js';
+
+export function registerExecutionCommands(program) {
+  program
+    .command('query_data')
+    .alias('query')
+    .argument('<platform>', 'Platform slug (e.g., google-analytics, shopify)')
+    .option('-b, --body <json>', 'Request body as inline JSON')
+    .option('-f, --file <path>', 'Request body from a JSON file')
+    .description('Execute a read-only data query for a platform')
+    .action(async (platform, opts) => {
+      const body = ensureJsonObject(await readJsonInput(opts, true), 'Request body');
+      const data = handleApiError(await apiPost('/', withPlatform(platform, body)));
+      printJson(data);
+    });
+
+  program
+    .command('execute_action')
+    .alias('action')
+    .argument('<platform>', 'Platform slug (e.g., facebook-pages, google-ads)')
+    .option('-b, --body <json>', 'Request body as inline JSON')
+    .option('-f, --file <path>', 'Request body from a JSON file')
+    .option('-y, --yes', 'Skip confirmation prompt')
+    .description('Execute a write or mutating action for a platform')
+    .action(async (platform, opts) => {
+      const body = ensureJsonObject(await readJsonInput(opts, true), 'Request body');
+      await confirmWriteAction(platform, body, opts.yes);
+      const data = handleApiError(await apiPost('/', withPlatform(platform, body)));
+      printJson(data);
+    });
+
+  program
+    .command('raw')
+    .option('-b, --body <json>', 'Request body as inline JSON')
+    .option('-f, --file <path>', 'Request body from a JSON file')
+    .description('Send a raw request to the universal dispatcher')
+    .action(async (opts) => {
+      const body = ensureJsonObject(await readJsonInput(opts, true), 'Request body');
+      const data = handleApiError(await apiPost('/', body));
+      printJson(data);
+    });
+}

package/src/cli/errors.js

@@ -0,0 +1,22 @@
+export function fail(message, tip) {
+  console.error(`Error: ${message}`);
+  if (tip) {
+    console.error(`Tip: ${tip}`);
+  }
+  process.exit(1);
+}
+
+export function handleApiError(data) {
+  if (!data || !data.error) {
+    return data;
+  }
+
+  const message =
+    data.message ||
+    data.details ||
+    data.error ||
+    data.api_error ||
+    (data.status ? `Request failed with status ${data.status}` : 'Request failed');
+
+  fail(message, data.tip);
+}

package/src/cli/input.js

@@ -0,0 +1,139 @@
+import { readFileSync } from 'fs';
+import { createInterface } from 'readline';
+import { fail } from './errors.js';
+
+function readJson(value, sourceLabel) {
+  try {
+    return JSON.parse(value);
+  } catch (error) {
+    fail(`Invalid JSON from ${sourceLabel}: ${error.message}`);
+  }
+}
+
+export function ensureJsonObject(value, sourceLabel) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    fail(`${sourceLabel} must be a JSON object.`);
+  }
+  return value;
+}
+
+async function readStdin() {
+  const chunks = [];
+  process.stdin.setEncoding('utf-8');
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  return chunks.join('');
+}
+
+export async function readJsonInput(opts, allowStdin = true) {
+  if (opts.body && opts.file) {
+    fail('Provide either --body or --file, not both.');
+  }
+
+  if (opts.file) {
+    let contents;
+    try {
+      contents = readFileSync(opts.file, 'utf-8');
+    } catch (error) {
+      fail(`Unable to read ${opts.file}: ${error.message}`);
+    }
+    return readJson(contents, `file ${opts.file}`);
+  }
+
+  if (opts.body) {
+    return readJson(opts.body, '--body');
+  }
+
+  if (!allowStdin) {
+    fail('Provide a request body via --body, --file, or stdin.');
+  }
+
+  const input = await readStdin();
+  if (!input.trim()) {
+    fail('Provide a request body via --body, --file, or stdin.');
+  }
+
+  return readJson(input, 'stdin');
+}
+
+function promptInput(promptText) {
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  return new Promise((resolve) => {
+    rl.question(promptText, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+export async function promptSecret(promptText) {
+  if (!process.stdin.isTTY) {
+    return (await readStdin()).trim();
+  }
+
+  const stdin = process.stdin;
+  stdin.resume();
+  stdin.setEncoding('utf-8');
+  stdin.setRawMode(true);
+  process.stderr.write(promptText);
+
+  return new Promise((resolve) => {
+    let secret = '';
+
+    const cleanup = () => {
+      stdin.off('data', onData);
+      stdin.setRawMode(false);
+      stdin.pause();
+      process.stderr.write('\n');
+    };
+
+    const onData = (chunk) => {
+      for (const input of String(chunk)) {
+        if (input === '\u0003') {
+          cleanup();
+          process.exit(130);
+        }
+
+        if (input === '\r' || input === '\n') {
+          cleanup();
+          resolve(secret.trim());
+          return;
+        }
+
+        if (input === '\u007f' || input === '\b' || input === '\x08') {
+          if (secret.length > 0) {
+            secret = secret.slice(0, -1);
+          }
+          continue;
+        }
+
+        if (input === '\u0004') {
+          cleanup();
+          resolve(secret.trim());
+          return;
+        }
+
+        secret += input;
+      }
+    };
+
+    stdin.on('data', onData);
+  });
+}
+
+export async function confirmWriteAction(platform, body, skipConfirmation) {
+  if (skipConfirmation) {
+    return;
+  }
+
+  if (!process.stdin.isTTY) {
+    fail('Write actions require confirmation in non-interactive mode. Re-run with --yes.');
+  }
+
+  const actionName = body.action || 'unknown-action';
+  const answer = await promptInput(`Execute write action "${actionName}" on "${platform}"? [y/N] `);
+  if (!/^(y|yes)$/i.test(answer)) {
+    fail('Write action cancelled.');
+  }
+}

package/src/cli/options.js

@@ -0,0 +1,88 @@
+import { validatePlatformSlug } from '../api.js';
+import { fail } from './errors.js';
+
+export function parseIntegerOption(name, value) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    fail(`${name} must be a positive integer.`);
+  }
+  return parsed;
+}
+
+export function parseIdList(value, optionName) {
+  const parts = String(value)
+    .split(',')
+    .map((part) => part.trim())
+    .filter(Boolean);
+
+  if (parts.length === 0) {
+    return [];
+  }
+
+  return parts.map((part) => parseIntegerOption(optionName, part));
+}
+
+export function parseStringList(value) {
+  return String(value)
+    .split(',')
+    .map((part) => part.trim())
+    .filter(Boolean);
+}
+
+export function buildQueryString(params) {
+  const searchParams = new URLSearchParams();
+
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined || value === null || value === '') {
+      continue;
+    }
+    searchParams.set(key, String(value));
+  }
+
+  const query = searchParams.toString();
+  return query ? `?${query}` : '';
+}
+
+export function validateConfiguredUrl(url, allowInsecure) {
+  let urlObj;
+  try {
+    urlObj = new URL(url);
+  } catch {
+    fail('API URL must be a valid absolute URL.');
+  }
+
+  if (urlObj.protocol !== 'https:' && urlObj.protocol !== 'http:') {
+    fail('API URL must use http:// or https://.');
+  }
+
+  if (urlObj.protocol !== 'https:' && !allowInsecure) {
+    fail('API URL must use HTTPS. Use --allow-insecure for local development.');
+  }
+
+  if (
+    urlObj.hostname !== 'localhost' &&
+    urlObj.hostname !== '127.0.0.1' &&
+    !urlObj.hostname.endsWith('.insightfulpipe.com')
+  ) {
+    console.error(
+      'Warning: API URL points to a non-InsightfulPipe domain. Your API token will be sent to this server.'
+    );
+  }
+
+  return urlObj.toString().replace(/\/+$/, '');
+}
+
+export function withPlatform(platform, body) {
+  validatePlatformSlug(platform);
+
+  if (body.platform && body.platform !== platform) {
+    fail(`Body platform "${body.platform}" does not match command platform "${platform}".`);
+  }
+
+  return { ...body, platform };
+}
+
+export function toPromptDataSource(platform) {
+  validatePlatformSlug(platform);
+  return platform.replace(/-/g, '_');
+}

package/src/cli/program.js

@@ -0,0 +1,48 @@
+import { Command } from 'commander';
+import { registerAuthCommand } from './commands/auth.js';
+import { registerConfigCommand } from './commands/config.js';
+import { registerDiscoveryCommands } from './commands/discovery.js';
+import { registerExecutionCommands } from './commands/execution.js';
+
+export function buildProgram() {
+  const program = new Command();
+
+  program
+    .name('insightfulpipe')
+    .description(
+      'InsightfulPipe CLI — query your marketing data from the terminal.\n\n' +
+      'Run "insightfulpipe platforms" to see all supported platforms.\n\n' +
+      'Query workflow:\n' +
+      '  1. insightfulpipe accounts --platform <platform>\n' +
+      '     Get workspace_id, brand_id, and source identifiers (e.g. property_id, site_url).\n\n' +
+      '  2. insightfulpipe helper <platform>\n' +
+      '     List all actions available for the platform.\n\n' +
+      '  3. insightfulpipe helper <platform> --actions <action1>,<action2>\n' +
+      '     Get the exact request body schema. Never guess the body — always check here first.\n\n' +
+      '  4. insightfulpipe query <platform> -b \'{"action":"...","workspace_id":...}\'\n' +
+      '     Execute a read query. Replace "xxx" in the schema with real values from step 1.\n\n' +
+      '     insightfulpipe action <platform> -b \'{"action":"..."}\'  --yes\n' +
+      '     Execute a write operation (create, update, delete, publish, send).\n' +
+      '     Requires --yes in non-interactive mode.\n\n' +
+      'Other useful commands:\n' +
+      '  insightfulpipe platforms              All supported platforms\n' +
+      '  insightfulpipe sources --platform X   Connected sources with IDs\n' +
+      '  insightfulpipe prompts <platform>     Prompt templates for a platform\n' +
+      '  insightfulpipe brands --workspace ID  Brand metadata\n' +
+      '  insightfulpipe whoami                 Current authenticated user\n' +
+      '  insightfulpipe doctor                 Check auth and connectivity\n\n' +
+      'Authentication:\n' +
+      '  insightfulpipe auth                   Save your API token (starts with ip_sk_)\n' +
+      '  Or set INSIGHTFULPIPE_TOKEN env var.'
+    )
+    .version('0.1.0')
+    .option('--json', 'Print JSON output when supported')
+    .showHelpAfterError();
+
+  registerAuthCommand(program);
+  registerDiscoveryCommands(program);
+  registerExecutionCommands(program);
+  registerConfigCommand(program);
+
+  return program;
+}