insightfulpipe 0.1.0

package/src/cli/query-contexts.js

@@ -0,0 +1,222 @@
+import { apiGet, apiPost, validatePlatformSlug } from '../api.js';
+import { fail, handleApiError } from './errors.js';
+import { buildQueryString, parseIntegerOption, parseStringList } from './options.js';
+
+const SOURCE_NAME_KEYS = [
+  'source_name',
+  'account_name',
+  'ad_account_name',
+  'page_name',
+  'property_name',
+  'site_name',
+  'shop_name',
+  'company_name',
+  'channel_name',
+  'organization_name',
+  'portal_name',
+  'team_name',
+  'brand_name',
+];
+
+const SOURCE_ID_KEYS = [
+  'account_id',
+  'ad_account_id',
+  'customer_id',
+  'advertiser_id',
+  'property_id',
+  'page_id',
+  'site_url',
+  'channel_id',
+  'spreadsheet_id',
+  'sheet_id',
+  'location_id',
+  'organization_id',
+  'bot_id',
+];
+
+function pickFirst(source, keys) {
+  for (const key of keys) {
+    const value = source[key];
+    if (value !== undefined && value !== null && String(value).trim() !== '') {
+      return value;
+    }
+  }
+  return null;
+}
+
+function groupSourcesByPlatform(sources) {
+  const grouped = {};
+
+  for (const source of sources) {
+    const platform = source.platform || 'unknown';
+    if (!grouped[platform]) {
+      grouped[platform] = [];
+    }
+    grouped[platform].push(source);
+  }
+
+  return Object.fromEntries(Object.entries(grouped).sort(([left], [right]) => left.localeCompare(right)));
+}
+
+export function sourceDisplayName(source) {
+  return pickFirst(source, SOURCE_NAME_KEYS) || '-';
+}
+
+export function sourceIdentifier(source) {
+  return pickFirst(source, SOURCE_ID_KEYS) || '-';
+}
+
+export async function fetchConnectedSources(platform, prod = false) {
+  if (platform) {
+    validatePlatformSlug(platform);
+  }
+
+  const payload = {};
+  if (platform) {
+    payload.platform = platform;
+  }
+  if (prod) {
+    payload.prod = true;
+  }
+
+  return handleApiError(await apiPost('/connected-sources/', payload));
+}
+
+export async function fetchBrandMetadata(workspaceId, brandIds) {
+  const payload = { workspace_id: workspaceId };
+
+  if (brandIds && brandIds.length > 0) {
+    payload.brand_ids = brandIds;
+  }
+
+  return handleApiError(await apiPost('/brand-details/', payload));
+}
+
+export async function fetchHelperPayload(platform, actions) {
+  validatePlatformSlug(platform);
+  const data = handleApiError(
+    await apiGet(
+      `/helper/${buildQueryString({
+        platform,
+        actions: actions && actions.length > 0 ? actions.join(',') : undefined,
+      })}`
+    )
+  );
+
+  // Rewrite next_step from MCP language to CLI commands
+  if (data && typeof data === 'object' && !actions) {
+    // List response — next step is actions_details
+    data.next_step = {
+      request: 'actions_details',
+      command: `insightfulpipe helper ${platform} --actions <action1>,<action2>`,
+      description: 'Pick actions from the list above and pass them via --actions',
+    };
+  } else if (data && typeof data === 'object' && actions) {
+    // Detail response — next step is query or action
+    data.next_step = {
+      read: 'query_data',
+      write: 'execute_action',
+      read_command: `insightfulpipe query ${platform} -b '<request body JSON>'`,
+      write_command: `insightfulpipe action ${platform} -b '<request body JSON>'`,
+      description: 'Use query to fetch reports, analytics, and listings. Use action to create, update, delete, or publish.',
+    };
+  }
+
+  return data;
+}
+
+export async function runQueryContexts(requestName, opts) {
+  switch (requestName) {
+    case 'accounts': {
+      const data = await fetchConnectedSources(opts.platform);
+      const sources = Array.isArray(data.sources) ? data.sources : [];
+
+      if (opts.platform) {
+        // Try to include actions so agent can skip available_actions step
+        let availableActions;
+        try {
+          const actionsData = await fetchHelperPayload(opts.platform);
+          availableActions = actionsData?.actions || [];
+        } catch {
+          availableActions = [];
+        }
+
+        const result = {
+          ...data,
+          sources,
+          platform: opts.platform,
+          next_step: {
+            request: 'actions_details',
+            command: `insightfulpipe helper ${opts.platform} --actions <action1>,<action2>`,
+            description: 'Pick actions from the list above and pass them via --actions',
+          },
+        };
+        if (availableActions.length > 0) {
+          result.available_actions = availableActions;
+        }
+        return result;
+      }
+
+      const groupedSources = groupSourcesByPlatform(sources);
+      const platformsWithSources = Object.keys(groupedSources);
+
+      return {
+        ...data,
+        sources: groupedSources,
+        platforms_with_sources: platformsWithSources,
+        total_sources: sources.length,
+        next_step: {
+          request: 'accounts',
+          command: 'insightfulpipe query_contexts accounts --platform <platform>',
+          description: 'Pick a platform from the list above',
+        },
+      };
+    }
+    case 'brands': {
+      if (!opts.platform) {
+        fail('platform is required for request "brands".');
+      }
+      if (!opts.workspaceId) {
+        fail('workspace_id is required for request "brands".');
+      }
+      if (!opts.brandId) {
+        fail('brand_id is required for request "brands".');
+      }
+
+      validatePlatformSlug(opts.platform);
+      const data = await fetchBrandMetadata(
+        parseIntegerOption('workspace_id', opts.workspaceId),
+        [parseIntegerOption('brand_id', opts.brandId)]
+      );
+
+      return {
+        platform: opts.platform,
+        ...data,
+      };
+    }
+    case 'available_actions': {
+      if (!opts.platform) {
+        fail('platform is required for request "available_actions".');
+      }
+
+      return fetchHelperPayload(opts.platform);
+    }
+    case 'actions_details': {
+      if (!opts.platform) {
+        fail('platform is required for request "actions_details".');
+      }
+
+      const actions = opts.actions ? parseStringList(opts.actions) : [];
+      if (actions.length === 0) {
+        fail('actions is required for request "actions_details". Use a comma-separated list.');
+      }
+
+      return fetchHelperPayload(opts.platform, actions);
+    }
+    default:
+      fail(
+        `Unknown query_contexts request "${requestName}".`,
+        'Use one of: accounts, brands, available_actions, actions_details.'
+      );
+  }
+}

