better-supabase 0.0.0 → 0.2.0

package/dist/index-Bw1bwtC0.d.ts

@@ -0,0 +1,144 @@
+import { N as TableKey, O as Row, n as AnyModels, t as AnyFunctions } from "./types-C83v5SQz.js";
+import { l as CountMode } from "./executor-CGdNQ27g.js";
+import { b as ValidationIssue, t as AsyncResult } from "./result-CTkCZ6JA.js";
+import { C as FindExt, Ct as WhereInput, O as RepositoryOf, T as OffsetPageArgs, dt as IncludeArg, gt as OrderByArg, t as BetterSupabase, vt as Payload, w as OffsetPage, xt as SelectArg } from "./define-e3zI4_4g.js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/list/index.d.ts
+/** Facet value meaning "not set": filters with `is null`. */
+declare const UNSET = "__unset__";
+type Column<M extends AnyModels, T extends keyof M> = Extract<keyof Row<M, T>, string>;
+type TextColumn<M extends AnyModels, T extends keyof M> = { [K in Column<M, T>]: [NonNullable<Row<M, T>[K]>] extends [string] ? K : never; }[Column<M, T>];
+interface ListQueryConfig<M extends AnyModels, T extends keyof M, S extends string, F extends string, C extends boolean = boolean> {
+  /**
+   * Also count rows per facet value, with one grouped aggregate that runs
+   * next to the page: 2 calls, 1 wave. Needs PostgREST aggregates.
+   */
+  readonly facetCounts?: C;
+  /** How the page total is counted. Defaults to `'exact'`. */
+  readonly count?: CountMode;
+  /** Text columns matched case-insensitively (OR), or a full-text column. */
+  readonly search?: readonly TextColumn<M, T>[] | {
+    readonly fts: Column<M, T>;
+    readonly config?: string;
+  };
+  /** Filterable columns by URL key. Values are validated against enums and CHECK unions. */
+  readonly facets?: { readonly [K in F]: Column<M, T>; };
+  /** Named orderings. Add a unique column last for stable pages. */
+  readonly sorts: { readonly [K in S]: OrderByArg<M, T>; };
+  readonly defaultSort: NoInfer<S>;
+  /** Defaults to 50. */
+  readonly pageSize?: number;
+  /** Defaults to 200. */
+  readonly maxPageSize?: number;
+  /** Defaults to 200 characters. */
+  readonly maxSearchLength?: number;
+}
+interface ListQuery<S extends string, F extends string> {
+  readonly q?: string;
+  readonly sort: S;
+  /** 1-based. */
+  readonly page: number;
+  readonly size: number;
+  readonly facets: { readonly [K in F]?: readonly string[]; };
+}
+/** Typed input (JSON APIs, actions, MCP tools). Everything is optional. */
+interface ListQueryInput<S extends string, F extends string> {
+  readonly q?: string;
+  readonly sort?: S;
+  readonly page?: number;
+  readonly size?: number;
+  readonly facets?: { readonly [K in F]?: readonly string[]; };
+}
+/** URL input: `URLSearchParams` or a Next.js `searchParams` record. */
+type ListSearchParams = URLSearchParams | Readonly<Record<string, string | readonly string[] | undefined>>;
+type ListParseResult<S extends string, F extends string> = {
+  readonly ok: true;
+  readonly value: ListQuery<S, F>;
+  readonly issues?: undefined;
+} | {
+  readonly ok: false;
+  readonly value?: undefined;
+  readonly issues: readonly ValidationIssue[];
+};
+interface ParserSpec<V> {
+  parse(value: string): V | null;
+  serialize(value: V): string;
+}
+interface OpenApiParameter {
+  readonly name: string;
+  readonly in: "query";
+  readonly required: false;
+  readonly description: string;
+  readonly schema: Readonly<Record<string, unknown>>;
+  readonly style?: "form";
+  readonly explode?: boolean;
+}
+interface FacetInfo {
+  readonly key: string;
+  readonly column: string;
+  readonly nullable: boolean;
+  /** Allowed values when the column is an enum or CHECK union. */
+  readonly values?: readonly string[];
+}
+/** Rows per facet value, keyed by facet and then by value (`UNSET` for empty). */
+type FacetCounts<F extends string> = { readonly [K in F]: Readonly<Record<string, number>>; };
+/** A page of a list; with `facetCounts: true`, also the counts per facet value. */
+type ListPage<R, F extends string, C extends boolean> = OffsetPage<R> & ([C] extends [true] ? {
+  readonly facetCounts: FacetCounts<F>;
+} : [C] extends [false] ? unknown : {
+  readonly facetCounts?: FacetCounts<F>;
+});
+interface ListDefinition<M extends AnyModels, T extends TableKey<M>, E, S extends string, F extends string, C extends boolean = false> {
+  readonly table: T;
+  readonly defaults: ListQuery<S, F>;
+  readonly facets: readonly FacetInfo[];
+  /** Validates typed input or URL params. Also a Standard Schema (`schema`). */
+  parse(input: ListQueryInput<S, F> | ListSearchParams | undefined): ListParseResult<S, F>;
+  readonly schema: StandardSchemaV1<ListQueryInput<S, F> | ListSearchParams | undefined, ListQuery<S, F>>;
+  /** URL params, leaving out defaults. */
+  toSearchParams(query: Partial<ListQuery<S, F>>): URLSearchParams;
+  /** `{ parse, serialize }` per URL key, for routers and nuqs (`list.nuqs(createParser)`). */
+  readonly parsers: ListParsers<S, F>;
+  nuqs<P>(createParser: (spec: ParserSpec<unknown>) => P): { readonly [K in keyof ListParsers<S, F>]: P; };
+  /** Repository arguments: `where`, `orderBy`, `page`, `size`, `count`. */
+  args(query: ListQuery<S, F>): OffsetPageArgs<M, T>;
+  /**
+   * Runs the list against a table, merging your `select`, `include`, `where`
+   * and `count`. One request, plus one for `facetCounts`, always one wave.
+   */
+  run<const A extends ListExtra<M, T> & FindExt<E, M, T>>(db: { readonly [K in T]: RepositoryOf<M, K, E>; }, query: ListQuery<S, F>, extra?: A): AsyncResult<ListPage<Payload<M, T, A>, F, C>>;
+  /** OpenAPI 3.1 query parameters. */
+  readonly openapi: readonly OpenApiParameter[];
+  /** JSON Schema of the typed input, e.g. for MCP tool arguments. */
+  readonly jsonSchema: Readonly<Record<string, unknown>>;
+}
+interface ListExtra<M extends AnyModels, T extends keyof M> {
+  readonly select?: SelectArg<M, T>;
+  readonly include?: IncludeArg<M, T>;
+  readonly where?: WhereInput<M, T>;
+  /** Overrides the config's `count` for this run. */
+  readonly count?: CountMode;
+}
+type ListParsers<S extends string, F extends string> = {
+  readonly q: ParserSpec<string>;
+  readonly sort: ParserSpec<S>;
+  readonly page: ParserSpec<number>;
+  readonly size: ParserSpec<number>;
+} & { readonly [K in F]: ParserSpec<readonly string[]>; };
+/**
+ * A reusable list endpoint for one table: search, facets, sorts and
+ * pagination, validated from URL params or typed input, with URL parsers,
+ * OpenAPI parameters and a JSON Schema derived from the same definition.
+ *
+ * ```ts
+ * export const customerList = defineListQuery(sb, 'customers', {
+ *   search: ['name', 'kvk'],
+ *   facets: { status: 'status' },
+ *   sorts: { name: { name: 'asc' }, newest: [{ createdAt: 'desc' }, { id: 'asc' }] },
+ *   defaultSort: 'newest',
+ * });
+ * ```
+ */
+declare function defineListQuery<M extends AnyModels, D, Fn extends AnyFunctions, E, T extends TableKey<M>, const S extends string, const F extends string = never, const C extends boolean = false>(sb: BetterSupabase<M, D, Fn, E>, table: T, config: ListQueryConfig<M, T, S, F, C>): ListDefinition<M, T, E, S, F, C>;
+//#endregion
+export { ListPage as a, ListQuery as c, ListSearchParams as d, OpenApiParameter as f, defineListQuery as h, ListExtra as i, ListQueryConfig as l, UNSET as m, FacetInfo as n, ListParseResult as o, ParserSpec as p, ListDefinition as r, ListParsers as s, FacetCounts as t, ListQueryInput as u };

