better-supabase 0.8.0 → 0.9.0

package/dist/jws-milwSg7E.js

@@ -0,0 +1,191 @@
+import { n as isRecord } from "./guards-6F2bCtQR.js";
+import { a as toBase64Url, r as fromBase64 } from "./base64-BmeCBgGo.js";
+//#region src/core/jws.ts
+const encoder = /* @__PURE__ */ new TextEncoder();
+const decoder = /* @__PURE__ */ new TextDecoder();
+const EC = {
+	name: "ECDSA",
+	namedCurve: "P-256"
+};
+/** The members WebCrypto imports, without `kid`, `alg` and other extras. */
+function keyMaterial(jwk, alg, withPrivate) {
+	const key = publicJwk(jwk);
+	return {
+		kty: key.kty,
+		crv: String(key.crv),
+		x: String(key.x),
+		...alg === "ES256" ? { y: String(key.y) } : {},
+		...withPrivate ? { d: String(jwk.d) } : {}
+	};
+}
+const importParams = (alg) => alg === "Ed25519" ? { name: "Ed25519" } : EC;
+const signParams = (alg) => alg === "Ed25519" ? { name: "Ed25519" } : {
+	name: "ECDSA",
+	hash: "SHA-256"
+};
+/** The key type behind a JWS `alg`, or undefined for one this module doesn't verify. */
+function keyAlgorithmOf(alg) {
+	if (alg === "ES256" || alg === "RS256" || alg === "PS256") return alg;
+	if (alg === "EdDSA" || alg === "Ed25519") return "Ed25519";
+}
+/** RFC 7518 section 3.3: an RSA key for RS256 or PS256 has at least 2048 bits. */
+const RSA_MIN_BYTES = 256;
+function isRsaKey(jwk) {
+	if (jwk.kty !== "RSA" || typeof jwk.n !== "string") return false;
+	try {
+		const modulus = fromBase64(jwk.n);
+		const leadingZero = modulus[0] === 0 ? 1 : 0;
+		return typeof jwk.e === "string" && modulus.length - leadingZero >= RSA_MIN_BYTES;
+	} catch {
+		return false;
+	}
+}
+/** Whether `jwk` can verify a JWS of key type `alg`. */
+function verifiesWith(jwk, alg, name) {
+	if (alg === "RS256" || alg === "PS256") return isRsaKey(jwk) && (jwk.alg === void 0 || jwk.alg === name);
+	return jwkAlgorithm(jwk) === alg;
+}
+const RSA_PARAMS = {
+	RS256: {
+		name: "RSASSA-PKCS1-v1_5",
+		hash: "SHA-256"
+	},
+	PS256: {
+		name: "RSA-PSS",
+		hash: "SHA-256"
+	}
+};
+const verifyParams = (alg) => {
+	switch (alg) {
+		case "RS256": return { name: "RSASSA-PKCS1-v1_5" };
+		case "PS256": return {
+			name: "RSA-PSS",
+			saltLength: 32
+		};
+		case "Ed25519":
+		case "ES256": return signParams(alg);
+		default: return alg;
+	}
+};
+/** The key type of a JWK: `OKP`/`Ed25519` or `EC`/`P-256`. */
+function jwkAlgorithm(jwk) {
+	if (jwk.kty === "OKP" && jwk.crv === "Ed25519") return "Ed25519";
+	if (jwk.kty === "EC" && jwk.crv === "P-256") return "ES256";
+}
+/** The public members of `jwk`, without `d` and other private parts. */
+function publicJwk(jwk) {
+	const alg = jwkAlgorithm(jwk);
+	if (alg === "Ed25519") return {
+		kty: "OKP",
+		crv: "Ed25519",
+		x: String(jwk.x)
+	};
+	if (alg === "ES256") return {
+		kty: "EC",
+		crv: "P-256",
+		x: String(jwk.x),
+		y: String(jwk.y)
+	};
+	throw new TypeError("Only Ed25519 and P-256 keys are supported");
+}
+/** The RFC 7638 SHA-256 thumbprint of a key, base64url: a stable `kid`. */
+async function jwkThumbprint(jwk) {
+	const key = publicJwk(jwk);
+	const canonical = key.kty === "OKP" ? `{"crv":"${key.crv}","kty":"OKP","x":"${key.x}"}` : `{"crv":"${key.crv}","kty":"EC","x":"${key.x}","y":"${key.y}"}`;
+	const digest = await crypto.subtle.digest("SHA-256", encoder.encode(canonical));
+	return toBase64Url(new Uint8Array(digest));
+}
+/** A new key pair as JWKs, with the RFC 7638 thumbprint as `kid`. */
+async function generateSigningKey(alg) {
+	const pair = await crypto.subtle.generateKey(importParams(alg), true, ["sign", "verify"]);
+	if (!("privateKey" in pair)) throw new TypeError("WebCrypto returned a single key, not a key pair");
+	const privateKey = await crypto.subtle.exportKey("jwk", pair.privateKey);
+	return {
+		kid: await jwkThumbprint(privateKey),
+		publicKey: publicJwk(privateKey),
+		privateKey
+	};
+}
+/** Imports the private JWK of an Ed25519 or P-256 key for signing. */
+function importSigningKey(jwk) {
+	const alg = jwkAlgorithm(jwk);
+	if (alg === void 0 || typeof jwk.d !== "string") throw new TypeError("A signing key is a private Ed25519 or P-256 JWK");
+	return crypto.subtle.importKey("jwk", keyMaterial(jwk, alg, true), importParams(alg), false, ["sign"]);
+}
+/** Imports the public JWK of a key whose type `verifiesWith` already matched to `alg`. */
+function importVerifyKey(jwk, alg) {
+	if (alg === "RS256" || alg === "PS256") return crypto.subtle.importKey("jwk", {
+		kty: "RSA",
+		n: String(jwk.n),
+		e: String(jwk.e)
+	}, RSA_PARAMS[alg], false, ["verify"]);
+	return crypto.subtle.importKey("jwk", keyMaterial(jwk, alg, false), importParams(alg), false, ["verify"]);
+}
+/** The raw signature of `data`: 64 bytes for Ed25519, `r || s` for ES256 (as JWS needs). */
+async function signBytes(key, alg, data) {
+	return new Uint8Array(await crypto.subtle.sign(signParams(alg), key, data.slice()));
+}
+/** A compact JWS (RFC 7515) over the JSON `payload`. */
+async function signCompact(key, alg, header, payload) {
+	const input = `${toBase64Url(JSON.stringify(header))}.${toBase64Url(JSON.stringify(payload))}`;
+	const signature = await signBytes(key, alg, encoder.encode(input));
+	return `${input}.${toBase64Url(signature)}`;
+}
+/** Why a token failed `verifyCompact`. */
+var JwsError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.name = "JwsError";
+		this.code = code;
+	}
+};
+function part(text) {
+	if (text === void 0) throw new JwsError("JWS_MALFORMED", "Not a JWS");
+	let value;
+	try {
+		value = JSON.parse(decoder.decode(fromBase64(text)));
+	} catch {
+		throw new JwsError("JWS_MALFORMED", "A JWS part is not base64url JSON");
+	}
+	if (!isRecord(value)) throw new JwsError("JWS_MALFORMED", "A JWS part is not a JSON object");
+	return value;
+}
+/**
+* Verifies a compact JWS against `jwks`: the header's `kid` picks the key
+* (or the only key of the matching type when there is no `kid`). Throws a
+* `JwsError`; checks no claims, which are the caller's to read.
+*/
+async function verifyCompact(token, jwks, options = {}) {
+	const pieces = token.split(".");
+	if (pieces.length !== 3) throw new JwsError("JWS_MALFORMED", "A compact JWS has three parts");
+	const header = part(pieces[0]);
+	const payload = part(pieces[1]);
+	const alg = typeof header["alg"] === "string" ? header["alg"] : "";
+	const allowed = options.algorithms ?? [
+		"EdDSA",
+		"Ed25519",
+		"ES256"
+	];
+	const keyAlg = keyAlgorithmOf(alg);
+	if (keyAlg === void 0 || !allowed.some((name) => name === alg)) throw new JwsError("JWS_ALG", `The alg ${alg || "(none)"} is not accepted`);
+	if (options.typ !== void 0 && (typeof header["typ"] !== "string" || header["typ"].toLowerCase() !== options.typ.toLowerCase())) throw new JwsError("JWS_TYP", `The typ must be ${options.typ}`);
+	const kid = typeof header["kid"] === "string" ? header["kid"] : void 0;
+	const candidates = jwks.keys.filter((jwk) => verifiesWith(jwk, keyAlg, alg) && (kid === void 0 || jwk.kid === kid));
+	const jwk = candidates.length === 1 ? candidates[0] : void 0;
+	if (jwk === void 0) throw new JwsError("JWS_KEY", `No key matches kid ${kid ?? "(none)"}`);
+	if (!await crypto.subtle.verify(verifyParams(keyAlg), await importVerifyKey(jwk, keyAlg), fromBase64(pieces[2] ?? ""), encoder.encode(`${pieces[0]}.${pieces[1]}`))) throw new JwsError("JWS_SIGNATURE", "The signature is invalid");
+	return {
+		header,
+		payload
+	};
+}
+function isJwkCandidate(value) {
+	return isRecord(value) && typeof value["kty"] === "string";
+}
+/** Parses a JWK Set, keeping only the Ed25519 and P-256 keys (and RSA keys with `rsa`). */
+function jwksOf(value, options = {}) {
+	return { keys: (isRecord(value) && Array.isArray(value["keys"]) ? value["keys"] : []).filter((key) => isJwkCandidate(key) && (jwkAlgorithm(key) !== void 0 || options.rsa === true && isRsaKey(key))) };
+}
+//#endregion
+export { jwksOf as a, verifyCompact as c, jwkThumbprint as i, generateSigningKey as n, signBytes as o, importSigningKey as r, signCompact as s, JwsError as t };

