better-supabase 0.0.0 → 0.2.0

package/dist/live-DJyZMD6w.d.ts

@@ -0,0 +1,191 @@
+import { A as SchemaMeta, N as TableKey, O as Row, n as AnyModels, t as AnyFunctions, x as PermdockTopicPolicy } from "./types-C83v5SQz.js";
+import { b as ValidationIssue, o as Result, p as DbError, t as AsyncResult } from "./result-CTkCZ6JA.js";
+import { Z as QuerySpec, t as BetterSupabase } from "./define-e3zI4_4g.js";
+import { n as TemplateValues, t as TemplateParams } from "./template-mbvlysOo.js";
+import { RealtimeChannel, SupabaseClient } from "@supabase/supabase-js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/realtime/index.d.ts
+type EventSchemas = Readonly<Record<string, StandardSchemaV1>>;
+interface TopicOptions<E extends EventSchemas> {
+  /** 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 `{orgId}` against
+   * `tenant_id` / `app_metadata.tenant_id` when the template has `{orgId}`.
+   */
+  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 PermDock's SQL helpers instead of the tenant claim:
+   * `permitted_<scope>_ids(receive)` on the scope segment (or
+   * `permdock_has` for `scope: 'global'`), and `send` for broadcasting.
+   *
+   * The helpers check role and scope only. Use this just for permissions
+   * whose grants have no row conditions beyond the scope: for a permission
+   * with row conditions (e.g. `authorId = principal.id`) every member of the
+   * scope may join. Leave those to the policies `permdock rls generate` writes.
+   */
+  readonly permdock?: PermdockTopicPolicy;
+  /** Let clients broadcast on the topic, not only receive. Defaults to `false`. */
+  readonly send?: boolean;
+  /** Also authorize presence. Defaults to `false`. */
+  readonly presence?: boolean;
+}
+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>;
+}
+type RealtimeClient = Pick<SupabaseClient, "channel" | "removeChannel" | "realtime">;
+interface TriggerOptions<M extends AnyModels, T extends keyof M, P extends string> {
+  /** Column that fills each placeholder. */
+  readonly values: { readonly [K in TemplateParams<P>]: Extract<keyof Row<M, T>, string>; };
+  /** Defaults to all three. */
+  readonly events?: readonly ("insert" | "update" | "delete")[];
+  /** Schema for the generated function. Defaults to `public`. */
+  readonly functionSchema?: string;
+}
+interface RowChange<R> {
+  readonly operation: "INSERT" | "UPDATE" | "DELETE";
+  readonly table: string;
+  readonly record: R | null;
+  readonly oldRecord: Partial<R> | null;
+}
+interface Topic<P extends string, E extends EventSchemas> {
+  readonly template: P;
+  readonly name: string;
+  readonly params: readonly TemplateParams<P>[];
+  readonly private: boolean;
+  topic(values: TemplateValues<P>): string;
+  match(topic: string): TemplateValues<P> | null;
+  /** `realtime.messages` policies for this topic. Idempotent. */
+  sql(): string;
+  /** A trigger that broadcasts row changes (`realtime.broadcast_changes`) to this topic. */
+  triggerSql<M extends AnyModels, D, F extends AnyFunctions, X, T extends TableKey<M>>(sb: BetterSupabase<M, D, F, X>, table: T, options: TriggerOptions<M, T, P>): string;
+  subscribe(client: RealtimeClient, values: TemplateValues<P>, handlers: TopicHandlers<E>, options?: SubscribeOptions): Subscription;
+  /** 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>;
+}
+/**
+ * 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('org:{orgId}:notifications:{userId}', {
+ *   events: { created: v.object({ id: v.string(), title: v.string() }) },
+ * });
+ * using sub = notifications.subscribe(supabase, { orgId, userId }, { created: (n) => toast(n.title) });
+ * ```
+ */
+declare function defineTopic<const P extends string, const E extends EventSchemas = Record<never, never>>(template: P, options?: TopicOptions<E>): Topic<P, E>;
+/**
+ * Reads a `realtime.broadcast_changes` 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>>(sb: BetterSupabase<M, D, F, X>, table: T, message: TopicMessage): RowChange<Row<M, T>> | null;
+//#endregion
+//#region src/realtime/live.d.ts
+/** What `liveQuery` needs from `sb`: metadata and the tables a spec reads. */
+interface LiveSource {
+  readonly meta: SchemaMeta;
+  tablesOf(spec: QuerySpec): string[];
+}
+interface LiveQueryOptions {
+  /** Called once per burst of changes, with the app keys of the tables that changed. */
+  readonly onChange: (tables: readonly string[]) => void;
+  /** Tenant value for tables scoped by a tenant column (`realtime-tables` topics). */
+  readonly tenant?: string;
+  /** Waits this long after the last change before calling `onChange`. Defaults to 100 ms. */
+  readonly debounceMs?: number;
+  readonly onStatus?: (status: SubscriptionStatus, error?: Error) => void;
+}
+interface LiveSubscription extends Disposable, AsyncDisposable {
+  /** App keys of the watched tables. */
+  readonly tables: readonly string[];
+  /** Tables the query reads that don't broadcast changes (not in `realtime.tables`). */
+  readonly unwatched: readonly string[];
+  readonly ready: Promise<void>;
+  unsubscribe(): Promise<void>;
+}
+/**
+ * A count from the server plus the spec to keep it live on the client:
+ * `next.liveCount(spec)` makes one, `useLiveCount(seed)` reads it. `count`
+ * is `null` when the server read failed; the client then fetches it.
+ */
+interface LiveCountSeed<T extends string = string> {
+  readonly spec: QuerySpec<T, "count", number>;
+  readonly count: number | null;
+}
+/** Topic a `realtime-tables` trigger broadcasts on: `bs:t:<schema>.<table>[:<tenant>]`. */
+declare function liveTopic(meta: SchemaMeta, table: string, tenant?: string): string;
+/**
+ * Calls `onChange` when a table the spec reads changes, so you can refetch.
+ * Needs the `realtime-tables` SQL module and the tables in
+ * `realtime.tables`. Live queries on the same client share one channel per
+ * table, so any number of them can run at once.
+ *
+ * ```ts
+ * using live = liveQuery(sb, supabase, spec, { onChange: () => refetch() });
+ * ```
+ */
+declare function liveQuery(sb: LiveSource, client: RealtimeClient, spec: QuerySpec | readonly string[], options: LiveQueryOptions): LiveSubscription;
+/** What `liveCount` runs the spec with: a `db` from `sb.connect()` or `createBrowser()`. */
+interface CountRunner {
+  $run(spec: QuerySpec): PromiseLike<Result<unknown>>;
+}
+interface LiveCountOptions extends Omit<LiveQueryOptions, "onChange"> {
+  readonly onCount: (count: number) => void;
+  /** A failed refetch; the previous count stays valid. */
+  readonly onError?: (error: DbError) => void;
+  /** Count right away. Defaults to `true`; pass `false` when you have a seed. */
+  readonly immediate?: boolean;
+}
+/**
+ * Keeps a count current: runs the `count` spec (a HEAD request) now, after
+ * each debounced change to a table it reads, and after the channel rejoins.
+ * Responses that arrive out of order are dropped.
+ *
+ * ```ts
+ * using live = liveCount(sb, supabase, db, sb.spec.notes.count(), {
+ *   onCount: (count) => render(count),
+ * });
+ * ```
+ */
+declare function liveCount(sb: LiveSource, client: RealtimeClient, db: CountRunner, spec: QuerySpec<string, "count", number>, options: LiveCountOptions): LiveSubscription;
+//#endregion
+export { defineTopic as C, TriggerOptions as S, TopicEvent as _, LiveSource as a, TopicOptions as b, liveQuery as c, RealtimeClient as d, RowChange as f, Topic as g, SubscriptionStatus as h, LiveQueryOptions as i, liveTopic as l, Subscription as m, LiveCountOptions as n, LiveSubscription as o, SubscribeOptions as p, LiveCountSeed as r, liveCount as s, CountRunner as t, EventSchemas as u, TopicHandlers as v, rowChange as w, TopicPayload as x, TopicMessage as y };

package/dist/logger-glM28NVN.js

@@ -0,0 +1,21 @@
+//#region src/core/logger.ts
+const log = (method) => (message, fields) => {
+	if (fields === void 0) console[method](`better-supabase: ${message}`);
+	else console[method](`better-supabase: ${message}`, fields);
+};
+/** The default: `console`, with a `better-supabase:` prefix. */
+const consoleLogger = {
+	debug: log("debug"),
+	info: log("info"),
+	warn: log("warn"),
+	error: log("error")
+};
+const noop = () => {};
+const silentLogger = {
+	debug: noop,
+	info: noop,
+	warn: noop,
+	error: noop
+};
+//#endregion
+export { silentLogger as n, consoleLogger as t };

package/dist/mcp/index.d.ts

@@ -0,0 +1,142 @@
+import { N as TableKey, n as AnyModels, t as AnyFunctions } from "../types-C83v5SQz.js";
+import { t as BetterSupabase } from "../define-e3zI4_4g.js";
+import { d as ServerContext, f as ServerOptions, l as BetterServer, n as GuardOptions } from "../respond-Dne1ARSa.js";
+import { i as ResourceRouteOptions } from "../resource-CgZa3YG_.js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/mcp/index.d.ts
+export declare const MCP_PROTOCOL_VERSION: string;
+type Json = Readonly<Record<string, unknown>>;
+/** MCP tool annotations (hints for clients, not guarantees). */
+export interface ToolAnnotations {
+  readonly title?: string;
+  readonly readOnlyHint?: boolean;
+  readonly destructiveHint?: boolean;
+  readonly idempotentHint?: boolean;
+  readonly openWorldHint?: boolean;
+}
+/** A tool as listed by `tools/list`. */
+export interface ToolInfo {
+  readonly name: string;
+  readonly title?: string;
+  readonly description?: string;
+  readonly inputSchema: Json;
+  readonly outputSchema?: Json;
+  readonly annotations?: ToolAnnotations;
+}
+export interface ToolContext<M extends AnyModels, F extends AnyFunctions, E> extends ServerContext<M, F, E> {
+  readonly request: Request;
+  readonly signal: AbortSignal;
+}
+export interface McpTool<M extends AnyModels, F extends AnyFunctions, E> {
+  readonly info: ToolInfo;
+  /** Validates arguments; its output is what `run` receives. */
+  readonly input?: StandardSchemaV1;
+  /** Opaque data for the `authorize` and `visible` hooks. Never sent to clients. */
+  readonly meta?: unknown;
+  run(args: never, ctx: ToolContext<M, F, E>): unknown;
+}
+/** What the `authorize` and `visible` hooks see of a tool. */
+export interface ToolRef {
+  readonly info: ToolInfo;
+  /** The tool's `meta`, e.g. a PermDock permission. `undefined` for table tools. */
+  readonly meta: unknown;
+}
+/** The outcome of `authorize`. `scopes` turns a refusal into an OAuth challenge. */
+export type ToolDecision = {
+  readonly allowed: true;
+} | {
+  readonly allowed: false;
+  readonly reason?: string;
+  /** OAuth scopes the call needs, sent in an `insufficient_scope` challenge. */
+  readonly scopes?: readonly string[];
+};
+export interface ToolDefinition<M extends AnyModels, F extends AnyFunctions, E, I> {
+  readonly name: string;
+  readonly title?: string;
+  readonly description: string;
+  /**
+   * Validator for the arguments. Its JSON Schema comes from Standard JSON
+   * Schema (zod 4, arktype, valibot) unless `inputSchema` is given.
+   */
+  readonly input?: StandardSchemaV1<unknown, I>;
+  readonly inputSchema?: Json;
+  readonly outputSchema?: Json;
+  readonly annotations?: ToolAnnotations;
+  /** Opaque data for the `authorize` and `visible` hooks. Never sent to clients. */
+  readonly meta?: unknown;
+  run(args: I, ctx: ToolContext<M, F, E>): unknown;
+}
+export type ToolResources<M extends AnyModels> = { readonly [T in TableKey<M>]?: ResourceRouteOptions<M, T> | true; };
+export interface McpOptions<M extends AnyModels, F extends AnyFunctions, E> extends ServerOptions, GuardOptions {
+  readonly name: string;
+  readonly version: string;
+  readonly title?: string;
+  /** Sent to clients on `initialize`, e.g. how the tools fit together. */
+  readonly instructions?: string;
+  /** Tables exposed as tools: `<table>_list`, `_get`, `_create`, `_update`, `_delete`. */
+  readonly resources?: ToolResources<M>;
+  readonly tools?: readonly McpTool<M, F, E>[];
+  /**
+   * Canonical URL of this MCP server (RFC 9728 `resource`). Defaults to the
+   * request URL without query.
+   */
+  readonly resource?: string | ((request: Request) => string);
+  /** Defaults to Supabase Auth of `env.url` (`<url>/auth/v1`). */
+  readonly authorizationServers?: readonly string[];
+  /**
+   * Scopes the tools need, published as RFC 9728 `scopes_supported` and in
+   * `insufficient_scope` challenges. `offline_access` is left out: refresh
+   * tokens are between the client and the authorization server.
+   */
+  readonly scopes?: readonly string[];
+  /** Origins allowed to call the server (DNS rebinding protection). Defaults to any. */
+  readonly allowedOrigins?: readonly string[];
+  /** Custom jsonb types, as in `createOpenApi`. */
+  readonly json?: Readonly<Record<string, unknown>>;
+  /** Include internal error messages in tool results. Defaults to `NODE_ENV === 'development'`. */
+  readonly exposeErrors?: boolean;
+  /**
+   * Decides each `tools/call` after the arguments are validated and before
+   * `run`. `args` are the validated arguments (raw for table tools, which
+   * validate in the repository). A refusal is a tool error; a refusal with
+   * `scopes` is a 403 `insufficient_scope` challenge naming them.
+   */
+  readonly authorize?: (ctx: ToolContext<M, F, E>, tool: ToolRef, args: unknown) => ToolDecision | Promise<ToolDecision>;
+  /**
+   * Whether the caller sees a tool in `tools/list`. A hidden tool is called
+   * like an unknown one. Lists are cached per token (`cacheScope: 'private'`).
+   */
+  readonly visible?: (ctx: ToolContext<M, F, E>, tool: ToolRef) => boolean | Promise<boolean>;
+}
+export interface BetterMcp<M extends AnyModels, F extends AnyFunctions, E> extends BetterServer<M, F, E> {
+  /** Everything in one handler: the MCP endpoint and `/.well-known/oauth-protected-resource`. */
+  readonly fetch: (request: Request) => Promise<Response>;
+  /** The Streamable HTTP endpoint (POST JSON-RPC). */
+  readonly handler: (request: Request) => Promise<Response>;
+  /** RFC 9728 protected resource metadata. */
+  metadata(request: Request): Response;
+  readonly tools: readonly ToolInfo[];
+  /** Adds a tool typed against this app's repositories. */
+  tool<I = Record<string, unknown>>(definition: ToolDefinition<M, F, E, I>): this;
+  /** Calls a tool directly, e.g. from tests or another transport. */
+  call(name: string, args: unknown, ctx: ToolContext<M, F, E>): Promise<ToolResult>;
+}
+export interface ToolResult {
+  readonly content: readonly {
+    readonly type: "text";
+    readonly text: string;
+  }[];
+  readonly structuredContent?: Json;
+  readonly isError?: boolean;
+}
+/** A custom tool. Pass it in `createMcp({ tools: [...] })`. */
+export declare function defineTool<M extends AnyModels, F extends AnyFunctions, E, I = Record<string, unknown>>(definition: ToolDefinition<M, F, E, I>): McpTool<M, F, E>;
+/**
+ * An MCP server (Streamable HTTP, stateless) whose tools run as the caller:
+ * the Bearer token from the MCP client is verified and every query goes
+ * through RLS. Answers 401 with RFC 9728 metadata so clients can sign in with
+ * Supabase Auth's OAuth server.
+ */
+export declare function createMcp<M extends AnyModels, D, F extends AnyFunctions, E>(sb: BetterSupabase<M, D, F, E>, options: McpOptions<M, F, E>): BetterMcp<M, F, E>;
+//#endregion
+export type { GuardOptions, ResourceRouteOptions };