package/dist/index-CBDufH1M.d.ts

@@ -0,0 +1,120 @@
+import { p as DbError } from "./result-CTkCZ6JA.js";
+import { Z as QuerySpec } from "./define-e3zI4_4g.js";
+import { i as BrowserAuth, t as AuthSnapshot } from "./index-D4v7sncu.js";
+import { n as TemplateValues } from "./template-mbvlysOo.js";
+import { t as AuthSession } from "./view-D1s0wa0T.js";
+import { a as LiveSource, g as Topic, h as SubscriptionStatus, p as SubscribeOptions, r as LiveCountSeed, u as EventSchemas, v as TopicHandlers, y as TopicMessage } from "./live-DJyZMD6w.js";
+import "./entitlements-Dng-ctuT.js";
+import "./session-C3LxnQ0e.js";
+import { SupabaseClient } from "@supabase/supabase-js";
+import { ReactNode } from "react";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+import { QueryClient } from "@tanstack/query-core";
+//#region src/react/index.d.ts
+/** The parts of `createBrowser()` the provider needs. */
+interface BrowserLike {
+  readonly sb: LiveSource;
+  readonly supabase: SupabaseClient;
+  readonly auth: BrowserAuth;
+  readonly db: object;
+  readonly queries: object;
+}
+interface BetterSupabaseProviderProps {
+  readonly browser: BrowserLike;
+  /** better-supabase queries are removed when the user signs out or changes. */
+  readonly queryClient?: QueryClient;
+  readonly children?: ReactNode;
+}
+/** Provides the browser client to the hooks. */
+declare function BetterSupabaseProvider(props: BetterSupabaseProviderProps): ReactNode;
+/** The session state for UI: `loading`, `signed-out` or `signed-in` with the user and claims. */
+declare function useAuth(): AuthSnapshot;
+declare function useSupabase(): SupabaseClient;
+interface BetterHooks<B extends BrowserLike> {
+  /** Repositories bound to the current session. Re-renders when the user changes. */
+  readonly useDb: () => B["db"];
+  /** TanStack Query option factories: `useQuery(useQueries().customers.findMany())`. */
+  readonly useQueries: () => B["queries"];
+  readonly useSupabase: () => SupabaseClient;
+  readonly useAuth: () => AuthSnapshot;
+  /** `useSession()` typed by the browser's `sb.claims(schema)` and `sb.userMetadata(schema)`. */
+  readonly useSession: () => AuthSession<ClaimsOf<B>, ProfileOf<B>>;
+}
+/** The claims type of a browser's `sb.claims(schema)`, `unknown` without one. */
+type ClaimsOf<B extends BrowserLike> = B["sb"] extends {
+  readonly claimsSchema: StandardSchemaV1<unknown, infer C> | undefined;
+} ? C : unknown;
+/** The profile type of a browser's `sb.userMetadata(schema)`, `unknown` without one. */
+type ProfileOf<B extends BrowserLike> = B["sb"] extends {
+  readonly userMetadataSchema: StandardSchemaV1<unknown, infer P> | undefined;
+} ? P : unknown;
+/**
+ * Hooks typed for your schema.
+ *
+ * ```ts
+ * export const { useDb, useQueries, useAuth } = createHooks<typeof browser>();
+ * ```
+ */
+declare function createHooks<B extends BrowserLike>(): BetterHooks<B>;
+interface BroadcastOptions extends Omit<SubscribeOptions, "onStatus"> {
+  /**
+   * Refetch after each message: table keys (every query that read one of
+   * them), or a function returning query keys. Needs `queryClient` on the
+   * provider.
+   */
+  readonly invalidate?: readonly string[] | ((message: TopicMessage) => readonly (readonly unknown[])[]);
+}
+/**
+ * Subscribes to a topic while mounted. Pass `null` values to pause. It
+ * resubscribes when the topic or the signed-in user changes.
+ *
+ * ```ts
+ * useBroadcast(customersTopic, orgId ? { orgId } : null, {}, { invalidate: ['customers'] });
+ * ```
+ */
+declare function useBroadcast<P extends string, E extends EventSchemas>(topic: Topic<P, E>, values: TemplateValues<P> | null | undefined, handlers?: TopicHandlers<E>, options?: BroadcastOptions): SubscriptionStatus;
+interface LiveQueryHookOptions {
+  /**
+   * Tenant for tenant-scoped tables. Defaults to the `config.claims.tenant`
+   * claim (`tenant_id`, top-level or in `app_metadata`).
+   */
+  readonly tenant?: string;
+  /** Defaults to 100 ms. */
+  readonly debounceMs?: number;
+}
+/**
+ * Keeps a query fresh: invalidates every cached query that read a table the
+ * spec touches whenever one of them changes. Pass `null` to pause. It
+ * resubscribes when the spec, tenant or user changes.
+ *
+ * ```ts
+ * const spec = sb.spec.customers.findMany({ include: { notes: true } });
+ * const { data } = useQuery(q.$spec(spec));
+ * useLiveQuery(spec);
+ * ```
+ */
+declare function useLiveQuery(spec: QuerySpec | null | undefined, options?: LiveQueryHookOptions): SubscriptionStatus;
+interface LiveCountHookOptions extends LiveQueryHookOptions {
+  /** The count to show before the first fetch, e.g. from the server. */
+  readonly initial?: number;
+}
+interface LiveCount {
+  /** `undefined` until the first count arrives. */
+  readonly count: number | undefined;
+  readonly status: SubscriptionStatus;
+  /** The last failed refetch; the previous count stays. */
+  readonly error: DbError | undefined;
+}
+/**
+ * A count that stays current: refetches only the `count` spec (a HEAD
+ * request) after each debounced change to a table it reads, and after the
+ * channel rejoins. Takes a spec or a `next.liveCount()` seed; pass `null` to
+ * pause. Doesn't need a `QueryClient`.
+ *
+ * ```tsx
+ * const { count } = useLiveCount(seed); // seed = await next.liveCount(spec)
+ * ```
+ */
+declare function useLiveCount(source: QuerySpec<string, "count", number> | LiveCountSeed | null | undefined, options?: LiveCountHookOptions): LiveCount;
+//#endregion
+export { BrowserLike as a, LiveCountHookOptions as c, createHooks as d, useAuth as f, useSupabase as g, useLiveQuery as h, BroadcastOptions as i, LiveQueryHookOptions as l, useLiveCount as m, BetterSupabaseProvider as n, ClaimsOf as o, useBroadcast as p, BetterSupabaseProviderProps as r, LiveCount as s, BetterHooks as t, ProfileOf as u };

