better-supabase 0.13.0 → 0.15.0

package/dist/knowledge-CtL-Vfgy.d.ts

@@ -0,0 +1,217 @@
+/// <reference lib="esnext.temporal" />
+import { T as ErrorMapper, t as AsyncResult } from "./result-DZeA5KS6.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { r as BlockTemporalOptions } from "./block-helpers-CRpAHrp_.js";
+import { t as BlockTransport } from "./block-transport-DWZSJrwN.js";
+import { n as BlockHooks } from "./block-hooks-DZN2w69m.js";
+import { f as AiFiles, o as AiFile } from "./types-Dr9wZgNy.js";
+import { g as JobHandler } from "./types-SFRomQF7.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>;
+    /**
+     * Creates a pending document for a ready ai-files file and enqueues its
+     * ingestion on `options.ingestQueue` (`queue_knowledge_file`, with the
+     * ai-files and jobs blocks). `ingestJob()` does the work.
+     */
+    queue(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;
+  }>;
+  /**
+   * The handler for the `knowledge_ingest` queue: reads the document's file
+   * through `options.files`, extracts its text and writes the chunks, which
+   * enqueues their embedding. Runs as the service role, so `files` needs a
+   * service transport. The last attempt marks the document failed.
+   */
+  ingestJob(): 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 };

package/dist/lint/index.d.ts

@@ -1,17 +1,100 @@
-//#region src/lint/index.d.ts
+import { Mt as Plugin, Pt as RepositoryExtension, m as Operation } from "../types-DFdg_4yN.js";
+//#region src/lint/guards.d.ts
+type GuardLevel = "off" | "warn" | "error";
+/** A level, or a level with the rule's option: `['error', 500]`. */
+type GuardSetting<Option = never> = GuardLevel | ([Option] extends [never] ? never : readonly [GuardLevel, Option]);
+interface GuardSet {
+  /** `list` without `limit` (reads the whole table). */
+  readonly noUnboundedList?: GuardSetting;
+  /** `limit` above the given maximum (default 1000). */
+  readonly maxLimit?: GuardSetting<number>;
+  /**
+   * Paging (`offset`, or `limit` above 1) without `orderBy`: Postgres returns
+   * rows in no particular order, so pages overlap or skip rows. `list` orders
+   * by the primary key by default, so this only fires on views and tables
+   * without one.
+   */
+  readonly requireOrderByForCursor?: GuardSetting;
+  /** Includes nested deeper than the given depth (default 3). */
+  readonly maxIncludeDepth?: GuardSetting<number>;
+  /**
+   * Tenant tables queried without a tenant: neither `context.tenant` nor the
+   * given claim (default `config.claims.tenant`, `tenant_id`). Service
+   * connections are exempt.
+   */
+  readonly requireTenantContext?: GuardSetting<string>;
+  /** A service-role connection used where `window` and `document` exist. */
+  readonly noAdminInBrowser?: GuardSetting;
+  /**
+   * Reads of columns listed in `config.sensitive` without `sensitive: true` on
+   * the call.
+   */
+  readonly noSensitiveSelect?: GuardSetting;
+  /**
+   * Delete operations without `where`. The repository refuses a `delete({ where
+   * })` that filters nothing on its own, so this catches deletes built by
+   * blocks and extensions; the `no-empty-where` lint rule flags the call in the
+   * editor.
+   */
+  readonly noDeleteWithoutWhere?: GuardSetting;
+  /**
+   * `update({ where })` and `delete({ where })` without `maxAffected`, or with
+   * one above the given maximum (default 1000). With a bound, a `where` that
+   * matches more rows than intended fails with `max_affected` and writes
+   * nothing. Updates and deletes by key are exempt.
+   */
+  readonly requireMaxAffected?: GuardSetting<number>;
+  /**
+   * Storage objects written to `*_url` text columns: a column listed in
+   * `storagePaths`, or a value that is a Storage URL or matches a bucket's path
+   * template. Signed URLs expire and public URLs pin the project host, so store
+   * the path in a `*_path` column and build URLs when rendering.
+   */
+  readonly storagePathColumns?: GuardSetting;
+}
+type GuardName = keyof GuardSet;
+interface GuardViolation {
+  readonly rule: GuardName;
+  readonly level: "warn" | "error";
+  readonly table: string;
+  readonly operation: Operation["kind"];
+  readonly message: string;
+}
+interface GuardsOptions {
+  readonly rules?: GuardSet;
+  /**
+   * Called for every violation. Defaults to `console.warn` for warnings. Errors
+   * fail the call with `invalid_request` after reporting.
+   */
+  readonly report?: (violation: GuardViolation) => void;
+}
+interface GuardsFindArgs {
+  /** Allow reading `config.sensitive` columns in this call. */
+  readonly sensitive?: boolean;
+}
+interface GuardsExtension extends RepositoryExtension {
+  readonly findArgs: GuardsFindArgs;
+}
+/** Catches data-exposure and correctness mistakes; everything else off. */
+export declare function safeGuards(): GuardSet;
+/** `safeGuards()` plus performance warnings. */
+export declare function recommendedGuards(): GuardSet;
+/** Every rule as an error. */
+export declare function strictGuards(): GuardSet;
 /**
- * Static checks for better-supabase calls, written against the ESLint rule API
- * so it loads in ESLint (flat config) and in oxlint's `jsPlugins`:
+ * Runtime query guards, checked before each request is built:
  *
- * ```js
- * import betterSupabase from "better-supabase/lint";
- * export default [betterSupabase.configs.recommended];
+ * ```ts
+ * defineSupabase(schema).use(guards({ rules: recommendedGuards() }));
  * ```
  *
- * Rules match calls by method name (`.findMany(...)`, `.deleteMany(...)`) with
- * an inline object literal; spread or variable arguments are skipped rather
- * than guessed at. The runtime `rules()` plugin covers the rest.
+ * Runs first (`enforce: 'first'`) so it sees the query as written, before
+ * tenant or soft-delete filters are added. Pair with the static
+ * `better-supabase/lint` plugin to catch the same mistakes in the editor.
  */
+export declare function guards(options?: GuardsOptions): Plugin<"guards", GuardsExtension>;
+//#endregion
+//#region src/lint/index.d.ts
 interface Node {
   readonly type: string;
 }
@@ -42,7 +125,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" | "require-max-affected" | "require-escape-like";
+export type RuleId = "no-unbounded-list" | "no-empty-where" | "max-limit" | "require-order-by" | "unbounded-read" | "require-max-affected" | "require-escape-like";
 /** The part of `supabase/snapshot.json` that `largeTables` reads. */
 export interface LintSnapshot {
   readonly extras: {
@@ -72,4 +155,4 @@ export declare const plugin: {
   };
 };
 //#endregion
-export { plugin as default };
+export { type GuardLevel, type GuardName, type GuardSet, type GuardSetting, type GuardViolation, type GuardsExtension, type GuardsFindArgs, type GuardsOptions, plugin as default };