package/dist/kit-D5S7KNFe.d.ts

@@ -0,0 +1,66 @@
+import { b as DbError } from "./result-Cj3yWhjH.js";
+import { r as AuthState } from "./resolve-w9EpHzuM.js";
+import { t as AuthSession } from "./view-Dv0A949a.js";
+import { r as GuardOptions } from "./respond-C7I8kLK_.js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/server/kit.d.ts
+/** What a server action returns: plain data, safe across any serialization boundary. */
+type ActionResult<T> = {
+  readonly ok: true;
+  readonly data: T;
+  readonly error: null;
+} | {
+  readonly ok: false;
+  readonly data: null;
+  readonly error: DbError;
+};
+/**
+ * Checks after `allow`, `aal` and `scopes`. A caller who fails one gets
+ * `forbidden`: an `ActionResult` error, a 403, or the framework's refusal.
+ */
+interface AuthorizeOptions<I, C, P, R extends boolean, Ref = unknown> {
+  /** Refuse callers without an active tenant, so `ctx.tenant` is a string. */
+  readonly requireTenant?: R;
+  /** Admit only users holding one of these roles at `roleClaim`. */
+  readonly roles?: readonly string[];
+  /** The dotted claim path `roles` reads: one string or an array. Defaults to `app_metadata.role`. */
+  readonly roleClaim?: string;
+  /**
+   * The permission the server's `authorizer` must grant. Without an
+   * authorizer, or on any outcome but `granted`, the caller is refused;
+   * `approval-required` refuses with `code: "APPROVAL_REQUIRED"`.
+   */
+  readonly permission?: Ref;
+  /** Return `false` to refuse the caller, e.g. `(session, input) => input.ownerId === session.user.id`. */
+  readonly authorize?: (session: AuthSession<C, P>, input: I) => boolean | Promise<boolean>;
+}
+/** What `requireTenant` and `authorize` add to the context. */
+interface AuthorizedContext<C, P, R extends boolean> {
+  readonly session: AuthSession<C, P>;
+  /**
+   * The active tenant: the action's `tenant`, then the server's `tenant`
+   * option, then the tenant claim (`tenantOf(session)`).
+   */
+  readonly tenant: R extends true ? string : string | undefined;
+}
+type ActionInput<S> = S extends StandardSchemaV1 ? StandardSchemaV1.InferInput<S> | FormData : unknown;
+type ActionParsed<S> = S extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<S> : unknown;
+type Unwrapped<T> = T extends {
+  readonly ok: true;
+  readonly data: infer D;
+} ? D : T extends {
+  readonly ok: false;
+} ? never : T;
+/** Guard, authorize and validate options of a framework-neutral action. */
+interface BlockActionOptions<S extends StandardSchemaV1 | undefined, C = unknown, P = unknown, R extends boolean = boolean, Ref = unknown> extends GuardOptions, AuthorizeOptions<ActionParsed<S>, C, P, R, Ref> {
+  /** Validates the input (plain object or `FormData`) with any Standard Schema. */
+  readonly input?: S;
+}
+/** The guard and authorize checks of a loader, page or route. */
+interface BlockRequireOptions<C = unknown, P = unknown, R extends boolean = boolean, Ref = unknown> extends GuardOptions, AuthorizeOptions<undefined, C, P, R, Ref> {}
+/** The strings at a dotted claim path: one string, or every string in an array. */
+declare function rolesAt(claims: Readonly<Record<string, unknown>> | undefined, path: string): readonly string[];
+/** Whether a signed-in caller holds one of `roles` at the claim `path`. */
+declare function hasRole(auth: AuthState, roles: readonly string[], path?: string): boolean;
+//#endregion
+export { AuthorizedContext as a, Unwrapped as c, AuthorizeOptions as i, hasRole as l, ActionParsed as n, BlockActionOptions as o, ActionResult as r, BlockRequireOptions as s, ActionInput as t, rolesAt as u };