package/dist/index-CG69s15v.d.ts

@@ -0,0 +1,38 @@
+import { m as StoredSession } from "./resolve-CjHILk2w.js";
+import "./view-D1s0wa0T.js";
+import "./entitlements-Dng-ctuT.js";
+//#region src/auth/refresh.d.ts
+interface RefreshOptions {
+  readonly url: string;
+  readonly publishableKey: string;
+  /**
+   * Sends `Sb-Forwarded-For: ip` with the secret key, so Auth rate-limits the
+   * refresh by the user's IP (when IP forwarding is on for the project).
+   */
+  readonly forwardedFor?: {
+    readonly ip: string;
+    readonly secretKey: string;
+  };
+  readonly fetch?: typeof fetch;
+  readonly now?: () => number;
+}
+type RefreshOutcome = {
+  readonly ok: true;
+  readonly session: StoredSession;
+  /** Served from a concurrent or just-finished refresh of the same token. */
+  readonly shared?: boolean;
+} | {
+  readonly ok: false;
+  /** `rejected`: the refresh token is dead, sign the user out. `network`: keep the session and retry later. */
+  readonly reason: "rejected" | "network";
+  readonly status?: number;
+  readonly message: string;
+};
+/**
+ * Exchanges a refresh token for a new session. Concurrent calls with the same
+ * token share one request, and a successful result is reused for a short
+ * window so parallel requests carrying the old cookie converge on one session.
+ */
+declare function refreshSession(refreshToken: string, options: RefreshOptions): Promise<RefreshOutcome>;
+//#endregion
+export { RefreshOutcome as n, refreshSession as r, RefreshOptions as t };

