@inferencesh/sdk 0.1.0 → 0.1.3

package/CHANGELOG.md

@@ -7,7 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.1.0] - 2024-01-XX
+## [0.1.1] - 2024-11-30
+
+### Added
+
+- Partial data handling for streaming updates (matches Python SDK behavior)
+- `onPartialUpdate` callback option to receive list of changed fields
+- Export `StreamManager` and `PartialDataWrapper` types
+
+### Fixed
+
+- Stream updates now properly extract data from server's partial update wrapper
+- Removed unused `onYield` callback
+
+## [0.1.0] - 2024-11-30
 
 ### Added
 

package/README.md

@@ -17,6 +17,10 @@ yarn add @inferencesh/sdk
 pnpm add @inferencesh/sdk
 ```
 
+## Getting an API Key
+
+Get your API key from the [inference.sh dashboard](https://app.inference.sh/settings/keys).
+
 ## Quick Start
 
 ```typescript

package/dist/client.d.ts

@@ -14,6 +14,8 @@ export interface InferenceConfig {
 export interface RunOptions {
     /** Callback for real-time status updates */
     onUpdate?: (update: Task) => void;
+    /** Callback for partial updates with list of changed fields */
+    onPartialUpdate?: (update: Task, fields: string[]) => void;
     /** Wait for task completion (default: true) */
     wait?: boolean;
     /** Auto-reconnect on connection loss (default: true) */

package/dist/client.js

@@ -4,6 +4,7 @@ exports.inference = exports.Inference = void 0;
 const types_1 = require("./types");
 const stream_1 = require("./stream");
 const eventsource_1 = require("eventsource");
+const errors_1 = require("./errors");
 /**
  * Inference.sh SDK Client
  *
@@ -43,11 +44,45 @@ class Inference {
             fetchOptions.body = JSON.stringify(options.data);
         }
         const response = await fetch(url.toString(), fetchOptions);
-        const data = await response.json();
-        if (!data.success) {
-            throw new Error(data.error?.message || "Request failed");
+        const responseText = await response.text();
+        // Try to parse as JSON
+        let data = null;
+        try {
+            data = JSON.parse(responseText);
         }
-        return data.data;
+        catch {
+            // Not JSON
+        }
+        // Check for HTTP errors
+        if (!response.ok) {
+            // Check for RequirementsNotMetException (412 with errors array)
+            if (response.status === 412 && data && 'errors' in data && Array.isArray(data.errors)) {
+                throw errors_1.RequirementsNotMetException.fromResponse(data, response.status);
+            }
+            // General error handling
+            let errorDetail;
+            if (data && typeof data === 'object') {
+                const apiData = data;
+                if (apiData.error) {
+                    errorDetail = typeof apiData.error === 'object' ? apiData.error.message : String(apiData.error);
+                }
+                else if ('message' in data) {
+                    errorDetail = String(data.message);
+                }
+                else {
+                    errorDetail = JSON.stringify(data);
+                }
+            }
+            else if (responseText) {
+                errorDetail = responseText.slice(0, 500);
+            }
+            throw new errors_1.InferenceError(response.status, errorDetail || 'Request failed', responseText);
+        }
+        const apiResponse = data;
+        if (!apiResponse?.success) {
+            throw new errors_1.InferenceError(response.status, apiResponse?.error?.message || 'Request failed', responseText);
+        }
+        return apiResponse.data;
     }
     createEventSource(endpoint) {
         const url = new URL(`${this.baseUrl}${endpoint}`);
@@ -128,7 +163,7 @@ class Inference {
      * ```
      */
     async run(params, options = {}) {
-        const { onUpdate, wait = true, autoReconnect = true, maxReconnects = 5, reconnectDelayMs = 1000, } = options;
+        const { onUpdate, onPartialUpdate, wait = true, autoReconnect = true, maxReconnects = 5, reconnectDelayMs = 1000, } = options;
         // Process input data and upload any files
         const processedInput = await this.processInputData(params.input);
         const task = await this.request("post", "/run", {
@@ -165,6 +200,13 @@ class Inference {
                         reject(new Error("task cancelled"));
                     }
                 },
+                onPartialData: (data, fields) => {
+                    // Call onPartialUpdate if provided
+                    if (onPartialUpdate) {
+                        const stripped = this._stripTask(data);
+                        onPartialUpdate(stripped, fields);
+                    }
+                },
                 onError: (error) => {
                     reject(error);
                     streamManager.stop();

package/dist/client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/client.test.js

@@ -0,0 +1,212 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const client_1 = require("./client");
+const errors_1 = require("./errors");
+// Mock fetch globally
+const mockFetch = jest.fn();
+global.fetch = mockFetch;
+describe('Inference', () => {
+    beforeEach(() => {
+        jest.clearAllMocks();
+    });
+    describe('constructor', () => {
+        it('should create an instance with valid config', () => {
+            const client = new client_1.Inference({ apiKey: 'test-api-key' });
+            expect(client).toBeInstanceOf(client_1.Inference);
+        });
+        it('should throw error when apiKey is missing', () => {
+            expect(() => new client_1.Inference({ apiKey: '' })).toThrow('API key is required');
+            expect(() => new client_1.Inference({})).toThrow('API key is required');
+        });
+        it('should use default baseUrl when not provided', () => {
+            const client = new client_1.Inference({ apiKey: 'test-api-key' });
+            expect(client).toBeDefined();
+        });
+        it('should accept custom baseUrl', () => {
+            const client = new client_1.Inference({
+                apiKey: 'test-api-key',
+                baseUrl: 'https://custom-api.example.com',
+            });
+            expect(client).toBeDefined();
+        });
+    });
+    describe('run', () => {
+        it('should make a POST request to /run', async () => {
+            const mockTask = {
+                id: 'task-123',
+                status: 9, // TaskStatusCompleted
+                created_at: new Date().toISOString(),
+                updated_at: new Date().toISOString(),
+                input: { message: 'hello world' },
+                output: { result: 'success' },
+            };
+            const responseData = { success: true, data: mockTask };
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                text: () => Promise.resolve(JSON.stringify(responseData)),
+                json: () => Promise.resolve(responseData),
+            });
+            const client = new client_1.Inference({ apiKey: 'test-api-key' });
+            // Use input that won't trigger base64 detection (contains spaces/special chars)
+            const result = await client.run({ app: 'test-app', input: { message: 'hello world!' } }, { wait: false });
+            expect(result.id).toBe('task-123');
+            expect(mockFetch).toHaveBeenCalledWith(expect.stringContaining('/run'), expect.objectContaining({
+                method: 'POST',
+                headers: expect.objectContaining({
+                    Authorization: 'Bearer test-api-key',
+                    'Content-Type': 'application/json',
+                }),
+            }));
+        });
+        it('should throw error on API failure', async () => {
+            const responseData = { success: false, error: { message: 'Invalid app' } };
+            mockFetch.mockResolvedValueOnce({
+                ok: false,
+                status: 400,
+                text: () => Promise.resolve(JSON.stringify(responseData)),
+                json: () => Promise.resolve(responseData),
+            });
+            const client = new client_1.Inference({ apiKey: 'test-api-key' });
+            await expect(client.run({ app: 'invalid-app', input: { message: 'test!' } }, { wait: false })).rejects.toThrow('Invalid app');
+        });
+        it('should throw RequirementsNotMetException on 412 with errors', async () => {
+            const requirementErrors = [
+                {
+                    type: 'secret',
+                    key: 'OPENAI_API_KEY',
+                    message: 'Missing secret: OPENAI_API_KEY',
+                    action: { type: 'add_secret', secret_key: 'OPENAI_API_KEY' },
+                },
+                {
+                    type: 'integration',
+                    key: 'google',
+                    message: 'Integration not connected: google',
+                    action: { type: 'connect', provider: 'google' },
+                },
+            ];
+            const responseData = { errors: requirementErrors };
+            mockFetch.mockResolvedValueOnce({
+                ok: false,
+                status: 412,
+                text: () => Promise.resolve(JSON.stringify(responseData)),
+                json: () => Promise.resolve(responseData),
+            });
+            const client = new client_1.Inference({ apiKey: 'test-api-key' });
+            try {
+                await client.run({ app: 'test-app', input: { message: 'test!' } }, { wait: false });
+                fail('Expected RequirementsNotMetException to be thrown');
+            }
+            catch (e) {
+                expect(e).toBeInstanceOf(errors_1.RequirementsNotMetException);
+                const exception = e;
+                expect(exception.errors).toHaveLength(2);
+                expect(exception.errors[0].type).toBe('secret');
+                expect(exception.errors[0].key).toBe('OPENAI_API_KEY');
+                expect(exception.errors[1].type).toBe('integration');
+                expect(exception.statusCode).toBe(412);
+                expect(exception.message).toBe('Missing secret: OPENAI_API_KEY');
+            }
+        });
+        it('should include action details in RequirementsNotMetException', async () => {
+            const requirementErrors = [
+                {
+                    type: 'scope',
+                    key: 'calendar.readonly',
+                    message: 'Missing scope: calendar.readonly',
+                    action: {
+                        type: 'add_scopes',
+                        provider: 'google',
+                        scopes: ['calendar.readonly', 'calendar.events'],
+                    },
+                },
+            ];
+            const responseData = { errors: requirementErrors };
+            mockFetch.mockResolvedValueOnce({
+                ok: false,
+                status: 412,
+                text: () => Promise.resolve(JSON.stringify(responseData)),
+                json: () => Promise.resolve(responseData),
+            });
+            const client = new client_1.Inference({ apiKey: 'test-api-key' });
+            try {
+                await client.run({ app: 'test-app', input: {} }, { wait: false });
+                fail('Expected RequirementsNotMetException to be thrown');
+            }
+            catch (e) {
+                expect(e).toBeInstanceOf(errors_1.RequirementsNotMetException);
+                const exception = e;
+                expect(exception.errors[0].action?.type).toBe('add_scopes');
+                expect(exception.errors[0].action?.scopes).toEqual(['calendar.readonly', 'calendar.events']);
+            }
+        });
+    });
+    describe('cancel', () => {
+        it('should make a POST request to cancel endpoint', async () => {
+            const responseData = { success: true, data: null };
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                text: () => Promise.resolve(JSON.stringify(responseData)),
+                json: () => Promise.resolve(responseData),
+            });
+            const client = new client_1.Inference({ apiKey: 'test-api-key' });
+            await client.cancel('task-123');
+            expect(mockFetch).toHaveBeenCalledWith(expect.stringContaining('/tasks/task-123/cancel'), expect.objectContaining({ method: 'POST' }));
+        });
+    });
+    describe('backward compatibility', () => {
+        it('should export lowercase inference as alias', () => {
+            expect(client_1.inference).toBe(client_1.Inference);
+        });
+        it('should work with lowercase inference', () => {
+            const client = new client_1.inference({ apiKey: 'test-api-key' });
+            expect(client).toBeInstanceOf(client_1.Inference);
+        });
+    });
+});
+describe('uploadFile', () => {
+    beforeEach(() => {
+        jest.clearAllMocks();
+    });
+    it('should upload a base64 string', async () => {
+        const mockFile = {
+            id: 'file-123',
+            uri: 'https://example.com/file.png',
+            upload_url: 'https://upload.example.com/signed-url',
+        };
+        const responseData = { success: true, data: [mockFile] };
+        mockFetch
+            .mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            text: () => Promise.resolve(JSON.stringify(responseData)),
+            json: () => Promise.resolve(responseData),
+        })
+            .mockResolvedValueOnce({ ok: true });
+        const client = new client_1.Inference({ apiKey: 'test-api-key' });
+        // Use valid base64 that won't be mistaken for regular text
+        const result = await client.uploadFile('SGVsbG8gV29ybGQh', {
+            filename: 'test.txt',
+            contentType: 'text/plain',
+        });
+        expect(result.uri).toBe('https://example.com/file.png');
+        expect(mockFetch).toHaveBeenCalledTimes(2);
+    });
+    it('should throw error when no upload URL provided', async () => {
+        const mockFile = {
+            id: 'file-123',
+            uri: 'https://example.com/file.png',
+            // Missing upload_url
+        };
+        const responseData = { success: true, data: [mockFile] };
+        mockFetch.mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            text: () => Promise.resolve(JSON.stringify(responseData)),
+            json: () => Promise.resolve(responseData),
+        });
+        const client = new client_1.Inference({ apiKey: 'test-api-key' });
+        await expect(client.uploadFile('SGVsbG8gV29ybGQh', { filename: 'test.txt' })).rejects.toThrow('No upload URL provided by the server');
+    });
+});

