@intfunc/sdk

Official TypeScript client for the Intelligent Functions API. An intelligent function is a stateless, versioned function backed by a single LLM call. The function stores only its instruction; you declare the input and output types in your own code with the SDK's built-in schema builder, ift.

import { IntelligentFunctions, ift } from "@intfunc/sdk";

const client = new IntelligentFunctions();

const summarize = client.fn("blog/summarize", {
  input: ift.Object({ text: ift.String() }),
  output: ift.Object({ summary: ift.String() }),
});

const { summary } = await summarize({ text: article }); // fully typed

Install

npm install @intfunc/sdk

That's the only dependency — the schema builder is bundled, no Zod or other library required. Requires a runtime with a global fetch (Node 18+, Bun, Deno, Cloudflare Workers, or the browser). To use a custom implementation, pass options.fetch.

How it works

An intelligent function's I/O contract lives in your code, not in the database:

• output is sent with each call. The server injects it into the prompt and validates the model's response against it (retrying on a mismatch), so you get back a value that provably matches the schema. Its type is inferred, so the result is fully typed. Omit it to get the model's raw text (string).
• input is checked at compile time and validated at runtime before the request is sent (a bad input throws InputValidationError locally). The data itself is passed to the model, which infers its meaning.

Defining types with ift

ift is the SDK's schema builder. Each schema is simultaneously a TypeScript type, a runtime validator, and a JSON Schema — so one declaration drives typing, input validation, and the output contract.

import { ift, type Static } from "@intfunc/sdk";

const Sentiment = ift.Object({
  label: ift.Union([ift.Literal("positive"), ift.Literal("negative"), ift.Literal("neutral")]),
  score: ift.Number(),
});

// Recover the static type when you need to name it:
type Sentiment = Static<typeof Sentiment>; // { label: "positive" | "negative" | "neutral"; score: number }

