@inferencesh/sdk 0.4.4 → 0.4.8

package/dist/client.d.ts

@@ -1,10 +1,10 @@
-import { ApiAppRunRequest, TaskDTO as Task, File, ChatDTO, ChatMessageDTO, AgentRuntimeConfig } from './types';
+import { ApiAppRunRequest, TaskDTO as Task, File, ChatDTO, ChatMessageDTO, AgentConfig } from './types';
 import { EventSource } from 'eventsource';
 /**
- * Ad-hoc agent configuration - extends AgentRuntimeConfig with core_app_ref required
- * Uses Partial to make name/system_prompt optional for ad-hoc usage
+ * Ad-hoc agent configuration - extends AgentConfig with core_app_ref required
+ * Uses Partial to make fields optional for ad-hoc usage
  */
-export type AdHocAgentConfig = Partial<AgentRuntimeConfig> & {
+export type AdHocAgentConfig = Partial<AgentConfig> & {
     /** Core LLM app ref: namespace/name@shortid (required for ad-hoc agents) */
     core_app_ref: string;
 };
@@ -29,10 +29,17 @@ export interface UploadFileOptions {
     public?: boolean;
 }
 export interface InferenceConfig {
-    /** Your inference.sh API key */
-    apiKey: string;
+    /** Your inference.sh API key (required unless using proxyUrl) */
+    apiKey?: string;
     /** Custom API base URL (defaults to https://api.inference.sh) */
     baseUrl?: string;
+    /**
+     * Proxy URL for frontend apps.
+     * When set, requests are routed through your proxy server to protect API keys.
+     * @example "/api/inference/proxy"
+     * @example "https://myapp.com/api/inference/proxy"
+     */
+    proxyUrl?: string;
 }
 export interface RunOptions {
     /** Callback for real-time status updates */
@@ -60,6 +67,7 @@ export interface RunOptions {
 export declare class Inference {
     private readonly apiKey;
     private readonly baseUrl;
+    private readonly proxyUrl;
     constructor(config: InferenceConfig);
     /** @internal */
     _request<T>(method: "get" | "post" | "put" | "delete", endpoint: string, options?: {

package/dist/client.js

@@ -17,26 +17,39 @@ const errors_1 = require("./errors");
  */
 class Inference {
     constructor(config) {
-        if (!config.apiKey) {
-            throw new Error('API key is required');
+        // Either apiKey or proxyUrl must be provided
+        if (!config.apiKey && !config.proxyUrl) {
+            throw new Error('Either apiKey or proxyUrl is required');
         }
         this.apiKey = config.apiKey;
         this.baseUrl = config.baseUrl || "https://api.inference.sh";
+        this.proxyUrl = config.proxyUrl;
     }
     /** @internal */
     async _request(method, endpoint, options = {}) {
-        const url = new URL(`${this.baseUrl}${endpoint}`);
+        // Build the target URL (always points to the API)
+        const targetUrl = 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));
+                    targetUrl.searchParams.append(key, String(value));
                 }
             });
         }
+        // In proxy mode, requests go to the proxy with target URL in a header
+        const isProxyMode = !!this.proxyUrl;
+        const fetchUrl = isProxyMode ? this.proxyUrl : targetUrl.toString();
         const headers = {
             "Content-Type": "application/json",
-            Authorization: `Bearer ${this.apiKey}`,
         };
+        if (isProxyMode) {
+            // Proxy mode: send target URL as header, no auth (proxy handles it)
+            headers["x-inf-target-url"] = targetUrl.toString();
+        }
+        else {
+            // Direct mode: include authorization header
+            headers["Authorization"] = `Bearer ${this.apiKey}`;
+        }
         const fetchOptions = {
             method: method.toUpperCase(),
             headers,
@@ -45,7 +58,7 @@ class Inference {
         if (options.data) {
             fetchOptions.body = JSON.stringify(options.data);
         }
-        const response = await fetch(url.toString(), fetchOptions);
+        const response = await fetch(fetchUrl, fetchOptions);
         const responseText = await response.text();
         // Try to parse as JSON
         let data = null;
@@ -94,15 +107,27 @@ class Inference {
     }
     /** @internal */
     _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}`,
-                },
-            }),
+        const targetUrl = new URL(`${this.baseUrl}${endpoint}`);
+        const isProxyMode = !!this.proxyUrl;
+        const fetchUrl = isProxyMode ? this.proxyUrl : targetUrl.toString();
+        return new eventsource_1.EventSource(fetchUrl, {
+            fetch: (input, init) => {
+                const headers = {
+                    ...init?.headers,
+                };
+                if (isProxyMode) {
+                    // Proxy mode: send target URL as header
+                    headers["x-inf-target-url"] = targetUrl.toString();
+                }
+                else {
+                    // Direct mode: include authorization header
+                    headers["Authorization"] = `Bearer ${this.apiKey}`;
+                }
+                return fetch(input, {
+                    ...init,
+                    headers,
+                });
+            },
         });
     }
     _stripTask(task) {

package/dist/client.test.js

@@ -14,9 +14,9 @@ describe('Inference', () => {
             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 throw error when neither apiKey nor proxyUrl is provided', () => {
+            expect(() => new client_1.Inference({ apiKey: '' })).toThrow('Either apiKey or proxyUrl is required');
+            expect(() => new client_1.Inference({})).toThrow('Either apiKey or proxyUrl is required');
         });
         it('should use default baseUrl when not provided', () => {
             const client = new client_1.Inference({ apiKey: 'test-api-key' });

package/dist/index.d.ts

@@ -1,5 +1,4 @@
 export { Inference, inference, InferenceConfig, RunOptions, UploadFileOptions, Agent, AdHocAgentConfig, SendMessageOptions, } from './client';
-export { AgentConfig, AdHocAgentOptions, TemplateAgentOptions, AgentOptions, } from './agent';
 export { tool, appTool, agentTool, webhookTool, internalTools, string, number, integer, boolean, enumOf, object, array, optional } from './tool-builder';
 export { StreamManager, PartialDataWrapper } from './stream';
 export { InferenceError, RequirementsNotMetException } from './errors';

package/dist/proxy/express.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Express.js proxy handler for Inference.sh API
+ *
+ * @example
+ * ```typescript
+ * import express from "express";
+ * import * as inferenceProxy from "@inferencesh/sdk/proxy/express";
+ *
+ * const app = express();
+ * app.use(express.json());
+ * app.all(inferenceProxy.route, inferenceProxy.handler);
+ * ```
+ */
+import type { RequestHandler } from "express";
+/**
+ * The default proxy route path.
+ */
+export declare const route = "/api/inference/proxy";
+/**
+ * Express middleware handler for the Inference.sh proxy.
+ *
+ * Requires `express.json()` middleware to be applied before this handler.
+ *
+ * @example
+ * ```typescript
+ * import express from "express";
+ * import cors from "cors";
+ * import * as inferenceProxy from "@inferencesh/sdk/proxy/express";
+ *
+ * const app = express();
+ * app.use(express.json());
+ *
+ * // If clients are external, enable CORS
+ * app.all(inferenceProxy.route, cors(), inferenceProxy.handler);
+ * ```
+ */
+export declare const handler: RequestHandler;

package/dist/proxy/express.js

@@ -0,0 +1,84 @@
+"use strict";
+/**
+ * Express.js proxy handler for Inference.sh API
+ *
+ * @example
+ * ```typescript
+ * import express from "express";
+ * import * as inferenceProxy from "@inferencesh/sdk/proxy/express";
+ *
+ * const app = express();
+ * app.use(express.json());
+ * app.all(inferenceProxy.route, inferenceProxy.handler);
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handler = exports.route = void 0;
+const index_1 = require("./index");
+/**
+ * The default proxy route path.
+ */
+exports.route = index_1.DEFAULT_PROXY_ROUTE;
+/**
+ * Express middleware handler for the Inference.sh proxy.
+ *
+ * Requires `express.json()` middleware to be applied before this handler.
+ *
+ * @example
+ * ```typescript
+ * import express from "express";
+ * import cors from "cors";
+ * import * as inferenceProxy from "@inferencesh/sdk/proxy/express";
+ *
+ * const app = express();
+ * app.use(express.json());
+ *
+ * // If clients are external, enable CORS
+ * app.all(inferenceProxy.route, cors(), inferenceProxy.handler);
+ * ```
+ */
+const handler = async (req, res, _next) => {
+    const responseHeaders = {};
+    return (0, index_1.handleRequest)({
+        id: "express",
+        method: req.method,
+        getRequestBody: async () => JSON.stringify(req.body),
+        getHeaders: () => req.headers,
+        getHeader: (name) => req.headers[name],
+        sendHeader: (name, value) => {
+            responseHeaders[name] = value;
+            res.setHeader(name, value);
+        },
+        respondWith: (status, data) => {
+            return res.status(status).json(data);
+        },
+        sendResponse: async (response) => {
+            // Copy status
+            res.status(response.status);
+            // Handle streaming responses
+            const contentType = response.headers.get("content-type");
+            if (contentType?.includes("text/event-stream") ||
+                contentType?.includes("application/octet-stream")) {
+                // Stream the response
+                if (response.body) {
+                    const reader = response.body.getReader();
+                    while (true) {
+                        const { done, value } = await reader.read();
+                        if (done)
+                            break;
+                        res.write(value);
+                    }
+                }
+                res.end();
+                return res;
+            }
+            // Handle JSON responses
+            if (contentType?.includes("application/json")) {
+                return res.json(await response.json());
+            }
+            // Handle text responses
+            return res.send(await response.text());
+        },
+    });
+};
+exports.handler = handler;

package/dist/proxy/express.mjs

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

package/dist/proxy/hono.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Hono proxy handler for Inference.sh API
+ *
+ * Lightweight handler for Hono framework, ideal for edge/serverless deployments.
+ *
+ * @example
+ * ```typescript
+ * import { Hono } from "hono";
+ * import { createRouteHandler } from "@inferencesh/sdk/proxy/hono";
+ *
+ * const app = new Hono();
+ * const proxyHandler = createRouteHandler();
+ *
+ * app.all("/api/inference/proxy", proxyHandler);
+ * ```
+ */
+import type { Context } from "hono";
+export interface HonoProxyOptions {
+    /**
+     * Custom function to resolve the API key.
+     * Defaults to reading from INFERENCE_API_KEY environment variable.
+     */
+    resolveApiKey?: () => Promise<string | undefined>;
+}
+type RouteHandler = (context: Context) => Promise<Response>;
+/**
+ * Creates a Hono route handler that proxies requests to the Inference.sh API.
+ *
+ * This is a drop-in handler for Hono applications that keeps API keys safe
+ * by running on your server.
+ *
+ * @param options - Proxy options
+ * @returns A Hono route handler function
+ *
+ * @example
+ * ```typescript
+ * import { Hono } from "hono";
+ * import { createRouteHandler } from "@inferencesh/sdk/proxy/hono";
+ *
+ * const app = new Hono();
+ * const proxyHandler = createRouteHandler();
+ *
+ * app.all("/api/inference/proxy", proxyHandler);
+ *
+ * export default app;
+ * ```
+ *
+ * @example Custom API key resolver
+ * ```typescript
+ * const proxyHandler = createRouteHandler({
+ *   resolveApiKey: async () => {
+ *     // Load from a secrets manager
+ *     return await getSecretFromVault("INFERENCE_API_KEY");
+ *   },
+ * });
+ * ```
+ */
+export declare function createRouteHandler({ resolveApiKey, }?: HonoProxyOptions): RouteHandler;
+export {};

package/dist/proxy/hono.js

@@ -0,0 +1,84 @@
+"use strict";
+/**
+ * Hono proxy handler for Inference.sh API
+ *
+ * Lightweight handler for Hono framework, ideal for edge/serverless deployments.
+ *
+ * @example
+ * ```typescript
+ * import { Hono } from "hono";
+ * import { createRouteHandler } from "@inferencesh/sdk/proxy/hono";
+ *
+ * const app = new Hono();
+ * const proxyHandler = createRouteHandler();
+ *
+ * app.all("/api/inference/proxy", proxyHandler);
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRouteHandler = createRouteHandler;
+const index_1 = require("./index");
+/**
+ * Creates a Hono route handler that proxies requests to the Inference.sh API.
+ *
+ * This is a drop-in handler for Hono applications that keeps API keys safe
+ * by running on your server.
+ *
+ * @param options - Proxy options
+ * @returns A Hono route handler function
+ *
+ * @example
+ * ```typescript
+ * import { Hono } from "hono";
+ * import { createRouteHandler } from "@inferencesh/sdk/proxy/hono";
+ *
+ * const app = new Hono();
+ * const proxyHandler = createRouteHandler();
+ *
+ * app.all("/api/inference/proxy", proxyHandler);
+ *
+ * export default app;
+ * ```
+ *
+ * @example Custom API key resolver
+ * ```typescript
+ * const proxyHandler = createRouteHandler({
+ *   resolveApiKey: async () => {
+ *     // Load from a secrets manager
+ *     return await getSecretFromVault("INFERENCE_API_KEY");
+ *   },
+ * });
+ * ```
+ */
+function createRouteHandler({ resolveApiKey = index_1.resolveApiKeyFromEnv, } = {}) {
+    const routeHandler = async (context) => {
+        const responseHeaders = new Headers();
+        return (0, index_1.handleRequest)({
+            id: "hono",
+            method: context.req.method,
+            respondWith: (status, data) => {
+                return new Response(JSON.stringify(data), {
+                    status,
+                    headers: {
+                        "Content-Type": "application/json",
+                        ...Object.fromEntries(responseHeaders.entries()),
+                    },
+                });
+            },
+            getHeaders: () => (0, index_1.fromHeaders)(context.req.raw.headers),
+            getHeader: (name) => context.req.header(name),
+            sendHeader: (name, value) => responseHeaders.set(name, value),
+            getRequestBody: async () => {
+                try {
+                    return await context.req.text();
+                }
+                catch {
+                    return undefined;
+                }
+            },
+            sendResponse: index_1.responsePassthrough,
+            resolveApiKey,
+        });
+    };
+    return routeHandler;
+}

package/dist/proxy/hono.mjs

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

package/dist/proxy/index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @inferencesh/sdk/proxy - Server-side proxy for Inference.sh API
+ *
+ * Protects API keys by proxying requests from frontend apps through your server.
+ * Supports Next.js (App & Page Router), Express, Hono, Remix, and SvelteKit.
+ */
+export declare const TARGET_URL_HEADER = "x-inf-target-url";
+export declare const DEFAULT_PROXY_ROUTE = "/api/inference/proxy";
+export type HeaderValue = string | string[] | undefined | null;
+/**
+ * The proxy behavior interface - a subset of request/response objects
+ * that abstracts framework-specific APIs.
+ */
+export interface ProxyBehavior<ResponseType> {
+    /** Framework identifier for logging/debugging */
+    id: string;
+    /** HTTP method */
+    method: string;
+    /** Return an error response */
+    respondWith(status: number, data: string | object): ResponseType;
+    /** Pass through a fetch Response */
+    sendResponse(response: Response): Promise<ResponseType>;
+    /** Get all headers as a record */
+    getHeaders(): Record<string, HeaderValue>;
+    /** Get a single header value */
+    getHeader(name: string): HeaderValue;
+    /** Set a response header */
+    sendHeader(name: string, value: string): void;
+    /** Get the request body as a string */
+    getRequestBody(): Promise<string | undefined>;
+    /** Optional custom API key resolver */
+    resolveApiKey?: () => Promise<string | undefined>;
+}
+/**
+ * Core proxy request handler.
+ *
+ * Proxies requests to the Inference.sh API with server-side credential injection.
+ * This handler is framework-agnostic and works via the ProxyBehavior interface.
+ *
+ * @param behavior - Framework-specific request/response handling
+ * @returns Promise that resolves when the request is handled
+ */
+export declare function handleRequest<ResponseType>(behavior: ProxyBehavior<ResponseType>): Promise<ResponseType>;
+/**
+ * Convert a Headers object to a plain record.
+ */
+export declare function fromHeaders(headers: Headers): Record<string, string | string[]>;
+/**
+ * Simple passthrough for Response objects (used in app router style handlers).
+ */
+export declare const responsePassthrough: (res: Response) => Promise<Response>;
+/**
+ * Resolve API key from environment (exposed for custom handlers).
+ */
+export declare const resolveApiKeyFromEnv: () => Promise<string | undefined>;

package/dist/proxy/index.js

@@ -0,0 +1,136 @@
+"use strict";
+/**
+ * @inferencesh/sdk/proxy - Server-side proxy for Inference.sh API
+ *
+ * Protects API keys by proxying requests from frontend apps through your server.
+ * Supports Next.js (App & Page Router), Express, Hono, Remix, and SvelteKit.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveApiKeyFromEnv = exports.responsePassthrough = exports.DEFAULT_PROXY_ROUTE = exports.TARGET_URL_HEADER = void 0;
+exports.handleRequest = handleRequest;
+exports.fromHeaders = fromHeaders;
+exports.TARGET_URL_HEADER = "x-inf-target-url";
+exports.DEFAULT_PROXY_ROUTE = "/api/inference/proxy";
+const INFERENCE_API_KEY = process.env.INFERENCE_API_KEY;
+// Only allow requests to inference.sh domains
+const INFERENCE_URL_REGEX = /(\.|^)inference\.sh$/;
+/**
+ * Utility to get a header value as string from potentially array value.
+ */
+function singleHeaderValue(value) {
+    if (!value)
+        return undefined;
+    if (Array.isArray(value))
+        return value[0];
+    return value;
+}
+/**
+ * Get the API key from environment variables.
+ */
+function getApiKey() {
+    return INFERENCE_API_KEY;
+}
+// Headers to exclude from response passthrough
+const EXCLUDED_HEADERS = ["content-length", "content-encoding"];
+/**
+ * Core proxy request handler.
+ *
+ * Proxies requests to the Inference.sh API with server-side credential injection.
+ * This handler is framework-agnostic and works via the ProxyBehavior interface.
+ *
+ * @param behavior - Framework-specific request/response handling
+ * @returns Promise that resolves when the request is handled
+ */
+async function handleRequest(behavior) {
+    // 1. Get and validate target URL
+    const targetUrl = singleHeaderValue(behavior.getHeader(exports.TARGET_URL_HEADER));
+    if (!targetUrl) {
+        return behavior.respondWith(400, {
+            error: `Missing the ${exports.TARGET_URL_HEADER} header`,
+        });
+    }
+    // 2. Validate target is an inference.sh domain
+    let urlHost;
+    try {
+        urlHost = new URL(targetUrl).host;
+    }
+    catch {
+        return behavior.respondWith(400, {
+            error: `Invalid ${exports.TARGET_URL_HEADER} header: not a valid URL`,
+        });
+    }
+    if (!INFERENCE_URL_REGEX.test(urlHost)) {
+        return behavior.respondWith(412, {
+            error: `Invalid ${exports.TARGET_URL_HEADER} header: must be an inference.sh domain`,
+        });
+    }
+    // 3. Get API key
+    const apiKey = behavior.resolveApiKey
+        ? await behavior.resolveApiKey()
+        : getApiKey();
+    if (!apiKey) {
+        return behavior.respondWith(401, {
+            error: "Missing INFERENCE_API_KEY environment variable",
+        });
+    }
+    // 4. Build forwarded headers (x-inf-* prefixed)
+    const forwardedHeaders = {};
+    const allHeaders = behavior.getHeaders();
+    for (const key of Object.keys(allHeaders)) {
+        if (key.toLowerCase().startsWith("x-inf-")) {
+            const value = singleHeaderValue(allHeaders[key]);
+            if (value) {
+                forwardedHeaders[key.toLowerCase()] = value;
+            }
+        }
+    }
+    // 5. Forward content-type if present
+    const contentType = singleHeaderValue(behavior.getHeader("content-type"));
+    // 6. Build proxy user agent
+    const proxyUserAgent = `@inferencesh/sdk-proxy/${behavior.id}`;
+    const userAgent = singleHeaderValue(behavior.getHeader("user-agent"));
+    // 7. Make the proxied request
+    const res = await fetch(targetUrl, {
+        method: behavior.method,
+        headers: {
+            ...forwardedHeaders,
+            authorization: singleHeaderValue(behavior.getHeader("authorization")) ??
+                `Bearer ${apiKey}`,
+            accept: "application/json",
+            "content-type": contentType || "application/json",
+            "user-agent": userAgent || proxyUserAgent,
+            "x-inf-client-proxy": proxyUserAgent,
+        },
+        body: behavior.method?.toUpperCase() === "GET"
+            ? undefined
+            : await behavior.getRequestBody(),
+    });
+    // 8. Copy response headers (excluding certain ones)
+    res.headers.forEach((value, key) => {
+        if (!EXCLUDED_HEADERS.includes(key.toLowerCase())) {
+            behavior.sendHeader(key, value);
+        }
+    });
+    // 9. Return the response
+    return behavior.sendResponse(res);
+}
+/**
+ * Convert a Headers object to a plain record.
+ */
+function fromHeaders(headers) {
+    const result = {};
+    headers.forEach((value, key) => {
+        result[key] = value;
+    });
+    return result;
+}
+/**
+ * Simple passthrough for Response objects (used in app router style handlers).
+ */
+const responsePassthrough = (res) => Promise.resolve(res);
+exports.responsePassthrough = responsePassthrough;
+/**
+ * Resolve API key from environment (exposed for custom handlers).
+ */
+const resolveApiKeyFromEnv = () => Promise.resolve(getApiKey());
+exports.resolveApiKeyFromEnv = resolveApiKeyFromEnv;

package/dist/proxy/index.mjs

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

package/dist/proxy/index.test.d.ts

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