@supermodeltools/sdk 0.6.3 → 0.7.0

package/README.md

@@ -1,12 +1,10 @@
 # Supermodel TypeScript SDK
 
-[![npm](https://img.shields.io/npm/v/@supermodeltools/sdk)](https://www.npmjs.com/package/@supermodeltools/sdk)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue)](https://www.typescriptlang.org/)
-[![CI](https://github.com/supermodeltools/typescript-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/supermodeltools/typescript-sdk/actions/workflows/ci.yml)
+Official TypeScript/JavaScript SDK for the [Supermodel API](https://supermodeltools.com).
 
-TypeScript client for the [Supermodel API](https://docs.supermodeltools.com) - code graph generation and static analysis.
+Generate code graphs, dependency analysis, and domain models from your source code repositories.
 
-## Install
+## Installation
 
 ```bash
 npm install @supermodeltools/sdk
@@ -14,43 +12,297 @@ npm install @supermodeltools/sdk
 
 ## Quick Start
 
-Get your API key from the [Supermodel Dashboard](https://dashboard.supermodeltools.com) and set it as `SUPERMODEL_API_KEY`.
+### Basic Usage (Auto-Polling)
+
+The SDK provides a high-level `SupermodelClient` that automatically handles async job polling:
 
 ```typescript
-import { Configuration, DefaultApi } from '@supermodeltools/sdk';
+import { SupermodelClient, DefaultApi, Configuration } from '@supermodeltools/sdk';
 import { readFile } from 'node:fs/promises';
 
-const config = new Configuration({
+// Configure the API client
+const api = new DefaultApi(new Configuration({
   basePath: 'https://api.supermodeltools.com',
-  apiKey: process.env.SUPERMODEL_API_KEY,
+  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:
+
+```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,
+});
+```
+
+### Per-Request Configuration
+
+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
+
+### 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:
+
+```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
+
+### 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
+
+```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
+
+### For Git Repositories (Recommended)
+
+```bash
+cd /path/to/your/repo
+git archive -o /tmp/repo.zip HEAD
+```
+
+This automatically respects `.gitignore` and creates clean, reproducible archives.
+
+### For Any Directory
+
+```bash
+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
 
-const api = new DefaultApi(config);
+Archives should be under 50MB. If larger:
+- Ensure dependencies are excluded
+- Consider analyzing a subdirectory
+- Check for accidentally committed binaries
 
-// Create a ZIP of your repo: git archive -o /tmp/repo.zip HEAD
-const file = new Blob([await readFile('/tmp/repo.zip')], { type: 'application/zip' });
+## TypeScript Support
 
-const result = await api.generateSupermodelGraph({
-  idempotencyKey: 'my-repo:supermodel:abc123',
-  file,
+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](https://dashboard.supermodeltools.com).
+
+```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(result.graph.nodes.length, 'nodes');
+console.log(response.raw.headers.get('RateLimit-Limit'));
+console.log(response.raw.headers.get('RateLimit-Remaining'));
+console.log(response.raw.headers.get('RateLimit-Reset'));
 ```
 
-## Methods
+## Examples
+
+### Integration with mcpbr
 
-| Method | Description |
-|--------|-------------|
-| `generateDependencyGraph` | File-level dependency graph |
-| `generateCallGraph` | Function-level call graph |
-| `generateDomainGraph` | Domain model classification |
-| `generateParseGraph` | AST parse tree relationships |
-| `generateSupermodelGraph` | Full Supermodel IR bundle |
+```typescript
+import { SupermodelClient, DefaultApi, Configuration } from '@supermodeltools/sdk';
 
-All methods require `idempotencyKey` (string) and `file` (Blob) parameters.
+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](https://docs.supermodeltools.com)
-- [OpenAPI Spec](https://www.npmjs.com/package/@supermodeltools/openapi-spec)
+- [GitHub Repository](https://github.com/supermodeltools/supermodel-public-api)
+- [Dashboard](https://dashboard.supermodeltools.com)
+- [Terms of Service](https://supermodeltools.com/legal/api-terms)
+
+## License
+
+This SDK is licensed under the MIT License. See the main repository for details.

package/dist/apis/DefaultApi.d.ts

@@ -2,7 +2,7 @@
  * Supermodel
  * Code Graphing & Analysis API
  *
- * The version of the OpenAPI document: 0.6.3
+ * The version of the OpenAPI document: 0.7.0
  *
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).

package/dist/apis/DefaultApi.js

@@ -5,7 +5,7 @@
  * Supermodel
  * Code Graphing & Analysis API
  *
- * The version of the OpenAPI document: 0.6.3
+ * The version of the OpenAPI document: 0.7.0
  *
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).

package/dist/esm/apis/DefaultApi.d.ts

@@ -2,7 +2,7 @@
  * Supermodel
  * Code Graphing & Analysis API
  *
- * The version of the OpenAPI document: 0.6.3
+ * The version of the OpenAPI document: 0.7.0
  *
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).

package/dist/esm/apis/DefaultApi.js

@@ -4,7 +4,7 @@
  * Supermodel
  * Code Graphing & Analysis API
  *
- * The version of the OpenAPI document: 0.6.3
+ * The version of the OpenAPI document: 0.7.0
  *
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).

package/dist/esm/models/ClassificationStats.d.ts

@@ -2,7 +2,7 @@
  * Supermodel
  * Code Graphing & Analysis API
  *
- * The version of the OpenAPI document: 0.6.3
+ * The version of the OpenAPI document: 0.7.0
  *
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
@@ -15,6 +15,34 @@
  * @interface ClassificationStats
  */
 export interface ClassificationStats {
+    /**
+     * Total number of nodes in the graph
+     * @type {number}
+     * @memberof ClassificationStats
+     */
+    nodeCount: number;
+    /**
+     * Total number of relationships in the graph
+     * @type {number}
+     * @memberof ClassificationStats
+     */
+    relationshipCount: number;
+    /**
+     * Count of nodes by type
+     * @type {{ [key: string]: number; }}
+     * @memberof ClassificationStats
+     */
+    nodeTypes: {
+        [key: string]: number;
+    };
+    /**
+     * Count of relationships by type
+     * @type {{ [key: string]: number; }}
+     * @memberof ClassificationStats
+     */
+    relationshipTypes: {
+        [key: string]: number;
+    };
     /**
      * Number of domains discovered
      * @type {number}
@@ -22,11 +50,29 @@ export interface ClassificationStats {
      */
     domainCount: number;
     /**
-     * Number of relationships
+     * Number of subdomains discovered
      * @type {number}
      * @memberof ClassificationStats
      */
-    relationshipCount: number;
+    subdomainCount: number;
+    /**
+     * Number of files assigned to domains/subdomains
+     * @type {number}
+     * @memberof ClassificationStats
+     */
+    assignedFileCount: number;
+    /**
+     * Number of functions assigned to domains/subdomains
+     * @type {number}
+     * @memberof ClassificationStats
+     */
+    assignedFunctionCount: number;
+    /**
+     * Number of classes assigned to domains/subdomains
+     * @type {number}
+     * @memberof ClassificationStats
+     */
+    assignedClassCount: number;
     /**
      * Count of file assignments
      * @type {number}

package/dist/esm/models/ClassificationStats.js

@@ -4,7 +4,7 @@
  * Supermodel
  * Code Graphing & Analysis API
  *
- * The version of the OpenAPI document: 0.6.3
+ * The version of the OpenAPI document: 0.7.0
  *
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
@@ -15,10 +15,24 @@
  * Check if a given object implements the ClassificationStats interface.
  */
 export function instanceOfClassificationStats(value) {
-    if (!('domainCount' in value) || value['domainCount'] === undefined)
+    if (!('nodeCount' in value) || value['nodeCount'] === undefined)
         return false;
     if (!('relationshipCount' in value) || value['relationshipCount'] === undefined)
         return false;
+    if (!('nodeTypes' in value) || value['nodeTypes'] === undefined)
+        return false;
+    if (!('relationshipTypes' in value) || value['relationshipTypes'] === undefined)
+        return false;
+    if (!('domainCount' in value) || value['domainCount'] === undefined)
+        return false;
+    if (!('subdomainCount' in value) || value['subdomainCount'] === undefined)
+        return false;
+    if (!('assignedFileCount' in value) || value['assignedFileCount'] === undefined)
+        return false;
+    if (!('assignedFunctionCount' in value) || value['assignedFunctionCount'] === undefined)
+        return false;
+    if (!('assignedClassCount' in value) || value['assignedClassCount'] === undefined)
+        return false;
     if (!('fileAssignments' in value) || value['fileAssignments'] === undefined)
         return false;
     if (!('functionAssignments' in value) || value['functionAssignments'] === undefined)
@@ -37,8 +51,15 @@ export function ClassificationStatsFromJSONTyped(json, ignoreDiscriminator) {
         return json;
     }
     return {
-        'domainCount': json['domainCount'],
+        'nodeCount': json['nodeCount'],
         'relationshipCount': json['relationshipCount'],
+        'nodeTypes': json['nodeTypes'],
+        'relationshipTypes': json['relationshipTypes'],
+        'domainCount': json['domainCount'],
+        'subdomainCount': json['subdomainCount'],
+        'assignedFileCount': json['assignedFileCount'],
+        'assignedFunctionCount': json['assignedFunctionCount'],
+        'assignedClassCount': json['assignedClassCount'],
         'fileAssignments': json['fileAssignments'],
         'functionAssignments': json['functionAssignments'],
         'unassignedFunctions': json['unassignedFunctions'],
@@ -50,8 +71,15 @@ export function ClassificationStatsToJSON(value) {
         return value;
     }
     return {
-        'domainCount': value['domainCount'],
+        'nodeCount': value['nodeCount'],
         'relationshipCount': value['relationshipCount'],
+        'nodeTypes': value['nodeTypes'],
+        'relationshipTypes': value['relationshipTypes'],
+        'domainCount': value['domainCount'],
+        'subdomainCount': value['subdomainCount'],
+        'assignedFileCount': value['assignedFileCount'],
+        'assignedFunctionCount': value['assignedFunctionCount'],
+        'assignedClassCount': value['assignedClassCount'],
         'fileAssignments': value['fileAssignments'],
         'functionAssignments': value['functionAssignments'],
         'unassignedFunctions': value['unassignedFunctions'],

package/dist/esm/models/CodeGraphEnvelope.d.ts

@@ -2,7 +2,7 @@
  * Supermodel
  * Code Graphing & Analysis API
  *
- * The version of the OpenAPI document: 0.6.3
+ * The version of the OpenAPI document: 0.7.0
  *
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
@@ -11,6 +11,7 @@
  */
 import type { CodeGraphStats } from './CodeGraphStats';
 import type { CodeGraphEnvelopeGraph } from './CodeGraphEnvelopeGraph';
+import type { CodeGraphEnvelopeMetadata } from './CodeGraphEnvelopeMetadata';
 /**
  *
  * @export
@@ -35,6 +36,12 @@ export interface CodeGraphEnvelope {
      * @memberof CodeGraphEnvelope
      */
     stats?: CodeGraphStats;
+    /**
+     *
+     * @type {CodeGraphEnvelopeMetadata}
+     * @memberof CodeGraphEnvelope
+     */
+    metadata?: CodeGraphEnvelopeMetadata;
     /**
      *
      * @type {CodeGraphEnvelopeGraph}

package/dist/esm/models/CodeGraphEnvelope.js

@@ -4,7 +4,7 @@
  * Supermodel
  * Code Graphing & Analysis API
  *
- * The version of the OpenAPI document: 0.6.3
+ * The version of the OpenAPI document: 0.7.0
  *
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
@@ -13,6 +13,7 @@
  */
 import { CodeGraphStatsFromJSON, CodeGraphStatsToJSON, } from './CodeGraphStats';
 import { CodeGraphEnvelopeGraphFromJSON, CodeGraphEnvelopeGraphToJSON, } from './CodeGraphEnvelopeGraph';
+import { CodeGraphEnvelopeMetadataFromJSON, CodeGraphEnvelopeMetadataToJSON, } from './CodeGraphEnvelopeMetadata';
 /**
  * Check if a given object implements the CodeGraphEnvelope interface.
  */
@@ -32,6 +33,7 @@ export function CodeGraphEnvelopeFromJSONTyped(json, ignoreDiscriminator) {
         'generatedAt': json['generatedAt'] == null ? undefined : (new Date(json['generatedAt'])),
         'message': json['message'] == null ? undefined : json['message'],
         'stats': json['stats'] == null ? undefined : CodeGraphStatsFromJSON(json['stats']),
+        'metadata': json['metadata'] == null ? undefined : CodeGraphEnvelopeMetadataFromJSON(json['metadata']),
         'graph': CodeGraphEnvelopeGraphFromJSON(json['graph']),
     };
 }
@@ -43,6 +45,7 @@ export function CodeGraphEnvelopeToJSON(value) {
         'generatedAt': value['generatedAt'] == null ? undefined : ((value['generatedAt']).toISOString()),
         'message': value['message'],
         'stats': CodeGraphStatsToJSON(value['stats']),
+        'metadata': CodeGraphEnvelopeMetadataToJSON(value['metadata']),
         'graph': CodeGraphEnvelopeGraphToJSON(value['graph']),
     };
 }

package/dist/esm/models/CodeGraphEnvelopeAsync.d.ts

@@ -2,7 +2,7 @@
  * Supermodel
  * Code Graphing & Analysis API
  *
- * The version of the OpenAPI document: 0.6.3
+ * The version of the OpenAPI document: 0.7.0
  *
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).

package/dist/esm/models/CodeGraphEnvelopeAsync.js

@@ -4,7 +4,7 @@
  * Supermodel
  * Code Graphing & Analysis API
  *
- * The version of the OpenAPI document: 0.6.3
+ * The version of the OpenAPI document: 0.7.0
  *
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).

package/dist/esm/models/CodeGraphEnvelopeGraph.d.ts

@@ -2,7 +2,7 @@
  * Supermodel
  * Code Graphing & Analysis API
  *
- * The version of the OpenAPI document: 0.6.3
+ * The version of the OpenAPI document: 0.7.0
  *
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).

package/dist/esm/models/CodeGraphEnvelopeGraph.js

@@ -4,7 +4,7 @@
  * Supermodel
  * Code Graphing & Analysis API
  *
- * The version of the OpenAPI document: 0.6.3
+ * The version of the OpenAPI document: 0.7.0
  *
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).

package/dist/esm/models/CodeGraphEnvelopeMetadata.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Supermodel
+ * Code Graphing & Analysis API
+ *
+ * The version of the OpenAPI document: 0.7.0
+ *
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+/**
+ * Analysis metadata including timing and file information
+ * @export
+ * @interface CodeGraphEnvelopeMetadata
+ */
+export interface CodeGraphEnvelopeMetadata {
+    /**
+     *
+     * @type {Date}
+     * @memberof CodeGraphEnvelopeMetadata
+     */
+    analysisStartTime?: Date;
+    /**
+     *
+     * @type {Date}
+     * @memberof CodeGraphEnvelopeMetadata
+     */
+    analysisEndTime?: Date;
+    /**
+     *
+     * @type {number}
+     * @memberof CodeGraphEnvelopeMetadata
+     */
+    fileCount?: number;
+    /**
+     *
+     * @type {Array<string>}
+     * @memberof CodeGraphEnvelopeMetadata
+     */
+    languages?: Array<string>;
+}
+/**
+ * Check if a given object implements the CodeGraphEnvelopeMetadata interface.
+ */
+export declare function instanceOfCodeGraphEnvelopeMetadata(value: object): value is CodeGraphEnvelopeMetadata;
+export declare function CodeGraphEnvelopeMetadataFromJSON(json: any): CodeGraphEnvelopeMetadata;
+export declare function CodeGraphEnvelopeMetadataFromJSONTyped(json: any, ignoreDiscriminator: boolean): CodeGraphEnvelopeMetadata;
+export declare function CodeGraphEnvelopeMetadataToJSON(value?: CodeGraphEnvelopeMetadata | null): any;