@inferencesh/sdk 0.21.0 → 0.22.0

package/dist/proxy/index.d.ts

@@ -4,11 +4,18 @@
  * Protects API keys by proxying requests from frontend apps through your server.
  * Supports Next.js (App & Page Router), Express, Hono, Remix, and SvelteKit.
  *
+ * The proxy forwards only what a frontend needs to run things (app runs,
+ * agent chats, and reading or streaming their task or chat; see
+ * PROXY_ENDPOINTS) and refuses every other API call with 403.
+ *
  * @example Next.js App Router
  * ```typescript
  * // app/api/inference/proxy/route.ts
  * import { createHandler } from "@inferencesh/sdk/proxy/nextjs";
- * export const { GET, POST, PUT } = createHandler();
+ * export const { GET, POST } = createHandler({
+ *     allowedEndpoints: ["my-team/support-agent"],
+ *     isAuthenticated: async (req) => Boolean(req.cookies.get("session")),
+ * });
  * ```
  */
 /** Header name for target URL */
@@ -17,15 +24,24 @@ export declare const INF_TARGET_HEADER = "x-inf-target-url";
 export declare const INF_TARGET_PARAM = "__inf_target";
 /** Default proxy route path */
 export declare const PROXY_PATH = "/api/inference/proxy";
+/** The API the proxy forwards to unless `apiUrl` or `apiBaseUrl` says otherwise. */
+export declare const DEFAULT_API_URL = "https://api.inference.sh";
+/**
+ * Default `maxUploadBytes`: 100 MiB, well under the API's own per-file limit
+ * (storage.max_upload_bytes, 5 GiB by default).
+ */
+export declare const DEFAULT_MAX_UPLOAD_BYTES: number;
 /** Header value from various HTTP libraries */
 export type HttpHeaderValue = string | string[] | undefined | null;
 /**
  * Framework adapter interface for proxy handlers.
  * Implement this to support a new framework.
  */