package/dist/errors.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Error classes for the inference.sh SDK.
+ *
+ * Note: types.ts contains interfaces (APIError, RequirementsNotMetError) that describe
+ * the API response data shapes. These classes are throwable Error subclasses for SDK use.
+ */
+import type { RequirementError } from './types';
+/**
+ * General HTTP/API error thrown by the SDK.
+ *
+ * Note: This is distinct from the `APIError` interface in types.ts which describes
+ * the error payload shape in API responses.
+ */
+export declare class InferenceError extends Error {
+    readonly statusCode: number;
+    readonly responseBody?: string;
+    constructor(statusCode: number, message: string, responseBody?: string);
+}
+/**
+ * Error thrown when app requirements (secrets, integrations, scopes) are not met.
+ *
+ * Thrown for HTTP 412 responses that contain structured requirement errors.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const task = await client.run(params);
+ * } catch (e) {
+ *   if (e instanceof RequirementsNotMetException) {
+ *     for (const err of e.errors) {
+ *       console.log(`Missing ${err.type}: ${err.key}`);
+ *       if (err.action) {
+ *         console.log(`  Fix: ${err.action.type}`);
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare class RequirementsNotMetException extends Error {
+    readonly errors: RequirementError[];
+    readonly statusCode: number;
+    constructor(errors: RequirementError[], statusCode?: number);
+    /**
+     * Create from API response data.
+     */
+    static fromResponse(data: {
+        errors?: RequirementError[];
+    }, statusCode?: number): RequirementsNotMetException;
+}

