better-supabase 0.8.0 → 0.10.0

package/dist/types-DM8q3IOr.d.ts

@@ -0,0 +1,240 @@
+/// <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 StandardSchemaV1 } from "./standard-C3_AAF3g.js";
+import { t as BlockTransport } from "./block-transport-NbUJygA7.js";
+import { r as BlockTemporalOptions } from "./block-helpers-7pMBVsE6.js";
+import { n as BlockHooks } from "./block-hooks-C_WaodoA.js";
+import { r as FieldsOf } from "./block-fields-5UA84ZUg.js";
+import { i as AiMessage } from "./message-B0fNJgq8.js";
+//#region src/blocks/ai-files/types.d.ts
+interface StorageReply<T> {
+  readonly data: T | null;
+  readonly error: unknown;
+}
+/** The `supabase.storage.from(bucket)` methods the block uses. */
+interface AiFileBucket {
+  createSignedUploadUrl(path: string): PromiseLike<StorageReply<{
+    readonly signedUrl: string;
+    readonly token: string;
+  }>>;
+  createSignedUrl(path: string, expiresIn: number): PromiseLike<StorageReply<{
+    readonly signedUrl: string;
+  }>>;
+  download(path: string): PromiseLike<StorageReply<Blob>>;
+  remove(paths: string[]): PromiseLike<StorageReply<unknown>>;
+  upload?(path: string, body: Blob | ArrayBuffer | Uint8Array, options?: {
+    readonly contentType?: string;
+    readonly upsert?: boolean;
+  }): PromiseLike<StorageReply<unknown>>;
+}
+/** `supabase.storage`, typed structurally. */
+interface AiFileStorage {
+  from(bucket: string): AiFileBucket;
+}
+interface AiFilesOptions<S extends StandardSchemaV1 | undefined = undefined> extends BlockTemporalOptions {
+  /**
+   * A Standard Schema for the file columns the app adds
+   * (`blocks.ai-files.options.extraColumns`), keyed by column name. It
+   * types and parses them on the file reads, and validates them on
+   * `files.upload` and `files.store`, which return a `validation` error for
+   * a bad value.
+   */
+  readonly fields?: S;
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: NoInfer<BlockHooks<AiFiles<FieldsOf<S>>>>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+  /** Calls as the user: `rpcTransport(supabase)`. */
+  readonly transport: BlockTransport;
+  /** The user's `supabase.storage`, so the bucket policies apply. */
+  readonly storage: AiFileStorage;
+  /** Calls as the service role, for `store`, provider files and `purge`. */
+  readonly service?: BlockTransport;
+  /** The service role's `supabase.storage`, for `store` and `purge`. */
+  readonly serviceStorage?: AiFileStorage;
+  /** The module schema (`blocks["ai-files"].schema`), default `better_supabase`. */
+  readonly schema?: string;
+  readonly mappers?: readonly ErrorMapper[];
+  /** Lifetime of a signed download URL in seconds. Default 300. */
+  readonly downloadTtl?: number;
+  /** The most bytes `read` returns before it fails. Default 50 MB. */
+  readonly maxBytes?: number;
+}
+type AiFileStatus = "pending" | "ready" | "failed";
+type AiFileSource = "upload" | "generated" | "provider";
+interface AiFile {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly ownerId: string;
+  readonly chatId: string | undefined;
+  readonly projectId: string | undefined;
+  readonly bucket: string;
+  /** `{organizationId}/{ownerId}/{id}/{filename}` in the bucket. */
+  readonly path: string;
+  readonly mediaType: string;
+  readonly filename: string;
+  readonly size: number;
+  readonly sha256: string | undefined;
+  readonly status: AiFileStatus;
+  readonly source: AiFileSource;
+  readonly createdAt: Temporal.Instant;
+  readonly uploadedAt: Temporal.Instant | undefined;
+  readonly expiresAt: Temporal.Instant | undefined;
+}
+interface NewAiFile {
+  readonly filename: string;
+  readonly mediaType: string;
+  /** Bytes; `confirm()` replaces it with the stored size. */
+  readonly size: number;
+  readonly chatId?: string;
+  readonly projectId?: string;
+}
+interface AiFileUpload<F extends object = Record<never, never>> {
+  readonly file: AiFile & F;
+  /** PUT the file here, or pass `token` to `uploadToSignedUrl(path, token, file)`. */
+  readonly signedUrl: string;
+  readonly token: string;
+}
+interface StoredAiFile {
+  /** The user the file belongs to. */
+  readonly ownerId: string;
+  readonly filename: string;
+  readonly mediaType: string;
+  readonly data: Uint8Array | Blob;
+  readonly chatId?: string;
+  readonly source?: AiFileSource;
+}
+interface AiProviderFile {
+  readonly fileId: string;
+  readonly provider: string;
+  /** What the provider's file API returned: a file id or a file URI. */
+  readonly reference: string;
+  readonly expiresAt: Temporal.Instant | undefined;
+}
+type AiDocumentKind = "text" | "code" | "sheet" | "image";
+interface AiDocument {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly ownerId: string;
+  readonly chatId: string | undefined;
+  readonly kind: AiDocumentKind;
+  readonly title: string;
+  readonly version: number;
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+}
+/** A document with the content of its current version. */
+interface AiDocumentWithContent extends AiDocument {
+  readonly content: string | undefined;
+  /** A path in the bucket, for an image or a large document. */
+  readonly storagePath: string | undefined;
+}
+interface AiDocumentVersion {
+  readonly documentId: string;
+  readonly version: number;
+  readonly content: string | undefined;
+  readonly storagePath: string | undefined;
+  /** The assistant message that wrote this version. */
+  readonly messageId: string | undefined;
+  readonly createdBy: string | undefined;
+  readonly createdAt: Temporal.Instant;
+}
+interface NewAiDocument {
+  readonly kind: AiDocumentKind;
+  readonly title: string;
+  readonly content?: string;
+  readonly storagePath?: string;
+  readonly chatId?: string;
+  readonly messageId?: string;
+  /** The service role only: the user the document belongs to. */
+  readonly ownerId?: string;
+}
+interface AiDocumentEdit {
+  readonly content?: string;
+  readonly storagePath?: string;
+  readonly title?: string;
+  readonly messageId?: string;
+  /** Fails with `conflict` when the document moved past this version. */
+  readonly expectedVersion?: number;
+}
+interface AiSuggestion {
+  readonly id: string;
+  readonly documentId: string;
+  readonly version: number;
+  readonly originalText: string;
+  readonly suggestedText: string;
+  readonly description: string | undefined;
+  readonly createdBy: string | undefined;
+  readonly createdAt: Temporal.Instant;
+  readonly resolvedAt: Temporal.Instant | undefined;
+  readonly accepted: boolean | undefined;
+}
+/** `F` is the extra file fields `options.fields` describes. */
+interface AiFiles<F extends object = Record<never, never>> {
+  readonly files: {
+    /**
+     * Reserves the file and returns a signed upload URL for its path. Keys
+     * besides the input's own are the file's extra columns.
+     */
+    upload(organizationId: string, file: NewAiFile & Partial<F>): AsyncResult<AiFileUpload<F>>;
+    /** Marks the upload done once the object exists. */
+    confirm(fileId: string, sha256?: string): AsyncResult<AiFile & F>;
+    get(fileId: string): AsyncResult<AiFile & F>;
+    /** The file a `supabase-storage://` URL names, when the caller may read it. */
+    resolve(url: string | URL): AsyncResult<AiFile & F>;
+    list(chatId: string): AsyncResult<readonly (AiFile & F)[]>;
+    /** A signed download URL that expires after `downloadTtl`. */
+    sign(file: AiFile | string): AsyncResult<string>;
+    /** The bytes of a ready file, refusing more than `maxBytes`. */
+    read(file: AiFile | string): AsyncResult<{
+      readonly file: AiFile & F;
+      readonly data: Uint8Array;
+    }>;
+    /** Deletes the object and the record. */
+    remove(fileId: string): AsyncResult<boolean>;
+    /** Writes a ready file for `ownerId` from the server (service role). */
+    store(organizationId: string, file: StoredAiFile & Partial<F>): AsyncResult<AiFile & F>;
+    /**
+     * Deletes stale pending uploads, expired files and the files of
+     * deleted chats, then their objects (service role). Returns how many.
+     */
+    purge(options?: {
+      readonly olderThan?: string;
+      readonly batch?: number;
+    }): AsyncResult<number>;
+  };
+  readonly providerFiles: {
+    /** The provider's reference while it is valid (service role). */
+    get(fileId: string, provider: string): AsyncResult<AiProviderFile | undefined>;
+    set(fileId: string, provider: string, reference: string, expiresAt?: Temporal.Instant): AsyncResult<boolean>;
+    /** References that expire within `horizon` (an interval, default `1 day`). */
+    expiring(horizon?: string, batch?: number): AsyncResult<readonly AiProviderFile[]>;
+  };
+  readonly documents: {
+    create(organizationId: string, document: NewAiDocument): AsyncResult<AiDocument>;
+    get(documentId: string): AsyncResult<AiDocumentWithContent>;
+    update(documentId: string, edit: AiDocumentEdit): AsyncResult<AiDocument>;
+    /** Writes `version` as the newest version again. */
+    rollback(documentId: string, version: number): AsyncResult<AiDocument>;
+    versions(documentId: string): AsyncResult<readonly AiDocumentVersion[]>;
+    remove(documentId: string): AsyncResult<boolean>;
+    suggest(documentId: string, suggestion: {
+      readonly originalText: string;
+      readonly suggestedText: string;
+      readonly description?: string;
+    }): AsyncResult<AiSuggestion>;
+    suggestions(documentId: string, options?: {
+      readonly openOnly?: boolean;
+    }): AsyncResult<readonly AiSuggestion[]>;
+    resolve(suggestionId: string, accepted: boolean): AsyncResult<AiSuggestion>;
+  };
+  /**
+   * Replaces the `supabase-storage://` URLs of file parts with signed
+   * download URLs, so a browser or a provider can fetch them. Parts the
+   * caller may not read keep their URL.
+   */
+  sign(messages: readonly AiMessage[]): Promise<readonly AiMessage[]>;
+}
+//#endregion
+export { NewAiFile as _, AiDocumentWithContent as a, AiFileSource as c, AiFileUpload as d, AiFiles as f, NewAiDocument as g, AiSuggestion as h, AiDocumentVersion as i, AiFileStatus as l, AiProviderFile as m, AiDocumentEdit as n, AiFile as o, AiFilesOptions as p, AiDocumentKind as r, AiFileBucket as s, AiDocument as t, AiFileStorage as u, StoredAiFile as v };

