@k9o/core 1.1.1 → 1.3.0

package/dist/types.d.ts

@@ -27,7 +27,7 @@
  *     canonical org subdomain `https://<orgSlug>.api.k9o.io`. Pass an explicit host to override — an explicit `<orgSlug>` subdomain,
  *     or a self-hosted / Sovereign-Control host, or a dev host — used as-is.
  *   - `fetch` — custom fetch implementation (defaults to global)
- *   - `retryConfig` — retry/backoff config (reserved; currently ships single-attempt)
+ *   - `retryConfig` — retry/backoff config for idempotent requests
  *   - `defaultHeaders` — headers merged into every request
  */
 type CreateClientOptions = {
@@ -40,8 +40,8 @@ type CreateClientOptions = {
     defaultHeaders?: Record<string, string> | undefined;
 };
 /**
- * Retry config. The type is reserved; the HTTP client currently makes a
- * single attempt per request and does not yet honour this config.
+ * Retry config. Only GET, HEAD, OPTIONS and DELETE are retried, on network failure and on
+ * HTTP 429, 502, 503 and 504.
  */
 type RetryConfig = {
     maxRetries: number;

package/dist/url-grammar.d.ts

@@ -2,12 +2,15 @@
  * URL grammar.
  *
  * Canonical URL shapes:
- *   - Member-plane (project-scoped): `<orgSlug>.api.k9o.io/@<projectSlug>/<sub-resource>/...`
- *   - Org-plane (org-scoped):        `<orgSlug>.api.k9o.io/<resource>/...`
- *   - Platform-plane (cross-org):    `api.k9o.io/discovery/...` + `api.k9o.io/auth/...` etc.
+ *   - Member-plane (project-scoped): `<orgSlug>.api.<apex>/@<projectSlug>/<sub-resource>/...`
+ *   - Org-plane (org-scoped):        `<orgSlug>.api.<apex>/<resource>/...`
+ *   - Platform-plane (cross-org):    `api.<apex>/discovery/...` + `api.<apex>/auth/...` etc.
+ *
+ * `<apex>` is whatever the deployment uses (public cloud, internal, air-gapped, localhost);
+ * the SDK takes the host from the baseUrl it is given and never matches it against a list.
  *
  * The `baseUrl` passed to `createClient` is the gateway host root —
- * scheme + host (+ optional port). Path-bearing baseUrls
+ * scheme + host (+ optional port) Path-bearing baseUrls
  * are rejected with `K9O_INVALID_BASE_URL`.
  *
  * The SDK constructs URLs by composing `baseUrl + path-from-builder`.
@@ -32,18 +35,31 @@
  *   - query / fragment (`https://api.k9o.io?x=1`)
  */
 declare function validateBaseUrl(baseUrl: string): string;
+/** The convenience default when the caller passes no baseUrl. A default value only: never used to parse a host. */
+declare const DEFAULT_BASE_URL = "https://api.k9o.io";
+/** The structure of a gateway API host, read from the host itself. */
+type ApiHost = {
+    /** First label of an org host (`acme` in `acme.api.corp.internal`); null for a platform host (`api.corp.internal`). */
+    orgSlug: string | null;
+    /** `api` or `api-staging`: the label that marks a gateway host. */
+    family: "api" | "api-staging";
+    /** 4-character region code when the host is regional (`api-de01`), else null (region-free). */
+    region: string | null;
+    /** Everything after the gateway label (`corp.internal`, `k9o.io`): the apex, never matched against a list. */
+    apex: string;
+};
+/**
+ * Read the org slug and region out of a gateway host without knowing its apex. The gateway label is `api` or
+ * `api-staging`, optionally followed by `-<rgn>`; the label before it is the org slug and whatever follows it is the
+ * apex. Returns null for any other shape (localhost, an IP, a single-label host, a host with no gateway label), which
+ * callers use exactly as given.
+ */
+declare function parseApiHost(host: string): ApiHost | null;
 /**
- * Resolve the effective baseUrl. `baseUrl` is
- * OPTIONAL — it defaults to the platform apex `https://api.k9o.io`. When the
- * (validated) host is a bare apex in `K9O_ORG_DERIVABLE_APEXES` and `orgSlug`
- * is supplied, the SDK composes the canonical org-subdomain wire root
- * `https://<orgSlug>.<apex>`. An explicit `<orgSlug>` subdomain, a
- * self-hosted / Sovereign host, or a dev host (anything not in that set)
- * passes through unchanged — `orgSlug` is intentionally NOT validated or
- * composed onto a non-apex host (fixed 2026-08-30: this used to silently
- * ignore `orgSlug` for `api-staging.k9o.io` too, not just genuine
- * self-hosted/custom hosts, since only the literal production apex string
- * was checked).
+ * Resolve the effective baseUrl. `baseUrl` is OPTIONAL: omitted, it defaults to {@link DEFAULT_BASE_URL} (the public
+ * cloud, a convenience only). When the (validated) host is a platform host (`api.<apex>` or `api-staging.<apex>`, any
+ * apex) and `orgSlug` is supplied, the canonical org host `<orgSlug>.<host>` is composed. Any other host (an org host
+ * already, an internal or air-gapped host, localhost) passes through unchanged; `orgSlug` is then only sent as a header.
  */
 declare function resolveBaseUrl(baseUrl: string | undefined, orgSlug?: string): string;
 declare function validateSlug(slug: string, kind: "org" | "project"): void;
@@ -72,4 +88,4 @@ declare function orgPath(resource: string): string;
  */
 declare function platformPath(resource: string): string;
 
-export { orgPath, platformPath, projectPath, resolveBaseUrl, validateBaseUrl, validateSlug };
+export { type ApiHost, DEFAULT_BASE_URL, orgPath, parseApiHost, platformPath, projectPath, resolveBaseUrl, validateBaseUrl, validateSlug };

package/dist/url-grammar.js

@@ -1,14 +1,18 @@
 import {
+  DEFAULT_BASE_URL,
   orgPath,
+  parseApiHost,
   platformPath,
   projectPath,
   resolveBaseUrl,
   validateBaseUrl,
   validateSlug
-} from "./chunk-2NDFTHUB.js";
+} from "./chunk-UL53GNYM.js";
 import "./chunk-LJZ45UA2.js";
 export {
+  DEFAULT_BASE_URL,
   orgPath,
+  parseApiHost,
   platformPath,
   projectPath,
   resolveBaseUrl,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k9o/core",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "description": "Kilimanjaro platform SDK — createClient + data-plane + projects + migrations + functions + studio (workflows/dashboards) + compute.llms + realtime subscriptions + KError + meta accessor sugar. Composes with @k9o/gate (auth) and @k9o/extensions (extension consumption).",
   "type": "module",
   "main": "./dist/index.js",
@@ -60,9 +60,9 @@
     "url": "https://github.com/k9o-dev/sdk-typescript"
   },
   "dependencies": {
-    "@k9o/gate": "1.1.1",
-    "@k9o/extensions": "1.1.1",
-    "@k9o/kibo": "1.1.1"
+    "@k9o/gate": "1.3.0",
+    "@k9o/extensions": "1.3.0",
+    "@k9o/kibo": "1.3.0"
   },
   "devDependencies": {
     "bun-types": "^1.1.0",

package/src/audit.ts

@@ -4,25 +4,21 @@
  * Backed by the gateway audit-log routes.
  *
  * Wire mapping:
- *   - `query({ since, until, type, actorId, targetKind, targetId, limit, cursor })`
+ *   - `query({ eventType, actorId, after, before, limit, cursor })`
  *     → GET /@<slug>/audit-log?...
  *
- * The endpoint accepts cursor-paginated reverse-chronological queries.
- * `type` is the audit-event namespace (e.g. `data.write.access.insert`,
- * `gate.signin.success`) per the event-name taxonomy +
- * `feedback_error_code_namespace_boundary_and_prefix.md` cement.
+ * Option names are the gateway's query parameter names. The endpoint
+ * accepts cursor-paginated reverse-chronological queries. `eventType` is
+ * the audit-event name (e.g. `data.write.access.insert`).
  *
- * Returns audit events with full context payload — actorId / targetKind /
- * targetId / payload / occurredAt / requestId / traceId.
+ * Returns audit events with full context payload.
  */
 
 import { request, type HttpClientConfig } from "./http.ts";
 import { projectPath } from "./url-grammar.ts";
 import type { Envelope } from "./envelope.ts";
 
-/**
- * Audit event record `_sys.audit_log` shape.
- */
+/** Audit event record. */
 export type AuditEvent = {
   id: string;
   /** Dotted namespace (e.g. `data.write.access.insert`). */
@@ -37,18 +33,14 @@ export type AuditEvent = {
 };
 
 export type AuditQueryOpts = {
-  /** ISO 8601 lower bound (inclusive). */
-  since?: string | undefined;
-  /** ISO 8601 upper bound (exclusive). */
-  until?: string | undefined;
-  /** Filter by event type (exact match; future cycles may add prefix-match). */
-  type?: string | undefined;
+  /** Filter by event type. */
+  eventType?: string | undefined;
   /** Filter by actor. */
   actorId?: string | undefined;
-  /** Filter by target resource kind. */
-  targetKind?: string | undefined;
-  /** Filter by target resource id. */
-  targetId?: string | undefined;
+  /** ISO 8601 lower bound: only events after this instant. */
+  after?: string | undefined;
+  /** ISO 8601 upper bound: only events before this instant. */
+  before?: string | undefined;
   /** Page size (per-tier max bounded server-side). */
   limit?: number | undefined;
   /** Cursor from prior response. */
@@ -68,9 +60,8 @@ export function makeAuditNamespace(config: HttpClientConfig) {
      * Query the audit log. Returns reverse-chronological events matching
      * all supplied filters (AND composition).
      *
-     * Per RBAC: requires `AUDIT_READER` role minimum; Custodian-
-     * class roles inherit. Project-level audit is project-scoped (this
-     * endpoint); platform-level audit is admin-only (separate surface).
+     * Requires the `AUDIT_READER` role at minimum. This endpoint is
+     * project-scoped.
      */
     async query(opts?: AuditQueryOpts): Promise<Envelope<ReadonlyArray<AuditEvent>>> {
       const slug = requireProjectSlug(config);
@@ -83,8 +74,7 @@ export function makeAuditNamespace(config: HttpClientConfig) {
 
     /**
      * Convenience: live-tail recent events. Currently single-shot read
-     * with `since` defaulted to "1 minute ago"; subscription-mode tail
-     * (SSE) lands when the streaming layer ships pattern.
+     * with `after` defaulted to "1 minute ago".
      */
     async tail(opts?: { sinceMinutes?: number; limit?: number }): Promise<Envelope<ReadonlyArray<AuditEvent>>> {
       const slug = requireProjectSlug(config);
@@ -93,7 +83,7 @@ export function makeAuditNamespace(config: HttpClientConfig) {
       return request(config, {
         method: "GET",
         path: projectPath(slug, "audit-log"),
-        query: { since, limit: opts?.limit ?? 100 },
+        query: { after: since, limit: opts?.limit ?? 100 },
       });
     },
   };

package/src/compute/llms.ts

@@ -1,20 +1,20 @@
 /**
  * Compute LLMs SDK — `client.compute.llms.*`.
  *
- * Compute LLMs registry. Curated 9-model library
- * + 4-endpoint family + per-model tier-gating.
+ * Compute LLMs registry: a curated model library, four endpoints and
+ * per-model tier gating.
  *
- * Wire mapping (project-plane;):
+ * Wire mapping (project-plane):
  *   - list()                    → GET  /@<slug>/compute/llms
  *   - read(modelId)             → GET  /@<slug>/compute/llms/<model-id>
  *   - invoke(modelId, ...)      → POST /@<slug>/compute/llms/<model-id>/invoke
  *   - invokeStream(modelId,...) → POST /@<slug>/compute/llms/<model-id>/invoke-stream (SSE)
  *
- * Per RBAC: list/read against all cohort roles; invoke +
- * invokeStream require PROJECT_AUTHOR or PROJECT_ADMIN (LLM cost gate).
- * Per, surfaces K9O_LLM_PROVIDER_UNAVAILABLE (503) +
- * reuses K9O_MODEL_NOT_DECLARED / K9O_TIER_FEATURE_GATED /
- * K9O_AGENT_INFERENCE_TIMEOUT.
+ * RBAC: list/read against all cohort roles; invoke + invokeStream require
+ * PROJECT_AUTHOR or PROJECT_ADMIN (LLM cost gate). External-provider models
+ * answer 501 `K9O_NOT_IMPLEMENTED` until the provider client is built.
+ * Surfaces K9O_LLM_PROVIDER_UNAVAILABLE (503), K9O_MODEL_NOT_DECLARED and
+ * K9O_TIER_FEATURE_GATED.
  */
 
 import { request, requestStream, type HttpClientConfig } from "../http.ts";
@@ -22,7 +22,7 @@ import { projectPath } from "../url-grammar.ts";
 import type { Envelope } from "../envelope.ts";
 import { parseSseStream } from "../internal/sse.ts";
 
-/** Curated 9-model closed enum at v2 launch (extensible v2.x). */
+/** Curated model ids. */
 export type LLMModelId =
   | "mistral-7b"
   | "mistral-8x7b"
@@ -37,7 +37,7 @@ export type LLMModelId =
 export type LLMProviderClass = "self-hosted" | "external";
 export type LLMModality = "text-completion" | "text-completion+tool-use" | "embeddings";
 
-/** Model metadata + (cost transparency). */
+/** Model metadata with per-model cost. */
 export type LLMModel = {
   id: LLMModelId;
   providerClass: LLMProviderClass;
@@ -46,35 +46,54 @@ export type LLMModel = {
   tierGate: string;
   contextWindow: number;
   capabilities: ReadonlyArray<string>;
-  /** Per-model token cost for cost-transparency. */
+  /** Per-model token cost. */
   costPerMillionInputTokens: number;
   costPerMillionOutputTokens: number;
 };
 
-/** Inference parameters (passed through to provider). */
+/** Inference parameters the route reads; sent flat in the request body. */
 export type LLMInvokeParams = {
+  /** 1 to 32000. */
   maxTokens?: number;
+  /** 0 to 2. */
   temperature?: number;
-  topP?: number;
-  stop?: ReadonlyArray<string>;
-  [key: string]: unknown;
+  /** Free-form usage label recorded with the call. */
+  usageType?: string;
+};
+
+/** Token counts the model server reported for a call. */
+export type LLMUsage = {
+  promptTokens: number;
+  completionTokens: number;
+  totalTokens: number;
 };
 
-/** Synchronous inference response `/invoke`. */
+/** Synchronous inference response from `/invoke`. */
 export type LLMResponse = {
-  completion: string;
-  tokensUsed: number;
-  latencyMs: number;
+  modelId: string;
+  /** The generated text. */
+  content: string;
+  finishReason: string | null;
+  usage: LLMUsage;
+  usageType: string;
 };
 
-/** Streaming chunk `/invoke-stream` (SSE per-token). */
+/**
+ * One chunk of the `/invoke-stream` response: the model server's OpenAI-style
+ * chat-completion chunk, passed through unchanged. Read incremental text from
+ * `choices[0].delta.content`; the final chunk may carry `usage`.
+ */
 export type LLMStreamChunk = {
-  /** Incremental completion delta. */
-  delta: string;
-  /** True on the terminal chunk. */
-  done?: boolean;
-  /** Populated on terminal chunk. */
-  tokensUsed?: number;
+  id?: string;
+  object?: string;
+  model?: string;
+  choices?: ReadonlyArray<{
+    index?: number;
+    delta?: { role?: string; content?: string | null };
+    finish_reason?: string | null;
+  }>;
+  usage?: { prompt_tokens?: number; completion_tokens?: number; total_tokens?: number } | null;
+  [key: string]: unknown;
 };
 
 export type LLMInvokeInput = {
@@ -82,7 +101,11 @@ export type LLMInvokeInput = {
   params?: LLMInvokeParams;
 };
 
-/** Error code coined in (others reused). */
+function invokeBody(input: LLMInvokeInput): Record<string, unknown> {
+  return { prompt: input.prompt, ...input.params };
+}
+
+/** Error codes specific to LLM calls. */
 export const LLM_ERROR_CODES = {
   PROVIDER_UNAVAILABLE: "K9O_LLM_PROVIDER_UNAVAILABLE",
 } as const;
@@ -120,24 +143,23 @@ export function makeLlmsNamespace(config: HttpClientConfig) {
       return request(config, {
         method: "POST",
         path: projectPath(slug, `compute/llms/${encodeURIComponent(modelId)}/invoke`),
-        body: { prompt: input.prompt, params: input.params },
+        body: invokeBody(input),
       });
     },
 
     /**
      * POST /@<slug>/compute/llms/<model-id>/invoke-stream — streaming
-     * inference (SSE; per-token delta for low-latency UX).
+     * inference (SSE; the model server's OpenAI-style chunks).
      * Returns an async iterable of `LLMStreamChunk` — caller writes
      * `for await (const chunk of client.compute.llms.invokeStream(...))`.
-     * The SDK handles SSE framing internally per
-     * `feedback_sdk_abstracted_primitive_default_to_richer_interaction.md`.
+     * The SDK handles SSE framing internally.
      */
     async *invokeStream(modelId: LLMModelId | string, input: LLMInvokeInput): AsyncGenerator<LLMStreamChunk, void, void> {
       const slug = requireProjectSlug(config);
       const response = await requestStream(config, {
         method: "POST",
         path: projectPath(slug, `compute/llms/${encodeURIComponent(modelId)}/invoke-stream`),
-        body: { prompt: input.prompt, params: input.params },
+        body: invokeBody(input),
         accept: "text/event-stream",
       });
       // requestStream guarantees a non-null body on 2xx.
@@ -148,7 +170,7 @@ export function makeLlmsNamespace(config: HttpClientConfig) {
 
 export function makeComputeNamespace(config: HttpClientConfig) {
   return {
-    /** LLM registry + inference — `client.compute.llms.*`. */
+    /** LLM registry + inference — `client.compute.llms.*` . */
     llms: makeLlmsNamespace(config),
   };
 }

package/src/functions.ts

@@ -4,15 +4,14 @@
  * Backed by the gateway functions and invoke routes.
  *
  * Wire mapping:
- *   - `deploy({ name, runtime, code, ... })`  → POST   /@<slug>/functions
+ *   - `deploy({ name, runtime, tier, artifactKey, version })` → POST /@<slug>/functions
  *   - `list()`                                → GET    /@<slug>/functions
  *   - `get(name)`                             → GET    /@<slug>/functions/<name>
  *   - `delete(name)`                          → DELETE /@<slug>/functions/<name>
  *   - `invoke(name, payload)`                 → POST   /@<slug>/functions/<name>/invoke
  *
- * Per: deploy requires PROJECT_ADMIN; invoke authority is per
- * function manifest. Per: deploy returns 202 with status
- * `deploying`; the function is ready when status flips to `active`.
+ * Deploy requires PROJECT_ADMIN and returns with status `deploying`; the
+ * function is ready when status flips to `active`.
  */
 
 import { request, type HttpClientConfig } from "./http.ts";
@@ -26,23 +25,45 @@ export type FunctionRecord = {
   /** `fn_<base62>`. */
   id: string;
   name: string;
-  runtime: "wasm" | "bun" | "node";
-  status: "deploying" | "active" | "retired" | "failed";
-  tier: "low" | "medium" | "high";
+  runtime: DeployFunctionInput["runtime"];
+  tier: "gateway" | "sandbox";
+  entryPoint: string;
+  version: string;
+  status: "deploying" | "active" | "error" | "retired";
+  /** Who manages the function: a developer deploy, or an extension (`extension:<id>`). */
+  source: string;
+  description: string | null;
   createdAt: string;
-  updatedAt: string | null;
+  deployedAt: string | null;
+  retiredAt: string | null;
+  errorDetail: string | null;
 };
 
 /**
- * Deploy input. The `code` field is the runtime bundle (base64-encoded
- * WASM or JS source).
+ * Deploy input. The function's bytes are uploaded first (the gateway's
+ * function-artifact upload returns the `artifactKey`); deploy references
+ * that artifact.
  */
 export type DeployFunctionInput = {
+  /** Function name (1 to 128 characters). */
   name: string;
-  runtime: "wasm" | "bun" | "node";
-  code: string;
-  tier?: "low" | "medium" | "high";
-  config?: Record<string, unknown>;
+  runtime: "bun" | "python" | "go" | "java" | "kotlin" | "dotnet" | "swift" | "php" | "ruby" | "rust" | "tinygo" | "zig" | "assemblyscript";
+  /** `gateway` runs WebAssembly in the gateway; `sandbox` runs an OCI image archive. */
+  tier: "gateway" | "sandbox";
+  /** Content-addressed key of the uploaded artifact. */
+  artifactKey: string;
+  /** Version label for this deploy (1 to 64 characters). */
+  version: string;
+  description?: string | undefined;
+};
+
+/** Optional invoke controls; property names are the gateway's. */
+export type InvokeFunctionOptions = {
+  /** Run asynchronously instead of waiting for the result. */
+  background?: boolean | undefined;
+  delegation?: { token: string; invokeSessionId?: string | undefined } | undefined;
+  onBehalfOf?: string | undefined;
+  confinedTo?: string | undefined;
 };
 
 function requireProjectSlug(config: HttpClientConfig): string {
@@ -54,7 +75,22 @@ function requireProjectSlug(config: HttpClientConfig): string {
 
 export function makeFunctionsNamespace(config: HttpClientConfig) {
   return {
-    /** Deploy or redeploy a function. Returns the function record with status. */
+    /**
+     * Upload a function artifact and get back its content-addressed `artifactKey`, to pass to `deploy`.
+     * `POST /@<projectSlug>/functions/artifacts` with the raw bytes: a WebAssembly module for the gateway tier (up to
+     * 16 MiB) or an OCI image archive for the sandbox tier (up to 256 MiB). Uploading the same bytes again returns the same key.
+     */
+    async uploadArtifact(bytes: Uint8Array | ArrayBuffer | Blob, kind: "wasm" | "tar"): Promise<Envelope<{ artifactKey: string }>> {
+      const slug = requireProjectSlug(config);
+      return request(config, {
+        method: "POST",
+        path: projectPath(slug, "functions/artifacts"),
+        rawBody: bytes,
+        headers: { "content-type": kind === "wasm" ? "application/wasm" : "application/x-tar" },
+      });
+    },
+
+    /** Deploy or redeploy a function from an uploaded artifact. Returns the function record with status. */
     async deploy(input: DeployFunctionInput): Promise<Envelope<FunctionRecord>> {
       const slug = requireProjectSlug(config);
       return request(config, {
@@ -65,7 +101,7 @@ export function makeFunctionsNamespace(config: HttpClientConfig) {
     },
 
     /** List deployed functions (cursor pagination). */
-    async list(opts?: { limit?: number; cursor?: string; status?: FunctionRecord["status"] }): Promise<Envelope<ReadonlyArray<FunctionRecord>>> {
+    async list(opts?: { limit?: number; cursor?: string; status?: FunctionRecord["status"]; tier?: FunctionRecord["tier"]; source?: string }): Promise<Envelope<ReadonlyArray<FunctionRecord>>> {
       const slug = requireProjectSlug(config);
       return request(config, {
         method: "GET",
@@ -83,8 +119,8 @@ export function makeFunctionsNamespace(config: HttpClientConfig) {
       });
     },
 
-    /** Retire a function. Returns confirmation; the function name enters a 24h cooldown. */
-    async delete(name: string): Promise<Envelope<{ retired: boolean; cooldownUntil: string }>> {
+    /** Retire a function. Returns the retired record; the function name enters a 24h cooldown. */
+    async delete(name: string): Promise<Envelope<FunctionRecord>> {
       const slug = requireProjectSlug(config);
       return request(config, {
         method: "DELETE",
@@ -93,21 +129,18 @@ export function makeFunctionsNamespace(config: HttpClientConfig) {
     },
 
     /**
-     * Invoke a function. The `payload` is passed to the function runtime
-     * verbatim; the gateway returns whatever the function returns wrapped
-     * in the standard envelope.
-     *
-     * Per: invoke authority is per-function (declared in the
-     * function manifest). Per: streaming responses use the
-     * subscription/async-iterator pattern; this method covers the
+     * Invoke a function. The `payload` is sent as the `payload` field of
+     * the request body and passed to the function runtime verbatim; the
+     * gateway returns whatever the function returns wrapped in the standard
+     * envelope. Invoke authority is per function. This method covers the
      * request-response variant only.
      */
-    async invoke<TResult = unknown, TPayload = unknown>(name: string, payload: TPayload): Promise<Envelope<TResult>> {
+    async invoke<TResult = unknown, TPayload = unknown>(name: string, payload?: TPayload, options?: InvokeFunctionOptions): Promise<Envelope<TResult>> {
       const slug = requireProjectSlug(config);
       return request(config, {
         method: "POST",
         path: projectPath(slug, `functions/${encodeURIComponent(name)}/invoke`),
-        body: payload,
+        body: { ...(payload !== undefined ? { payload } : {}), ...(options ?? {}) },
       });
     },
   };

package/src/http.ts

@@ -53,6 +53,8 @@ export type RequestInit = {
   method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
   path: string;
   body?: unknown;
+  /** Send these bytes as the body, unchanged, with the `content-type` given in `headers` (for binary routes). Wins over `body`. */
+  rawBody?: Uint8Array | ArrayBuffer | Blob | undefined;
   /** Per-call bearer override (wins over config.apiKey). */
   bearerToken?: string | undefined;
   /** Per-call additional headers (merged with config.defaultHeaders + auth). */
@@ -109,7 +111,9 @@ export async function requestOnce<T>(
     method: init.method,
     headers,
   };
-  if (init.body !== undefined) {
+  if (init.rawBody !== undefined) {
+    requestInit["body"] = init.rawBody;
+  } else if (init.body !== undefined) {
     if (typeof FormData !== "undefined" && init.body instanceof FormData) {
       // Multipart: the runtime sets the content type (with its boundary); never JSON-encode it.
       requestInit["body"] = init.body;