package/src/config.js

@@ -0,0 +1,194 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import { getTokenFromKeyring, saveTokenToKeyring, isKeyringAvailable } from './keyring.js';
+
+const ENV_API_URL = 'INSIGHTFULPIPE_API_URL';
+const ENV_TOKEN = 'INSIGHTFULPIPE_TOKEN';
+const ENV_TIMEOUT_MS = 'INSIGHTFULPIPE_TIMEOUT_MS';
+
+const DEFAULT_CONFIG = {
+  api_url: 'https://app.insightfulpipe.com',
+  token: null,
+  timeout_ms: 30000,
+};
+
+function getConfigDir() {
+  return join(homedir(), '.insightfulpipe');
+}
+
+function getConfigFile() {
+  return join(getConfigDir(), 'config.json');
+}
+
+function ensureConfigDir() {
+  const configDir = getConfigDir();
+  if (!existsSync(configDir)) {
+    mkdirSync(configDir, { recursive: true, mode: 0o700 });
+  }
+}
+
+function configError(message) {
+  console.error(`Error: ${message}`);
+  process.exit(1);
+}
+
+function normalizeConfig(rawConfig, sourceLabel) {
+  if (!rawConfig || typeof rawConfig !== 'object' || Array.isArray(rawConfig)) {
+    configError(`${sourceLabel} must contain a JSON object.`);
+  }
+
+  const normalized = {};
+
+  if ('api_url' in rawConfig) {
+    if (typeof rawConfig.api_url !== 'string' || !rawConfig.api_url.trim()) {
+      configError(`${sourceLabel} field "api_url" must be a non-empty string.`);
+    }
+    normalized.api_url = rawConfig.api_url;
+  }
+
+  if ('token' in rawConfig) {
+    if (rawConfig.token !== null && typeof rawConfig.token !== 'string') {
+      configError(`${sourceLabel} field "token" must be a string or null.`);
+    }
+    normalized.token = rawConfig.token;
+  }
+
+  if ('timeout_ms' in rawConfig) {
+    normalized.timeout_ms = normalizeTimeoutMs(rawConfig.timeout_ms, `${sourceLabel} field "timeout_ms"`);
+  }
+
+  return normalized;
+}
+
+function readStoredConfig() {
+  ensureConfigDir();
+  const configFile = getConfigFile();
+
+  if (!existsSync(configFile)) {
+    return {};
+  }
+
+  try {
+    return normalizeConfig(JSON.parse(readFileSync(configFile, 'utf-8')), configFile);
+  } catch (error) {
+    configError(`Unable to read ${configFile}: ${error.message}`);
+  }
+}
+
+function sourceLabel(kind, envName) {
+  if (kind === 'env') {
+    return `environment variable ${envName}`;
+  }
+  if (kind === 'file') {
+    return 'config file';
+  }
+  return 'default';
+}
+
+function readEnvOverride(name) {
+  const value = process.env[name];
+  if (value === undefined || value === '') {
+    return null;
+  }
+  return value;
+}
+
+function buildConfigSnapshot() {
+  const stored = readStoredConfig();
+  const values = { ...DEFAULT_CONFIG, ...stored };
+  const sources = {
+    api_url: Object.hasOwn(stored, 'api_url') ? sourceLabel('file') : sourceLabel('default'),
+    token: Object.hasOwn(stored, 'token') && stored.token ? sourceLabel('file') : sourceLabel('default'),
+    timeout_ms: Object.hasOwn(stored, 'timeout_ms') ? sourceLabel('file') : sourceLabel('default'),
+  };
+
+  // Token priority: env var > keyring > config file
+  const tokenOverride = readEnvOverride(ENV_TOKEN);
+  if (tokenOverride) {
+    values.token = tokenOverride;
+    sources.token = sourceLabel('env', ENV_TOKEN);
+  } else {
+    const keyringToken = getTokenFromKeyring();
+    if (keyringToken) {
+      values.token = keyringToken;
+      sources.token = 'keyring';
+    }
+    // else: keep token from config file (already in values from stored)
+  }
+
+  const apiUrlOverride = readEnvOverride(ENV_API_URL);
+  if (apiUrlOverride) {
+    values.api_url = apiUrlOverride;
+    sources.api_url = sourceLabel('env', ENV_API_URL);
+  }
+
+  const timeoutOverride = readEnvOverride(ENV_TIMEOUT_MS);
+  if (timeoutOverride) {
+    values.timeout_ms = normalizeTimeoutMs(timeoutOverride, `environment variable ${ENV_TIMEOUT_MS}`);
+    sources.timeout_ms = sourceLabel('env', ENV_TIMEOUT_MS);
+  }
+
+  values.timeout_ms = normalizeTimeoutMs(values.timeout_ms, 'timeout_ms');
+
+  return {
+    configFile: getConfigFile(),
+    rawValues: stored,
+    values,
+    sources,
+  };
+}
+
+export function normalizeTimeoutMs(value, sourceLabel = 'timeout_ms') {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    configError(`${sourceLabel} must be a positive integer.`);
+  }
+  return parsed;
+}
+
+export function loadConfig() {
+  return buildConfigSnapshot().values;
+}
+
+export function saveConfig(config, { insecure = false } = {}) {
+  ensureConfigDir();
+  const configFile = getConfigFile();
+  const nextConfig = normalizeConfig(config, 'config');
+
+  // Try to save token to OS keyring; fall back to config file
+  let tokenInKeyring = false;
+  if (nextConfig.token && !insecure) {
+    tokenInKeyring = saveTokenToKeyring(nextConfig.token);
+  }
+
+  // Write config file — exclude token if it's in the keyring
+  const fileConfig = { ...nextConfig };
+  if (tokenInKeyring) {
+    delete fileConfig.token;
+  }
+
+  const tempFile = `${configFile}.tmp`;
+  writeFileSync(tempFile, JSON.stringify(fileConfig, null, 2) + '\n', { mode: 0o600 });
+  renameSync(tempFile, configFile);
+
+  return { tokenInKeyring };
+}
+
+export function getConfigSnapshot() {
+  return buildConfigSnapshot();
+}
+
+export function getToken() {
+  const config = loadConfig();
+  return config.token;
+}
+
+export function getApiUrl() {
+  const config = loadConfig();
+  return config.api_url;
+}
+
+export function getRequestTimeoutMs() {
+  return loadConfig().timeout_ms;
+}

