better-supabase 0.12.0 → 0.14.0

package/dist/agents-CmZlLPXC.d.ts

@@ -0,0 +1,117 @@
+/// <reference lib="esnext.temporal" />
+import { T as ErrorMapper, t as AsyncResult } from "./result-C6jDfedy.js";
+import { t as StandardSchemaV1 } from "./standard-DbQsD2xZ.js";
+import { r as FieldsOf } from "./block-fields-3w4MZr8U.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { r as BlockTemporalOptions } from "./block-helpers-BaugZlJV.js";
+import { t as BlockTransport } from "./block-transport-d53POsem.js";
+import { n as BlockHooks } from "./block-hooks-CmjPKqQ_.js";
+import { u as KnowledgeScope } from "./knowledge-CFkCRxO9.js";
+//#region src/blocks/agents/agents.d.ts
+type AgentVisibility = "private" | "organization" | "public";
+/** A knowledge scope an agent searches: its own (`agent`) or another one. */
+interface AgentKnowledgeScope {
+  readonly scope: KnowledgeScope;
+  readonly id?: string;
+}
+interface AgentSkill {
+  readonly id: string;
+  /** Who serves the skill, such as `vercel` or `local`. */
+  readonly provider: string;
+  readonly reference: Readonly<Record<string, unknown>>;
+}
+interface Agent {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly ownerId: string | undefined;
+  readonly slug: string;
+  readonly name: string;
+  readonly description: string;
+  readonly instructions: string;
+  /** A model id for the app's provider registry; the app's default when unset. */
+  readonly model: string | undefined;
+  /** The names of the tools the agent may call. */
+  readonly tools: readonly string[];
+  readonly connectorIds: readonly string[];
+  readonly knowledgeScopes: readonly AgentKnowledgeScope[];
+  /** Prompts the chat offers before the first message. */
+  readonly starters: readonly string[];
+  readonly visibility: AgentVisibility;
+  readonly publishedAt: Temporal.Instant | undefined;
+  readonly installCount: number;
+  readonly ratingCount: number;
+  /** The mean rating, or `undefined` before the first one. */
+  readonly rating: number | undefined;
+  /** Whether the caller installed it; only `get` and `list` set it. */
+  readonly installed: boolean;
+  /** The caller's rating; only `get` sets it. */
+  readonly myRating: number | undefined;
+  /** Only `get` loads the skills. */
+  readonly skills: readonly AgentSkill[];
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+}
+interface AgentFields {
+  readonly slug?: string;
+  readonly name?: string;
+  readonly description?: string;
+  readonly instructions?: string;
+  readonly model?: string | null;
+  readonly tools?: readonly string[];
+  readonly connectorIds?: readonly string[];
+  readonly knowledgeScopes?: readonly AgentKnowledgeScope[];
+  readonly starters?: readonly string[];
+}
+type NewAgent = AgentFields & {
+  readonly slug: string;
+  readonly name: string;
+};
+type AgentFilter = "store" | "mine" | "installed";
+interface AgentsOptions<S extends StandardSchemaV1 | undefined = undefined> extends BlockTemporalOptions {
+  /**
+   * A Standard Schema for the agent columns the app adds
+   * (`blocks.agents.options.extraColumns`), keyed by column name. It types and
+   * parses them on every read, and validates them on `create` and `update`,
+   * which return a `validation` error for a bad value.
+   */
+  readonly fields?: S;
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: NoInfer<BlockHooks<Agents<FieldsOf<S>>>>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+  /** Calls as the user: `rpcTransport(supabase)`. */
+  readonly transport: 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[];
+}
+/** `F` is the extra fields `options.fields` describes. */
+interface Agents<F extends object = Record<never, never>> {
+  /** Keys besides the agent's own are its extra columns. */
+  create(organizationId: string, agent: NewAgent & Partial<F>): AsyncResult<Agent & F>;
+  update(organizationId: string, agentId: string, fields: AgentFields & Partial<F>): AsyncResult<Agent & F>;
+  get(agentId: string): AsyncResult<Agent & F>;
+  bySlug(organizationId: string, slug: string): AsyncResult<Agent & F>;
+  /**
+   * The store (published to the tenant or public), the caller's own, or the
+   * installed ones.
+   */
+  list(organizationId: string, options?: {
+    readonly filter?: AgentFilter;
+    readonly search?: string;
+    readonly limit?: number;
+  }): AsyncResult<readonly (Agent & F)[]>;
+  publish(agentId: string, visibility: AgentVisibility): AsyncResult<Agent & F>;
+  install(organizationId: string, agentId: string, installed?: boolean): AsyncResult<boolean>;
+  /** Rates 1 to 5; `null` removes the caller's rating. */
+  rate(agentId: string, rating: number | null, comment?: string): AsyncResult<Agent & F>;
+  setSkills(agentId: string, skills: readonly Omit<AgentSkill, "id">[]): AsyncResult<number>;
+  remove(agentId: string): AsyncResult<boolean>;
+}
+/** Custom assistants: build, publish to a store, install and rate. */
+declare function createAgents<S extends StandardSchemaV1 | undefined = undefined>(options: AgentsOptions<S>): Agents<FieldsOf<S>>;
+//#endregion
+export { AgentSkill as a, AgentsOptions as c, AgentKnowledgeScope as i, NewAgent as l, AgentFields as n, AgentVisibility as o, AgentFilter as r, Agents as s, Agent as t, createAgents as u };

