insightfulpipe 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## Unreleased
+
+- Refactored the CLI into modular command registration under `src/cli/`
+- Split shared CLI helpers into focused modules for errors, input, options, and query-context workflows
+- Aligned command names with the server surface using `query_data`, `execute_action`, and `query_contexts`
+- Added workspace, brand, prompt, doctor, and discovery commands
+- Added environment variable overrides and configurable request timeouts
+- Hardened API error handling for invalid URLs, transport failures, request timeouts, and HTML error pages
+- Added automated tests for routing, validation, confirmation behavior, JSON output, health checks, and timeout handling
+- Added opt-in live smoke tests and repository documentation
+- Added a CI workflow for automated test and package verification

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) InsightfulPipe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,140 @@
+# InsightfulPipe CLI
+
+Terminal access to InsightfulPipe raw APIs.
+
+Recommended workflow:
+
+1. Discover accounts and metadata with `query_contexts`
+2. Inspect supported actions with `query_contexts available_actions`
+3. Inspect exact request bodies with `query_contexts actions_details`
+4. Execute read operations with `query_data`
+5. Execute write operations with `execute_action`
+
+## Requirements
+
+- Node.js 18+
+- An InsightfulPipe API token starting with `ip_sk_`
+
+## Installation
+
+```bash
+npm install
+```
+
+Run locally with:
+
+```bash
+node bin/cli.js --help
+```
+
+## Authentication
+
+Store a token in `~/.insightfulpipe/config.json`:
+
+```bash
+node bin/cli.js auth
+```
+
+You can also pipe the token instead of typing it interactively:
+
+```bash
+printf '%s\n' "$INSIGHTFULPIPE_TOKEN" | node bin/cli.js auth
+```
+
+The CLI also reads these environment variables:
+
+- `INSIGHTFULPIPE_TOKEN`
+- `INSIGHTFULPIPE_API_URL`
+- `INSIGHTFULPIPE_TIMEOUT_MS`
+
+## Core Commands
+
+### Discovery
+
+```bash
+node bin/cli.js whoami
+node bin/cli.js platforms
+node bin/cli.js workspaces
+node bin/cli.js accounts --platform google-analytics
+node bin/cli.js sources --platform google-search-console
+node bin/cli.js brands --workspace 34
+```
+
+### Query Workflow
+
+```bash
+node bin/cli.js query_contexts accounts
+node bin/cli.js query_contexts available_actions --platform google-analytics
+node bin/cli.js query_contexts actions_details --platform google-analytics --actions get_report
+node bin/cli.js query_data google-analytics --body '{"action":"get_report","workspace_id":34,"brand_id":343,"property_id":"510157516","dimensions":["date"],"metrics":["sessions"],"start_date":"2026-03-01","end_date":"2026-03-07"}'
+```
+
+### Write operations
+
+`execute_action` is the canonical write command. The shorter `action` alias is still available.
+
+```bash
+node bin/cli.js execute_action facebook-pages --file payload.json
+```
+
+In non-interactive environments, pass `--yes` to confirm explicitly:
+
+```bash
+node bin/cli.js execute_action facebook-pages --file payload.json --yes
+```
+
+### Operational Checks
+
+```bash
+node bin/cli.js doctor
+node bin/cli.js --json doctor
+node bin/cli.js --json config
+```
+
+### Prompts
+
+```bash
+node bin/cli.js prompts google-ads
+node bin/cli.js prompts google-ads --id 12
+node bin/cli.js prompts google-ads --custom --workspace 34 --id 18
+```
+
+## Configuration
+
+Show the current config:
+
+```bash
+node bin/cli.js config
+```
+
+Set a custom API base URL:
+
+```bash
+node bin/cli.js config --set-url https://app.insightfulpipe.com
+```
+
+Local HTTP endpoints are allowed only with `--allow-insecure`.
+
+Set a request timeout:
+
+```bash
+node bin/cli.js config --set-timeout 15000
+```
+
+Use `--json` with discovery, configuration, and health commands when you want machine-readable output.
+
+## Testing
+
+Run the local test suite:
+
+```bash
+npm test
+```
+
+Run opt-in live smoke tests against the real backend:
+
+```bash
+INSIGHTFULPIPE_LIVE_TOKEN=ip_sk_xxx npm run test:live
+```
+
+The live smoke test creates an isolated temporary home directory and does not overwrite your real `~/.insightfulpipe` config.

