@inferencesh/sdk 0.1.0 → 0.1.1

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

@@ -128,7 +128,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 +165,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,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const client_1 = require("./client");
+// 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' },
+            };
+            mockFetch.mockResolvedValueOnce({
+                json: () => Promise.resolve({ success: true, data: mockTask }),
+            });
+            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 () => {
+            mockFetch.mockResolvedValueOnce({
+                json: () => Promise.resolve({ success: false, error: { message: 'Invalid app' } }),
+            });
+            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');
+        });
+    });
+    describe('cancel', () => {
+        it('should make a POST request to cancel endpoint', async () => {
+            mockFetch.mockResolvedValueOnce({
+                json: () => Promise.resolve({ success: true, data: null }),
+            });
+            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',
+        };
+        mockFetch
+            .mockResolvedValueOnce({
+            json: () => Promise.resolve({ success: true, data: [mockFile] }),
+        })
+            .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
+        };
+        mockFetch.mockResolvedValueOnce({
+            json: () => Promise.resolve({ success: true, data: [mockFile] }),
+        });
+        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/index.d.ts

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

package/dist/index.js

@@ -14,10 +14,13 @@ 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.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; } });
 // 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 {};

package/dist/stream.test.js

@@ -0,0 +1,168 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const stream_1 = require("./stream");
+describe('StreamManager', () => {
+    let mockEventSource;
+    beforeEach(() => {
+        mockEventSource = {
+            onmessage: null,
+            onerror: null,
+            close: jest.fn(),
+        };
+    });
+    describe('constructor', () => {
+        it('should create instance with default options', () => {
+            const manager = new stream_1.StreamManager({
+                createEventSource: async () => mockEventSource,
+            });
+            expect(manager).toBeDefined();
+        });
+    });
+    describe('connect', () => {
+        it('should call createEventSource', async () => {
+            const createEventSource = jest
+                .fn()
+                .mockResolvedValue(mockEventSource);
+            const manager = new stream_1.StreamManager({ createEventSource });
+            await manager.connect();
+            expect(createEventSource).toHaveBeenCalled();
+        });
+        it('should call onStart when connected', async () => {
+            const onStart = jest.fn();
+            const manager = new stream_1.StreamManager({
+                createEventSource: async () => mockEventSource,
+                onStart,
+            });
+            await manager.connect();
+            expect(onStart).toHaveBeenCalled();
+        });
+        it('should parse JSON messages and call onData', async () => {
+            const onData = jest.fn();
+            const manager = new stream_1.StreamManager({
+                createEventSource: async () => mockEventSource,
+                onData,
+            });
+            await manager.connect();
+            // Simulate receiving a message
+            const testData = { status: 'running', id: 'task-123' };
+            mockEventSource.onmessage?.({ data: JSON.stringify(testData) });
+            expect(onData).toHaveBeenCalledWith(testData);
+        });
+        it('should extract data from partial data wrapper and call onData', async () => {
+            const onData = jest.fn();
+            const manager = new stream_1.StreamManager({
+                createEventSource: async () => mockEventSource,
+                onData,
+            });
+            await manager.connect();
+            // Simulate receiving a partial data wrapper from server
+            const innerData = { status: 7, id: 'task-123', logs: ['log1'] };
+            const partialWrapper = { data: innerData, fields: ['status', 'logs'] };
+            mockEventSource.onmessage?.({ data: JSON.stringify(partialWrapper) });
+            // onData should receive the extracted inner data, not the wrapper
+            expect(onData).toHaveBeenCalledWith(innerData);
+        });
+        it('should call onPartialData with data and fields for partial updates', async () => {
+            const onData = jest.fn();
+            const onPartialData = jest.fn();
+            const manager = new stream_1.StreamManager({
+                createEventSource: async () => mockEventSource,
+                onData,
+                onPartialData,
+            });
+            await manager.connect();
+            // Simulate receiving a partial data wrapper
+            const innerData = { status: 7, id: 'task-123' };
+            const fields = ['status'];
+            const partialWrapper = { data: innerData, fields };
+            mockEventSource.onmessage?.({ data: JSON.stringify(partialWrapper) });
+            expect(onPartialData).toHaveBeenCalledWith(innerData, fields);
+            expect(onData).toHaveBeenCalledWith(innerData);
+        });
+        it('should not call onPartialData for non-partial data', async () => {
+            const onData = jest.fn();
+            const onPartialData = jest.fn();
+            const manager = new stream_1.StreamManager({
+                createEventSource: async () => mockEventSource,
+                onData,
+                onPartialData,
+            });
+            await manager.connect();
+            // Regular data without partial wrapper
+            const regularData = { status: 9, id: 'task-123' };
+            mockEventSource.onmessage?.({ data: JSON.stringify(regularData) });
+            expect(onPartialData).not.toHaveBeenCalled();
+            expect(onData).toHaveBeenCalledWith(regularData);
+        });
+        it('should call onError for invalid JSON', async () => {
+            const onError = jest.fn();
+            const manager = new stream_1.StreamManager({
+                createEventSource: async () => mockEventSource,
+                onError,
+            });
+            await manager.connect();
+            mockEventSource.onmessage?.({ data: 'invalid json' });
+            expect(onError).toHaveBeenCalled();
+        });
+    });
+    describe('stop', () => {
+        it('should close the event source', async () => {
+            const onStop = jest.fn();
+            const manager = new stream_1.StreamManager({
+                createEventSource: async () => mockEventSource,
+                onStop,
+            });
+            await manager.connect();
+            manager.stop();
+            expect(mockEventSource.close).toHaveBeenCalled();
+            expect(onStop).toHaveBeenCalled();
+        });
+        it('should not process messages after stop', async () => {
+            const onData = jest.fn();
+            const manager = new stream_1.StreamManager({
+                createEventSource: async () => mockEventSource,
+                onData,
+            });
+            await manager.connect();
+            manager.stop();
+            mockEventSource.onmessage?.({ data: '{"status":"running"}' });
+            expect(onData).not.toHaveBeenCalled();
+        });
+    });
+    describe('reconnection', () => {
+        it('should attempt reconnection on error when autoReconnect is true', async () => {
+            jest.useFakeTimers();
+            const createEventSource = jest
+                .fn()
+                .mockResolvedValue(mockEventSource);
+            const manager = new stream_1.StreamManager({
+                createEventSource,
+                autoReconnect: true,
+                reconnectDelayMs: 100,
+            });
+            await manager.connect();
+            expect(createEventSource).toHaveBeenCalledTimes(1);
+            // Simulate error
+            mockEventSource.onerror?.({});
+            // Fast-forward past reconnect delay
+            jest.advanceTimersByTime(100);
+            await Promise.resolve(); // Flush promises
+            expect(createEventSource).toHaveBeenCalledTimes(2);
+            jest.useRealTimers();
+        });
+        it('should not reconnect when autoReconnect is false', async () => {
+            const createEventSource = jest
+                .fn()
+                .mockResolvedValue(mockEventSource);
+            const manager = new stream_1.StreamManager({
+                createEventSource,
+                autoReconnect: false,
+            });
+            await manager.connect();
+            mockEventSource.onerror?.({});
+            // Wait a bit
+            await new Promise((r) => setTimeout(r, 50));
+            expect(createEventSource).toHaveBeenCalledTimes(1);
+        });
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inferencesh/sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Official JavaScript/TypeScript SDK for inference.sh - Run AI models with a simple API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",