package/dist/errors.js

@@ -0,0 +1,61 @@
+"use strict";
+/**
+ * Error classes for the inference.sh SDK.
+ *
+ * Note: types.ts contains interfaces (APIError, RequirementsNotMetError) that describe
+ * the API response data shapes. These classes are throwable Error subclasses for SDK use.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RequirementsNotMetException = exports.InferenceError = void 0;
+/**
+ * General HTTP/API error thrown by the SDK.
+ *
+ * Note: This is distinct from the `APIError` interface in types.ts which describes
+ * the error payload shape in API responses.
+ */
+class InferenceError extends Error {
+    constructor(statusCode, message, responseBody) {
+        super(`HTTP ${statusCode}: ${message}`);
+        this.name = 'InferenceError';
+        this.statusCode = statusCode;
+        this.responseBody = responseBody;
+    }
+}
+exports.InferenceError = InferenceError;
+/**
+ * Error thrown when app requirements (secrets, integrations, scopes) are not met.
+ *
+ * Thrown for HTTP 412 responses that contain structured requirement errors.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const task = await client.run(params);
+ * } catch (e) {
+ *   if (e instanceof RequirementsNotMetException) {
+ *     for (const err of e.errors) {
+ *       console.log(`Missing ${err.type}: ${err.key}`);
+ *       if (err.action) {
+ *         console.log(`  Fix: ${err.action.type}`);
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+class RequirementsNotMetException extends Error {
+    constructor(errors, statusCode = 412) {
+        const message = errors.length > 0 ? errors[0].message : 'requirements not met';
+        super(message);
+        this.name = 'RequirementsNotMetException';
+        this.errors = errors;
+        this.statusCode = statusCode;
+    }
+    /**
+     * Create from API response data.
+     */
+    static fromResponse(data, statusCode = 412) {
+        return new RequirementsNotMetException(data.errors || [], statusCode);
+    }
+}
+exports.RequirementsNotMetException = RequirementsNotMetException;