package/src/keyring.js

@@ -0,0 +1,65 @@
+import { createRequire } from 'module';
+
+const SERVICE = 'insightfulpipe-cli';
+const ACCOUNT = 'api-token';
+
+let _Entry;
+let _loaded = false;
+
+function loadEntry() {
+  if (_loaded) return _Entry;
+  _loaded = true;
+  try {
+    const require = createRequire(import.meta.url);
+    _Entry = require('@napi-rs/keyring').Entry;
+  } catch {
+    _Entry = null;
+  }
+  return _Entry;
+}
+
+function getEntry() {
+  const Entry = loadEntry();
+  if (!Entry) return null;
+  try {
+    return new Entry(SERVICE, ACCOUNT);
+  } catch {
+    return null;
+  }
+}
+
+export function saveTokenToKeyring(token) {
+  const entry = getEntry();
+  if (!entry) return false;
+  try {
+    entry.setPassword(token);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function getTokenFromKeyring() {
+  const entry = getEntry();
+  if (!entry) return null;
+  try {
+    return entry.getPassword() || null;
+  } catch {
+    return null;
+  }
+}
+
+export function deleteTokenFromKeyring() {
+  const entry = getEntry();
+  if (!entry) return false;
+  try {
+    entry.deletePassword();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function isKeyringAvailable() {
+  return getEntry() !== null;
+}

package/src/output.js

@@ -0,0 +1,33 @@
+export function printJson(data) {
+  console.log(JSON.stringify(data, null, 2));
+}
+
+export function wantsJson(command) {
+  return Boolean(command?.optsWithGlobals?.().json);
+}
+
+export function printTable(rows, columns) {
+  if (!rows || rows.length === 0) {
+    console.log('No data.');
+    return;
+  }
+
+  const widths = {};
+  for (const col of columns) {
+    widths[col.key] = col.label.length;
+    for (const row of rows) {
+      const val = String(row[col.key] ?? '');
+      widths[col.key] = Math.max(widths[col.key], val.length);
+    }
+  }
+
+  const header = columns.map(c => c.label.padEnd(widths[c.key])).join('  ');
+  const separator = columns.map(c => '-'.repeat(widths[c.key])).join('  ');
+
+  console.log(header);
+  console.log(separator);
+  for (const row of rows) {
+    const line = columns.map(c => String(row[c.key] ?? '').padEnd(widths[c.key])).join('  ');
+    console.log(line);
+  }
+}