Supermodel TypeScript SDK

Official TypeScript/JavaScript SDK for the Supermodel API.

Generate code graphs, dependency analysis, and domain models from your source code repositories.

Installation

npm install @supermodeltools/sdk

Quick Start

Basic Usage (Auto-Polling)

The SDK provides a high-level SupermodelClient that automatically handles async job polling:

import { SupermodelClient, DefaultApi, Configuration } from '@supermodeltools/sdk';
import { readFile } from 'node:fs/promises';

// Configure the API client
const api = new DefaultApi(new Configuration({
  basePath: 'https://api.supermodeltools.com',
  apiKey: () => process.env.SUPERMODEL_API_KEY || ''
}));

// Create the async client wrapper
const client = new SupermodelClient(api);

// Generate a code graph (polling handled automatically)
const zipBuffer = await readFile('./my-repo.zip');
const zipBlob = new Blob([zipBuffer]);

const result = await client.generateSupermodelGraph(zipBlob);
console.log(`Generated graph with ${result.graph.nodes.length} nodes`);

Advanced Configuration

Configure polling behavior for long-running operations:

const client = new SupermodelClient(api, {
  // Maximum time to wait for job completion
  timeoutMs: 900000,  // 15 minutes (default)

  // Polling interval when server doesn't specify
  defaultRetryIntervalMs: 10000,  // 10 seconds (default)

  // Maximum number of polling attempts
  maxPollingAttempts: 90,  // (default)

  // Progress callback
  onPollingProgress: (progress) => {
    console.log(`Job ${progress.jobId}: ${progress.status} ` +
                `(${progress.attempt}/${progress.maxAttempts})`);
  },

  // Cancellation support
  signal: abortController.signal,
});

Per-Request Configuration

Override client defaults for specific requests:

// Use a custom idempotency key
const result = await client.generateDependencyGraph(zipBlob, {
  idempotencyKey: 'my-repo:dependency:abc123',
});

// Add custom headers (e.g., for different auth)
const result = await client.generateCallGraph(zipBlob, {
  initOverrides: {
    headers: { 'Authorization': 'Bearer custom-token' }
  }
});

// Cancel a specific request
const controller = new AbortController();
const promise = client.generateParseGraph(zipBlob, {
  signal: controller.signal
});

// Later: controller.abort();

Available Methods

SupermodelClient (Async Wrapper)

All methods automatically handle polling until job completion:

• generateSupermodelGraph(file, options?) - Full Supermodel IR with all analysis
• generateDependencyGraph(file, options?) - Module/package dependencies
• generateCallGraph(file, options?) - Function-level call relationships
• generateDomainGraph(file, options?) - High-level domain model
• generateParseGraph(file, options?) - AST-level parse tree

Raw API (Manual Polling)

Access the underlying API for manual control:

const rawApi = client.rawApi;

// Make initial request
let response = await rawApi.generateDependencyGraph({
  idempotencyKey: 'my-key',
  file: zipBlob
});

// Poll manually
while (response.status === 'pending' || response.status === 'processing') {
  await sleep(response.retryAfter * 1000);
  response = await rawApi.generateDependencyGraph({
    idempotencyKey: 'my-key',
    file: zipBlob
  });
}

if (response.status === 'completed') {
  console.log(response.result);
}

Configuration Options

AsyncClientOptions

Option	Type	Default	Description
timeoutMs	number	900000 (15 min)	Maximum time to wait for job completion
defaultRetryIntervalMs	number	10000 (10 sec)	Polling interval when server doesn't specify
maxPollingAttempts	number	90	Maximum number of polling attempts
onPollingProgress	function	undefined	Callback for polling progress updates
generateIdempotencyKey	function	crypto.randomUUID()	Custom idempotency key generator
signal	AbortSignal	undefined	AbortSignal for cancelling operations

GraphRequestOptions

Option	Type	Default	Description
idempotencyKey	string	auto-generated	Idempotency key for request deduplication
initOverrides	RequestInit	undefined	Custom fetch options (headers, etc.)
signal	AbortSignal	undefined	Request-specific abort signal