package/dist/index.d.ts

@@ -1,3 +1,5 @@
 export { Inference, inference, InferenceConfig, RunOptions, UploadFileOptions } from './client';
+export { StreamManager, PartialDataWrapper } from './stream';
+export { InferenceError, RequirementsNotMetException } from './errors';
 export * from './types';
 export type { TaskDTO as Task } from './types';

package/dist/index.js

@@ -14,10 +14,17 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.inference = exports.Inference = void 0;
+exports.RequirementsNotMetException = exports.InferenceError = exports.StreamManager = exports.inference = exports.Inference = void 0;
 // Main client export
 var client_1 = require("./client");
 Object.defineProperty(exports, "Inference", { enumerable: true, get: function () { return client_1.Inference; } });
 Object.defineProperty(exports, "inference", { enumerable: true, get: function () { return client_1.inference; } });
+// Stream utilities
+var stream_1 = require("./stream");
+Object.defineProperty(exports, "StreamManager", { enumerable: true, get: function () { return stream_1.StreamManager; } });
+// Error classes (throwable)
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "InferenceError", { enumerable: true, get: function () { return errors_1.InferenceError; } });
+Object.defineProperty(exports, "RequirementsNotMetException", { enumerable: true, get: function () { return errors_1.RequirementsNotMetException; } });
 // Types - includes TaskStatus constants and all DTOs
 __exportStar(require("./types"), exports);