Common builders: ift.Object, ift.String, ift.Number, ift.Integer, ift.Boolean, ift.Array, ift.Union, ift.Literal, ift.Optional. (ift is a re-export of TypeBox's Type under an SDK-owned name, so its full builder API is available.)

Quickstart

import { IntelligentFunctions, ift } from "@intfunc/sdk";

// Reads INTFUNC_API_KEY (and optional INTFUNC_BASE_URL) from the environment.
const client = new IntelligentFunctions();

// Bind a "projectSlug/functionSlug" key to a reusable, typed handle.
const sentiment = client.fn("blog/sentiment", {
  input: ift.Object({ text: ift.String() }),
  output: ift.Object({
    label: ift.Union([ift.Literal("positive"), ift.Literal("negative"), ift.Literal("neutral")]),
    score: ift.Number(),
  }),
});

// Call it like a local async function — you get just the typed output.
const { label, score } = await sentiment({ text: "I love this!" });

Configuration

new IntelligentFunctions(options?) — every option is optional and falls back to an environment variable or a default.

| Option | Env var | Default | Description | | ------------ | ------------------- | -------------------------- | -------------------------------------------------- | | apiKey | INTFUNC_API_KEY | — | Project API key issued from the console. | | baseUrl | INTFUNC_BASE_URL | https://api.intfunc.com | API base URL. | | timeout | — | 120000 (ms) | Per-request timeout; aborts and retries if exceeded. | | maxRetries | — | 2 | Retries on network errors, 408, 429, and 5xx. | | fetch | — | globalThis.fetch | Custom fetch implementation. |

const client = new IntelligentFunctions({
  apiKey: "if_live_...",
  timeout: 60_000,
  maxRetries: 3,
});

An API key is scoped to a single project, so a handle can only invoke functions in that key's own project — a mismatched projectSlug returns FunctionNotFoundError.

Calling functions

Handles (recommended)

const classify = client.fn("support/classify", {
  input: ift.Object({ text: ift.String() }),
  output: ift.Object({ category: ift.String() }),
});

await classify({ text });            // -> { category }            (just the output)
await classify.run({ text });        // -> { output, provider, model, version, usage, runId }
const v3 = classify.pin(3);          // a handle locked to version 3 (types preserved)
await v3({ text });                  // always runs version 3

• handle(input, options?) — returns the output only. The 90% case.
• handle.run(input, options?) — returns the full envelope with token usage, the resolved version, and the captured dataset runId.
• handle.setReferenceOutput(runId, reference, options?) — annotate a past run with its known-correct output; validated against the output schema (see Reference outputs).
• handle.pin(version) — a new handle bound to a fixed version. Without a pin, calls always use the latest published version.

The input and output schemas are optional and independent:

// Raw text out — no output schema:
const tldr = client.fn("blog/tldr", { input: ift.Object({ text: ift.String() }) });
const text: string = await tldr({ text: article });

// No input schema — input is `unknown` (still passed to the model):
const summarize = client.fn("blog/summarize", { output: ift.Object({ summary: ift.String() }) });

Per-call options:

const controller = new AbortController();
await classify({ text }, {
  version: 2,               // one-off version override
  timeout: 30_000,          // override the client timeout for this call
  signal: controller.signal // cancel in flight
});

Direct method

If you prefer not to bind a handle:

const result = await client.runFunction(
  "support", "classify", { text },
  { version: 2, output: ift.Object({ category: ift.String() }) },
);
result.output; // typed from the output schema

Unlike fn, runFunction does not validate input; it is the low-level escape hatch.

Reference outputs

Every captured run can be annotated with a reference output — the known-correct "true answer" for that call. It's the dataset's supervision signal: it pairs an input with the output it should have produced, independent of what the model actually returned. Use it to build eval/training sets or to grade a new function version against past runs.

Grab the runId from a .run() result, then set the reference later — once you know (or a human labels) the correct answer:

const { runId, output } = await sentiment.run({ text: "I love this!" });

// ...later, once the true answer is known:
await sentiment.setReferenceOutput(runId, { label: "positive", score: 1 });

The reference is validated against the handle's output schema client-side, exactly the way input is checked — a mismatch throws ReferenceOutputValidationError before any request is sent. Pass null to clear a previously set reference.

await sentiment.setReferenceOutput(runId, { label: "yes", score: 1 });
// throws ReferenceOutputValidationError: "positive" | "negative" | "neutral" expected

await sentiment.setReferenceOutput(runId, null); // clears it

Two caveats:

• A runId exists only if the run was actually captured (the function's captureEnabled is on and it wasn't sampled out). Setting a reference on an uncaptured run throws FunctionNotFoundError (404).
• The run must belong to your API key's project.

The low-level client.setReferenceOutput(runId, reference) does the same PATCH without the schema check — the escape hatch, mirroring runFunction.

Errors

Input is validated client-side and throws before any request is sent. Everything else is an ApiError (or a subclass) mapped from the HTTP response:

import {
  InputValidationError,           // client-side — input didn't match the declared input schema (no request sent)
  ReferenceOutputValidationError, // client-side — reference output didn't match the output schema (no request sent)
  AuthError,                      // 401 — missing/invalid/revoked API key
  FunctionNotFoundError,          // 404 — no such function/run (or wrong project)
  OutputValidationError,          // 422 — the model never produced output matching the schema (after retries)
  FunctionRunError,               // 502 — the underlying model call failed
  ApiError,                       // base — any other status (has `.status`, `.body`)
} from "@intfunc/sdk";

try {
  await sentiment({ text });
} catch (err) {
  if (err instanceof InputValidationError) {
    // fix the input — this never left the process
  } else if (err instanceof OutputValidationError) {
    // the model couldn't satisfy the output schema
  } else if (err instanceof FunctionRunError) {
    // transient model failure — surface or retry manually
  } else if (err instanceof ApiError) {
    console.error(err.status, err.message, err.body);
  }
}

InputValidationError and ReferenceOutputValidationError are the only ones that are not an ApiError — they have no .status because they originate locally, not from the server.

Retries & timeouts

Requests are retried automatically with exponential backoff (plus jitter, and honoring a Retry-After header) on network errors, timeouts, 408, 429, and 5xx responses — up to maxRetries times. A caller-initiated AbortSignal is never retried. Set maxRetries: 0 to disable.

Managing functions

A function stores only its instruction (prompt) — the I/O contract is supplied per call, so there are no schemas here:

await client.listFunctions({ project: "blog" });
await client.getFunction("blog", "summarize", { version: 2 });
await client.createFunction({
  projectId: "prj_...",
  name: "Summarize",
  provider: "anthropic",
  model: "claude-sonnet-5",
  prompt: "Summarize the input article in one sentence.",
});

Creating a function with an existing slug publishes the next version of it.

API reference

| Member | Returns | | --------------------------------------------------------- | ------------------------------------ | | fn(key, { input?, output?, version? }) | FunctionHandle<In, Out> (typed from the schemas) | | runFunction(project, fn, input, { output?, ...options })| RunIFunctionResult<T> | | setReferenceOutput(runId, reference, options?) | Promise<void> (unvalidated escape hatch) | | getFunction(project, fn, { version? }) | IFunction | | listFunctions({ project? }) | IFunction[] | | createFunction(input) | IFunction | | health() | { status: string } |

Also exported: ift (schema builder), Static / TSchema (schema types), and the error classes above.