package/SECURITY.md

@@ -0,0 +1,23 @@
+# Security Policy
+
+## Supported Scope
+
+This repository contains the local CLI only. Backend authorization, platform permissions, and data access are enforced by the InsightfulPipe API.
+
+## Reporting a Vulnerability
+
+Report security issues privately to the InsightfulPipe team. Do not open public issues for token leakage, privilege escalation, SSRF, authentication bypass, or sensitive data exposure.
+
+## Token Handling
+
+- API tokens are stored in `~/.insightfulpipe/config.json`
+- `INSIGHTFULPIPE_TOKEN` can be used instead of storing a token on disk
+- Interactive `auth` input is hidden from terminal echo
+- The CLI masks stored tokens in `config` output
+- Non-HTTPS API base URLs require explicit `--allow-insecure`
+
+## Operational Guidance
+
+- Prefer piping tokens through stdin in automation instead of placing them in shell history
+- Use a temporary `HOME` when running smoke tests against production
+- Treat `execute_action` as a privileged operation and require explicit confirmation in non-interactive flows

package/bin/cli.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+
+import { buildProgram } from '../src/cli/program.js';
+
+const program = buildProgram();
+
+try {
+  await program.parseAsync();
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`Error: ${message}`);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "insightfulpipe",
+  "version": "0.1.0",
+  "description": "InsightfulPipe CLI — query your marketing data from the terminal",
+  "bin": {
+    "insightfulpipe": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "scripts": {
+    "start": "node bin/cli.js",
+    "test": "node --test",
+    "test:unit": "node --test test/cli.test.js",
+    "test:live": "node --test test/live-smoke.test.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "insightfulpipe",
+    "marketing",
+    "analytics",
+    "cli",
+    "mcp"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@napi-rs/keyring": "^1.2.0",
+    "commander": "^13.0.0"
+  }
+}

package/src/api.js

