mantisai-cli 2.0.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "mantis-plugins",
+  "owner": {
+    "name": "Kellis Lab"
+  },
+  "plugins": [
+    {
+      "name": "mantis",
+      "description": "Mantis MCP: spaces, threads, and map context for Claude Code",
+      "version": "1.0.15",
+      "source": "./"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "mantis",
+  "description": "Connect Claude Code to Mantis MCP — explore maps, clusters, and notebooks in your spaces",
+  "version": "1.0.15",
+  "author": {
+    "name": "MIT Mantis"
+  },
+  "homepage": "https://mantis.csail.mit.edu",
+  "userConfig": {
+    "api_base_url": {
+      "type": "string",
+      "title": "Mantis API URL",
+      "description": "Base URL only (no path). Default is the CSAIL H200 API; use http://localhost:8000 for local Docker.",
+      "default": "https://kellis-h200-1.csail.mit.edu",
+      "required": true
+    }
+  }
+}

package/.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "mantis": {
+      "type": "http",
+      "url": "http://localhost:8000/mcp_integrated/",
+      "headers": {
+        "X-Space-State-ID": "51e4a4c2-1510-4456-afe9-ccbd422c7646"
+      }
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Kellis Lab, MIT
+
+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,125 @@
+# mantisai-cli
+
+Mantis developer CLI — manage spaces, create maps from local data, and configure [Claude Code](https://code.claude.com) as a Mantis client. Distributed alongside the **mantis@mantis-plugins** Claude Code plugin.
+
+> **Naming note:** the repo is `KellisLab/mantis-cli` but the npm package is published as **`mantisai-cli`** because `mantis-cli` was already taken on npm. The binary you run is just `mantis`.
+
+## Requirements
+
+- [Node.js](https://nodejs.org/) 18+
+- A running Mantis API (default `https://kellis-h200-1.csail.mit.edu`; local dev: `http://localhost:8000`)
+- A Mantis **Developer API key** (`live_…`) from https://mantis.csail.mit.edu/developer/#keys
+- (Optional, for plugin features) [Claude Code](https://code.claude.com) (`claude` on your PATH)
+
+## Install
+
+```bash
+npm install -g mantisai-cli
+mantis setup
+```
+
+`mantis setup` walks through API URL, API key, space, and thread selection. If Claude Code is installed, it also registers the **mantis@mantis-plugins** plugin and writes the MCP config.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `mantis setup` | Connect to Mantis, pick space & thread, configure Claude Code |
+| `mantis status` | Show current API, space, thread, and MCP URL |
+| `mantis select [space\|thread\|both]` | Switch active space and/or thread |
+| `mantis create map <file>` | Create a Mantis map from a local CSV/XLSX |
+| `mantis create codebase [root]` | Index a local codebase to CSV; optionally create a map |
+
+Run any command with `--help` for full options.
+
+### Examples
+
+```bash
+# Create a new private space and load a CSV as a map
+mantis create map ./data.csv \
+  --space-mode new --space-name "Sales" --private \
+  --map-name "Q4 Pipeline" \
+  --title-column name --semantic-column description --numeric-column revenue
+
+# Add a map to an existing space
+mantis create map ./more-data.csv \
+  --space-mode existing --space-id <uuid> \
+  --map-name "Cohort 2"
+
+# Index your repo into Mantis
+mantis create codebase . --create-map --space-mode new --space-name "Repo Index" --private
+```
+
+## Claude Code integration
+
+After `mantis setup`:
+
+1. Open Claude Code (restart if it was already running).
+2. `/plugin` → enable **mantis @ mantis-plugins** (user scope) if needed.
+3. `/reload-plugins`
+4. Confirm with `/mantis:status`.
+
+### Slash commands
+
+| Command | Description |
+|---------|-------------|
+| `/mantis:connect` | Run setup / reconnect |
+| `/mantis:space` | Change space (search or paste a `/space/{uuid}` link) |
+| `/mantis:thread` | Change thread (space state) |
+| `/mantis:status` | Show current space, thread, and MCP URL |
+| `/mantis:select` | Quick space/thread selection |
+
+After changing **thread**, run `/reload-plugins` so MCP picks up the new `X-Space-State-ID` header.
+
+### Paste a space link
+
+In `mantis setup` or `/mantis:space`, paste a URL such as:
+
+`https://mantis.csail.mit.edu/space/1e1ed055-c869-4b78-b41f-4216a44049d4/`
+
+Use the same Mantis API base URL as the space you are targeting (local vs production).
+
+## Update
+
+**CLI**:
+
+```bash
+npm install -g mantisai-cli@latest
+```
+
+**Plugin (slash commands, MCP, skills)** — in Claude Code:
+
+```text
+/plugin marketplace update mantis-plugins
+```
+
+Then update **mantis@mantis-plugins** and `/reload-plugins`.
+
+## Manual plugin install
+
+```bash
+claude plugin marketplace add KellisLab/mantis-cli
+claude plugin install mantis@mantis-plugins --scope user
+```
+
+Enable in `/plugin`, then `/reload-plugins`.
+
+## Migrating from `mantis-claude-code`
+
+If you previously installed the package as `mantis-claude-code`, migrate with:
+
+```bash
+npm uninstall -g mantis-claude-code
+npm install -g mantisai-cli
+mantis setup
+```
+
+Your local config at `~/.mantis/claude-code/config.json` is preserved.
+
+## npm
+
+https://www.npmjs.com/package/mantisai-cli
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/bin/mantis-list-spaces.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import { spacesForPrompt } from '../lib/list-cli.js';
+
+const args = process.argv.slice(2);
+let filter = '';
+let offset = 0;
+let limit = 4;
+for (let i = 0; i < args.length; i++) {
+  const a = args[i];
+  if (a === '--offset') {
+    offset = parseInt(args[++i], 10) || 0;
+    continue;
+  }
+  if (a === '--limit') {
+    limit = parseInt(args[++i], 10) || 4;
+    continue;
+  }
+  if (a === '--filter') {
+    filter = args[++i] ?? '';
+    continue;
+  }
+  filter = args.slice(i).join(' ').trim();
+  break;
+}
+
+try {
+  const data = await spacesForPrompt(filter, { limit, offset });
+  process.stdout.write(JSON.stringify(data));
+} catch (e) {
+  console.error(JSON.stringify({ error: e.message }));
+  process.exit(1);
+}

package/bin/mantis-list-threads.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import { threadsForPrompt } from '../lib/list-cli.js';
+
+const args = process.argv.slice(2);
+let filter = '';
+let offset = 0;
+let limit = 4;
+for (let i = 0; i < args.length; i++) {
+  const a = args[i];
+  if (a === '--offset') {
+    offset = parseInt(args[++i], 10) || 0;
+    continue;
+  }
+  if (a === '--limit') {
+    limit = parseInt(args[++i], 10) || 4;
+    continue;
+  }
+  if (a === '--filter') {
+    filter = args[++i] ?? '';
+    continue;
+  }
+  filter = args.slice(i).join(' ').trim();
+  break;
+}
+
+try {
+  const data = await threadsForPrompt(filter, { limit, offset });
+  process.stdout.write(JSON.stringify(data));
+} catch (e) {
+  console.error(JSON.stringify({ error: e.message }));
+  process.exit(1);
+}

package/bin/mantis-mcp-headers.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { loadConfig } from '../lib/config.js';
+
+const cfg = loadConfig();
+const headers = {};
+if (cfg.spaceStateId) {
+  headers['X-Space-State-ID'] = String(cfg.spaceStateId);
+}
+process.stdout.write(JSON.stringify(headers));

package/bin/mantis-pick-space.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { pickSpace } from '../lib/picker.js';
+
+const filter = process.argv.slice(2).join(' ').trim();
+await pickSpace(filter);

package/bin/mantis-pick-thread.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { pickThread } from '../lib/picker.js';
+
+const filter = process.argv.slice(2).join(' ').trim();
+await pickThread(filter);

package/bin/mantis-resolve-space.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { loadConfig } from '../lib/config.js';
+import { resolveSpaceFromInput } from '../lib/spaces.js';
+
+const input = process.argv.slice(2).join(' ').trim();
+if (!input) {
+  console.error(JSON.stringify({ error: 'Provide a space link or UUID' }));
+  process.exit(1);
+}
+
+try {
+  const cfg = loadConfig();
+  if (!cfg.apiKey || !cfg.apiBaseUrl) {
+    throw new Error('Run mantis setup first (API key + URL).');
+  }
+  const space = await resolveSpaceFromInput(cfg.apiBaseUrl, cfg.apiKey, input);
+  if (!space) {
+    console.error(JSON.stringify({ error: 'Space not found or no access' }));
+    process.exit(1);
+  }
+  process.stdout.write(JSON.stringify({ space, threadCleared: true }));
+} catch (e) {
+  console.error(JSON.stringify({ error: e.message }));
+  process.exit(1);
+}

package/bin/mantis-select.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { pickSpace, pickThread } from '../lib/picker.js';
+import { banner } from '../lib/ui.js';
+
+banner('Mantis — switch space / thread');
+await pickSpace();
+await pickThread();

package/bin/mantis-set-space.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { loadConfig, saveConfig } from '../lib/config.js';
+import { syncMcpConfigs } from '../lib/mcp-config.js';
+
+const id = process.argv[2];
+const name = process.argv[3] || '';
+if (!id) {
+  console.error('Usage: mantis-set-space <space-uuid> [name]');
+  process.exit(1);
+}
+
+const cfg = loadConfig();
+const changed = cfg.spaceId !== id;
+const next = {
+  ...cfg,
+  spaceId: id,
+  spaceName: name || cfg.spaceName,
+  ...(changed ? { spaceStateId: undefined, spaceStateName: undefined } : {}),
+};
+saveConfig(next);
+syncMcpConfigs(next);
+console.log(
+  JSON.stringify({
+    ok: true,
+    spaceId: id,
+    spaceName: name,
+    threadCleared: changed,
+    needThread: changed,
+    needReloadPlugins: true,
+  }),
+);

package/bin/mantis-set-thread.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import { createSpaceState } from '../lib/api.js';
+import { loadConfig, saveConfig } from '../lib/config.js';
+import { syncMcpConfigs } from '../lib/mcp-config.js';
+
+const arg = process.argv[2];
+const arg2 = process.argv[3];
+if (!arg) {
+  console.error('Usage: mantis-set-thread <thread-uuid> [name] | mantis-set-thread --new [name]');
+  process.exit(1);
+}
+
+const cfg = loadConfig();
+if (!cfg.apiKey || !cfg.apiBaseUrl || !cfg.spaceId) {
+  console.error('Run mantis setup and pick a space first.');
+  process.exit(1);
+}
+
+let thread;
+if (arg === '--new') {
+  const name = arg2 || 'Claude Code';
+  thread = await createSpaceState(cfg.apiBaseUrl, cfg.apiKey, cfg.spaceId, name);
+} else {
+  thread = { id: arg, name: arg2 || arg };
+}
+
+const next = {
+  ...cfg,
+  spaceStateId: thread.id,
+  spaceStateName: thread.name,
+};
+saveConfig(next);
+syncMcpConfigs(next);
+console.log(JSON.stringify({ ok: true, spaceStateId: thread.id, name: thread.name }));

package/bin/mantis-setup.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+import {
+  DEFAULT_API_BASE,
+  DEVELOPER_PORTAL_URL,
+  loadConfig,
+  normalizeBaseUrl,
+  saveConfig,
+} from '../lib/config.js';
+import { pickSpace, pickThread } from '../lib/picker.js';
+import { installClaudePlugin } from '../lib/claude-plugin.js';
+import { syncMcpConfigs } from '../lib/mcp-config.js';
+import { banner, die, info, promptInput, promptSecret, success } from '../lib/ui.js';
+
+async function main() {
+  const prev = loadConfig();
+  banner('Mantis ↔ Claude Code', 'Links your Claude Code session to a Mantis space and thread');
+
+  const apiBaseUrl = normalizeBaseUrl(
+    await promptInput('Mantis API URL', {
+      default: prev.apiBaseUrl || process.env.MANTIS_API_URL || DEFAULT_API_BASE,
+    }),
+  );
+  info(`API keys: ${DEVELOPER_PORTAL_URL}`);
+  const apiKey = (await promptSecret('API key (Ctrl+click link above to open portal)', {
+    default: prev.apiKey,
+  }))?.trim();
+  if (!apiKey) die('API key is required.');
+
+  saveConfig({ apiBaseUrl, apiKey });
+
+  const afterSpace = await pickSpace();
+  const final = await pickThread();
+  saveConfig({ ...final, apiBaseUrl, apiKey });
+  syncMcpConfigs({ ...final, apiBaseUrl, apiKey });
+
+  console.log('');
+  success('Setup complete');
+  info(`Space:  ${final.spaceName} (${final.spaceId})`);
+  info(`Thread: ${final.spaceStateName} (${final.spaceStateId})`);
+  info(`MCP:    ${apiBaseUrl}/mcp_integrated/`);
+  info('In Claude Code run /reload-plugins so MCP uses this space and thread.');
+  try {
+    const cc = installClaudePlugin();
+    if (cc.method === 'cli') {
+      success(`Claude Code plugin installed (mantis@mantis-plugins, ${cc.scope || 'user'} scope)`);
+      info('Run /reload-plugins in Claude Code if it is already open');
+    } else {
+      success('Claude Code settings updated');
+      info(cc.hint);
+    }
+  } catch (e) {
+    info(`Claude plugin install failed: ${e.message}`);
+    info('Fix: claude plugin install mantis@mantis-plugins');
+    info('Then in Claude Code: Enable plugin → /reload-plugins');
+  }
+  console.log('');
+}
+
+main().catch((e) => die(e.message || String(e)));

package/bin/mantis-status.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { loadConfig, configPath, mcpUrl } from '../lib/config.js';
+
+const cfg = loadConfig();
+console.log('Mantis Claude Code — status\n');
+console.log(`Config file: ${configPath()}`);
+console.log(`API base:    ${cfg.apiBaseUrl || '(not set — use mantis setup)'}`);
+console.log(`MCP URL:     ${cfg.apiBaseUrl ? mcpUrl(cfg) : '(run setup)'}`);
+console.log(`API key:     ${cfg.apiKey ? '***' + cfg.apiKey.slice(-6) : '(not set)'}`);
+console.log(`Space:       ${cfg.spaceName || '-'} (${cfg.spaceId || '-'})`);
+console.log(`Thread:      ${cfg.spaceStateName || '-'} (${cfg.spaceStateId || '-'})`);
+if (!cfg.spaceStateId) {
+  console.log('\nNo thread selected. Run: mantis setup');
+  process.exit(1);
+}

package/bin/mantis.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import { Command } from 'commander';
+
+import { createCodebaseCsv } from '../lib/codebase-csv.js';
+import { createMapFlow } from '../lib/map-create.js';
+import { die, info, success } from '../lib/ui.js';
+
+const program = new Command();
+
+function defaultCodebaseOut(root) {
+  const base = path.basename(path.resolve(root || process.cwd())) || 'codebase';
+  return path.resolve(process.cwd(), `${base}-codebase.csv`);
+}
+
+function addMapOptions(cmd) {
+  return cmd
+    .option('--space-mode <mode>', 'new or existing')
+    .option('--space-id <uuid>', 'existing Mantis space id')
+    .option('--space-name <name>', 'new space name or display name for existing space')
+    .option('--space-search <query>', 'search text for choosing an existing space')
+    .option('--public', 'make a new space public')
+    .option('--private', 'make a new space private')
+    .option('--map-name <name>', 'map name')
+    .option('--title-column <columns>', 'comma-separated title column names')
+    .option('--semantic-column <columns>', 'comma-separated semantic column names')
+    .option('--numeric-column <columns>', 'comma-separated numeric column names')
+    .option('--categoric-column <columns>', 'comma-separated categorical column names')
+    .option('--date-column <columns>', 'comma-separated date column names')
+    .option('--links-column <columns>', 'comma-separated link column names')
+    .option('--delete-column <columns>', 'comma-separated ignored column names')
+    .option('--data-types <json>', 'raw data_types JSON array')
+    .option('--activate', 'set created space/thread as active in Claude Code')
+    .option('--no-activate', 'do not set active Claude Code context')
+    .option('--thread-name <name>', 'thread name when activating');
+}
+
+program
+  .name('mantis')
+  .description('Mantis developer CLI — manage spaces, create maps, and configure Claude Code integration')
+  .version('2.0.0');
+
+program
+  .command('setup')
+  .description('Connect Claude Code to Mantis')
+  .action(async () => import('./mantis-setup.js'));
+
+program
+  .command('status')
+  .description('Show current Mantis Claude Code config')
+  .action(async () => import('./mantis-status.js'));
+
+program
+  .command('select')
+  .description('Select active Mantis space and thread')
+  .argument('[target]', 'space, thread, or both', 'both')
+  .action(async (target) => {
+    if (target === 'space') return import('./mantis-pick-space.js');
+    if (target === 'thread') return import('./mantis-pick-thread.js');
+    return import('./mantis-select.js');
+  });
+
+const create = program.command('create').description('Create Mantis resources from local inputs');
+
+addMapOptions(create
+  .command('map')
+  .description('Create a Mantis map from a local CSV/XLSX file')
+  .argument('<file>', 'CSV/XLSX file path'))
+  .action(async (file, opts) => {
+    try {
+      if (opts.private) opts.public = false;
+      const result = await createMapFlow(path.resolve(file), opts);
+      console.log(JSON.stringify(result, null, 2));
+    } catch (e) {
+      die(e.message || String(e));
+    }
+  });
+
+addMapOptions(create
+  .command('codebase')
+  .description('Index a local codebase into CSV, optionally creating a Mantis map')
+  .argument('[root]', 'codebase root', '.')
+  .option('--out <file>', 'output CSV path')
+  .option('--max-chars <n>', 'max characters stored per file', (v) => Number(v), 12000)
+  .option('--create-map', 'create a Mantis map after writing the CSV'))
+  .action(async (root, opts) => {
+    try {
+      if (opts.private) opts.public = false;
+      const out = path.resolve(opts.out || defaultCodebaseOut(root));
+      const result = await createCodebaseCsv(root, out, { maxChars: opts.maxChars });
+      success(`Indexed ${result.count} files`);
+      info(`CSV: ${result.outFile}`);
+      if (opts.createMap) {
+        const mapResult = await createMapFlow(result.outFile, {
+          ...opts,
+          mapName: opts.mapName || `${path.basename(path.resolve(root))} Code Index`,
+          titleColumn: opts.titleColumn || 'path',
+          semanticColumn: opts.semanticColumn || 'summary,content,imports',
+          categoricColumn: opts.categoricColumn || 'language,kind,extension',
+          numericColumn: opts.numericColumn || 'loc,bytes',
+        });
+        console.log(JSON.stringify({ csv: result, map: mapResult }, null, 2));
+      } else {
+        console.log(JSON.stringify(result, null, 2));
+      }
+    } catch (e) {
+      die(e.message || String(e));
+    }
+  });
+
+program.parseAsync(process.argv);

package/lib/api.js

@@ -0,0 +1,100 @@
+import { normalizeBaseUrl } from './config.js';
+
+async function request(baseUrl, apiKey, method, pathname, { params, body } = {}) {
+  const root = normalizeBaseUrl(baseUrl);
+  const url = new URL(pathname.startsWith('/') ? pathname : `/${pathname}`, `${root}/`);
+  if (params) {
+    for (const [k, v] of Object.entries(params)) {
+      if (v != null && v !== '') url.searchParams.set(k, String(v));
+    }
+  }
+  const res = await fetch(url, {
+    method,
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      Accept: 'application/json',
+      ...(body ? { 'Content-Type': 'application/json' } : {}),
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const text = await res.text();
+  let data;
+  try {
+    data = text ? JSON.parse(text) : {};
+  } catch {
+    data = { error: text || res.statusText };
+  }
+  if (!res.ok) {
+    const msg = data.error || data.detail || res.statusText || `HTTP ${res.status}`;
+    throw new Error(msg);
+  }
+  return data;
+}
+
+export function listSpaces(
+  baseUrl,
+  apiKey,
+  { scope = 'accessible', limit = 20, offset = 0, q, space_id } = {},
+) {
+  return request(baseUrl, apiKey, 'GET', '/api/v1/me/spaces/', {
+    params: { scope, limit, offset, q, space_id },
+  });
+}
+
+export function listSpaceStates(baseUrl, apiKey, spaceId, { limit = 20, offset = 0 } = {}) {
+  return request(baseUrl, apiKey, 'GET', '/api/v1/me/space-states/', {
+    params: { space_id: spaceId, limit, offset },
+  });
+}
+
+export function createSpaceState(baseUrl, apiKey, spaceId, name = 'Claude Code') {
+  return request(baseUrl, apiKey, 'POST', '/api/v1/me/space-states/', {
+    body: { space_id: spaceId, name },
+  });
+}
+
+export function createSpace(baseUrl, apiKey, { name, isPublic = false }) {
+  return request(baseUrl, apiKey, 'POST', '/api/v1/spaces/', {
+    body: { name, public: Boolean(isPublic) },
+  });
+}
+
+export async function createMapInSpace(baseUrl, apiKey, spaceId, {
+  file,
+  mapName,
+  dataTypes,
+  selectedFields,
+  fieldWeights,
+}) {
+  const root = normalizeBaseUrl(baseUrl);
+  const url = new URL(`/api/v1/spaces/${encodeURIComponent(spaceId)}/maps/`, `${root}/`);
+  const form = new FormData();
+  const bytes = await import('node:fs/promises').then((fs) => fs.readFile(file));
+  const name = await import('node:path').then((path) => path.basename(file));
+  form.set('file', new Blob([bytes]), name);
+  if (mapName) form.set('map_name', mapName);
+  if (dataTypes) form.set('data_types', JSON.stringify(dataTypes));
+  if (selectedFields) form.set('selected_fields', JSON.stringify(selectedFields));
+  if (fieldWeights) form.set('field_weights', JSON.stringify(fieldWeights));
+
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      Accept: 'application/json',
+    },
+    body: form,
+  });
+  const text = await res.text();
+  let data;
+  try {
+    data = text ? JSON.parse(text) : {};
+  } catch {
+    data = { error: text || res.statusText };
+  }
+  if (!res.ok) {
+    const msg = data.error || data.detail || res.statusText || `HTTP ${res.status}`;
+    throw new Error(msg);
+  }
+  return data;
+}