package/dist/types-DOaUIJxW.d.ts

@@ -0,0 +1,205 @@
+/// <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-NbUJygA7.js";
+import { r as BlockTemporalOptions } from "./block-helpers-7pMBVsE6.js";
+import { n as BlockHooks } from "./block-hooks-C_WaodoA.js";
+import { n as Embedder } from "./knowledge-BYtgA52P.js";
+//#region src/blocks/memory/types.d.ts
+type MemoryScope = "user" | "agent" | "chat" | "project" | "organization";
+type MemoryKind = "core" | "archival";
+/**
+ * Whose memory a call reads or changes. The default is the caller's own
+ * memory; `organization` memory is shared and only admins change it. The
+ * `project` scope takes a `projectId` (an ai-chat project) and no other
+ * scope does. The service role names the user in `ownerId`.
+ */
+interface MemoryNamespace {
+  readonly scope?: MemoryScope;
+  readonly agentId?: string;
+  readonly chatId?: string;
+  readonly projectId?: string;
+  readonly ownerId?: string;
+}
+interface MemoryRecord {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly ownerId: string | undefined;
+  readonly scope: MemoryScope;
+  readonly agentId: string | undefined;
+  readonly chatId: string | undefined;
+  readonly projectId: string | undefined;
+  readonly kind: MemoryKind;
+  /** A path under `/memories`, for core memory. */
+  readonly path: string | undefined;
+  readonly content: string;
+  readonly version: number;
+  readonly embeddingModel: string | undefined;
+  readonly sourceMessageId: string | undefined;
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+}
+interface MemoryHit extends MemoryRecord {
+  readonly score: number;
+  /** Cosine similarity to the query embedding, when both have one. */
+  readonly similarity: number | undefined;
+}
+type MemoryView = {
+  readonly type: "file";
+  readonly path: string;
+  readonly content: string;
+  readonly version: number;
+} | {
+  readonly type: "directory";
+  readonly path: string;
+  readonly entries: readonly {
+    readonly path: string;
+    readonly size: number;
+  }[];
+};
+/** The commands of Anthropic's memory tool (`memory_20250818`). */
+type MemoryCommand = {
+  readonly command: "view";
+  readonly path: string;
+  readonly view_range?: readonly [number, number];
+} | {
+  readonly command: "create";
+  readonly path: string;
+  readonly file_text: string;
+} | {
+  readonly command: "str_replace";
+  readonly path: string;
+  readonly old_str: string;
+  readonly new_str?: string;
+} | {
+  readonly command: "insert";
+  readonly path: string;
+  readonly insert_line: number;
+  readonly insert_text: string;
+} | {
+  readonly command: "delete";
+  readonly path: string;
+} | {
+  readonly command: "rename";
+  readonly old_path: string;
+  readonly new_path: string;
+};
+interface RecalledMessage {
+  readonly chatId: string;
+  readonly messageId: string;
+  readonly similarity: number;
+}
+interface MemoryOptions extends BlockTemporalOptions {
+  /** Calls as the user: `rpcTransport(supabase)`. */
+  readonly transport: BlockTransport;
+  /** Calls as the service role, for embeddings and extracted memories. */
+  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 archival memories, messages and queries. */
+  readonly embedder?: Embedder;
+  /** The most characters `render` returns. Default 8000. */
+  readonly maxRender?: number;
+  /** `saveExtracted` skips a fact this similar to a saved one. Default 0.92. */
+  readonly dedupeThreshold?: number;
+  /** `withBlockHooks` hooks around the methods, and around each group's under its name. */
+  readonly hooks?: MemoryHooks;
+  /** Receives the errors `after` hooks throw. */
+  readonly logger?: Logger;
+}
+/** Hooks for `Memory`: the top-level methods, and `core`, `archival`, `recall` and `documents` by group. */
+type MemoryHooks = BlockHooks<Memory> & {
+  readonly core?: BlockHooks<Memory["core"]>;
+  readonly archival?: BlockHooks<Memory["archival"]>;
+  readonly recall?: BlockHooks<Memory["recall"]>;
+  readonly documents?: BlockHooks<Memory["documents"]>;
+};
+interface Memory {
+  readonly core: {
+    view(organizationId: string, path?: string, ns?: MemoryNamespace): AsyncResult<MemoryView | undefined>;
+    /** Creates or overwrites a file; `expectedVersion` 0 means it must be new. */
+    write(organizationId: string, path: string, content: string, ns?: MemoryNamespace, options?: {
+      readonly expectedVersion?: number;
+    }): AsyncResult<MemoryRecord>;
+    strReplace(organizationId: string, path: string, oldText: string, newText: string, ns?: MemoryNamespace): AsyncResult<MemoryRecord>;
+    insert(organizationId: string, path: string, line: number, text: string, ns?: MemoryNamespace): AsyncResult<MemoryRecord>;
+    /** Deletes a file or a directory. Returns how many files. */
+    remove(organizationId: string, path: string, ns?: MemoryNamespace): AsyncResult<number>;
+    rename(organizationId: string, oldPath: string, newPath: string, ns?: MemoryNamespace): AsyncResult<number>;
+    list(organizationId: string, ns?: MemoryNamespace): AsyncResult<readonly MemoryRecord[]>;
+  };
+  /** Runs a memory tool command and returns the text for the model. */
+  run(organizationId: string, command: MemoryCommand, ns?: MemoryNamespace): AsyncResult<string>;
+  readonly archival: {
+    save(organizationId: string, content: string, ns?: MemoryNamespace, options?: {
+      readonly sourceMessageId?: string;
+    }): AsyncResult<MemoryRecord>;
+    search(organizationId: string, query: string, ns?: MemoryNamespace, options?: {
+      readonly k?: number;
+      readonly signal?: AbortSignal;
+    }): AsyncResult<readonly MemoryHit[]>;
+    list(organizationId: string, ns?: MemoryNamespace, options?: {
+      readonly limit?: number;
+    }): AsyncResult<readonly MemoryRecord[]>;
+    /** Deletes a memory, or marks it replaced by `supersededBy`. */
+    forget(memoryId: string, options?: {
+      readonly supersededBy?: string;
+    }): AsyncResult<boolean>;
+  };
+  readonly recall: {
+    /** Embeds a message so later chats can recall it (service role). */
+    index(message: {
+      readonly organizationId: string;
+      readonly chatId: string;
+      readonly messageId: string;
+      readonly userId: string;
+      readonly text: string;
+    }): AsyncResult<boolean>;
+    /** The caller's earlier messages closest to `query`. */
+    search(organizationId: string, query: string, options?: {
+      readonly k?: number;
+      readonly excludeChat?: string;
+      /** The service role only: whose messages. */
+      readonly ownerId?: string;
+      readonly signal?: AbortSignal;
+    }): AsyncResult<readonly RecalledMessage[]>;
+  };
+  /**
+   * Core memory as delimited text for a system prompt, cut at
+   * `maxRender` characters. Empty when there is none.
+   */
+  render(organizationId: string, ns?: MemoryNamespace): AsyncResult<string>;
+  /** Saves facts that aren't already remembered. Returns the new ones. */
+  saveExtracted(organizationId: string, facts: readonly string[], ns?: MemoryNamespace, options?: {
+    readonly sourceMessageId?: string;
+  }): AsyncResult<readonly MemoryRecord[]>;
+  /** Embeds memories edited since their last embedding (service role). Returns how many. */
+  embedPending(options?: {
+    readonly batch?: number;
+    readonly signal?: AbortSignal;
+  }): AsyncResult<number>;
+  /**
+   * Documents under an opaque scope key, for agent runtimes (service role).
+   * A write names the version it read; a stale one fails with the hint
+   * `MEMORY_DOCUMENT_CONFLICT`.
+   */
+  readonly documents: {
+    read(scopeKey: string, path: string): AsyncResult<MemoryDocument | undefined>;
+    /** `expectedVersion: null` means the document must not exist yet. */
+    write(scopeKey: string, path: string, content: string, options: {
+      readonly expectedVersion: string | null;
+      /** Seconds until the document expires. */
+      readonly expiresIn?: number;
+    }): AsyncResult<MemoryDocument>;
+    /** Deletes expired documents, at most `batch`. Returns how many. */
+    purge(batch?: number): AsyncResult<number>;
+  };
+}
+interface MemoryDocument {
+  readonly content: string;
+  /** Opaque; pass it back as `expectedVersion`. */
+  readonly version: string;
+}
+//#endregion
+export { MemoryHooks as a, MemoryOptions as c, MemoryView as d, RecalledMessage as f, MemoryHit as i, MemoryRecord as l, MemoryCommand as n, MemoryKind as o, MemoryDocument as r, MemoryNamespace as s, Memory as t, MemoryScope as u };