{"id":34503468,"url":"https://github.com/supermodeltools/typescript-sdk","last_synced_at":"2026-04-01T16:37:31.245Z","repository":{"id":330223447,"uuid":"1121991475","full_name":"supermodeltools/typescript-sdk","owner":"supermodeltools","description":"Generate useful graphs of your codebase with our TypeScript SDK!","archived":false,"fork":false,"pushed_at":"2026-01-24T14:20:53.000Z","size":105,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-25T02:57:19.880Z","etag":null,"topics":["api-client","code-graph","sdk","static-analysis","supermodel","typescript"],"latest_commit_sha":null,"homepage":"https://docs.supermodeltools.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/supermodeltools.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-23T23:09:52.000Z","updated_at":"2026-01-24T14:20:55.000Z","dependencies_parsed_at":"2026-01-16T19:03:07.708Z","dependency_job_id":null,"html_url":"https://github.com/supermodeltools/typescript-sdk","commit_stats":null,"previous_names":["supermodeltools/typescript-sdk"],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/supermodeltools/typescript-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supermodeltools%2Ftypescript-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supermodeltools%2Ftypescript-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supermodeltools%2Ftypescript-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supermodeltools%2Ftypescript-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/supermodeltools","download_url":"https://codeload.github.com/supermodeltools/typescript-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supermodeltools%2Ftypescript-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28907408,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-30T06:42:00.998Z","status":"ssl_error","status_checked_at":"2026-01-30T06:41:58.659Z","response_time":66,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-client","code-graph","sdk","static-analysis","supermodel","typescript"],"created_at":"2025-12-24T02:33:30.488Z","updated_at":"2026-01-30T07:14:04.414Z","avatar_url":"https://github.com/supermodeltools.png","language":"TypeScript","readme":"# Supermodel TypeScript SDK\n\nOfficial TypeScript/JavaScript SDK for the [Supermodel API](https://supermodeltools.com).\n\nGenerate code graphs, dependency analysis, and domain models from your source code repositories.\n\n## Installation\n\n```bash\nnpm install @supermodeltools/sdk\n```\n\n## Quick Start\n\n### Basic Usage (Auto-Polling)\n\nThe SDK provides a high-level `SupermodelClient` that automatically handles async job polling:\n\n```typescript\nimport { SupermodelClient, DefaultApi, Configuration } from '@supermodeltools/sdk';\nimport { readFile } from 'node:fs/promises';\n\n// Configure the API client\nconst api = new DefaultApi(new Configuration({\n  basePath: 'https://api.supermodeltools.com',\n  apiKey: () =\u003e process.env.SUPERMODEL_API_KEY || ''\n}));\n\n// Create the async client wrapper\nconst client = new SupermodelClient(api);\n\n// Generate a code graph (polling handled automatically)\nconst zipBuffer = await readFile('./my-repo.zip');\nconst zipBlob = new Blob([zipBuffer]);\n\nconst result = await client.generateSupermodelGraph(zipBlob);\nconsole.log(`Generated graph with ${result.graph.nodes.length} nodes`);\n```\n\n### Advanced Configuration\n\nConfigure polling behavior for long-running operations:\n\n```typescript\nconst client = new SupermodelClient(api, {\n  // Maximum time to wait for job completion\n  timeoutMs: 900000,  // 15 minutes (default)\n\n  // Polling interval when server doesn't specify\n  defaultRetryIntervalMs: 10000,  // 10 seconds (default)\n\n  // Maximum number of polling attempts\n  maxPollingAttempts: 90,  // (default)\n\n  // Progress callback\n  onPollingProgress: (progress) =\u003e {\n    console.log(`Job ${progress.jobId}: ${progress.status} ` +\n                `(${progress.attempt}/${progress.maxAttempts})`);\n  },\n\n  // Cancellation support\n  signal: abortController.signal,\n});\n```\n\n### Per-Request Configuration\n\nOverride client defaults for specific requests:\n\n```typescript\n// Use a custom idempotency key\nconst result = await client.generateDependencyGraph(zipBlob, {\n  idempotencyKey: 'my-repo:dependency:abc123',\n});\n\n// Add custom headers (e.g., for different auth)\nconst result = await client.generateCallGraph(zipBlob, {\n  initOverrides: {\n    headers: { 'Authorization': 'Bearer custom-token' }\n  }\n});\n\n// Cancel a specific request\nconst controller = new AbortController();\nconst promise = client.generateParseGraph(zipBlob, {\n  signal: controller.signal\n});\n\n// Later: controller.abort();\n```\n\n## Available Methods\n\n### SupermodelClient (Async Wrapper)\n\nAll methods automatically handle polling until job completion:\n\n- `generateSupermodelGraph(file, options?)` - Full Supermodel IR with all analysis\n- `generateDependencyGraph(file, options?)` - Module/package dependencies\n- `generateCallGraph(file, options?)` - Function-level call relationships\n- `generateDomainGraph(file, options?)` - High-level domain model\n- `generateParseGraph(file, options?)` - AST-level parse tree\n\n### Raw API (Manual Polling)\n\nAccess the underlying API for manual control:\n\n```typescript\nconst rawApi = client.rawApi;\n\n// Make initial request\nlet response = await rawApi.generateDependencyGraph({\n  idempotencyKey: 'my-key',\n  file: zipBlob\n});\n\n// Poll manually\nwhile (response.status === 'pending' || response.status === 'processing') {\n  await sleep(response.retryAfter * 1000);\n  response = await rawApi.generateDependencyGraph({\n    idempotencyKey: 'my-key',\n    file: zipBlob\n  });\n}\n\nif (response.status === 'completed') {\n  console.log(response.result);\n}\n```\n\n## Configuration Options\n\n### AsyncClientOptions\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `timeoutMs` | `number` | `900000` (15 min) | Maximum time to wait for job completion |\n| `defaultRetryIntervalMs` | `number` | `10000` (10 sec) | Polling interval when server doesn't specify |\n| `maxPollingAttempts` | `number` | `90` | Maximum number of polling attempts |\n| `onPollingProgress` | `function` | `undefined` | Callback for polling progress updates |\n| `generateIdempotencyKey` | `function` | `crypto.randomUUID()` | Custom idempotency key generator |\n| `signal` | `AbortSignal` | `undefined` | AbortSignal for cancelling operations |\n\n### GraphRequestOptions\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `idempotencyKey` | `string` | auto-generated | Idempotency key for request deduplication |\n| `initOverrides` | `RequestInit` | `undefined` | Custom fetch options (headers, etc.) |\n| `signal` | `AbortSignal` | `undefined` | Request-specific abort signal |\n\n## Error Handling\n\n```typescript\nimport { JobFailedError, PollingTimeoutError } from '@supermodeltools/sdk';\n\ntry {\n  const result = await client.generateDependencyGraph(zipBlob);\n} catch (error) {\n  if (error instanceof JobFailedError) {\n    console.error(`Job ${error.jobId} failed: ${error.errorMessage}`);\n  } else if (error instanceof PollingTimeoutError) {\n    console.error(`Job ${error.jobId} timed out after ${error.timeoutMs}ms`);\n  } else if (error.name === 'AbortError') {\n    console.log('Operation cancelled');\n  } else {\n    throw error;\n  }\n}\n```\n\n## Idempotency\n\nThe API uses idempotency keys to prevent duplicate processing. The same key will always return the same result:\n\n```typescript\n// Generate a stable key from your repo state\nimport crypto from 'crypto';\nimport { execSync } from 'child_process';\n\nconst gitHash = execSync('git rev-parse --short HEAD').toString().trim();\nconst idempotencyKey = `my-project:supermodel:${gitHash}`;\n\n// This will generate once, then return cached result on subsequent calls\nconst result = await client.generateSupermodelGraph(zipBlob, {\n  idempotencyKey\n});\n```\n\n## Preparing Repository Archives\n\n### For Git Repositories (Recommended)\n\n```bash\ncd /path/to/your/repo\ngit archive -o /tmp/repo.zip HEAD\n```\n\nThis automatically respects `.gitignore` and creates clean, reproducible archives.\n\n### For Any Directory\n\n```bash\ncd /path/to/your/repo\nzip -r /tmp/repo.zip . \\\n  -x \"node_modules/*\" \\\n  -x \".git/*\" \\\n  -x \"dist/*\" \\\n  -x \"*.pyc\" \\\n  -x \"__pycache__/*\"\n```\n\n### What to Include\n\n- ✅ Source code files (`.py`, `.js`, `.ts`, `.java`, etc.)\n- ✅ Configuration files (`package.json`, `pyproject.toml`, etc.)\n- ✅ Type definitions (`.d.ts`, `.pyi`)\n- ❌ Dependencies (`node_modules/`, `venv/`, `target/`)\n- ❌ Build outputs (`dist/`, `build/`, `.next/`)\n- ❌ Large binaries, images, datasets\n\n### Size Limits\n\nArchives should be under 50MB. If larger:\n- Ensure dependencies are excluded\n- Consider analyzing a subdirectory\n- Check for accidentally committed binaries\n\n## TypeScript Support\n\nFull TypeScript definitions are included. Types are automatically resolved via `package.json`.\n\n```typescript\nimport type {\n  SupermodelIR,\n  CodeGraphEnvelope,\n  DomainClassificationResponse,\n} from '@supermodeltools/sdk';\n\n// Types are available for all request/response models\n```\n\n## Environment Support\n\n- ✅ Node.js (18+)\n- ✅ Modern browsers (with Blob support)\n- ✅ Webpack, Vite, Rollup\n- ✅ ES6 modules and CommonJS\n\n## Authentication\n\nGet your API key from the [Supermodel Dashboard](https://dashboard.supermodeltools.com).\n\n```typescript\nconst api = new DefaultApi(new Configuration({\n  basePath: 'https://api.supermodeltools.com',\n  apiKey: () =\u003e process.env.SUPERMODEL_API_KEY || ''\n}));\n```\n\n## Rate Limiting\n\nThe API includes rate limiting headers in responses:\n\n```typescript\nconst response = await rawApi.generateDependencyGraphRaw({\n  idempotencyKey: 'key',\n  file: blob\n});\n\nconsole.log(response.raw.headers.get('RateLimit-Limit'));\nconsole.log(response.raw.headers.get('RateLimit-Remaining'));\nconsole.log(response.raw.headers.get('RateLimit-Reset'));\n```\n\n## Examples\n\n### Integration with mcpbr\n\n```typescript\nimport { SupermodelClient, DefaultApi, Configuration } from '@supermodeltools/sdk';\n\nconst api = new DefaultApi(new Configuration({\n  basePath: process.env.SUPERMODEL_BASE_URL || 'https://api.supermodeltools.com',\n  apiKey: () =\u003e process.env.SUPERMODEL_API_KEY || ''\n}));\n\n// Configure for long-running benchmark operations\nconst client = new SupermodelClient(api, {\n  timeoutMs: 900000,           // 15 minutes\n  maxPollingAttempts: 90,       // 90 attempts\n  onPollingProgress: (progress) =\u003e {\n    console.log(`[${progress.jobId}] ${progress.status} - ` +\n                `attempt ${progress.attempt}/${progress.maxAttempts}`);\n  }\n});\n```\n\n## Links\n\n- [API Documentation](https://docs.supermodeltools.com)\n- [GitHub Repository](https://github.com/supermodeltools/supermodel-public-api)\n- [Dashboard](https://dashboard.supermodeltools.com)\n- [Terms of Service](https://supermodeltools.com/legal/api-terms)\n\n## License\n\nThis SDK is licensed under the MIT License. See the main repository for details.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsupermodeltools%2Ftypescript-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsupermodeltools%2Ftypescript-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsupermodeltools%2Ftypescript-sdk/lists"}