@specific.dev/spectest 0.45.0 → 0.46.0

package/dist/components/supabase.d.ts

@@ -1,6 +1,7 @@
-import { type ServiceGroup, type ServicesMap } from "../index.js";
+import { type ServiceDefinition, type ServiceGroup, type ServicesMap } from "../index.js";
 import { type SqlClient } from "../sql.js";
 import { type EmailHelpers } from "./email.js";
+export type { MailTemplateId, MailTemplateSpec } from "./supabase-config.js";
 export interface SupabaseOptions {
     /**
      * Key of the API-gateway service and the prefix for every other piece.
@@ -22,25 +23,16 @@ export interface SupabaseOptions {
      * deterministically, so the warm-template cache stays stable.
      */
     jwtSecret?: string;
-    /** Studio dashboard Basic-Auth username (only relevant with `studio`). Default `"supabase"`. */
-    dashboardUsername?: string;
-    /** Studio dashboard Basic-Auth password (only relevant with `studio`). */
-    dashboardPassword?: string;
-    /** Include GoTrue auth (`<name>-auth`). Default `true`. */
-    auth?: boolean;
+    /**
+     * GoTrue auth. `false` drops it from the stack; an object configures the
+     * two settings that are **addresses in this environment** rather than
+     * behaviour — everything else about auth comes from your `config.toml`.
+     */
+    auth?: boolean | SupabaseAuthOptions;
     /** Include storage-api + imgproxy (`<name>-storage`, `<name>-imgproxy`). Default `true`. */
     storage?: boolean;
     /** Include Realtime (`<name>-realtime`). Default `true`. */
     realtime?: boolean;
-    /**
-     * Include the Studio dashboard (`<name>-studio`) and its postgres-meta
-     * backend (`<name>-meta`). Off by default — Studio is a heavy Next.js image
-     * and is only useful for interactive `ctx.browser()` exploration, not
-     * automated backend assertions. Turning it on implies `meta`.
-     */
-    studio?: boolean;
-    /** Include postgres-meta (`<name>-meta`). Defaults to whatever `studio` is. */
-    meta?: boolean;
     /**
      * Also serve the gateway over **HTTPS** at `https://<hostname>` via the
      * daemon's CA-trusted TLS reverse proxy (in addition to the plain
@@ -83,75 +75,130 @@ export interface SupabaseOptions {
         serviceRole?: string[];
     };
     /**
-     * Where the project's SQL migrations live, e.g. `"supabase/migrations"`
-     * (relative to the project root, or absolute). **Nothing is applied unless
-     * you set this** — there is no assumed path, so a project whose schema
-     * arrives some other way (an app that migrates itself at boot, a dump
-     * restored in `setup`) never gets a second, surprising source of DDL.
-     *
-     * Every `*.sql` directly in the directory is applied in sorted filename
-     * order, then — the standard Supabase layout — the **`seed.sql` beside
-     * that directory**, if there is one:
+     * The project's Supabase folder, e.g. `"supabase"` (relative to the project
+     * root, or absolute) — the layout `supabase init` creates and the CLI
+     * requires. This is the **only** way to point the stack at your project, and
+     * everything in the folder is used the way the Supabase CLI uses it:
      *
      * ```
      * supabase/
-     *   migrations/0001_init.sql   ← applied, sorted
-     *   migrations/0002_todos.sql
-     *   seed.sql                   ← applied last
+     *   config.toml     ← auth rules, mail templates, per-function JWT verification
+     *   migrations/     ← applied in filename order once the stack is up
+     *   seed.sql        ← applied after them, if it's there
+     *   functions/      ← one directory per function, served at /functions/v1/<name>
      * ```
      *
-     * It all runs **once the whole stack is up** — the same point `supabase db
-     * reset` applies migrations — so your SQL may use schema the services
-     * create when they boot (`storage.buckets`, the modern `auth.*` tables).
-     * PostgREST's schema cache is reloaded afterwards.
+     * `config.json` is read in preference to `config.toml` where a newer CLI has
+     * written one. Nothing is derived unless you name the folder, and each piece
+     * is optional inside it — a folder with only a `config.toml` is fine.
      *
-     * A path that doesn't resolve is an error at env start; a silent no-op
-     * there surfaces much later as a confusing `relation … does not exist`.
-     * Because `supabase/**` is project content, editing a migration correctly
-     * forces a cold rebuild and re-apply (unlike `spectest/tests/**`).
+     * There is deliberately no per-piece path option and no way to configure
+     * mail, OTP, redirect or JWT behaviour here: those live in `config.toml`,
+     * where your project already declares them and where the Supabase CLI reads
+     * them too. One source of truth, and the environment matches the one you run
+     * locally.
      */
-    migrations?: string;
+    dir?: string;
     /**
-     * Where the project's **edge functions** live, e.g.
-     * `"supabase/functions"` — one subdirectory per function, each with an
-     * entrypoint the runtime can serve (`supabase/functions/hello/index.ts`).
+     * The `.env` of this environment — the values your `config.toml` reads with
+     * `env(...)`.
      *
-     * **Nothing runs unless you set this.** Point at the directory and every
-     * function in it is served on the real Supabase edge runtime at
-     * `<url>/functions/v1/<name>` through the gateway — the same path
-     * `supabase.functions.invoke(...)` derives, so the app under test needs no
-     * override. Leave it unset and the runtime is left out of the stack
-     * entirely, along with the gateway's `/functions/v1` route.
+     * ```toml
+     * # supabase/config.toml
+     * [edge_runtime.secrets]
+     * STRIPE_KEY = "env(STRIPE_SECRET_KEY)"
+     * FEATURE_X  = "true"
      *
-     * Function code is read straight from the repo — nothing is copied or
-     * bundled — so editing a function is an ordinary project edit.
+     * [auth.external.google]
+     * client_id = "env(GOOGLE_OAUTH_CLIENT_ID)"
+     * ```
+     * ```ts
+     * supabase({
+     *   dir: "supabase",
+     *   env: {
+     *     STRIPE_SECRET_KEY: "sk_test_…",
+     *     GOOGLE_OAUTH_CLIENT_ID: "1234.apps.googleusercontent.com",
+     *   },
+     * })
+     * ```
+     *
+     * Keyed exactly as your `supabase/.env` is: by the name inside `env(...)`.
+     * That file is what the Supabase CLI resolves against — locally at `start`,
+     * and in CI at `config push` / `secrets set` — and it is excluded from the
+     * upload here, deliberately, since real credentials should not enter a test
+     * environment. This is its stand-in, holding test values.
+     *
+     * It covers every `env(...)` in the file, not only secrets: a provider's
+     * client id is a field on your project's auth settings rather than a named
+     * secret, and it reads from the same place.
      *
-     * Pass an object instead of a path to turn JWT verification off, or to set
-     * the function secrets your code reads with `Deno.env.get(...)`.
+     * A value reaches your **functions** because `[edge_runtime.secrets]`
+     * declares it — `SECRET = "env(NAME)"` — not merely because it is here. A
+     * deployed project can have secrets its config never mentions (the dashboard
+     * and `supabase secrets set` write straight to the project's store), but
+     * declaring them is what makes the test environment's inputs reviewable in
+     * the project's own config rather than implicit in its test setup. A name
+     * passed here and referenced nowhere is called out in the boot log.
+     *
+     * A literal in the file needs nothing. An inline `encrypted:` ciphertext
+     * cannot be supplied this way at all — it names no variable, and decrypting
+     * it needs a `DOTENV_PRIVATE_KEY` a test environment has no business
+     * holding — so it is named in the boot log and left unset. Anything else
+     * left unresolved is reported the same way, and never passed through as the
+     * string `env(NAME)` or as base64.
      */
-    functions?: string | SupabaseFunctionsOptions;
+    env?: Record<string, string>;
 }