Error Handling

import { JobFailedError, PollingTimeoutError } from '@supermodeltools/sdk';

try {
  const result = await client.generateDependencyGraph(zipBlob);
} catch (error) {
  if (error instanceof JobFailedError) {
    console.error(`Job ${error.jobId} failed: ${error.errorMessage}`);
  } else if (error instanceof PollingTimeoutError) {
    console.error(`Job ${error.jobId} timed out after ${error.timeoutMs}ms`);
  } else if (error.name === 'AbortError') {
    console.log('Operation cancelled');
  } else {
    throw error;
  }
}

Idempotency

The API uses idempotency keys to prevent duplicate processing. The same key will always return the same result:

// Generate a stable key from your repo state
import crypto from 'crypto';
import { execSync } from 'child_process';

const gitHash = execSync('git rev-parse --short HEAD').toString().trim();
const idempotencyKey = `my-project:supermodel:${gitHash}`;

// This will generate once, then return cached result on subsequent calls
const result = await client.generateSupermodelGraph(zipBlob, {
  idempotencyKey
});

Preparing Repository Archives

For Git Repositories (Recommended)

cd /path/to/your/repo
git archive -o /tmp/repo.zip HEAD

This automatically respects .gitignore and creates clean, reproducible archives.

For Any Directory

cd /path/to/your/repo
zip -r /tmp/repo.zip . \
  -x "node_modules/*" \
  -x ".git/*" \
  -x "dist/*" \
  -x "*.pyc" \
  -x "__pycache__/*"

What to Include

• ✅ Source code files (.py, .js, .ts, .java, etc.)
• ✅ Configuration files (package.json, pyproject.toml, etc.)
• ✅ Type definitions (.d.ts, .pyi)
• ❌ Dependencies (node_modules/, venv/, target/)
• ❌ Build outputs (dist/, build/, .next/)
• ❌ Large binaries, images, datasets

Size Limits

Archives should be under 50MB. If larger:

• Ensure dependencies are excluded
• Consider analyzing a subdirectory
• Check for accidentally committed binaries

TypeScript Support

Full TypeScript definitions are included. Types are automatically resolved via package.json.

import type {
  SupermodelIR,
  CodeGraphEnvelope,
  DomainClassificationResponse,
} from '@supermodeltools/sdk';

// Types are available for all request/response models

Environment Support

• ✅ Node.js (18+)
• ✅ Modern browsers (with Blob support)
• ✅ Webpack, Vite, Rollup
• ✅ ES6 modules and CommonJS

Authentication

Get your API key from the Supermodel Dashboard.

const api = new DefaultApi(new Configuration({
  basePath: 'https://api.supermodeltools.com',
  apiKey: () => process.env.SUPERMODEL_API_KEY || ''
}));

Rate Limiting

The API includes rate limiting headers in responses:

const response = await rawApi.generateDependencyGraphRaw({
  idempotencyKey: 'key',
  file: blob
});

console.log(response.raw.headers.get('RateLimit-Limit'));
console.log(response.raw.headers.get('RateLimit-Remaining'));
console.log(response.raw.headers.get('RateLimit-Reset'));

Examples

Integration with mcpbr

import { SupermodelClient, DefaultApi, Configuration } from '@supermodeltools/sdk';

const api = new DefaultApi(new Configuration({
  basePath: process.env.SUPERMODEL_BASE_URL || 'https://api.supermodeltools.com',
  apiKey: () => process.env.SUPERMODEL_API_KEY || ''
}));

// Configure for long-running benchmark operations
const client = new SupermodelClient(api, {
  timeoutMs: 900000,           // 15 minutes
  maxPollingAttempts: 90,       // 90 attempts
  onPollingProgress: (progress) => {
    console.log(`[${progress.jobId}] ${progress.status} - ` +
                `attempt ${progress.attempt}/${progress.maxAttempts}`);
  }
});

Links

• API Documentation
• GitHub Repository
• Dashboard
• Terms of Service

License

This SDK is licensed under the MIT License. See the main repository for details.