better-supabase 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ScaleDock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,90 @@
 # better-supabase
 
-This is a stub package published by setup-trusted-publishing to enable OIDC trusted publishing configuration.
+**A typed data layer, auth glue and CLI for Supabase apps, APIs, MCP servers and jobs.**
+
+[![npm](https://img.shields.io/npm/v/better-supabase)](https://www.npmjs.com/package/better-supabase)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/ScaleDockHQ/better-supabase/blob/main/LICENSE)
+![TypeScript](https://img.shields.io/badge/TypeScript-5.9%20%7C%206%20%7C%207-3178c6.svg)
+
+`better-supabase gen` extends `supabase gen types` with relation cardinality, unique keys, CHECK unions and typed jsonb. The generated `schema` gives every table a typed repository that compiles to one PostgREST request, returns a `Result` instead of throwing, and runs as the caller so RLS always applies.
+
+## Install
+
+```bash
+pnpm add better-supabase @supabase/supabase-js
+pnpm add -D pg
+```
+
+ESM only. Node 24 or later for the CLI; the runtime entries run on every WinterTC runtime (Node, Deno, Bun, Workers, Supabase Edge Functions). TypeScript 5.9, 6 and 7 are tested.
+
+## Quick start
+
+```bash
+supabase start
+pnpm better-supabase init   # config, src/lib/supabase.ts and framework glue
+pnpm better-supabase gen    # database.types.ts and generated.ts
+```
+
+```ts
+import { createClient } from '@supabase/supabase-js';
+import { defineSupabase } from 'better-supabase';
+
+import { schema } from './lib/supabase/generated.ts';
+
+export const sb = defineSupabase(schema);
+
+const db = sb.connect(createClient(url, publishableKey));
+
+const result = await db.customers.findMany({
+  select: ['id', 'name'],
+  where: { status: 'active', notes: { some: { kind: 'call' } } },
+  include: { organization: { select: ['name'] } },
+  orderBy: { name: 'asc' },
+  limit: 20,
+});
+if (!result.ok) return result; // DbError: kind, message, status, code
+```
+
+## Subpaths
+
+| Import | What it gives you |
+| --- | --- |
+| `better-supabase` | `defineSupabase`, repositories, `Result`, `DbError`, `SPEC_PINS` |
+| `better-supabase/config` | `defineConfig` and generators for `better-supabase.config.ts` |
+| `better-supabase/client` | Browser repositories that follow the session |
+| `better-supabase/react` | Provider, typed hooks and the server session |
+| `better-supabase/query` | TanStack Query options with table-based invalidation |
+| `better-supabase/server` | Repositories bound to the caller, admin and acting-as identities |
+| `better-supabase/postgres` | The same repositories over direct Postgres |
+| `better-supabase/ssr` | The `@supabase/ssr` cookie format for any framework |
+| `better-supabase/next`, `/next/image` | Proxy, Server Components, route handlers, server actions, Storage images |
+| `better-supabase/hono`, `/orpc`, `/edge` | Framework adapters |
+| `better-supabase/mcp` | MCP servers whose tools run as the signed-in user |
+| `better-supabase/jobs` | Supabase Queues jobs, idempotency keys and a webhook inbox |
+| `better-supabase/list` | Search, facets, sorting and pagination from one definition |
+| `better-supabase/storage`, `/realtime` | Typed bucket paths and broadcast topics |
+| `better-supabase/env` | Validated Supabase settings |
+| `better-supabase/events`, `/webhooks`, `/openapi`, `/otel` | CloudEvents, Standard Webhooks, OpenAPI 3.1 and OpenTelemetry |
+| `better-supabase/plugins/*` | Timestamps, soft delete, tenant, actor, validation and runtime rules |
+| `better-supabase/lint` | Editor rules for unbounded reads and unscoped deletes |
+| `better-supabase/testing` | `asUser`, `localAuth`, typed seeds and conformance kits |
+
+## For AI agents
+
+The package ships [Agent Skills](https://agentskills.io) in `skills/`:
+
+```bash
+npx skills add ScaleDockHQ/better-supabase
+# or, from the installed version:
+pnpm better-supabase skills install
+```
+
+The docs are also available as [`/llms.txt`](https://bettersupabase.com/llms.txt), as Markdown at `/docs/<page>.md`, and through the docs MCP server at `https://bettersupabase.com/mcp`.
+
+## Documentation
+
+[bettersupabase.com/docs](https://bettersupabase.com/docs)
+
+## License
+
+[MIT](https://github.com/ScaleDockHQ/better-supabase/blob/main/LICENSE)

package/bin/better-supabase.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+// Checked in so pnpm can link the bin on a fresh install, before dist/ is built.
+import '../dist/cli/bin.js';

package/dist/casing-da0uRTqt.js

@@ -0,0 +1,14 @@
+//#region src/casing/index.ts
+/** `first_name` to `firstName`. Leaves already camel-cased names untouched. */
+function toCamel(name) {
+	return name.replace(/_+([a-z0-9])/g, (_, char) => char.toUpperCase());
+}
+/** `firstName` to `first_name`. */
+function toSnake(name) {
+	return name.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/([A-Z])([A-Z][a-z])/g, "$1_$2").toLowerCase();
+}
+function applyCasing(name, casing) {
+	return casing === "camel" ? toCamel(name) : name;
+}
+//#endregion
+export { toCamel as n, toSnake as r, applyCasing as t };

package/dist/cli/bin.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/cli/bin.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { i as run } from "../cli-CoByWYja.js";
+//#region src/cli/bin.ts
+const controller = new AbortController();
+process.once("SIGINT", () => controller.abort());
+process.once("SIGTERM", () => controller.abort());
+const result = await run(process.argv.slice(2), {
+	signal: controller.signal,
+	io: {
+		stdout: (text) => process.stdout.write(text),
+		stderr: (text) => process.stderr.write(text)
+	}
+});
+process.exitCode = result.code;
+//#endregion

package/dist/cli/index.d.ts

@@ -0,0 +1,226 @@
+import { $ as ExtrasHook, B as CatalogCheck, G as CatalogFunctionArg, H as CatalogEnum, J as CatalogPolicy, K as CatalogGrant, Q as ExtrasFunction, U as CatalogForeignKey, V as CatalogColumn, W as CatalogFunction, X as CatalogTrigger, Y as CatalogTable, Z as CatalogUnique, at as SnapshotExtras, et as ExtrasHookFunction, it as SnapshotBucket, l as GeneratedFile, nt as ForeignKeyAction, ot as GeneratorMetadata, q as CatalogIndex, rt as Snapshot, st as Queryable, tt as ExtrasTable, v as ResolvedConfig, z as Catalog } from "../index-BD6wKthp.js";
+import { A as TableMeta, E as SchemaMeta, f as FunctionMeta, i as Casing, o as Codec, x as RelationMeta } from "../types-C2fslP1z.js";
+//#region src/cli/args.d.ts
+type FlagValue = string | boolean | readonly string[];
+interface ParsedArgs {
+  readonly command: string | undefined;
+  readonly rest: readonly string[];
+  readonly flags: Readonly<Record<string, FlagValue>>;
+}
+//#endregion
+//#region src/cli/io.d.ts
+interface CliIo {
+  readonly stdout: (text: string) => void;
+  readonly stderr: (text: string) => void;
+  readonly now?: () => Date;
+  /** Environment; defaults to `process.env`. */
+  readonly env?: Readonly<Record<string, string | undefined>>;
+}
+interface RunResult {
+  readonly code: number;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+interface CommandResult {
+  readonly code: number;
+  readonly output?: string;
+  readonly error?: string;
+}
+//#endregion
+//#region src/cli/run.d.ts
+export declare const HELP: string;
+type Command = (context: CommandContext) => Promise<CommandResult>;
+interface CommandContext {
+  readonly args: ParsedArgs;
+  readonly cwd: string;
+  readonly config: ResolvedConfig;
+  readonly io: CliIo;
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly signal: AbortSignal | undefined;
+}
+/** Registers a command; the built-in commands register themselves below. */
+export declare function registerCommand(name: string, command: Command, help?: string): void;
+interface RunOptions {
+  readonly cwd?: string;
+  readonly io?: CliIo;
+  readonly signal?: AbortSignal;
+}
+/** Runs the CLI. Never exits the process; returns the exit code and output. */
+export declare function run(argv: readonly string[], options?: RunOptions): Promise<RunResult>;
+//#endregion
+//#region src/cli/introspect/source.d.ts
+/** A connection introspection can query, plus how to release it. */
+interface IntrospectionSource {
+  readonly queryable: Queryable;
+  readonly describe: string;
+  close(): Promise<void>;
+}
+/**
+ * A `pg` connection. Typegen issues its queries concurrently; one `pg.Client`
+ * must run them one at a time, so calls are queued.
+ */
+export declare function pgSource(url: string): Promise<IntrospectionSource>;
+interface ManagementSourceOptions {
+  readonly projectRef: string;
+  readonly accessToken: string;
+  /** Defaults to `https://api.supabase.com`. */
+  readonly apiUrl?: string;
+  readonly fetch?: typeof fetch;
+}
+/**
+ * Runs introspection SQL through the Supabase Management API as the
+ * read-only database user, so hosted projects need no database password.
+ */
+export declare function managementSource(options: ManagementSourceOptions): IntrospectionSource;
+//#endregion
+//#region src/cli/commands/snapshot.d.ts
+interface SnapshotSource {
+  readonly snapshotPath?: string;
+  readonly dbUrl?: string;
+  readonly projectRef?: string;
+  /** Ignore `source.snapshot` and read the database. */
+  readonly live?: boolean;
+}
+type Env = Readonly<Record<string, string | undefined>>;
+/** Loads a saved snapshot or introspects the database. */
+export declare function loadSnapshot(config: ResolvedConfig, env: Env, source: SnapshotSource): Promise<Snapshot>;
+/** Validates a parsed snapshot document. */
+export declare function parseSnapshot(data: unknown, label?: string): Snapshot;
+export declare function serializeSnapshot(snapshot: Snapshot): string;
+//#endregion
+//#region src/cli/commands/gen.d.ts
+interface GenOptions extends SnapshotSource {
+  readonly config: ResolvedConfig;
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly check: boolean;
+  /** Pre-loaded snapshot (tests, watch mode). */
+  readonly snapshot?: Snapshot;
+}
+/**
+ * Renders every generated file for a snapshot, without touching disk:
+ * `database.types.ts` (what `supabase gen types` prints), the main module,
+ * then each configured generator's files.
+ */
+export declare function renderFiles(config: ResolvedConfig, snapshot: Snapshot): Promise<GeneratedFile[]>;
+export declare function runGen(options: GenOptions): Promise<CommandResult>;
+//#endregion
+//#region src/cli/introspect/extras.d.ts
+/** A hook function to introspect: `[auth.hook.<hook>]` pointing at `schema.name`. */
+interface HookTarget {
+  readonly hook: string;
+  readonly schema: string;
+  readonly name: string;
+}
+//#endregion
+//#region src/cli/introspect/catalog.d.ts
+/** Joins the typegen metadata and the extras into one record per object. */
+export declare function toCatalog(snapshot: Snapshot): Catalog;
+//#endregion
+//#region src/cli/introspect/index.d.ts
+interface IntrospectOptions {
+  /** Auth hook functions to read too, in any schema (`[auth.hook.*]`). */
+  readonly hooks?: readonly HookTarget[];
+}
+/** Reads a v2 snapshot: typegen metadata plus the extras. */
+export declare function introspect(db: Queryable, schemas: readonly string[], options?: IntrospectOptions): Promise<Snapshot>;
+//#endregion
+//#region src/cli/introspect/from-catalog.d.ts
+/**
+ * Builds a snapshot from catalog records: the inverse of `toCatalog`. Tests
+ * and benchmarks describe schemas as tables and functions; this produces the
+ * typegen metadata and extras those records imply.
+ */
+export declare function fromCatalog(catalog: Catalog): Snapshot;
+//#endregion
+//#region src/cli/gen/model.d.ts
+interface ColumnModel {
+  readonly app: string;
+  readonly db: string;
+  readonly snapshot: CatalogColumn;
+  /** TypeScript type without `| null`. */
+  readonly tsType: string;
+  readonly nullable: boolean;
+  /** Optional on insert. */
+  readonly optional: boolean;
+  /** Not writable (generated always / identity always). */
+  readonly readonly: boolean;
+  readonly values: readonly string[] | undefined;
+  readonly json: boolean;
+  readonly codec: Codec | undefined;
+  /** Bucket id from `config.storagePaths`. */
+  readonly storage: string | undefined;
+  readonly insertable: boolean;
+  readonly updatable: boolean;
+}
+interface RelationModel {
+  readonly name: string;
+  readonly meta: RelationMeta;
+}
+interface TableModel {
+  readonly key: string;
+  readonly snapshot: CatalogTable;
+  readonly casing: Casing;
+  readonly columns: readonly ColumnModel[];
+  readonly relations: readonly RelationModel[];
+  readonly meta: TableMeta;
+}
+interface EnumModel {
+  readonly schema: string;
+  readonly name: string;
+  /** Constant name for the value array, e.g. `noteKindValues`. */
+  readonly constant: string;
+  readonly values: readonly string[];
+}
+interface FunctionModel {
+  readonly key: string;
+  readonly meta: FunctionMeta;
+  readonly args: readonly {
+    name: string;
+    tsType: string;
+    optional: boolean;
+  }[];
+  readonly returns: string;
+}
+interface JsonImport {
+  readonly name: string;
+  /** Path relative to the project root, without the `#Name` part. */
+  readonly from: string;
+}
+interface Model {
+  readonly tables: readonly TableModel[];
+  readonly enums: readonly EnumModel[];
+  readonly functions: readonly FunctionModel[];
+  readonly jsonImports: readonly JsonImport[];
+  readonly meta: SchemaMeta;
+  readonly config: ResolvedConfig;
+  readonly catalog: Catalog;
+  /** Typegen metadata restricted to the configured schemas. */
+  readonly introspection: GeneratorMetadata;
+}
+/** Builds the codegen model from a snapshot and config. */
+export declare function buildModel(snapshot: Snapshot, config: ResolvedConfig): Model;
+//#endregion
+//#region src/cli/gen/emit.d.ts
+export declare const GENERATED_HEADER = "// @generated by better-supabase gen. Do not edit; run `better-supabase gen` instead.";
+interface EmitOptions {
+  /** Import path from the generated module to `better-supabase`. */
+  readonly runtimeImport?: string;
+  /** Import path from the generated module to `database.types.ts`. */
+  readonly databaseTypesImport?: string;
+  /** Import path for each JSON type import, keyed by the configured path. */
+  readonly importPathFor: (from: string) => string;
+}
+/** Renders the generated module. */
+export declare function emitModule(model: Model, options: EmitOptions): string;
+//#endregion
+//#region src/cli/config.d.ts
+/**
+ * Loads the config with a native `import()`. Node 24 strips types from
+ * `.ts` files, so no loader is needed.
+ */
+export declare function loadConfig(cwd: string, explicit?: string): Promise<ResolvedConfig>;
+//#endregion
+//#region src/cli/version.d.ts
+export declare const VERSION = "0.0.0";
+//#endregion
+export type { Catalog, CatalogCheck, CatalogColumn, CatalogEnum, CatalogForeignKey, CatalogFunction, CatalogFunctionArg, CatalogGrant, CatalogIndex, CatalogPolicy, CatalogTable, CatalogTrigger, CatalogUnique, CliIo, Command, CommandContext, CommandResult, ExtrasFunction, ExtrasHook, ExtrasHookFunction, ExtrasTable, ForeignKeyAction, GeneratorMetadata, IntrospectionSource, ManagementSourceOptions, Queryable, RunOptions, RunResult, Snapshot, SnapshotBucket, SnapshotExtras };

package/dist/cli/index.js

@@ -0,0 +1,3 @@
+import { t as VERSION } from "../version-Cqq1m3UY.js";
+import { _ as emitModule, a as renderFiles, c as parseSnapshot, d as managementSource, f as pgSource, g as GENERATED_HEADER, h as toCatalog, i as run, l as serializeSnapshot, m as buildModel, n as HELP, o as runGen, p as loadConfig, r as registerCommand, s as loadSnapshot, t as fromCatalog, u as introspect } from "../cli-CoByWYja.js";
+export { GENERATED_HEADER, HELP, VERSION, buildModel, emitModule, fromCatalog, introspect, loadConfig, loadSnapshot, managementSource, parseSnapshot, pgSource, registerCommand, renderFiles, run, runGen, serializeSnapshot, toCatalog };