@@ -0,0 +1,217 @@
+import { getApiUrl, getRequestTimeoutMs, getToken } from './config.js';
+
+let _insecureWarned = false;
+
+function warnIfInsecure() {
+  if (_insecureWarned) return;
+  const url = getApiUrl();
+  if (!url.startsWith('https://')) {
+    console.error('Warning: API URL is not using HTTPS. Traffic including your token is unencrypted.');
+    _insecureWarned = true;
+  }
+}
+
+const PLATFORM_SLUG_RE = /^[a-z0-9][a-z0-9-]*[a-z0-9]$/;
+
+export function validatePlatformSlug(slug) {
+  if (!PLATFORM_SLUG_RE.test(slug) || slug.includes('--')) {
+    console.error(`Error: Invalid platform slug "${slug}". Use lowercase letters, numbers, and hyphens only.`);
+    process.exit(1);
+  }
+}
+
+function requireAuth() {
+  const token = getToken();
+  if (!token) {
+    console.error('Error: Not authenticated. Run: insightfulpipe auth');
+    process.exit(1);
+  }
+  return token;
+}
+
+function buildApiUrl(path) {
+  const baseUrl = getApiUrl();
+
+  let base;
+  try {
+    base = new URL(baseUrl);
+  } catch {
+    throw new Error(`Configured API URL is invalid: ${baseUrl}`);
+  }
+
+  const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+  return new URL(`/api/raw${normalizedPath}`, base).toString();
+}
+
+function looksLikeHtml(text) {
+  const trimmed = text.trim().toLowerCase();
+  return trimmed.startsWith('<!doctype html') || trimmed.startsWith('<html');
+}
+
+function summarizeTextError(text, res) {
+  if (looksLikeHtml(text)) {
+    const titleMatch = text.match(/<title[^>]*>([^<]+)<\/title>/i);
+    const headingMatch = text.match(/<h1[^>]*>([^<]+)<\/h1>/i) || text.match(/<h2[^>]*>([^<]+)<\/h2>/i);
+    const summary = titleMatch?.[1]?.trim() || headingMatch?.[1]?.trim() || `HTTP ${res.status}`;
+
+    return {
+      error: true,
+      status: res.status,
+      message: `Server returned an HTML error page (${summary}).`,
+    };
+  }
+
+  return {
+    error: true,
+    status: res.status,
+    message: text,
+  };
+}
+
+async function parseJsonResponse(res) {
+  const text = await res.text();
+
+  if (!text.trim()) {
+    return {};
+  }
+
+  try {
+    return JSON.parse(text);
+  } catch {
+    if (res.ok) {
+      return {
+        error: true,
+        status: res.status,
+        message: 'Received invalid JSON from server.',
+        details: text,
+      };
+    }
+
+    return summarizeTextError(text, res);
+  }
+}
+
+async function apiRequest(method, path, body) {
+  warnIfInsecure();
+  const token = requireAuth();
+  const timeoutMs = getRequestTimeoutMs();
+
+  let url;
+  try {
+    url = buildApiUrl(path);
+  } catch (error) {
+    return {
+      error: true,
+      message: error.message,
+    };
+  }
+
+  const options = {
+    method,
+    headers: {
+      'Authorization': `Bearer ${token}`,
+      'Accept': 'application/json',
+    },
+  };
+
+  if (body !== undefined) {
+    options.headers['Content-Type'] = 'application/json';
+    options.body = JSON.stringify(body);
+  }
+
+  let res;
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    res = await fetch(url, { ...options, signal: controller.signal });
+  } catch (error) {
+    clearTimeout(timeout);
+    return {
+      error: true,
+      message:
+        error?.name === 'AbortError'
+          ? `Network request timed out after ${timeoutMs} ms`
+          : `Network request failed: ${error.message}`,
+    };
+  }
+  clearTimeout(timeout);
+
+  const data = await parseJsonResponse(res);
+
+  if (data && data.error) {
+    return data;
+  }
+
+  if (!res.ok) {
+    return {
+      error: true,
+      status: res.status,
+      ...(data && typeof data === 'object' ? data : { message: String(data) }),
+    };
+  }
+
+  return data;
+}
+
+export async function apiGet(path) {
+  return apiRequest('GET', path);
+}
+
+export async function apiPost(path, body) {
+  return apiRequest('POST', path, body);
+}
+
+export async function accountSummary() {
+  warnIfInsecure();
+  const token = requireAuth();
+  const timeoutMs = getRequestTimeoutMs();
+  let url;
+  try {
+    url = new URL('/oauth/api/account-summary/', new URL(getApiUrl())).toString();
+  } catch {
+    return {
+      error: true,
+      message: `Configured API URL is invalid: ${getApiUrl()}`,
+    };
+  }
+
+  let res;
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    res = await fetch(url, {
+      method: 'GET',
+      headers: {
+        'Authorization': `Bearer ${token}`,
+        'Accept': 'application/json',
+      },
+      signal: controller.signal,
+    });
+  } catch (error) {
+    clearTimeout(timeout);
+    return {
+      error: true,
+      message:
+        error?.name === 'AbortError'
+          ? `Network request timed out after ${timeoutMs} ms`
+          : `Network request failed: ${error.message}`,
+    };
+  }
+  clearTimeout(timeout);
+
+  const data = await parseJsonResponse(res);
+
+  if (data && data.error) {
+    return data;
+  }
+
+  if (!res.ok) {
+    return {
+      error: true,
+      status: res.status,
+      ...(data && typeof data === 'object' ? data : { message: String(data) }),
+    };
+  }
+
+  return data;
+}