-/** Tuning for `SupabaseOptions.functions`. */
-export interface SupabaseFunctionsOptions {
+/** Tuning for {@link SupabaseOptions.auth}. */
+export interface SupabaseAuthOptions {
     /**
-     * Directory holding one subdirectory per function, relative to the project
-     * root (or absolute). Required — there is no assumed location.
+     * Where GoTrue sends a user when a flow finishes — the base of every
+     * emailed confirmation, recovery and invite link's `redirect_to`, and the
+     * fallback when a requested redirect is refused. Defaults to the gateway
+     * (`http://<name>:8000`).
+     *
+     * This is deliberately **not** read from `config.toml`. That file's
+     * `site_url` is the developer's own machine (`http://localhost:3000`),
+     * which inside a VM is the browser's own namespace rather than the app
+     * container — so honouring it would point every redirect at nothing. Set
+     * it to the app under test's address in *this* environment:
+     *
+     * ```ts
+     * supabase({ dir: "supabase", auth: { siteUrl: "https://app.test" } })
+     * ```
      */
-    dir: string;
+    siteUrl?: string;
     /**
-     * Reject a call that carries no valid JWT, exactly as hosted Supabase
-     * does. Default `true` — so a test that forgets the `Authorization`
-     * header fails here instead of in production. Set `false` for the
-     * `--no-verify-jwt` behaviour (webhooks, public endpoints).
+     * Extra addresses a flow may redirect to, beyond `siteUrl` (which GoTrue
+     * always allows). Glob patterns, exactly as `config.toml` spells them:
+     * `["https://app.test/**"]`.
+     *
+     * **Redirect validation is off unless you set this.** GoTrue has no switch
+     * for it — an empty allow list is its *strictest* state, not its loosest,
+     * because a redirect is then refused unless it matches `siteUrl` — so the
+     * default here is the wildcard, and a suite is never rejected for a
+     * redirect it didn't declare. Set it to make the environment enforce what
+     * production enforces; the addresses are per-environment, so they belong
+     * here rather than in the config file.
      */
-    verifyJwt?: boolean;
+    additionalRedirectUrls?: string[];
     /**
-     * Extra environment variables the functions read (`Deno.env.get("…")`) —
-     * the local stand-in for function secrets. `SUPABASE_URL`,
-     * `SUPABASE_ANON_KEY`, `SUPABASE_SERVICE_ROLE_KEY`, `SUPABASE_DB_URL` and
-     * `JWT_SECRET` are already set for you.
+     * Provider components to serve the config's `[auth.external.*]` blocks
+     * with, keyed by the provider name GoTrue uses (`google`, `azure`,
+     * `github`, `apple`). **You do not normally need this**: a provider the
+     * config enables is stood up automatically with that component's defaults.
+     * Supply one to choose the accounts it offers, or to serve a provider this
+     * stack has no built-in emulator for:
+     *
+     * ```ts
+     * auth: {
+     *   providers: {
+     *     google: google({ users: [{ email: "alice@corp.test", name: "Alice" }] }),
+     *   },
+     * }
+     * ```
      */
-    env?: Record<string, string>;
+    providers?: Record<string, ServiceDefinition>;
 }
 /** Tuning for `SupabaseOptions.mail`. */
 export interface SupabaseMailOptions {
@@ -160,26 +207,14 @@ export interface SupabaseMailOptions {
      * services-map key) instead of adding one to the group — the way to keep a
      * single global mailbox when the app under test sends mail too. Assumes
      * the service's default ports (SMTP 1025, API 8025).
-     */
-    service?: string;
-    /**
-     * Whether GoTrue confirms a signup without the emailed verification.
-     * **`true` by default**: signups complete in one step and send no
-     * confirmation mail, which keeps account creation a single call in the
-     * suites where it is setup rather than the thing under test.
      *
-     * Set `false` to run the flow a hosted project runs: the signup issues no
-     * session, and the test follows the emailed link out of the mailbox
-     * exactly as a user would (see `examples/supabase-app`). Recovery,
-     * magic-link, OTP and invite mail is sent either way. Forced `true` when
-     * the stack has no mailbox (`mail: false`), since the confirmation would
-     * go nowhere.
+     * This is the only mail option, deliberately. Everything else about mail —
+     * whether a signup is confirmed, the sender identity, custom templates and
+     * their subjects — is GoTrue behaviour your project already declares in
+     * `config.toml` (`[auth.email]`, `[auth.email.smtp]`,
+     * `[auth.email.template.*]`), and it is read from there.
      */
-    autoconfirm?: boolean;
-    /** Sender address GoTrue mails from. Default `admin@example.com`. */
-    adminEmail?: string;
-    /** Sender display name. Default `Supabase`. */
-    senderName?: string;
+    service?: string;
 }
 /** Helpers the gateway service exposes on `ctx.svc.<name>`. */
 export interface SupabaseHelpers {
@@ -188,6 +223,11 @@ export interface SupabaseHelpers {
      * `postgres` superuser — every query lands on the test event log and its rows
      * come back provenance-wrapped, so `expect(...)` on a read links to the
      * query. Point of direct DB verification alongside the REST/auth surface.
+     *
+     * The same client the `postgres()` component exposes: a tagged template for
+     * ordinary queries, plus `unsafe(text, params?)` for what a template cannot
+     * carry — a whole `.sql` file, or a dynamic column list — which is recorded
+     * on the timeline just the same. See `spectest docs /components/postgres`.
      */
     sql: SqlClient;
     /** The gateway base URL the app uses as `SUPABASE_URL` (e.g. `http://supabase:8000`). */