@inferencesh/sdk 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2024-01-XX
+
+### Added
+
+- Initial release
+- `Inference` client class for API communication
+- `run()` method for executing tasks with optional waiting
+- `cancel()` method for cancelling running tasks
+- `uploadFile()` method for file uploads (base64, data URI, Blob)
+- Real-time status updates via `onUpdate` callback
+- Automatic reconnection for streaming connections
+- Full TypeScript support with exported types
+- Task status constants (`TaskStatusCompleted`, `TaskStatusFailed`, etc.)
+
+### Features
+
+- Simple, promise-based API
+- Streaming status updates via Server-Sent Events
+- Automatic file upload handling in task inputs
+- Configurable reconnection behavior
+- Comprehensive error handling
+
+[Unreleased]: https://github.com/inference-sh/sdk-js/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/inference-sh/sdk-js/releases/tag/v0.1.0
+

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 inference.sh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,216 @@
+# @inferencesh/sdk
+
+[![npm version](https://img.shields.io/npm/v/@inferencesh/sdk.svg)](https://www.npmjs.com/package/@inferencesh/sdk)
+[![npm downloads](https://img.shields.io/npm/dm/@inferencesh/sdk.svg)](https://www.npmjs.com/package/@inferencesh/sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+
+Official JavaScript/TypeScript SDK for [inference.sh](https://inference.sh) — Run AI models with a simple API.
+
+## Installation
+
+```bash
+npm install @inferencesh/sdk
+# or
+yarn add @inferencesh/sdk
+# or
+pnpm add @inferencesh/sdk
+```
+
+## Quick Start
+
+```typescript
+import { Inference, TaskStatusCompleted } from '@inferencesh/sdk';
+
+const client = new Inference({
+  apiKey: 'your-api-key'
+});
+
+// Run a task and wait for the result
+const result = await client.run({
+  app: 'your-app',
+  input: {
+    prompt: 'Hello, world!'
+  }
+});
+
+console.log(result.output);
+```
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { Inference } from '@inferencesh/sdk';
+
+const client = new Inference({ apiKey: 'your-api-key' });
+
+// Wait for result (default behavior)
+const result = await client.run({
+  app: 'my-app',
+  input: { prompt: 'Generate something amazing' }
+});
+
+console.log('Output:', result.output);
+```
+
+### Fire and Forget
+
+```typescript
+// Get task info immediately without waiting
+const task = await client.run(
+  { app: 'my-app', input: { prompt: 'hello' } },
+  { wait: false }
+);
+
+console.log('Task ID:', task.id);
+console.log('Status:', task.status);
+```
+
+### Real-time Status Updates
+
+```typescript
+const result = await client.run(
+  { app: 'my-app', input: { prompt: 'hello' } },
+  {
+    onUpdate: (update) => {
+      console.log('Status:', update.status);
+      console.log('Progress:', update.logs);
+    }
+  }
+);
+```
+
+### Batch Processing
+
+```typescript
+async function processImages(images: string[]) {
+  const results = [];
+  
+  for (const image of images) {
+    const result = await client.run({
+      app: 'image-processor',
+      input: { image }
+    }, {
+      onUpdate: (update) => console.log(`Processing: ${update.status}`)
+    });
+    
+    results.push(result);
+  }
+  
+  return results;
+}
+```
+
+### File Upload
+
+```typescript
+// Upload from base64
+const file = await client.uploadFile('data:image/png;base64,...', {
+  filename: 'image.png',
+  contentType: 'image/png'
+});
+
+// Use the uploaded file in a task
+const result = await client.run({
+  app: 'image-app',
+  input: { image: file.uri }
+});
+```
+
+### Cancel a Task
+
+```typescript
+const task = await client.run(
+  { app: 'long-running-app', input: {} },
+  { wait: false }
+);
+
+// Cancel if needed
+await client.cancel(task.id);
+```
+
+## API Reference
+
+### `new Inference(config)`
+
+Creates a new Inference client.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `config.apiKey` | `string` | Yes | Your inference.sh API key |
+| `config.baseUrl` | `string` | No | Custom API URL (default: `https://api.inference.sh`) |
+
+### `client.run(params, options?)`
+
+Runs a task on inference.sh.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `params.app` | `string` | Yes | App identifier (e.g., `'username/app-name'`) |
+| `params.input` | `object` | Yes | Input parameters for the app |
+| `params.infra` | `string` | No | Infrastructure: `'cloud'` or `'private'` |
+| `params.variant` | `string` | No | App variant to use |
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `wait` | `boolean` | `true` | Wait for task completion |
+| `onUpdate` | `function` | - | Callback for status updates |
+| `autoReconnect` | `boolean` | `true` | Auto-reconnect on connection loss |
+| `maxReconnects` | `number` | `5` | Max reconnection attempts |
+| `reconnectDelayMs` | `number` | `1000` | Delay between reconnects (ms) |
+
+### `client.cancel(taskId)`
+
+Cancels a running task.
+
+### `client.uploadFile(data, options?)`
+
+Uploads a file to inference.sh.
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `data` | `string \| Blob` | Base64 string, data URI, or Blob |
+| `options.filename` | `string` | Filename |
+| `options.contentType` | `string` | MIME type |
+| `options.public` | `boolean` | Make file publicly accessible |
+
+## Task Status Constants
+
+```typescript
+import {
+  TaskStatusQueued,
+  TaskStatusRunning,
+  TaskStatusCompleted,
+  TaskStatusFailed,
+  TaskStatusCancelled
+} from '@inferencesh/sdk';
+
+if (task.status === TaskStatusCompleted) {
+  console.log('Done!');
+}
+```
+
+## TypeScript Support
+
+This SDK is written in TypeScript and includes full type definitions. All types are exported:
+
+```typescript
+import type { Task, ApiTaskRequest, RunOptions } from '@inferencesh/sdk';
+```
+
+## Requirements
+
+- Node.js 18.0.0 or higher
+- Modern browsers with `fetch` support
+
+## License
+
+MIT © [inference.sh](https://inference.sh)

package/dist/client.d.ts

@@ -0,0 +1,77 @@
+import { ApiTaskRequest, TaskDTO as Task, File } from './types';
+export interface UploadFileOptions {
+    filename?: string;
+    contentType?: string;
+    path?: string;
+    public?: boolean;
+}
+export interface InferenceConfig {
+    /** Your inference.sh API key */
+    apiKey: string;
+    /** Custom API base URL (defaults to https://api.inference.sh) */
+    baseUrl?: string;
+}
+export interface RunOptions {
+    /** Callback for real-time status updates */
+    onUpdate?: (update: Task) => void;
+    /** Wait for task completion (default: true) */
+    wait?: boolean;
+    /** Auto-reconnect on connection loss (default: true) */
+    autoReconnect?: boolean;
+    /** Maximum reconnection attempts (default: 5) */
+    maxReconnects?: number;
+    /** Delay between reconnection attempts in ms (default: 1000) */
+    reconnectDelayMs?: number;
+}
+/**
+ * Inference.sh SDK Client
+ *
+ * @example
+ * ```typescript
+ * const client = new Inference({ apiKey: 'your-api-key' });
+ * const result = await client.run({ app: 'my-app', input: { prompt: 'hello' } });
+ * ```
+ */
+export declare class Inference {
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor(config: InferenceConfig);
+    private request;
+    private createEventSource;
+    private _stripTask;
+    private processInputData;
+    /**
+     * Run a task on inference.sh
+     *
+     * @param params - Task parameters including app and input
+     * @param options - Run options for waiting, updates, and reconnection
+     * @returns The completed task result
+     *
+     * @example
+     * ```typescript
+     * // Simple usage - wait for result
+     * const result = await client.run({ app: 'my-app', input: { prompt: 'hello' } });
+     *
+     * // With status updates
+     * const result = await client.run(
+     *   { app: 'my-app', input: { prompt: 'hello' } },
+     *   { onUpdate: (update) => console.log(update.status) }
+     * );
+     *
+     * // Fire and forget
+     * const task = await client.run({ app: 'my-app', input: {} }, { wait: false });
+     * ```
+     */
+    run(params: ApiTaskRequest, options?: RunOptions): Promise<Task>;
+    uploadFile(data: string | Blob, options?: UploadFileOptions): Promise<File>;
+    /**
+       * Cancel a running task
+       *
+       * @param taskId - The ID of the task to cancel
+       */
+    cancel(taskId: string): Promise<void>;
+}
+/**
+ * @deprecated Use `Inference` instead. Will be removed in v1.0.0
+ */
+export declare const inference: typeof Inference;

package/dist/client.js

@@ -0,0 +1,249 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inference = exports.Inference = void 0;
+const types_1 = require("./types");
+const stream_1 = require("./stream");
+const eventsource_1 = require("eventsource");
+/**
+ * Inference.sh SDK Client
+ *
+ * @example
+ * ```typescript
+ * const client = new Inference({ apiKey: 'your-api-key' });
+ * const result = await client.run({ app: 'my-app', input: { prompt: 'hello' } });
+ * ```
+ */
+class Inference {
+    constructor(config) {
+        if (!config.apiKey) {
+            throw new Error('API key is required');
+        }
+        this.apiKey = config.apiKey;
+        this.baseUrl = config.baseUrl || "https://api.inference.sh";
+    }
+    async request(method, endpoint, options = {}) {
+        const url = new URL(`${this.baseUrl}${endpoint}`);
+        if (options.params) {
+            Object.entries(options.params).forEach(([key, value]) => {
+                if (value !== undefined && value !== null) {
+                    url.searchParams.append(key, String(value));
+                }
+            });
+        }
+        const headers = {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${this.apiKey}`,
+        };
+        const fetchOptions = {
+            method: method.toUpperCase(),
+            headers,
+            credentials: "include",
+        };
+        if (options.data) {
+            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");
+        }
+        return data.data;
+    }
+    createEventSource(endpoint) {
+        const url = new URL(`${this.baseUrl}${endpoint}`);
+        return new eventsource_1.EventSource(url.toString(), {
+            fetch: (input, init) => fetch(input, {
+                ...init,
+                headers: {
+                    ...init.headers,
+                    Authorization: `Bearer ${this.apiKey}`,
+                },
+            }),
+        });
+    }
+    _stripTask(task) {
+        // Keep required fields and add stripped ones
+        return {
+            ...task,
+            id: task.id,
+            created_at: task.created_at,
+            updated_at: task.updated_at,
+            input: task.input,
+            output: task.output,
+            logs: task.logs,
+            status: task.status,
+        };
+    }
+    async processInputData(input, path = 'root') {
+        if (!input) {
+            return input;
+        }
+        // Handle arrays
+        if (Array.isArray(input)) {
+            return Promise.all(input.map((item, idx) => this.processInputData(item, `${path}[${idx}]`)));
+        }
+        // Handle objects
+        if (typeof input === 'object') {
+            // Handle Blob
+            if (typeof Blob !== "undefined" && input instanceof Blob) {
+                const file = await this.uploadFile(input);
+                return file.uri;
+            }
+            // Recursively process object properties
+            const processed = {};
+            for (const [key, value] of Object.entries(input)) {
+                processed[key] = await this.processInputData(value, `${path}.${key}`);
+            }
+            return processed;
+        }
+        // Handle base64 strings or data URIs
+        if (typeof input === 'string' &&
+            (input.startsWith('data:') ||
+                /^([A-Za-z0-9+/]{4})*([A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}==)?$/.test(input))) {
+            const file = await this.uploadFile(input);
+            return file.uri;
+        }
+        return input;
+    }
+    /**
+     * Run a task on inference.sh
+     *
+     * @param params - Task parameters including app and input
+     * @param options - Run options for waiting, updates, and reconnection
+     * @returns The completed task result
+     *
+     * @example
+     * ```typescript
+     * // Simple usage - wait for result
+     * const result = await client.run({ app: 'my-app', input: { prompt: 'hello' } });
+     *
+     * // With status updates
+     * const result = await client.run(
+     *   { app: 'my-app', input: { prompt: 'hello' } },
+     *   { onUpdate: (update) => console.log(update.status) }
+     * );
+     *
+     * // Fire and forget
+     * const task = await client.run({ app: 'my-app', input: {} }, { wait: false });
+     * ```
+     */
+    async run(params, options = {}) {
+        const { onUpdate, 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", {
+            data: {
+                ...params,
+                input: processedInput
+            },
+        });
+        // Return immediately if not waiting
+        if (!wait) {
+            return this._stripTask(task);
+        }
+        // Wait for completion with optional updates
+        return new Promise((resolve, reject) => {
+            const streamManager = new stream_1.StreamManager({
+                createEventSource: async () => this.createEventSource(`/tasks/${task.id}/stream`),
+                autoReconnect,
+                maxReconnects,
+                reconnectDelayMs,
+                onData: (data) => {
+                    // Strip and send update if callback provided
+                    const stripped = this._stripTask(data);
+                    onUpdate?.(stripped);
+                    if (data.status === types_1.TaskStatusCompleted) {
+                        streamManager.stop();
+                        resolve(stripped);
+                    }
+                    else if (data.status === types_1.TaskStatusFailed) {
+                        streamManager.stop();
+                        reject(new Error(data.error || "task failed"));
+                    }
+                    else if (data.status === types_1.TaskStatusCancelled) {
+                        streamManager.stop();
+                        reject(new Error("task cancelled"));
+                    }
+                },
+                onError: (error) => {
+                    reject(error);
+                    streamManager.stop();
+                },
+            });
+            streamManager.connect();
+        });
+    }
+    async uploadFile(data, options = {}) {
+        // Step 1: Create the file record
+        const fileRequest = {
+            uri: '', // Empty URI as it will be set by the server
+            filename: options.filename,
+            content_type: options.contentType || (data instanceof Blob ? data.type : 'application/octet-stream'),
+            path: options.path,
+            size: data instanceof Blob ? data.size : undefined,
+        };
+        const response = await this.request("post", "/files", {
+            data: {
+                files: [fileRequest]
+            }
+        });
+        const file = response[0];
+        // Step 2: Upload the file content to the provided upload_url
+        if (!file.upload_url) {
+            throw new Error('No upload URL provided by the server');
+        }
+        let contentToUpload;
+        if (data instanceof Blob) {
+            contentToUpload = data;
+        }
+        else {
+            // If it's a base64 string, convert it to a Blob
+            if (data.startsWith('data:')) {
+                const matches = data.match(/^data:([^;]+);base64,(.+)$/);
+                if (!matches) {
+                    throw new Error('Invalid base64 data URI format');
+                }
+                const binaryStr = atob(matches[2]);
+                const bytes = new Uint8Array(binaryStr.length);
+                for (let i = 0; i < binaryStr.length; i++) {
+                    bytes[i] = binaryStr.charCodeAt(i);
+                }
+                contentToUpload = new Blob([bytes], { type: matches[1] });
+            }
+            else {
+                // Assume it's a clean base64 string
+                const binaryStr = atob(data);
+                const bytes = new Uint8Array(binaryStr.length);
+                for (let i = 0; i < binaryStr.length; i++) {
+                    bytes[i] = binaryStr.charCodeAt(i);
+                }
+                contentToUpload = new Blob([bytes], { type: options.contentType || 'application/octet-stream' });
+            }
+        }
+        // Upload to S3 using the signed URL
+        const uploadResponse = await fetch(file.upload_url, {
+            method: 'PUT',
+            body: contentToUpload,
+            headers: {
+                'Content-Type': contentToUpload.type,
+            }
+        });
+        if (!uploadResponse.ok) {
+            throw new Error(`Failed to upload file content: ${uploadResponse.statusText}`);
+        }
+        return file;
+    }
+    /**
+       * Cancel a running task
+       *
+       * @param taskId - The ID of the task to cancel
+       */
+    async cancel(taskId) {
+        return this.request("post", `/tasks/${taskId}/cancel`);
+    }
+}
+exports.Inference = Inference;
+/**
+ * @deprecated Use `Inference` instead. Will be removed in v1.0.0
+ */
+exports.inference = Inference;

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,23 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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;
+// 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; } });
+// Types - includes TaskStatus constants and all DTOs
+__exportStar(require("./types"), exports);

package/dist/index.mjs

@@ -0,0 +1 @@
+export * from "./index.js";

package/dist/stream.d.ts

@@ -0,0 +1,29 @@
+export interface StreamManagerOptions<T> {
+    createEventSource: () => Promise<EventSource | null>;
+    autoReconnect?: boolean;
+    maxReconnects?: number;
+    reconnectDelayMs?: number;
+    onError?: (error: Error) => void;
+    onStart?: () => void;
+    onStop?: () => void;
+    onData?: (data: T) => void;
+    onYield?: (data: T) => void;
+}
+export declare class StreamManager<T> {
+    private options;
+    private eventSource;
+    private reconnectTimeout;
+    private stopTimeout;
+    private initialConnectionAttempts;
+    private isConnected;
+    private isStopped;
+    constructor(options: StreamManagerOptions<T>);
+    private clearTimeouts;
+    private closeEventSource;
+    private cleanup;
+    stopAfter(delayMs: number): void;
+    clearStopTimeout(): void;
+    stop(): void;
+    private scheduleReconnect;
+    connect(): Promise<void>;
+}