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

``bash
npm install @supermodeltools/sdk
`

Quick Start

$3

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

`typescript
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);
`

$3

Configure polling behavior for long-running operations:

`typescript
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,
});
`

$3

Override client defaults for specific requests:

`typescript
// 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

$3

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

$3

Access the underlying API for manual control:

`typescript
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

$3

| 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 |

$3

| 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

`typescript
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:

`typescript
// 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

$3

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

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

$3

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

$3

- ✅ 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

$3

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.

`typescript
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.

`typescript
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:

`typescript
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

$3

`typescript
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.