better-supabase 0.8.0 → 0.9.0

package/dist/topic-cMS7UtM1.d.ts

@@ -0,0 +1,359 @@
+import { E as ValidationIssue, b as DbError, t as AsyncResult } from "./result-Cj3yWhjH.js";
+import { M as Row, a as AnyModels, i as AnyFunctions, r as AccessTopicPolicy, z as TableKey } from "./types-YfwpIE-d.js";
+import { t as AuthorizationFunctions } from "./authorization-DpRfs6Wx.js";
+import { t as RealtimeStatus } from "./realtime-status-DcsO00Gw.js";
+import { J as TemplateValues, q as TemplateParams } from "./storage-api-Cx-1iWBd.js";
+import { t as BetterSupabase } from "./define-DxHHbNEb.js";
+import { g as SubscriberPolicy, h as SubscriberEvent, i as AuthorizationHooks, m as Subscriber } from "./authorization-hooks-DkmrnDX7.js";
+import { RealtimeChannel, SupabaseClient } from "@supabase/supabase-js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/realtime/fan-out.d.ts
+interface TopicFanOutOptions<P extends string, E extends EventSchemas, K extends TopicEvent<E>, S extends Subscriber> {
+  readonly subscribers: readonly S[];
+  /** The topic values of one subscriber, e.g. `(s) => ({ userId: s.principal })`. */
+  readonly values: (subscriber: S) => TemplateValues<P>;
+  readonly event: K;
+  readonly payload: TopicPayload<E, K>;
+  /** What the subscriber policy reads about the event. */
+  readonly source: SubscriberEvent;
+  /**
+   * Defaults to the topic's `subscribers`, then
+   * `server.authorization.delivery.subscribers`. With `server.authorization`
+   * and none of them, an event with a `subject` goes to no one
+   * (`REALTIME_SUBSCRIBER_POLICY_REQUIRED`); pass `subjectReaders(transport)`.
+   */
+  readonly policy?: SubscriberPolicy;
+  readonly server?: {
+    readonly authorization?: AuthorizationHooks | undefined;
+  };
+}
+interface FanOutResult<S> {
+  readonly sent: readonly S[];
+  /** Left out by the subscriber policy. */
+  readonly skipped: readonly S[];
+  /** Sends that failed, with their error. */
+  readonly failed: readonly {
+    readonly subscriber: S;
+    readonly error: DbError;
+  }[];
+}
+//#endregion
+//#region src/realtime/topic.d.ts
+type EventSchemas = Readonly<Record<string, StandardSchemaV1>>;
+/** `true`, or a schema every tracked presence state is validated against. */
+type PresenceSchema = boolean | StandardSchemaV1;
+interface TopicOptions<E extends EventSchemas, R extends PresenceSchema = PresenceSchema> {
+  /** Name used for generated policies and functions. Defaults to the template's literal parts. */
+  readonly name?: string;
+  /** Payload schemas per event. Incoming and outgoing payloads are validated. */
+  readonly events?: E;
+  /** Private channels are authorized by `realtime.messages` policies. Defaults to `true`. */
+  readonly private?: boolean;
+  /**
+   * Tenant check for the generated policy. Defaults to `{organizationId}` against
+   * `tenant_id` / `app_metadata.tenant_id` when the template has `{organizationId}`.
+   */
+  readonly tenant?: false | {
+    readonly param?: string;
+    readonly claim?: string | readonly string[];
+    readonly sql?: string;
+  };
+  /** Owner check. Defaults to `{userId}` against `auth.uid()` when the template has `{userId}`. */
+  readonly owner?: false | {
+    readonly param?: string;
+  };
+  /**
+   * Authorize with the SQL modules' access contract instead of the tenant
+   * claim: `tenant_ids_with(receive)` on the tenant segment (or
+   * `is_platform` for `scope: 'platform'`), or the `sql` templates it is
+   * given, and `send` for broadcasting.
+   *
+   * The checks decide by role and scope only: for a permission with row
+   * conditions (e.g. `authorId = principal.id`) every member of the scope
+   * could join. `better-supabase doctor` (BS214) refuses keys the
+   * authorization provider doesn't mark `sqlComplete: true`.
+   */
+  readonly access?: AccessTopicPolicy;
+  /**
+   * A permission on the instance the topic is about, such as
+   * `'posts.read'` on `org:{organizationId}:posts:{postId}`: every receiver
+   * and sender must hold it on that instance. With an authorization
+   * provider, `sql({ functions })` checks it with the provider's `permitted`
+   * template; without one, with the access contract's tenant check.
+   */
+  readonly permission?: string | TopicPermission;
+  /**
+   * Narrows `fanOut` to the subscribers that may read the event. Defaults
+   * to `server.authorization.delivery.subscribers` when `fanOut` gets the
+   * server.
+   */
+  readonly subscribers?: SubscriberPolicy;
+  /** Let clients broadcast on the topic, not only receive. Defaults to `false`. */
+  readonly send?: boolean;
+  /**
+   * Presence: authorizes it in the policies and adds `track` and
+   * `onPresence` to subscriptions. Pass a schema to validate the states
+   * this client tracks and the ones it receives. Defaults to `false`.
+   */
+  readonly presence?: R;
+}
+/** A topic's instance permission. */
+interface TopicPermission {
+  readonly key: string;
+  /** The placeholder holding the instance id, as a whole segment. Defaults to the last one. */
+  readonly param?: string;
+  /** `{resource}` in the `permitted` template. Defaults to the key up to its first `.`. */
+  readonly resource?: string;
+  /** `{scope}` in the `permitted` template. Defaults to `tenant`. */
+  readonly scope?: string;
+}
+interface TopicMessage {
+  readonly event: string;
+  readonly payload: unknown;
+  readonly topic: string;
+}
+type Output<S> = S extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<S> : unknown;
+type Input<S> = S extends StandardSchemaV1 ? StandardSchemaV1.InferInput<S> : unknown;
+type TopicHandlers<E extends EventSchemas> = [keyof E] extends [never] ? {
+  readonly [event: string]: ((payload: unknown, message: TopicMessage) => void) | undefined;
+} : { readonly [K in keyof E & string]?: (payload: Output<E[K]>, message: TopicMessage) => void; } & {
+  readonly "*"?: (payload: unknown, message: TopicMessage) => void;
+};
+type TopicEvent<E extends EventSchemas> = [keyof E] extends [never] ? string : keyof E & string;
+type TopicPayload<E extends EventSchemas, K extends string> = [keyof E] extends [never] ? unknown : Input<E[K]>;
+type SubscriptionStatus = "joining" | "subscribed" | "closed" | "error";
+interface SubscribeOptions {
+  /** Receive your own broadcasts. */
+  readonly self?: boolean;
+  readonly onStatus?: (status: SubscriptionStatus, error?: Error) => void;
+  /** Called when a payload fails its event schema. The handler is skipped. */
+  readonly onInvalid?: (message: TopicMessage, issues: readonly ValidationIssue[]) => void;
+}
+interface Subscription extends Disposable, AsyncDisposable {
+  readonly topic: string;
+  readonly channel: RealtimeChannel;
+  /** Resolves once joined; rejects if the join is refused or times out. */
+  readonly ready: Promise<void>;
+  unsubscribe(): Promise<void>;
+}
+/** One tracked state on a presence topic. */
+interface PresenceMember<S> {
+  /** The connection's presence key; a client tracking twice keeps one key. */
+  readonly key: string;
+  readonly state: S;
+}
+interface PresenceOptions<S> {
+  /**
+   * Called with everyone on the topic, this client included, after each
+   * presence sync. States that fail the presence schema are left out and
+   * passed to `onInvalid` as a `presence` message.
+   */
+  readonly onPresence?: (members: readonly PresenceMember<S>[]) => void;
+}
+interface PresenceSubscription<I, O> extends Subscription {
+  /**
+   * Validates the state, waits for the join and shares it with the topic.
+   * One state per client and topic: the last `track` wins, and leaving the
+   * topic removes it.
+   */
+  track(state: I): AsyncResult<void>;
+  /** Removes this client's state from the topic. */
+  untrack(): AsyncResult<void>;
+  /** Everyone from the last sync, as `onPresence` received them. */
+  members(): readonly PresenceMember<O>[];
+}
+type PresenceState = Readonly<Record<string, unknown>>;
+type PresenceInput<R> = R extends StandardSchemaV1 ? StandardSchemaV1.InferInput<R> : PresenceState;
+type PresenceOutput<R> = R extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<R> : PresenceState;
+/** What `subscribe` returns: with `track` and `members` on presence topics. */
+type TopicSubscription<R> = [R] extends [false] ? Subscription : PresenceSubscription<PresenceInput<R>, PresenceOutput<R>>;
+/** `subscribe` options: with `onPresence` on presence topics. */
+type TopicSubscribeOptions<R> = [R] extends [false] ? SubscribeOptions : SubscribeOptions & PresenceOptions<PresenceOutput<R>>;
+type RealtimeClient = Pick<SupabaseClient, "channel" | "getChannels" | "removeChannel" | "realtime">;
+/**
+ * A value read from another table: the `select` column of the `from` row
+ * whose `key` (its primary key by default) equals `via`, a column of the
+ * changed row or another lookup.
+ */
+interface TriggerLookup<M extends AnyModels> {
+  readonly from: TableKey<M>;
+  readonly via: string | TriggerLookup<M>;
+  readonly select: string;
+  readonly key?: string;
+}
+/** A trigger value: a column of the changed row, or a lookup through it. */
+type TriggerValue<M extends AnyModels, T extends keyof M> = Extract<keyof Row<M, T>, string> | TriggerLookup<M>;
+type TriggerOperation = "insert" | "update" | "delete";
+/**
+ * What a broadcast trigger sends. `"keys"` (the default) sends
+ * `{ operation, schema, table, id, values }`: the primary key and the
+ * topic's placeholder values, so clients refetch the row through RLS.
+ * `"row"` sends the whole row as `record` and `old_record`, which bypasses
+ * column grants: every receiver of the topic sees every column.
+ */
+type TriggerPayloadMode = "keys" | "row";
+/** A topic the same row change also goes to (`topics` on `trigger()`). */
+interface TriggerTopic<V> {
+  readonly topic: {
+    readonly template: string;
+    readonly params: readonly string[];
+    readonly private: boolean;
+  };
+  /** What fills each of its placeholders, as in `values`. */
+  readonly values?: Readonly<Record<string, V>>;
+}
+interface TriggerCommonOptions {
+  /** Defaults to all three. */
+  readonly events?: readonly TriggerOperation[];
+  /**
+   * The broadcast event name, or one per operation. Defaults to the
+   * operation (`INSERT`, `UPDATE`, `DELETE`).
+   */
+  readonly event?: string | { readonly [O in TriggerOperation]?: string; };
+  /**
+   * Schema for a generated function. Defaults to `better_supabase`, which
+   * the Data API does not expose.
+   */
+  readonly functionSchema?: string;
+}
+/** `topic.trigger()` with the app's `betterSupabase`: typed columns and lookups. */
+interface TriggerOptions<M extends AnyModels, T extends keyof M, P extends string> extends TriggerCommonOptions {
+  /**
+   * What fills each placeholder: a column of the changed row, or a lookup
+   * (`{ from, via, select }`) for a value on a parent row. A row whose
+   * topic comes out null is not sent to that topic.
+   */
+  readonly values: { readonly [K in TemplateParams<P>]: TriggerValue<M, T>; };
+  /**
+   * `"keys"` (default), `"row"` (bypasses column grants), or the payload
+   * itself: each key is a column, a lookup, or `{ sql }`, an expression on
+   * the row `{row}` (`tg_op` is the operation).
+   */
+  readonly payload?: TriggerPayloadMode | Readonly<Record<string, TriggerValue<M, T> | {
+    readonly sql: string;
+  }>>;
+  /** More topics the row change goes to, each with its own values. */
+  readonly topics?: readonly TriggerTopic<TriggerValue<M, T>>[];
+}
+/** `topic.trigger()` with columns only. */
+interface TopicTriggerOptions<P extends string> extends TriggerCommonOptions {
+  /**
+   * The column that fills each placeholder. Defaults to the placeholder in
+   * snake_case (`{organizationId}` reads `organization_id`).
+   */
+  readonly values?: { readonly [K in TemplateParams<P>]?: string; };
+  /** `"keys"` (default) or `"row"`, which bypasses column grants. */
+  readonly payload?: TriggerPayloadMode;
+  /** More topics the row change goes to, each with its own columns. */
+  readonly topics?: readonly TriggerTopic<string>[];
+}
+/** A row change sent with `payload: "row"`. */
+interface RowChange<R> {
+  readonly operation: "INSERT" | "UPDATE" | "DELETE";
+  readonly table: string;
+  readonly record: R | null;
+  readonly oldRecord: Partial<R> | null;
+}
+/** A row change sent with the default `payload: "keys"`: refetch the row through RLS. */
+interface RowKeys {
+  readonly operation: "INSERT" | "UPDATE" | "DELETE";
+  readonly schema: string;
+  readonly table: string;
+  /** The primary key value, or an object keyed by column for a composite key. */
+  readonly id: unknown;
+  /** The topic's placeholder values. */
+  readonly values: Readonly<Record<string, string>>;
+}
+/** Options for `topic.sql()`. */
+interface TopicSqlOptions {
+  /**
+   * The provider's templates, for an access policy with `sql: "provider"`
+   * and for `permission` (its `permitted` template).
+   */
+  readonly functions?: AuthorizationFunctions;
+}
+interface Topic<P extends string, E extends EventSchemas, R extends PresenceSchema = false> {
+  readonly template: P;
+  readonly name: string;
+  readonly params: readonly TemplateParams<P>[];
+  readonly private: boolean;
+  /** Whether subscriptions get `track` and `onPresence`. */
+  readonly presence: boolean;
+  /** The schema tracked presence states are validated against, if any. */
+  readonly presenceSchema: StandardSchemaV1 | undefined;
+  /** Payload schemas per event, as given to `defineTopic`. */
+  readonly events: E;
+  /** Whether clients may broadcast on the topic (the `send` option). */
+  readonly clientSend: boolean;
+  /** The instance permission's key, when the topic has one. */
+  readonly permission: string | undefined;
+  /**
+   * Supabase's status for what the topic relies on: `beta` for a private
+   * topic (Realtime Authorization is in public beta), `ga` otherwise.
+   */
+  readonly status: RealtimeStatus;
+  topic(values: TemplateValues<P>): string;
+  match(topic: string): TemplateValues<P> | null;
+  /**
+   * `realtime.messages` policies for this topic. Idempotent. An access
+   * policy with `sql: "provider"` needs the provider's templates in
+   * `options.functions`; `better-supabase sql sync` passes them.
+   */
+  sql(options?: TopicSqlOptions): string;
+  /**
+   * A trigger that broadcasts row changes on `table` to this topic, and to
+   * each of `topics`. A topic whose values come out null is skipped, and
+   * a value topics don't allow skips that topic with a warning instead of
+   * failing the write.
+   *
+   * With `betterSupabase`, `table` is a table key and values can be
+   * lookups; the statement creates a function for the topic. Without it,
+   * `table` is `table` or `schema.table`, and a single topic calls
+   * `better_supabase.broadcast_topic()` from the `realtime-tables` module.
+   *
+   * The payload carries keys only unless `payload` says otherwise:
+   * `payload: "row"` sends whole rows and bypasses column grants.
+   */
+  trigger<M extends AnyModels, D, F extends AnyFunctions, X, T extends TableKey<M>>(table: T, options: TriggerOptions<M, T, P> & {
+    readonly betterSupabase: BetterSupabase<M, D, F, X>;
+  }): string;
+  trigger(table: string, options?: TopicTriggerOptions<P>): string;
+  /**
+   * @deprecated Use `trigger(table, { ...options, betterSupabase })`. The
+   * payload default is keys only; pass `payload: "row"` for whole rows.
+   */
+  triggerSql<M extends AnyModels, D, F extends AnyFunctions, X, T extends TableKey<M>>(betterSupabase: BetterSupabase<M, D, F, X>, table: T, options: TriggerOptions<M, T, P>): string;
+  subscribe(client: RealtimeClient, values: TemplateValues<P>, handlers: TopicHandlers<E>, options?: TopicSubscribeOptions<R>): TopicSubscription<R>;
+  /** Sends over HTTP, without joining the channel. */
+  send<K extends TopicEvent<E>>(client: RealtimeClient, values: TemplateValues<P>, event: K, payload: TopicPayload<E, K>): AsyncResult<void>;
+  /**
+   * Sends one event to each subscriber's own topic (such as
+   * `notifications:{userId}`) after the subscriber policy narrows them.
+   * A policy that throws sends to no one and returns a `forbidden` error.
+   */
+  fanOut<S extends Subscriber, K extends TopicEvent<E>>(client: RealtimeClient, options: TopicFanOutOptions<P, E, K, S>): AsyncResult<FanOutResult<S>>;
+}
+/**
+ * A typed Realtime broadcast topic: names from a template, RLS policies for
+ * private channels, row-change triggers, and disposable subscriptions.
+ *
+ * ```ts
+ * export const notifications = defineTopic('organization:{organizationId}:notifications:{userId}', {
+ *   events: { created: v.object({ id: v.string(), title: v.string() }) },
+ * });
+ * using sub = notifications.subscribe(supabase, { organizationId, userId }, { created: (n) => toast(n.title) });
+ * ```
+ */
+declare function defineTopic<const P extends string, const E extends EventSchemas = Record<never, never>, const R extends PresenceSchema = false>(template: P, options?: TopicOptions<E, R>): Topic<P, E, R>;
+/**
+ * Reads a broadcast trigger's default message (`payload: "keys"`). Returns
+ * `null` for messages about other tables or with another shape.
+ */
+declare function rowKeys<M extends AnyModels, D, F extends AnyFunctions, X, T extends TableKey<M>>(betterSupabase: BetterSupabase<M, D, F, X>, table: T, message: TopicMessage): RowKeys | null;
+/**
+ * Reads a `payload: "row"` message as an app-cased row change. Returns
+ * `null` for messages about other tables.
+ */
+declare function rowChange<M extends AnyModels, D, F extends AnyFunctions, X, T extends TableKey<M>>(betterSupabase: BetterSupabase<M, D, F, X>, table: T, message: TopicMessage): RowChange<Row<M, T>> | null;
+//#endregion
+export { defineTopic as A, TopicSubscription as C, TriggerPayloadMode as D, TriggerOptions as E, rowKeys as M, FanOutResult as N, TriggerTopic as O, TopicFanOutOptions as P, TopicSubscribeOptions as S, TriggerLookup as T, TopicMessage as _, PresenceOutput as a, TopicPermission as b, RealtimeClient as c, SubscribeOptions as d, Subscription as f, TopicHandlers as g, TopicEvent as h, PresenceOptions as i, rowChange as j, TriggerValue as k, RowChange as l, Topic as m, PresenceInput as n, PresenceSchema as o, SubscriptionStatus as p, PresenceMember as r, PresenceSubscription as s, EventSchemas as t, RowKeys as u, TopicOptions as v, TopicTriggerOptions as w, TopicSqlOptions as x, TopicPayload as y };

package/dist/types-6oiy6rIa.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-DaGGXjIw.js";
+import { r as BlockTemporalOptions } from "./block-helpers-C86hPEjI.js";
+import { n as BlockHooks } from "./block-hooks-BLPWD3Jt.js";
+import { n as Embedder } from "./knowledge-BXQ2-V0a.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 };