@inferencesh/sdk 0.4.27 → 0.5.1

package/README.md

@@ -1,11 +1,13 @@
-# @inferencesh/sdk
+# @inferencesh/sdk — ai inference api for javascript & typescript
 
 [![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.
+official javascript/typescript sdk for [inference.sh](https://inference.sh) — the ai agent runtime for serverless ai inference.
+
+run ai models, build ai agents, and deploy generative ai applications with a simple api. access 150+ models including flux, stable diffusion, llms (claude, gpt, gemini), video generation (veo, seedance), and more.
 
 ## Installation
 
@@ -149,6 +151,53 @@ const task = await client.tasks.run(
 await client.tasks.cancel(task.id);
 ```
 
+### Sessions (Stateful Execution)
+
+Sessions allow you to maintain state across multiple task invocations. The worker stays warm between calls, preserving loaded models and in-memory state.
+
+```typescript
+// Start a new session
+const result = await client.tasks.run({
+  app: 'my-stateful-app',
+  input: { prompt: 'hello' },
+  session: 'new'
+});
+
+const sessionId = result.session_id;
+console.log('Session ID:', sessionId);
+
+// Continue the session with another call
+const result2 = await client.tasks.run({
+  app: 'my-stateful-app',
+  input: { prompt: 'remember what I said?' },
+  session: sessionId
+});
+```
+
+#### Custom Session Timeout
+
+By default, sessions expire after 60 seconds of inactivity. You can customize this with `session_timeout` (1-3600 seconds):
+
+```typescript
+// Create a session with 5-minute idle timeout
+const result = await client.tasks.run({
+  app: 'my-stateful-app',
+  input: { prompt: 'hello' },
+  session: 'new',
+  session_timeout: 300  // 5 minutes
+});
+
+// Session stays alive for 5 minutes after each call
+```
+
+**Notes:**
+- `session_timeout` is only valid when `session: 'new'`
+- Minimum timeout: 1 second
+- Maximum timeout: 3600 seconds (1 hour)
+- Each successful call resets the idle timer
+
+For complete session documentation including error handling, best practices, and advanced patterns, see the [Sessions Developer Guide](https://inference.sh/docs/extend/sessions).
+
 ## Agent Chat
 
 Chat with AI agents using `client.agents.create()`.
@@ -252,6 +301,8 @@ Runs a task on inference.sh.
 | `params.setup` | `object` | No | Setup parameters (affects worker warmth/scheduling) |
 | `params.infra` | `string` | No | Infrastructure: `'cloud'` or `'private'` |
 | `params.variant` | `string` | No | App variant to use |
+| `params.session` | `string` | No | Session ID or `'new'` to start a new session |
+| `params.session_timeout` | `number` | No | Session timeout in seconds (1-3600, only with `session: 'new'`) |
 
 **Options:**
 
@@ -331,6 +382,14 @@ import type { Task, ApiTaskRequest, RunOptions } from '@inferencesh/sdk';
 - Node.js 18.0.0 or higher
 - Modern browsers with `fetch` support
 
-## License
+## resources
+
+- [documentation](https://inference.sh/docs) — getting started guides and api reference
+- [blog](https://inference.sh/blog) — tutorials on ai agents, image generation, and more
+- [app store](https://app.inference.sh) — browse 150+ ai models
+- [discord](https://discord.gg/RM77SWSbyT) — community support
+- [github](https://github.com/inference-sh) — open source projects
+
+## license
 
 MIT © [inference.sh](https://inference.sh)

package/dist/api/apps.d.ts

@@ -1,14 +1,5 @@
 import { HttpClient } from '../http/client';
-import { AppDTO as App, AppVersionDTO, CursorListRequest, CursorListResponse } from '../types';
-interface LicenseRecord {
-    id: string;
-    created_at: string;
-    updated_at: string;
-    deleted_at?: string;
-    user_id: string;
-    app_id: string;
-    license: string;
-}
+import { AppDTO as App, AppVersionDTO, CursorListRequest, CursorListResponse, LicenseRecord } from '../types';
 /**
  * Apps API
  */
@@ -69,4 +60,3 @@ export declare class AppsAPI {
     saveLicense(appId: string, license: string): Promise<LicenseRecord>;
 }
 export declare function createAppsAPI(http: HttpClient): AppsAPI;
-export {};

package/dist/types.d.ts

@@ -192,9 +192,7 @@ export interface AgentImages {
     thumbnail: string;
     banner: string;
 }
-export interface Agent {
-    BaseModel: BaseModel;
-    PermissionModel: PermissionModel;
+export interface Agent extends BaseModel, PermissionModel {
     ProjectModel: ProjectModel;
     /**
      * Basic info
@@ -261,14 +259,8 @@ export interface AgentConfig {
      */
     output_schema?: any;
 }
-export interface AgentVersion {
-    BaseModel: BaseModel;
-    PermissionModel: PermissionModel;
+export interface AgentVersion extends BaseModel, PermissionModel {
     agent_id: string;
-    /**
-     * Short ID for human-readable version references (e.g., "abc123")
-     */
-    short_id: string;
     /**
      * ConfigHash for deduplication - SHA256 of config content
      */
@@ -360,6 +352,10 @@ export interface ApiAppRunRequest {
      * When using sessions, the worker is leased and state persists across calls
      */
     session?: string;
+    /**
+     * Session timeout in seconds (1-3600). Only valid when session="new"
+     */
+    session_timeout?: number;
 }
 /**
  * ApiAgentRunRequest is the request body for /agents/run endpoint.
@@ -710,9 +706,7 @@ export interface AppImages {
     thumbnail: string;
     banner: string;
 }
-export interface App {
-    BaseModel: BaseModel;
-    PermissionModel: PermissionModel;
+export interface App extends BaseModel, PermissionModel {
     /**
      * Namespace is copied from team.username at creation time and is IMMUTABLE.
      * This ensures stable references like "namespace/name" even if team username changes.
@@ -767,13 +761,7 @@ export interface AppFunction {
     input_schema: any;
     output_schema: any;
 }
-export interface AppVersion {
-    BaseModel: BaseModel;
-    /**
-     * ShortID is a human-friendly version identifier (e.g., "abc123")
-     * Unique within the app, used in references like "namespace/app@abc123"
-     */
-    short_id: string;
+export interface AppVersion extends BaseModel {
     app_id: string;
     metadata: {
         [key: string]: any;
@@ -811,6 +799,11 @@ export interface AppVersion {
      */
     checksum?: string;
 }
+export interface LicenseRecord extends BaseModel {
+    user_id: string;
+    app_id: string;
+    license: string;
+}
 export interface AppDTO extends BaseModel, PermissionModelDTO {
     namespace: string;
     name: string;
@@ -822,7 +815,6 @@ export interface AppDTO extends BaseModel, PermissionModelDTO {
     version?: AppVersionDTO;
 }
 export interface AppVersionDTO extends BaseModel {
-    short_id: string;
     metadata: {
         [key: string]: any;
     };
@@ -858,9 +850,7 @@ export type AppSessionStatus = string;
 export declare const AppSessionStatusActive: AppSessionStatus;
 export declare const AppSessionStatusEnded: AppSessionStatus;
 export declare const AppSessionStatusExpired: AppSessionStatus;
-export interface AppSession {
-    BaseModel: BaseModel;
-    PermissionModel: PermissionModel;
+export interface AppSession extends BaseModel, PermissionModel {
     /**
      * Affinity binding
      */
@@ -882,6 +872,10 @@ export interface AppSession {
      */
     call_count: number;
     last_call_at?: string;
+    /**
+     * Custom idle timeout in seconds (nil = use default)
+     */
+    idle_timeout?: number;
     /**
      * Relations
      */
@@ -890,6 +884,7 @@ export interface AppSession {
 }
 export interface BaseModel {
     id: string;
+    short_id: string;
     created_at: string;
     updated_at: string;
     deleted_at?: string;
@@ -1150,9 +1145,7 @@ export declare const EngineStatusRunning: EngineStatus;
 export declare const EngineStatusPending: EngineStatus;
 export declare const EngineStatusStopping: EngineStatus;
 export declare const EngineStatusStopped: EngineStatus;
-export interface EngineState {
-    BaseModel: BaseModel;
-    PermissionModel: PermissionModel;
+export interface EngineState extends BaseModel, PermissionModel {
     instance?: Instance;
     transaction_id: string;
     config: EngineConfig;
@@ -1182,9 +1175,7 @@ export interface EngineStateSummary extends BaseModel, PermissionModelDTO {
  * Worker-related types
  */
 export type WorkerStatus = string;
-export interface WorkerState {
-    BaseModel: BaseModel;
-    PermissionModel: PermissionModel;
+export interface WorkerState extends BaseModel, PermissionModel {
     index: number;
     status: WorkerStatus;
     status_updated_at?: string;
@@ -1262,9 +1253,7 @@ export interface WorkerStateSummary {
     cpus: WorkerCPU[];
     rams: WorkerRAM[];
 }
-export interface File {
-    BaseModel: BaseModel;
-    PermissionModel: PermissionModel;
+export interface File extends BaseModel, PermissionModel {
     path: string;
     remote_path: string;
     upload_url: string;
@@ -1284,8 +1273,7 @@ export interface FileDTO extends BaseModel, PermissionModelDTO {
     filename: string;
     rating: ContentRating;
 }
-export interface FlowVersion {
-    BaseModel: BaseModel;
+export interface FlowVersion extends BaseModel {
     /**
      * Permission fields - nullable for migration from existing data
      * After migration these will be populated from parent Flow
@@ -1295,10 +1283,6 @@ export interface FlowVersion {
     team_id: string;
     team?: Team;
     flow_id: string;
-    /**
-     * Short ID for human-readable version references (e.g., "abc123")
-     */
-    short_id: string;
     /**
      * ConfigHash for deduplication - SHA256 of config content
      */
@@ -1395,7 +1379,6 @@ export interface FlowDTO extends BaseModel, PermissionModelDTO {
     viewport?: FlowViewport;
 }
 export interface FlowVersionDTO extends BaseModel {
-    short_id: string;
     input_schema: any;
     input: FlowRunInputs;
     output_schema: any;
@@ -1564,9 +1547,7 @@ export interface ProjectModelDTO {
 /**
  * Project represents a container for organizing related resources
  */
-export interface Project {
-    BaseModel: BaseModel;
-    PermissionModel: PermissionModel;
+export interface Project extends BaseModel, PermissionModel {
     name: string;
     description: string;
     type: ProjectType;
@@ -1673,9 +1654,7 @@ export type InstanceStatus = string;
 export declare const InstanceStatusPending: InstanceStatus;
 export declare const InstanceStatusActive: InstanceStatus;
 export declare const InstanceStatusDeleted: InstanceStatus;
-export interface Instance {
-    BaseModel: BaseModel;
-    PermissionModel: PermissionModel;
+export interface Instance extends BaseModel, PermissionModel {
     cloud: InstanceCloudProvider;
     name: string;
     region: string;
@@ -1891,9 +1870,7 @@ export type Infra = string;
 export declare const InfraPrivate: Infra;
 export declare const InfraCloud: Infra;
 export declare const InfraPrivateFirst: Infra;
-export interface Task {
-    BaseModel: BaseModel;
-    PermissionModel: PermissionModel;
+export interface Task extends BaseModel, PermissionModel {
     is_featured: boolean;
     status: TaskStatus;
     /**
@@ -1953,6 +1930,10 @@ export interface Task {
      */
     session_id?: string;
     session?: AppSession;
+    /**
+     * Session timeout in seconds (only used when session="new")
+     */
+    session_timeout?: number;
 }
 export interface TaskEvent {
     id: string;
@@ -2012,6 +1993,7 @@ export interface TaskDTO extends BaseModel, PermissionModelDTO {
     transaction_id?: string;
     transaction?: Transaction;
     session_id?: string;
+    session_timeout?: number;
 }
 export interface TimescaleTask {
     id: string;
@@ -2029,8 +2011,7 @@ export type TeamType = string;
 export declare const TeamTypePersonal: TeamType;
 export declare const TeamTypeTeam: TeamType;
 export declare const TeamTypeSystem: TeamType;
-export interface Team {
-    BaseModel: BaseModel;
+export interface Team extends BaseModel {
     type: TeamType;
     username: string;
     email: string;
@@ -2137,8 +2118,7 @@ export declare const TransactionTypeDebit: TransactionType;
 /**
  * Transaction represents a single credit transaction
  */
-export interface Transaction {
-    BaseModel: BaseModel;
+export interface Transaction extends BaseModel {
     PermissionModel: PermissionModel;
     type: TransactionType;
     amount: number;
@@ -2168,9 +2148,7 @@ export declare const PaymentRecordTypeAutoRecharge: PaymentRecordType;
 /**
  * PaymentRecord stores Stripe payment details for both checkout sessions and direct charges
  */
-export interface PaymentRecord {
-    BaseModel: BaseModel;
-    PermissionModel: PermissionModel;
+export interface PaymentRecord extends BaseModel, PermissionModel {
     type: PaymentRecordType;
     status: PaymentRecordStatus;
     amount: number;
@@ -2248,9 +2226,7 @@ export interface OutputMeta {
     inputs: MetaItem[];
     outputs: MetaItem[];
 }
-export interface UsageEvent {
-    BaseModel: BaseModel;
-    PermissionModel: PermissionModel;
+export interface UsageEvent extends BaseModel, PermissionModel {
     usage_billing_record_id: string;
     reference_id: string;
     resource_id: string;
@@ -2263,9 +2239,7 @@ export interface UsageEvent {
     quantity: number;
     unit: string;
 }
-export interface UsageBillingRecord {
-    BaseModel: BaseModel;
-    PermissionModel: PermissionModel;
+export interface UsageBillingRecord extends BaseModel, PermissionModel {
     /**
      * Fee breakdown (all in microcents)
      */
@@ -2297,9 +2271,7 @@ export interface UsageBillingRecord {
     partner_credit_transaction_id: string;
     partner_credit_transaction?: Transaction;
 }
-export interface UsageBillingRefund {
-    BaseModel: BaseModel;
-    PermissionModel: PermissionModel;
+export interface UsageBillingRefund extends BaseModel, PermissionModel {
     usage_billing_record_id: string;
     usage_billing_record?: UsageBillingRecord;
     /**

package/package.json

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