better-supabase 0.5.1 → 0.6.1

package/dist/knowledge-BXBbT0Tr.d.ts

@@ -0,0 +1,176 @@
+/// <reference lib="esnext.temporal" />
+import { t as AsyncResult, w as ErrorMapper } from "./result-D7y2fT87.js";
+import { t as BlockTransport } from "./block-transport-DvaoPuZ9.js";
+import { r as BlockTemporalOptions } from "./block-helpers-CKtbFcRv.js";
+import { f as AiFiles, o as AiFile } from "./types-C05bxW-W.js";
+import { m as JobHandler } from "./queue-CLJurhdy.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 (`sql.modules.knowledge.schema`), 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;
+}
+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, KnowledgeQuery as c, KnowledgeStatus as d, NewKnowledgeDocument as f, KnowledgeChunk as i, KnowledgeScope as l, createKnowledge as m, Embedder as n, KnowledgeHit as o, chunk as p, Knowledge as r, KnowledgeOptions as s, ChunkOptions as t, KnowledgeSearchOptions as u };

package/dist/knowledge-CDmiMLew.js

@@ -0,0 +1,255 @@
+import { t as DbException } from "./db-exception-CnWcYPxL.js";
+import { n as dbError } from "./errors-B11Duf73.js";
+import { a as ok, r as err, t as AsyncResult } from "./result-DzUbqgdW.js";
+import { t as vectorLiteral } from "./search-CUWCRYKL.js";
+import { C as run, O as textOf, b as recordOrEmpty, c as errorText, d as isRecord, h as optionalText, i as blockCall, k as toInstant, l as injectableOf, n as applyTemporal, x as recordsOf, y as recordOf } from "./block-helpers-DWHxHsEQ.js";
+//#region src/blocks/knowledge/knowledge.ts
+const SCOPES = /* @__PURE__ */ new Set([
+	"organization",
+	"agent",
+	"project",
+	"chat",
+	"user"
+]);
+const STATUSES = /* @__PURE__ */ new Set([
+	"pending",
+	"ready",
+	"failed"
+]);
+const BREAKS = [
+	"\n\n",
+	"\n",
+	". ",
+	" "
+];
+const TEXT_TYPES = /^(text\/|application\/(json|xml|yaml|x-yaml|ld\+json|x-ndjson)\b)/;
+/**
+* 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.
+*/
+function chunk(text, options = {}) {
+	const size = options.size ?? 2e3;
+	const overlap = options.overlap ?? Math.min(200, Math.floor(size / 10));
+	if (!Number.isInteger(size) || size < 1) throw new RangeError("chunk size must be a positive whole number");
+	if (!Number.isInteger(overlap) || overlap < 0 || overlap >= size) throw new RangeError("chunk overlap must be at least 0 and below size");
+	const clean = text.replaceAll(/\r\n?/g, "\n").trim();
+	const chunks = [];
+	let start = 0;
+	while (start < clean.length) {
+		let end = Math.min(start + size, clean.length);
+		if (end < clean.length) {
+			const window = clean.slice(start, end);
+			for (const mark of BREAKS) {
+				const at = window.lastIndexOf(mark);
+				if (at >= window.length / 2) {
+					end = start + at + mark.length;
+					break;
+				}
+			}
+		}
+		const content = clean.slice(start, end).trim();
+		if (content !== "") chunks.push({
+			content,
+			tokens: Math.ceil(content.length / 4)
+		});
+		if (end >= clean.length) break;
+		const back = Math.max(end - overlap, start + 1);
+		const word = /\s/.test(clean.charAt(back - 1)) ? back - 1 : clean.indexOf(" ", back);
+		start = overlap > 0 && word >= back - 1 && word < end ? word + 1 : back;
+	}
+	return chunks;
+}
+/**
+* An `invalid_input` error unless the embedder returned `count` vectors of
+* one non-zero length with finite numbers.
+*/
+function checkVectors(vectors, count) {
+	const invalid = (message) => dbError("invalid_input", message, { hint: "EMBEDDING_INVALID" });
+	if (vectors.length !== count) return invalid(`The embedder returned ${vectors.length} vectors for ${count} values`);
+	const size = vectors[0]?.length ?? 0;
+	for (const vector of vectors) {
+		if (vector.length === 0 || vector.length !== size) return invalid("The embedder returned vectors of different or zero length");
+		if (!vector.every(Number.isFinite)) return invalid("The embedder returned a vector with a non-finite number");
+	}
+}
+const scopeOf = (value) => {
+	const text = textOf(value);
+	return SCOPES.has(text) ? text : "user";
+};
+const statusOf = (value) => {
+	const text = textOf(value);
+	return STATUSES.has(text) ? text : "failed";
+};
+const instant = (value) => value instanceof Date ? toInstant(value) : toInstant(textOf(value));
+function documentOf(value) {
+	const row = recordOf(value, "knowledge_documents");
+	return {
+		id: textOf(row["id"]),
+		organizationId: textOf(row["organization_id"]),
+		ownerId: textOf(row["owner_id"]),
+		scope: scopeOf(row["scope"]),
+		scopeId: optionalText(row["scope_id"]),
+		fileId: optionalText(row["file_id"]),
+		title: textOf(row["title"]),
+		source: optionalText(row["source"]),
+		metadata: recordOrEmpty(row["metadata"]),
+		status: statusOf(row["status"]),
+		error: optionalText(row["error"]),
+		chunkCount: Number(row["chunk_count"] ?? 0),
+		embeddingModel: optionalText(row["embedding_model"]),
+		createdAt: instant(row["created_at"]),
+		updatedAt: instant(row["updated_at"])
+	};
+}
+function hitOf(value) {
+	const row = recordOf(value, "knowledge_search");
+	return {
+		documentId: textOf(row["document_id"]),
+		index: Number(row["idx"]),
+		content: textOf(row["content"]),
+		metadata: recordOrEmpty(row["metadata"]),
+		title: textOf(row["title"]),
+		score: Number(row["score"])
+	};
+}
+const notFound = () => dbError("not_found", "No knowledge document you can see has this id", { hint: "KNOWLEDGE_NOT_FOUND" });
+const decoder = new TextDecoder("utf-8", { fatal: true });
+function defaultExtract(file, data) {
+	if (!TEXT_TYPES.test(file.mediaType)) return Promise.reject(/* @__PURE__ */ new TypeError(`No text extractor for ${file.mediaType}; pass extract to createKnowledge`));
+	return Promise.resolve(decoder.decode(data));
+}
+const unsupported = (cause) => dbError("invalid_request", errorText(cause), { hint: "KNOWLEDGE_UNSUPPORTED" });
+/** Documents, chunks and hybrid search for retrieval. */
+function createKnowledge(options) {
+	applyTemporal(options);
+	const call = blockCall(options.transport, options.schema, options.mappers);
+	const service = blockCall(options.service ?? options.transport, options.schema, options.mappers);
+	const batchSize = options.batchSize ?? 64;
+	const extract = options.extract ?? defaultExtract;
+	const embedder = injectableOf("embedder", options.embedder);
+	const found = (value) => isRecord(value) ? AsyncResult.ok(documentOf(value)) : AsyncResult.err(notFound());
+	const create = (organizationId, document) => call("create_knowledge_document", {
+		tenant: organizationId,
+		title: document.title,
+		scope: document.scope,
+		scope_id: document.scopeId,
+		file_id: document.fileId,
+		source: document.source,
+		metadata: document.metadata,
+		owner: document.ownerId
+	}, documentOf);
+	const write = (documentId, chunks) => call("write_knowledge_chunks", {
+		document_id: documentId,
+		chunks: { items: chunks },
+		model: embedder?.model
+	}, (value) => value).andThen(found);
+	const fromText = (organizationId, document, text) => run(() => Promise.resolve(chunk(text, options.chunking))).andThen((chunks) => create(organizationId, document).andThen((created) => write(created.id, chunks)));
+	const embed = (values, signal) => embedder ? run(() => embedder.embed(values, signal === void 0 ? void 0 : { signal })) : AsyncResult.err(dbError("invalid_request", "createKnowledge has no embedder", { hint: "KNOWLEDGE_NO_EMBEDDER" }));
+	const process = (documentId, processOptions = {}) => AsyncResult.from(async () => {
+		let before = Number.POSITIVE_INFINITY;
+		for (;;) {
+			const pending = await service("pending_knowledge_chunks", {
+				document_id: documentId,
+				batch: batchSize
+			}, (value) => recordsOf(value, "pending_knowledge_chunks"));
+			if (!pending.ok) return pending;
+			if (pending.data.length === 0) return ok(0);
+			const vectors = await embed(pending.data.map((row) => textOf(row["content"])), processOptions.signal);
+			if (!vectors.ok) return vectors;
+			const invalid = checkVectors(vectors.data, pending.data.length);
+			if (invalid) return err(invalid);
+			const remaining = await service("set_knowledge_embeddings", {
+				document_id: documentId,
+				embeddings: { items: pending.data.map((row, index) => ({
+					idx: Number(row["idx"]),
+					hash: row["hash"],
+					embedding: vectorLiteral(vectors.data[index] ?? [])
+				})) },
+				model: embedder?.model
+			}, Number);
+			if (!remaining.ok || remaining.data === 0) return remaining;
+			if (processOptions.signal?.aborted) return ok(remaining.data);
+			if (remaining.data >= before) return ok(remaining.data);
+			before = remaining.data;
+		}
+	});
+	return {
+		documents: {
+			create,
+			get: (documentId) => call("get_knowledge_document", { document_id: documentId }, (value) => value).andThen(found),
+			list: (organizationId, listOptions = {}) => call("list_knowledge_documents", {
+				tenant: organizationId,
+				scope: listOptions.scope,
+				scope_id: listOptions.scopeId,
+				max_rows: listOptions.limit
+			}, (value) => recordsOf(value, "list_knowledge_documents").map(documentOf)),
+			write,
+			remove: (documentId) => call("delete_knowledge_document", { document_id: documentId }, (value) => value === true)
+		},
+		ingest: {
+			text: (organizationId, { text, ...document }) => fromText(organizationId, document, text),
+			file: (organizationId, fileId, document = {}) => {
+				const files = options.files;
+				if (!files) return AsyncResult.err(dbError("invalid_request", "createKnowledge has no files block", { hint: "KNOWLEDGE_NO_FILES" }));
+				return files.files.read(fileId).andThen(({ file, data }) => AsyncResult.from(async () => {
+					try {
+						return ok(await extract(file, data));
+					} catch (cause) {
+						return err(unsupported(cause));
+					}
+				}).andThen((text) => fromText(organizationId, {
+					...document,
+					title: document.title ?? file.filename,
+					fileId: file.id,
+					source: document.source ?? file.filename
+				}, text)));
+			}
+		},
+		process,
+		embedJob: () => async (payload, job, signal) => {
+			const result = await process(payload.document_id, { signal });
+			if (result.ok) return;
+			if (job.attempts >= job.maxAttempts) await service("fail_knowledge_document", {
+				document_id: payload.document_id,
+				error: result.error.message
+			}, (value) => value);
+			throw new DbException(result.error);
+		},
+		drain: (drainOptions = {}) => service("pending_knowledge_documents", { batch: drainOptions.batch }, (value) => Array.isArray(value) ? value.map(textOf) : []).andThen((ids) => AsyncResult.from(async () => {
+			const attempts = Math.max(1, drainOptions.attempts ?? 3);
+			let done = 0;
+			for (const id of ids) {
+				if (drainOptions.signal?.aborted) break;
+				let result = await process(id, drainOptions);
+				for (let attempt = 1; !result.ok && attempt < attempts && !drainOptions.signal?.aborted; attempt += 1) result = await process(id, drainOptions);
+				if (result.ok) done += 1;
+				else if (!drainOptions.signal?.aborted) await service("fail_knowledge_document", {
+					document_id: id,
+					error: result.error.message
+				}, (value) => value);
+			}
+			return ok(done);
+		})),
+		search: (organizationId, query, searchOptions = {}) => {
+			const { text, embedding } = typeof query === "string" ? {
+				text: query,
+				embedding: void 0
+			} : query;
+			return (embedding === void 0 && embedder !== void 0 && text !== void 0 && text !== "" ? embed([text], searchOptions.signal).map((vectors) => vectors[0]) : AsyncResult.ok(embedding)).andThen((value) => call("knowledge_search", {
+				tenant: organizationId,
+				query_embedding: value === void 0 ? void 0 : vectorLiteral(value),
+				query_text: text === "" ? void 0 : text,
+				scopes: searchOptions.scopes === void 0 ? void 0 : { items: searchOptions.scopes },
+				k: searchOptions.k,
+				filter: searchOptions.filter
+			}, (rows) => recordsOf(rows, "knowledge_search").map(hitOf)));
+		},
+		reembed: (reembedOptions = {}) => service("reembed_knowledge", {
+			tenant: reembedOptions.organizationId,
+			model: reembedOptions.model
+		}, Number)
+	};
+}
+//#endregion
+export { chunk as n, createKnowledge as r, checkVectors as t };