-export interface ProxyAdapter<T> {
+export interface ProxyAdapter<T, R = unknown> {
     /** Framework name for user-agent */
     framework: string;
+    /** The framework's request, handed to `isAuthenticated` */
+    request?: R;
     /** HTTP method of the request */
     method: string;
     /** Get request body as string */
@@ -44,17 +60,159 @@ export interface ProxyAdapter<T> {
     respond: (response: Response) => Promise<T>;
     /** Custom API key resolver (optional) */
     apiKey?: () => Promise<string | undefined>;
+    /**
+     * Aborts the upstream request (optional). Adapters that copy the
+     * upstream body themselves abort it when their client disconnects, so a
+     * stream nobody reads any more (GET /chats/{id}/stream never ends on its
+     * own) does not stay open.
+     */
+    signal?: AbortSignal;
 }
 /**
  * Proxy handler options.
  */
-export interface ProxyOptions {
+export interface ProxyOptions<R = unknown> {
     /** Custom API key (defaults to INFERENCE_API_KEY env var) */
     apiKey?: string;
-    /** Override API base URL (defaults to INFERENCE_API_BASE_URL env var) */
+    /**
+     * The API the frontend's SDK client calls (its `baseUrl`), default
+     * https://api.inference.sh. The proxy attaches the key only to requests
+     * for this origin (or an `allowedDomains` host); a target on any other
+     * host, other inference.sh hosts included, is refused with 412.
+     */
+    apiUrl?: string;
+    /**
+     * Rewrite every target to this API base (defaults to the
+     * INFERENCE_API_BASE_URL env var). When set, it is also the only origin
+     * the proxy forwards to.
+     */
     apiBaseUrl?: string;
-    /** Allow requests to additional domains (besides *.inference.sh) */
+    /**
+     * Extra target hosts, besides the API's. Each pattern must match the
+     * whole host (`host:port` when the target names a port).
+     */
     allowedDomains?: RegExp[];
+    /**
+     * Largest file, in bytes, a visitor may upload through the proxy
+     * (default 100 MiB). `POST /files` declares each file's size and the API
+     * binds the upload URL to it; the bytes then go straight to storage and
+     * count against the API key owner's storage quota. One file per request.
+     */
+    maxUploadBytes?: number;
+    /**
+     * Apps and agents visitors may run, as `namespace/name` globs: "ana/helper",
+     * or "ana/*" for all of a namespace. Unset or empty allows every app and
+     * agent the API key can run.
+     *
+     * Checked where a request names the app or agent: a new app run, a new
+     * chat or agent message, a chat handed to another agent, an agent's info.
+     * Requests about an existing task or chat name it by id, and the proxy
+     * cannot tell which app or agent that is: whoever holds a task or chat id
+     * can read and stream it, cancel or stop it, and send messages in the
+     * chat (which run the chat's agent). All visitors share one key, so the
+     * id is the only boundary between them. When set, ad-hoc agent configs
+     * (`agent_config`) and runs by `app_id`/`version_id` are refused.
+     */
+    allowedEndpoints?: string[];
+    /**
+     * Match `allowedEndpoints` entries against the whole ref, version and
+     * function included, instead of as `namespace/name` globs: the entry
+     * "ana/helper@v2" lets only that exact ref through, and "ana/helper"
+     * only the unversioned ref. Entries are refs, without `*`.
+     */
+    exactRefs?: boolean;
+    /**
+     * The calls to forward, a subset of PROXY_ENDPOINTS (default: all of
+     * them). Entries must come from PROXY_ENDPOINTS or `pickProxyEndpoint`,
+     * which can narrow one further but never widen it; anything else
+     * refuses every request with 500.
+     */
+    endpoints?: readonly ProxyEndpoint[];
+    /**
+     * Decides whether a request may use the API key, e.g. by checking your
+     * session. Requests it answers false for are refused with 401. Receives
+     * the framework's request (NextRequest, Express Request, Hono Context, ...).
+     */
+    isAuthenticated?: (request: R) => boolean | Promise<boolean>;
+    /**
+     * Without `isAuthenticated`, whether anyone may use the proxy (default
+     * true, for compatibility). Set it to false to require `isAuthenticated`:
+     * with neither, every request is refused.
+     */
+    allowUnauthorizedRequests?: boolean;
+}
+/** Where a request names the app or agent it runs. */
+type RefSource = 
+/** Body field naming the app or agent, and fields that would name one another way. */
+{
+    body: string;
+    refuse: string[];
+}
+/** `/agents/{namespace}/{name}` in the path. */
+ | {
+    path: true;
+};
+/** One call of the API's proxy manifest (src/proxy/endpoints.json). */
+export interface ProxyManifestEndpoint {
+    method: string;
+    /** API path template: `{namespace}`/`{name}` are an agent ref, every other `{…}` an id. */
+    path: string;
+    purpose: string;
+    /** Scopes the call takes: what the site's API key must hold (the manifest's preset grants them all). */
+    scopes: string[];
+}
+export interface ProxyEndpoint {
+    method: "GET" | "POST";
+    /** The manifest's route, "METHOD /path/{id}" (what pickProxyEndpoint takes). */
+    route: string;
+    /** API path, matched whole. */
+    path: RegExp;
+    /** What the endpoint is for (used in docs and tests). */
+    purpose: string;
+    /** Scopes the call takes, from the manifest. */
+    scopes: readonly string[];
+    /** Set when the request names an app or agent: checked against allowedEndpoints. */
+    ref?: RefSource;
+    /** Set when only these body fields may be sent. */
+    onlyFields?: string[];
+    /** Further checks of the body (a JSON object), given the proxy's limits. */
+    validate?: (body: Record<string, unknown>, limits: ProxyLimits) => PolicyRefusal | undefined;
+}
+/** Limits from the proxy options, handed to endpoint checks. */
+export interface ProxyLimits {
+    maxUploadBytes: number;
+}
+/** What the proxy checks of a call's request, beyond the manifest. */
+type EndpointRules = Pick<ProxyEndpoint, "ref" | "onlyFields" | "validate">;
+/**
+ * The proxy's own checks, by manifest route. A route here that the manifest
+ * does not list is never forwarded (a test keeps the two in step).
+ */
+export declare const PROXY_ENDPOINT_RULES: Readonly<Record<string, EndpointRules>>;
+/** The API's proxy manifest as shipped in this package. */
+export declare const PROXY_MANIFEST: {
+    readonly preset: string;
+    readonly endpoints: readonly ProxyManifestEndpoint[];
+};
+/**
+ * The calls the proxy forwards: exactly the manifest's, with the proxy's
+ * request checks. Everything else is refused with 403.
+ */
+export declare const PROXY_ENDPOINTS: readonly ProxyEndpoint[];
+/** The PROXY_ENDPOINTS entry for a request, or undefined when the proxy does not forward it. */
+export declare function matchProxyEndpoint(method: string, pathname: string, endpoints?: readonly ProxyEndpoint[]): ProxyEndpoint | undefined;
+/**
+ * The PROXY_ENDPOINTS entry for `route` ("METHOD /path", with `{id}`,
+ * `{namespace}` and `{name}` placeholders, e.g. "POST /chats/{id}/messages"),
+ * optionally narrowed: `onlyFields` must be a subset of the entry's own,
+ * and `validate` runs after the entry's own check. For the `endpoints`
+ * option. Throws when the proxy does not forward the route.
+ */
+export declare function pickProxyEndpoint(route: string, narrow?: Pick<ProxyEndpoint, "onlyFields" | "validate">): ProxyEndpoint;
+/** A refusal: the HTTP status and the message sent back. */
+export interface PolicyRefusal {
+    status: number;
+    error: string;
 }
 /**
  * Process a proxied request to the Inference.sh API.
@@ -66,7 +224,7 @@ export interface ProxyOptions {
  * @param options - Optional configuration
  * @returns Promise resolving to the framework's response type
  */
-export declare function processProxyRequest<T>(adapter: ProxyAdapter<T>, options?: ProxyOptions): Promise<T>;
+export declare function processProxyRequest<T, R = unknown>(adapter: ProxyAdapter<T, R>, options?: ProxyOptions<R>): Promise<T>;
 /**
  * Convert Headers object to plain record.
  */
@@ -95,3 +253,4 @@ export declare const fromHeaders: typeof headersToRecord;
 export declare const responsePassthrough: (res: Response) => Promise<Response>;
 /** @deprecated Use getEnvApiKey */
 export declare const resolveApiKeyFromEnv: () => Promise<string | undefined>;
+export {};