TypeScript SDK for the Supermodel API - code graph generation and analysis
npm install @supermodeltools/sdkOfficial TypeScript/JavaScript SDK for the Supermodel API.
Generate code graphs, dependency analysis, and domain models from your source code repositories.
``bash`
npm install @supermodeltools/sdk
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);`
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,
});
`
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();
`
All methods automatically handle polling until job completion:
- generateSupermodelGraph(file, options?) - Full Supermodel IR with all analysisgenerateDependencyGraph(file, options?)
- - Module/package dependenciesgenerateCallGraph(file, options?)
- - Function-level call relationshipsgenerateDomainGraph(file, options?)
- - High-level domain modelgenerateParseGraph(file, options?)
- - AST-level parse tree
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);
}
`
| 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 |
| 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 |
`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});Job ${error.jobId} timed out after ${error.timeoutMs}ms
} else if (error instanceof PollingTimeoutError) {
console.error();`
} else if (error.name === 'AbortError') {
console.log('Operation cancelled');
} else {
throw error;
}
}
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
});
`
`bash`
cd /path/to/your/repo
git archive -o /tmp/repo.zip HEAD
This automatically respects .gitignore and creates clean, reproducible archives.
`bash`
cd /path/to/your/repo
zip -r /tmp/repo.zip . \
-x "node_modules/*" \
-x ".git/*" \
-x "dist/*" \
-x "*.pyc" \
-x "__pycache__/*"
- ✅ Source code files (.py, .js, .ts, .java, etc.)package.json
- ✅ Configuration files (, pyproject.toml, etc.).d.ts
- ✅ Type definitions (, .pyi)node_modules/
- ❌ Dependencies (, venv/, target/)dist/
- ❌ Build outputs (, build/, .next/)
- ❌ Large binaries, images, datasets
Archives should be under 50MB. If larger:
- Ensure dependencies are excluded
- Consider analyzing a subdirectory
- Check for accidentally committed binaries
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
`
- ✅ Node.js (18+)
- ✅ Modern browsers (with Blob support)
- ✅ Webpack, Vite, Rollup
- ✅ ES6 modules and CommonJS
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 || ''
}));
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'));
`
`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}
);``
}
});
- API Documentation
- GitHub Repository
- Dashboard
- Terms of Service
This SDK is licensed under the MIT License. See the main repository for details.