package/dist/ai-cache-BxlOkc_M.d.ts

@@ -0,0 +1,82 @@
+/// <reference lib="esnext.temporal" />
+import { T as ErrorMapper, t as AsyncResult } from "./result-C6jDfedy.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { r as BlockTemporalOptions } from "./block-helpers-BaugZlJV.js";
+import { t as BlockTransport } from "./block-transport-d53POsem.js";
+import { n as BlockHooks } from "./block-hooks-CmjPKqQ_.js";
+import { g as JobHandler } from "./types-CGUDoF5I.js";
+//#region src/blocks/ai-cache/ai-cache.d.ts
+/**
+ * What an entry caches: a whole generation, a replayable stream, embeddings, or
+ * anything else.
+ */
+type AiCacheKind = "generate" | "stream" | "embed" | "other";
+interface AiCacheEntry<T = unknown> {
+  readonly key: string;
+  readonly organizationId: string | undefined;
+  readonly kind: AiCacheKind;
+  readonly model: string | undefined;
+  readonly value: T;
+  readonly hits: number;
+  readonly createdAt: Temporal.Instant;
+  readonly lastHitAt: Temporal.Instant | undefined;
+  readonly expiresAt: Temporal.Instant;
+}
+interface AiCacheSetOptions {
+  /** Seconds the entry lives, capped by the module's `maxTtl`. */
+  readonly ttl: number;
+  /** The tenant the entry belongs to, so `clear` and tenant deletion find it. */
+  readonly organizationId?: string;
+  readonly kind?: AiCacheKind;
+  readonly model?: string;
+}
+interface AiCacheOptions extends BlockTemporalOptions {
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: NoInfer<BlockHooks<AiCache>>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+  /** Calls as the service role: entries hold prompts and outputs. */
+  readonly transport: 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[];
+}
+interface AiCache {
+  /**
+   * The entry under `key`, or `undefined` when there is none or it expired.
+   * Counts a hit.
+   */
+  get<T = unknown>(key: string): AsyncResult<AiCacheEntry<T> | undefined>;
+  /** Stores or replaces the entry under `key`. `value` must be JSON. */
+  set(key: string, value: unknown, options: AiCacheSetOptions): AsyncResult<Omit<AiCacheEntry<undefined>, "value">>;
+  delete(key: string): AsyncResult<boolean>;
+  /** Deletes every entry of a tenant, or of a model. Returns how many. */
+  clear(filter: {
+    readonly organizationId?: string;
+    readonly model?: string;
+  }): AsyncResult<number>;
+  /** Deletes up to `batch` expired entries. Returns how many. */
+  purge(options?: {
+    readonly batch?: number;
+  }): AsyncResult<number>;
+  /** A job handler that runs `purge`; schedule it hourly. */
+  purgeJob(options?: {
+    readonly batch?: number;
+  }): JobHandler<unknown>;
+}
+/**
+ * A cache key for `parts`: SHA-256 of their JSON with object keys sorted, so
+ * the same model, prompt and settings give the same key. Bytes count by content
+ * and `undefined` fields are left out.
+ */
+declare function cacheKey(parts: unknown): Promise<string>;
+/**
+ * Model responses cached in Postgres with a TTL, read and written as the
+ * service role.
+ */
+declare function createAiCache(options: AiCacheOptions): AiCache;
+//#endregion
+export { AiCacheSetOptions as a, AiCacheOptions as i, AiCacheEntry as n, cacheKey as o, AiCacheKind as r, createAiCache as s, AiCache as t };