package/dist/index-Ciu5Xlml.d.ts

@@ -0,0 +1,74 @@
+import { A as SchemaMeta } from "./types-C83v5SQz.js";
+import { a as EventHub, s as MutationNotice } from "./events-DOt3nSO-.js";
+import { l as MutationKind } from "./plugin-C4TR9J0Z.js";
+//#region src/events/index.d.ts
+/** A CloudEvents 1.0 event. Extension attributes are lowercase alphanumerics. */
+interface CloudEvent<T = unknown> {
+  readonly specversion: "1.0";
+  readonly id: string;
+  readonly source: string;
+  readonly type: string;
+  readonly subject?: string;
+  readonly time?: string;
+  readonly datacontenttype?: string;
+  readonly dataschema?: string;
+  readonly data?: T;
+  readonly [extension: string]: unknown;
+}
+declare const ROW_EVENT_TYPES: { readonly [K in MutationKind]: string; };
+interface RowEventData {
+  readonly table: string;
+  readonly row: Readonly<Record<string, unknown>>;
+}
+interface CloudEventOptions {
+  /** URI-reference of the producer, e.g. `https://crm.example.com` or `/crm`. */
+  readonly source: string;
+  /** Replaces the `dev.better-supabase` type prefix. */
+  readonly typePrefix?: string;
+  readonly id?: () => string;
+  readonly now?: () => Date;
+}
+/** Sends events somewhere: a queue, a bus, an outbox table, an HTTP endpoint. */
+interface EventSink {
+  send(events: readonly CloudEvent[]): void | Promise<void>;
+}
+/**
+ * One CloudEvent per mutated row: `dev.better-supabase.row.created` with the
+ * app-cased row as `data`, the primary key as `subject`, the tenant as
+ * `partitionkey` and the actor as `actorid`.
+ */
+declare function toCloudEvents(notice: MutationNotice, options: CloudEventOptions & {
+  readonly meta?: SchemaMeta;
+}): CloudEvent<RowEventData>[];
+interface ForwardOptions extends CloudEventOptions {
+  /** Only forward these tables or kinds. */
+  readonly filter?: (notice: MutationNotice) => boolean;
+  /** Sink failures never fail the mutation. Defaults to the `Logger`. */
+  readonly onError?: (error: unknown, events: readonly CloudEvent[]) => void;
+}
+/**
+ * Sends a CloudEvent for every mutation to `sink`. Returns a function that
+ * stops forwarding. Use an outbox (SQL kit) when events must not be lost.
+ */
+declare function forwardMutations(sb: {
+  readonly events: EventHub;
+  readonly meta: SchemaMeta;
+}, sink: EventSink, options: ForwardOptions): () => void;
+type HttpMode = "structured" | "binary" | "batch";
+/** The HTTP protocol binding: headers and body for one event (or a batch). */
+declare function toHttp(events: CloudEvent | readonly CloudEvent[], mode?: HttpMode): {
+  headers: Record<string, string>;
+  body: string;
+}[];
+declare function isCloudEvent(value: unknown): value is CloudEvent;
+/** Reads CloudEvents from a request in any of the three HTTP modes. */
+declare function fromHttp(request: Request): Promise<CloudEvent[]>;
+interface HttpSinkOptions {
+  readonly mode?: HttpMode;
+  readonly headers?: Readonly<Record<string, string>>;
+  readonly fetch?: typeof fetch;
+}
+/** POSTs events to `url`. Non-2xx responses reject. */
+declare function httpSink(url: string | URL, options?: HttpSinkOptions): EventSink;
+//#endregion
+export { HttpMode as a, RowEventData as c, httpSink as d, isCloudEvent as f, ForwardOptions as i, forwardMutations as l, toHttp as m, CloudEventOptions as n, HttpSinkOptions as o, toCloudEvents as p, EventSink as r, ROW_EVENT_TYPES as s, CloudEvent as t, fromHttp as u };