package/dist/lint/index.d.ts

@@ -42,7 +42,7 @@ export interface RuleModule {
     CallExpression(node: CallExpression): void;
   };
 }
-export type RuleId = "no-unbounded-find-many" | "no-delete-many-without-where" | "max-limit" | "require-order-by" | "unbounded-read";
+export type RuleId = "no-unbounded-find-many" | "no-delete-many-without-where" | "max-limit" | "require-order-by" | "unbounded-read" | "require-max-affected";
 /** The part of `supabase/snapshot.json` that `largeTables` reads. */
 export interface LintSnapshot {
   readonly extras: {

package/dist/lint/index.js

@@ -146,6 +146,43 @@ const rules = {
 			strict: { type: "boolean" }
 		},
 		additionalProperties: false
+	}]),
+	"require-max-affected": rule("Require maxAffected on updateMany and deleteMany", "require-max-affected", {
+		missing: "{{method}} without maxAffected can change every row its where matches.",
+		tooLarge: "maxAffected {{value}} is above the maximum of {{max}}."
+	}, (context) => {
+		const max = context.options[0]?.max ?? 1e3;
+		return { CallExpression(node) {
+			const method = methodName(node);
+			if (method !== "updateMany" && method !== "deleteMany") return;
+			const args = argsOf(node);
+			if (!args) return;
+			const bound = args.get("maxAffected");
+			if (bound === void 0) {
+				context.report({
+					node,
+					messageId: "missing",
+					data: { method }
+				});
+				return;
+			}
+			const value = numberOf(bound);
+			if (value !== void 0 && value > max) context.report({
+				node,
+				messageId: "tooLarge",
+				data: {
+					value: String(value),
+					max: String(max)
+				}
+			});
+		} };
+	}, [{
+		type: "object",
+		properties: { max: {
+			type: "integer",
+			minimum: 0
+		} },
+		additionalProperties: false
 	}])
 };
 const plugin = {

package/dist/list/index.d.ts

@@ -1,2 +1,3 @@
-import { a as ListPage, c as ListParsers, d as ListQueryInput, f as ListSearchParams, g as defineListQuery, h as UNSET, i as ListExtra, l as ListQuery, m as ParserSpec, n as FacetInfo, o as ListPagination, p as OpenApiParameter, r as ListDefinition, s as ListParseResult, t as FacetCounts, u as ListQueryConfig } from "../index-fag8VJZ2.js";
-export { type FacetCounts, type FacetInfo, type ListDefinition, type ListExtra, type ListPage, type ListPagination, type ListParseResult, type ListParsers, type ListQuery, type ListQueryConfig, type ListQueryInput, type ListSearchParams, type OpenApiParameter, type ParserSpec, UNSET, defineListQuery };
+import { _ as defineListQuery, a as ListExtra, c as ListParseResult, d as ListQueryConfig, f as ListQueryInput, g as UNSET, h as ParserSpec, i as ListDefinition, l as ListParsers, m as OpenApiParameter, n as FacetCounts, o as ListPage, p as ListSearchParams, r as FacetInfo, s as ListPagination, t as FacetCountFields, u as ListQuery } from "../list-query-BRt-zDF7.js";
+import "../index-CaxrMD1A.js";
+export { type FacetCountFields, type FacetCounts, type FacetInfo, type ListDefinition, type ListExtra, type ListPage, type ListPagination, type ListParseResult, type ListParsers, type ListQuery, type ListQueryConfig, type ListQueryInput, type ListSearchParams, type OpenApiParameter, type ParserSpec, UNSET, defineListQuery };