package/dist/kit-MUK34-ZG.js

@@ -0,0 +1,104 @@
+import { n as dbError } from "./errors-8i6tSICm.js";
+import { n as validate } from "./standard-B5fe2gnW.js";
+import { n as claimAt } from "./claims-PqzCxaTD.js";
+import { t as authContext } from "./context-BDDgjoxz.js";
+import { n as toSession } from "./view-DZ63nqwt.js";
+import { o as settle, r as guard } from "./respond-DdhZ9Wbn.js";
+import { n as checkPermission } from "./authorizer-DH7DjkL3.js";
+//#region src/server/kit.ts
+/** `FormData` as a plain object; repeated keys become arrays. */
+function formDataObject(form) {
+	const out = {};
+	for (const key of new Set(form.keys())) {
+		const values = form.getAll(key);
+		out[key] = values.length > 1 ? values : values[0];
+	}
+	return out;
+}
+/** A failed `ActionResult`. */
+function actionError(error) {
+	return {
+		ok: false,
+		data: null,
+		error
+	};
+}
+/** What a `permission` on an action or route is checked against. */
+function callerResource(input) {
+	if (input === void 0 || input instanceof Request) return { type: "route" };
+	if (typeof input !== "object" || input === null || Array.isArray(input) || input instanceof FormData) return { type: "action" };
+	return {
+		type: "action",
+		properties: input
+	};
+}
+/**
+* `requireTenant`, `roles`, `permission` and `authorize`, in that order: the
+* session and tenant, or why the caller is refused.
+*/
+async function authorizeCaller(auth, checks, input, tenant, authorizer) {
+	const session = toSession(auth);
+	if (checks.requireTenant && tenant === void 0) return dbError("forbidden", "Choose an organization first", { code: "NO_TENANT" });
+	if (checks.roles && !hasRole(auth, checks.roles, checks.roleClaim)) return dbError("forbidden", "You do not have the role this needs", { code: "MISSING_ROLE" });
+	if (checks.permission !== void 0) {
+		const permitted = await checkPermission({
+			authorizer,
+			permission: checks.permission,
+			resource: callerResource(input),
+			context: {
+				...authContext(auth),
+				...tenant === void 0 ? {} : { tenant }
+			}
+		});
+		if (!permitted.ok) return permitted.error;
+	}
+	if (checks.authorize && !await checks.authorize(session, input)) return dbError("forbidden", "You are not allowed to do this", { code: "NOT_AUTHORIZED" });
+	return {
+		session,
+		tenant
+	};
+}
+/** `guard`, then `authorizeCaller`: the caller, or the refusal. */
+async function requireCaller(auth, options, tenant, authorizer) {
+	return guard(auth, options.allow, options.aal, options.scopes) ?? authorizeCaller(auth, options, void 0, tenant, authorizer);
+}
+/**
+* Runs an action body with the guard, input validation and authorize checks
+* every adapter shares, and settles it into an `ActionResult`: `Result`s
+* unwrap, thrown `DbException`s become errors, other throws propagate (so
+* framework redirects keep working).
+*/
+async function runAction(auth, options, input, tenant, body, authorizer) {
+	const denied = guard(auth, options.allow, options.aal, options.scopes);
+	if (denied) return actionError(denied);
+	let parsed = input instanceof FormData ? formDataObject(input) : input;
+	if (options.input) {
+		const checked = await validate(options.input, parsed, "input");
+		if (!checked.ok) return actionError(checked.error);
+		parsed = checked.data;
+	}
+	const caller = await authorizeCaller(auth, options, parsed, tenant, authorizer);
+	if ("kind" in caller) return actionError(caller);
+	const settled = await settle(() => body(parsed, caller));
+	return settled.ok ? {
+		ok: true,
+		data: settled.data,
+		error: null
+	} : actionError(settled.error);
+}
+/** The strings at a dotted claim path: one string, or every string in an array. */
+function rolesAt(claims, path) {
+	const single = claimAt(claims, path);
+	if (single !== void 0) return [single];
+	let value = claims;
+	for (const segment of path.split(".")) value = typeof value === "object" && value !== null ? value[segment] : void 0;
+	return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+/** Whether a signed-in caller holds one of `roles` at the claim `path`. */
+function hasRole(auth, roles, path = "app_metadata.role") {
+	if (auth.kind !== "user") return false;
+	const held = rolesAt(auth.claims, path);
+	return roles.some((role) => held.includes(role));
+}
+//#endregion
+export { rolesAt as a, requireCaller as i, formDataObject as n, runAction as o, hasRole as r, authorizeCaller as t };

package/dist/knowledge-BXQ2-V0a.d.ts

@@ -0,0 +1,187 @@
+/// <reference lib="esnext.temporal" />
+import { t as AsyncResult, w as ErrorMapper } from "./result-Cj3yWhjH.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { t as BlockTransport } from "./block-transport-DaGGXjIw.js";
+import { r as BlockTemporalOptions } from "./block-helpers-C86hPEjI.js";
+import { n as BlockHooks } from "./block-hooks-BLPWD3Jt.js";
+import { f as AiFiles, o as AiFile } from "./types-pNY_UpDs.js";
+import { g as JobHandler } from "./types-CdP0z5tS.js";
+//#region src/blocks/knowledge/knowledge.d.ts
+/**
+ * Turns texts into vectors. `model` is stored with each document, so a
+ * document embedded by another model can be found and embedded again.
+ */
+interface Embedder {
+  /** The embedder contract version. Omitted means 1. */
+  readonly apiVersion?: 1;
+  readonly model: string;
+  embed(values: readonly string[], options?: {
+    readonly signal?: AbortSignal;
+  }): Promise<readonly (readonly number[])[]>;
+}
+type KnowledgeScope = "organization" | "agent" | "project" | "chat" | "user";
+type KnowledgeStatus = "pending" | "ready" | "failed";
+interface KnowledgeDocument {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly ownerId: string;
+  readonly scope: KnowledgeScope;
+  /** The agent, project, chat or user the document belongs to; none for organization scope. */
+  readonly scopeId: string | undefined;
+  readonly fileId: string | undefined;
+  readonly title: string;
+  readonly source: string | undefined;
+  readonly metadata: Readonly<Record<string, unknown>>;
+  readonly status: KnowledgeStatus;
+  readonly error: string | undefined;
+  readonly chunkCount: number;
+  readonly embeddingModel: string | undefined;
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+}
+interface NewKnowledgeDocument {
+  readonly title: string;
+  /** Default `user`, scoped to the caller. */
+  readonly scope?: KnowledgeScope;
+  readonly scopeId?: string;
+  readonly fileId?: string;
+  /** Where the text came from: a URL, a file name or a table. */
+  readonly source?: string;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+  /** The service role only: the user the document belongs to. */
+  readonly ownerId?: string;
+}
+interface KnowledgeChunk {
+  readonly content: string;
+  /** An estimate of the tokens in `content`. */
+  readonly tokens?: number;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+interface KnowledgeHit {
+  readonly documentId: string;
+  readonly index: number;
+  readonly content: string;
+  readonly metadata: Readonly<Record<string, unknown>>;
+  readonly title: string;
+  /** The fused reciprocal rank score; higher is better. */
+  readonly score: number;
+}
+interface KnowledgeQuery {
+  /** Searched as full text, and embedded when the block has an embedder. */
+  readonly text?: string;
+  /** An embedding of the query, used instead of embedding `text`. */
+  readonly embedding?: readonly number[];
+}
+interface KnowledgeSearchOptions {
+  /** The scopes to search, each with an optional id; every scope when unset. */
+  readonly scopes?: readonly {
+    readonly scope: KnowledgeScope;
+    readonly id?: string;
+  }[];
+  /** How many chunks to return. Default 8, at most 100. */
+  readonly k?: number;
+  /** Matches documents whose metadata contains this object. */
+  readonly filter?: Readonly<Record<string, unknown>>;
+  readonly signal?: AbortSignal;
+}
+interface ChunkOptions {
+  /** The most characters in a chunk. Default 2000. */
+  readonly size?: number;
+  /** Characters repeated from the end of the previous chunk. Default 200, or a tenth of a smaller `size`. */
+  readonly overlap?: number;
+}
+interface KnowledgeOptions extends BlockTemporalOptions {
+  /** Calls as the user: `rpcTransport(supabase)`. */
+  readonly transport: BlockTransport;
+  /** Calls as the service role, for `process`, `drain` and `reembed`. */
+  readonly service?: BlockTransport;
+  /** The module schema, or its API schema: `defineBlocks` passes it from `blocks.generated.ts`. Default `better_supabase`. */
+  readonly schema?: string;
+  readonly mappers?: readonly ErrorMapper[];
+  /** Embeds chunks and queries; without one, search is full text only. */
+  readonly embedder?: Embedder;
+  /** The ai-files block, for `ingest.file`. */
+  readonly files?: AiFiles;
+  /**
+   * The text of a file. The default decodes `text/*`, JSON, XML and YAML
+   * as UTF-8 and fails with `KNOWLEDGE_UNSUPPORTED` for anything else.
+   */
+  readonly extract?: (file: AiFile, data: Uint8Array) => Promise<string>;
+  readonly chunking?: ChunkOptions;
+  /** Chunks per embedding call. Default 64. */
+  readonly batchSize?: number;
+  /** `withBlockHooks` hooks around the methods, and around each group's under its name (ADR 0015). */
+  readonly hooks?: KnowledgeHooks;
+  /** Receives the errors `after` hooks throw. */
+  readonly logger?: Logger;
+}
+/** Hooks for `Knowledge`: the top-level methods, and `documents` and `ingest` by group. */
+type KnowledgeHooks = BlockHooks<Knowledge> & {
+  readonly documents?: BlockHooks<Knowledge["documents"]>;
+  readonly ingest?: BlockHooks<Knowledge["ingest"]>;
+};
+interface Knowledge {
+  readonly documents: {
+    create(organizationId: string, document: NewKnowledgeDocument): AsyncResult<KnowledgeDocument>;
+    get(documentId: string): AsyncResult<KnowledgeDocument>;
+    list(organizationId: string, options?: {
+      readonly scope?: KnowledgeScope;
+      readonly scopeId?: string;
+      readonly limit?: number;
+    }): AsyncResult<readonly KnowledgeDocument[]>;
+    /** Replaces the chunks; unchanged chunks keep their embedding. */
+    write(documentId: string, chunks: readonly KnowledgeChunk[]): AsyncResult<KnowledgeDocument>;
+    remove(documentId: string): AsyncResult<boolean>;
+  };
+  readonly ingest: {
+    /** Creates a document from text and writes its chunks. */
+    text(organizationId: string, document: NewKnowledgeDocument & {
+      readonly text: string;
+    }): AsyncResult<KnowledgeDocument>;
+    /** Creates a document from a ready ai-files file and writes its chunks. */
+    file(organizationId: string, fileId: string, document?: Partial<NewKnowledgeDocument>): AsyncResult<KnowledgeDocument>;
+  };
+  /**
+   * Embeds a document's pending chunks (service role). Returns how many
+   * still wait, 0 once the document is ready.
+   */
+  process(documentId: string, options?: {
+    readonly signal?: AbortSignal | undefined;
+  }): AsyncResult<number>;
+  /**
+   * The handler for the `knowledge_embed` queue. The last attempt marks
+   * the document failed with the error.
+   */
+  embedJob(): JobHandler<{
+    readonly document_id: string;
+  }>;
+  /**
+   * Processes pending documents without a queue (service role). Returns how
+   * many. A document is marked failed only after `attempts` (default 3)
+   * tries fail, and never when the signal aborted it.
+   */
+  drain(options?: {
+    readonly batch?: number;
+    readonly attempts?: number;
+    readonly signal?: AbortSignal;
+  }): AsyncResult<number>;
+  search(organizationId: string, query: string | KnowledgeQuery, options?: KnowledgeSearchOptions): AsyncResult<readonly KnowledgeHit[]>;
+  /**
+   * Marks documents embedded by another model (or every document when
+   * `model` is unset) pending again (service role). Returns how many.
+   */
+  reembed(options?: {
+    readonly organizationId?: string;
+    readonly model?: string;
+  }): AsyncResult<number>;
+}
+/**
+ * Splits text into chunks of at most `size` characters, preferring a
+ * paragraph, line, sentence or word break in the second half of each
+ * chunk, and repeating `overlap` characters of the previous one.
+ */
+declare function chunk(text: string, options?: ChunkOptions): readonly KnowledgeChunk[];
+/** Documents, chunks and hybrid search for retrieval. */
+declare function createKnowledge(options: KnowledgeOptions): Knowledge;
+//#endregion
+export { KnowledgeDocument as a, KnowledgeOptions as c, KnowledgeSearchOptions as d, KnowledgeStatus as f, createKnowledge as h, KnowledgeChunk as i, KnowledgeQuery as l, chunk as m, Embedder as n, KnowledgeHit as o, NewKnowledgeDocument as p, Knowledge as r, KnowledgeHooks as s, ChunkOptions as t, KnowledgeScope as u };