package/dist/stream.d.ts

@@ -1,3 +1,8 @@
+/** Partial data structure from server (contains data and list of updated fields) */
+export interface PartialDataWrapper<T> {
+    data: T;
+    fields: string[];
+}
 export interface StreamManagerOptions<T> {
     createEventSource: () => Promise<EventSource | null>;
     autoReconnect?: boolean;
@@ -6,8 +11,10 @@ export interface StreamManagerOptions<T> {
     onError?: (error: Error) => void;
     onStart?: () => void;
     onStop?: () => void;
+    /** Called with the extracted data (handles both full and partial data) */
     onData?: (data: T) => void;
-    onYield?: (data: T) => void;
+    /** Called specifically for partial updates with data and the list of updated fields */
+    onPartialData?: (data: T, fields: string[]) => void;
 }
 export declare class StreamManager<T> {
     private options;

package/dist/stream.js

@@ -1,6 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StreamManager = void 0;
+/**
+ * Check if the parsed data is a partial data wrapper from the server.
+ * The server sends partial updates in the format: { data: T, fields: string[] }
+ */
+function isPartialDataWrapper(parsed) {
+    return (typeof parsed === 'object' &&
+        parsed !== null &&
+        'data' in parsed &&
+        'fields' in parsed &&
+        Array.isArray(parsed.fields));
+}
 class StreamManager {
     constructor(options) {
         this.eventSource = null;
@@ -87,8 +98,22 @@ class StreamManager {
                     return;
                 try {
                     const parsed = JSON.parse(e.data);
-                    this.options.onData?.(parsed);
-                    this.options.onYield?.(parsed);
+                    // Check if this is a partial data wrapper from the server
+                    if (isPartialDataWrapper(parsed)) {
+                        // Extract the actual data from the wrapper
+                        const actualData = parsed.data;
+                        const fields = parsed.fields;
+                        // Call onPartialData if provided
+                        if (this.options.onPartialData) {
+                            this.options.onPartialData(actualData, fields);
+                        }
+                        // Always call onData with the extracted data
+                        this.options.onData?.(actualData);
+                    }
+                    else {
+                        // Not a partial wrapper, treat as full data
+                        this.options.onData?.(parsed);
+                    }
                 }
                 catch (err) {
                     const error = err instanceof Error ? err : new Error("Invalid JSON");

package/dist/stream.test.d.ts

@@ -0,0 +1 @@
+export {};