package/src/cli/commands/auth.js

@@ -0,0 +1,30 @@
+import { getConfigSnapshot, saveConfig } from '../../config.js';
+import { fail } from '../errors.js';
+import { promptSecret } from '../input.js';
+
+export function registerAuthCommand(program) {
+  program
+    .command('auth')
+    .description('Save your InsightfulPipe API key')
+    .option('--insecure-storage', 'Save token to config file instead of OS keyring')
+    .action(async (opts) => {
+      const token = await promptSecret('Enter your API token: ');
+
+      if (!token) {
+        fail('No token provided.');
+      }
+
+      if (!token.startsWith('ip_sk_')) {
+        fail('Token must start with ip_sk_.');
+      }
+
+      const config = { ...getConfigSnapshot().rawValues, token };
+      const { tokenInKeyring } = saveConfig(config, { insecure: opts.insecureStorage });
+
+      if (tokenInKeyring) {
+        console.log('Authenticated successfully. Token saved to OS keyring.');
+      } else {
+        console.log('Authenticated successfully. Token saved to config file.');
+      }
+    });
+}

package/src/cli/commands/config.js

@@ -0,0 +1,62 @@
+import { getConfigSnapshot, normalizeTimeoutMs, saveConfig } from '../../config.js';
+import { printJson, wantsJson } from '../../output.js';
+import { validateConfiguredUrl } from '../options.js';
+
+export function registerConfigCommand(program) {
+  program
+    .command('config')
+    .description('Show current configuration')
+    .option('--set-url <url>', 'Set API URL')
+    .option('--set-timeout <ms>', 'Set request timeout in milliseconds')
+    .option('--allow-insecure', 'Allow http:// URLs for local development only')
+    .action((opts, command) => {
+      const snapshot = getConfigSnapshot();
+      const nextConfig = { ...snapshot.rawValues };
+
+      if (opts.setUrl) {
+        nextConfig.api_url = validateConfiguredUrl(opts.setUrl, opts.allowInsecure);
+      }
+
+      if (opts.setTimeout) {
+        nextConfig.timeout_ms = normalizeTimeoutMs(opts.setTimeout, '--set-timeout');
+      }
+
+      if (opts.setUrl || opts.setTimeout) {
+        saveConfig(nextConfig);
+        if (wantsJson(command)) {
+          printJson({
+            updated: true,
+            values: {
+              api_url: nextConfig.api_url ?? snapshot.values.api_url,
+              timeout_ms: nextConfig.timeout_ms ?? snapshot.values.timeout_ms,
+            },
+          });
+          return;
+        }
+
+        console.log(`API URL:  ${nextConfig.api_url ?? snapshot.values.api_url}`);
+        console.log(`Timeout:  ${nextConfig.timeout_ms ?? snapshot.values.timeout_ms} ms`);
+        return;
+      }
+
+      const output = {
+        config_file: snapshot.configFile,
+        values: {
+          api_url: snapshot.values.api_url,
+          token: snapshot.values.token ? `${snapshot.values.token.slice(0, 10)}...` : null,
+          timeout_ms: snapshot.values.timeout_ms,
+        },
+        sources: snapshot.sources,
+      };
+
+      if (wantsJson(command)) {
+        printJson(output);
+        return;
+      }
+
+      console.log(`Config file: ${output.config_file}`);
+      console.log(`API URL:     ${output.values.api_url} (${output.sources.api_url})`);
+      console.log(`Token:       ${output.values.token || 'Not set'} (${output.sources.token})`);
+      console.log(`Timeout:     ${output.values.timeout_ms} ms (${output.sources.timeout_ms})`);
+    });
+}