package/dist/ai-cache-DQikwXhJ.js

@@ -0,0 +1,87 @@
+import { n as isRecord } from "./guards-6F2bCtQR.js";
+import { C as optionalText, D as recordOf, I as textOf, N as sha256Hex, S as optionalInstant, h as instantOf, n as applyTemporal, o as blockCall } from "./block-helpers-CiKtrb6g.js";
+import { r as withBlockHooks } from "./block-hooks-BymdcD0V.js";
+//#region src/blocks/ai-cache/ai-cache.ts
+const KINDS = /* @__PURE__ */ new Set([
+	"generate",
+	"stream",
+	"embed",
+	"other"
+]);
+function entryOf(value) {
+	const row = recordOf(value, "ai_cache_entries");
+	const kind = textOf(row["kind"]);
+	return {
+		key: textOf(row["key"]),
+		organizationId: optionalText(row["organization_id"]),
+		kind: KINDS.has(kind) ? kind : "other",
+		model: optionalText(row["model"]),
+		value: row["value"],
+		hits: typeof row["hits"] === "number" ? row["hits"] : 0,
+		createdAt: instantOf(row["created_at"]),
+		lastHitAt: optionalInstant(row["last_hit_at"]),
+		expiresAt: instantOf(row["expires_at"])
+	};
+}
+function canonical(value) {
+	if (value instanceof Uint8Array) {
+		let binary = "";
+		for (const byte of value) binary += String.fromCodePoint(byte);
+		return { $bytes: btoa(binary) };
+	}
+	if (value instanceof Date) return value.toISOString();
+	if (value instanceof URL) return value.href;
+	if (Array.isArray(value)) return value.map(canonical);
+	if (isRecord(value)) {
+		const out = {};
+		for (const key of Object.keys(value).toSorted()) {
+			const item = value[key];
+			if (item !== void 0 && typeof item !== "function") out[key] = canonical(item);
+		}
+		return out;
+	}
+	return value;
+}
+/**
+* A cache key for `parts`: SHA-256 of their JSON with object keys sorted, so
+* the same model, prompt and settings give the same key. Bytes count by content
+* and `undefined` fields are left out.
+*/
+function cacheKey(parts) {
+	return sha256Hex(JSON.stringify(canonical(parts) ?? null));
+}
+/**
+* Model responses cached in Postgres with a TTL, read and written as the
+* service role.
+*/
+function createAiCache(options) {
+	applyTemporal(options);
+	const call = blockCall(options.transport, options.schema, options.mappers);
+	const purge = (purgeOptions = {}) => call("purge_ai_cache", { batch: purgeOptions.batch }, (value) => Number(value ?? 0));
+	return withBlockHooks({
+		get: (key) => call("ai_cache_get", { key }, (value) => value === null || value === void 0 ? void 0 : entryOf(value)),
+		set: (key, value, setOptions) => call("ai_cache_set", {
+			key,
+			value,
+			ttl: Math.max(1, Math.ceil(setOptions.ttl)),
+			tenant: setOptions.organizationId,
+			kind: setOptions.kind,
+			model: setOptions.model
+		}, (row) => {
+			const { value: _value, ...entry } = entryOf(row);
+			return entry;
+		}),
+		delete: (key) => call("ai_cache_delete", { key }, (value) => Number(value ?? 0) > 0),
+		clear: (filter) => call("ai_cache_delete", {
+			tenant: filter.organizationId,
+			model: filter.model
+		}, (value) => Number(value ?? 0)),
+		purge,
+		purgeJob: (jobOptions) => async () => purge(jobOptions).orThrow()
+	}, options.hooks, {
+		block: "ai-cache",
+		...options.logger ? { logger: options.logger } : {}
+	});
+}
+//#endregion
+export { createAiCache as n, cacheKey as t };