package/dist/index-D4v7sncu.d.ts

@@ -0,0 +1,62 @@
+import { n as AnyModels, t as AnyFunctions } from "./types-C83v5SQz.js";
+import { t as BetterSupabase, y as Db } from "./define-e3zI4_4g.js";
+import { c as PublicEnv } from "./index-Dy6kuF0P.js";
+import { i as Queries } from "./index-K-3WM2Hp.js";
+import { SupabaseClient } from "@supabase/supabase-js";
+//#region src/client/index.d.ts
+interface BrowserOptions {
+  /** URL and publishable key. Not needed when `client` is given. */
+  readonly env?: PublicEnv;
+  /** Bring your own supabase-js client (React Native, custom storage). */
+  readonly client?: SupabaseClient;
+  /**
+   * `cookies` (default) shares the session with the server through
+   * `@supabase/ssr`; `local` keeps it in localStorage for SPAs without a server.
+   */
+  readonly storage?: "cookies" | "local";
+}
+interface AuthUser {
+  readonly id: string;
+  readonly email?: string;
+  readonly role?: string;
+}
+/** What the UI needs to know. Claims are decoded, not verified: RLS enforces access. */
+type AuthSnapshot = {
+  readonly status: "loading";
+  readonly user: null;
+  readonly claims: null;
+} | {
+  readonly status: "signed-out";
+  readonly user: null;
+  readonly claims: null;
+} | {
+  readonly status: "signed-in";
+  readonly user: AuthUser;
+  readonly claims: Readonly<Record<string, unknown>>;
+};
+interface BrowserAuth {
+  readonly current: () => AuthSnapshot;
+  /** `useSyncExternalStore`-compatible. */
+  readonly subscribe: (listener: () => void) => () => void;
+}
+interface BetterBrowser<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P = unknown> {
+  /** The definition the browser was created from (schema metadata, specs, live queries). */
+  readonly sb: BetterSupabase<M, unknown, F, E, C, P>;
+  readonly supabase: SupabaseClient;
+  /** Repositories with the current session's actor and claims. */
+  readonly db: Db<M, F, E, SupabaseClient>;
+  /** TanStack Query option factories over `db`. */
+  readonly queries: Queries<M, E, F>;
+  readonly auth: BrowserAuth;
+}
+/**
+ * The browser side: a supabase-js client, repositories that follow the
+ * session, TanStack Query options and an auth store for UI state.
+ *
+ * ```ts
+ * export const browser = createBrowser(sb, { env: { url, publishableKey } });
+ * ```
+ */
+declare function createBrowser<M extends AnyModels, D, F extends AnyFunctions, E, C = unknown, P = unknown>(sb: BetterSupabase<M, D, F, E, C, P>, options?: BrowserOptions): BetterBrowser<M, F, E, C, P>;
+//#endregion
+export { BrowserOptions as a, BrowserAuth as i, AuthUser as n, createBrowser as o, BetterBrowser as r, AuthSnapshot as t };