@guard-rail/core 0.2.1 → 0.5.0

package/README.md

@@ -25,14 +25,20 @@ pnpm add @guard-rail/core @supabase/ssr @supabase/supabase-js
 
 Set up the database:
 
-1. Copy `node_modules/@guard-rail/core/supabase/migrations/*.sql` into your own
-   project's `supabase/migrations/`, then run `supabase db push`. No Supabase
-   CLI yet? Paste the file's contents into the SQL editor instead — it runs
-   the same statements, just without the CLI's version tracking.
-2. **Required:** add `guardrail` under **Settings > API > Exposed schemas** in
-   the Supabase dashboard. PostgREST only serves schemas on that list; every
-   table below is otherwise invisible to the client with a "not found in
-   schema cache" error that looks identical to a missing table.
+1. Run `npx guardrail-init-db --push`. It copies the package's migration(s)
+   into your own project's `supabase/migrations/` (skipping any already
+   there — safe to re-run after upgrading), runs `supabase init` if needed,
+   adds `guardrail` to `config.toml`'s exposed schemas for local dev, and
+   applies the migration with `supabase db push`. Leave off `--push` to copy
+   without applying. No Supabase CLI at all? Paste the migration file's
+   contents into the SQL editor instead — same statements, just without the
+   CLI's version tracking.
+2. **Required for a hosted project:** also add `guardrail` under
+   **Settings > API > Exposed schemas** in the Supabase dashboard —
+   `config.toml`'s schemas list only governs local dev. PostgREST only
+   serves schemas on that list; every table below is otherwise invisible to
+   the client with a "not found in schema cache" error that looks identical
+   to a missing table.
 
 Guardrail's tables live in their own `guardrail` Postgres schema, not `public`
 — so a `supabase db reset`, a broad `DROP ... CASCADE`, or a migration tool
@@ -107,8 +113,72 @@ import { GRail } from "@guard-rail/core";
 `id` is the content key. `className` and every other prop pass straight through
 to the element — Guardrail never styles your content.
 
+Links take `as="a"` (so `href` type-checks) and edit both the text and the URL:
+
+```tsx
+<GRail id="nav.cta" as="a" type="link" href="/contact">Get in touch</GRail>
+```
+
 To edit, visit any page with `?edit=true`, sign in with a Supabase user, and
-click a field.
+click a field. `?edit=true` itself only grants a short (~10 minute) window to
+reach the sign-in form — a normal visitor never sees any Guardrail chrome, and
+a stray copy of that window (a shared computer, an old tab) self-expires
+rather than showing a sign-in bar indefinitely. It's a dismissable prompt, not
+a standing invitation: a signed-in editor's toolbar isn't on that timer at
+all, and persists for as long as their real session does, with no need to
+revisit `?edit=true` again after the first sign-in. `?edit=false` explicitly
+hides the toolbar (also for ~10 minutes) if you want to preview the site
+without it while still signed in.
+
+### In Client Components
+
+`<GRail>` works the same inside a `"use client"` component — a mobile-nav header,
+a carousel, an accordion — with the same import and the same props:
+
+```tsx
+"use client";
+import { GRail } from "@guard-rail/core";
+
+export function Header() {
+  const [open, setOpen] = useState(false);
+  return (
+    <header>
+      <GRail id="header.tagline" as="p">Built by hand in Oklahoma</GRail>
+      <button onClick={() => setOpen(!open)}>Menu</button>
+    </header>
+  );
+}
+```
+
+The package resolves `@guard-rail/core` to an async Server Component in server
+code and to a client-safe version in client code (via the `"react-server"` export
+condition), so moving a component between the two needs no changes. Edited
+content is still in the server-rendered HTML — a Client Component is rendered on
+the server for its first paint too — so SEO is unaffected.
+
+A Client Component can't await a query, so instead the layout **preloads** the
+site's content once per request and hands it down. That preload is the same
+single query the server-rendered fields read from, so there's no extra cost: one
+query per request, whether a page uses server fields, client fields, or both.
+
+By default it preloads up to 500 rows with no configuration. If a site outgrows
+that, a dev-mode warning says so — scope it, or turn it off:
+
+```tsx
+withGuardrail(RootLayout, {
+  ...supabase,
+  prefetch: { prefix: ["home.", "header."] }, // only preload these; optional
+  // prefetch: { limit: 2000 },               // or raise the ceiling
+  // prefetch: false,                         // off: client fields show their JSX
+});
+```
+
+What still needs a Server Component: `<GRepeater>`, `getFieldValue()`, and
+`listRepeaterItems()` throw a clear error if used from client code. Render them in
+a Server Component and pass the result into the client one as `children` or a
+prop. If your tooling doesn't set the `"react-server"` condition (a test runner,
+a plain Node script), import from `@guard-rail/core/server` or
+`@guard-rail/core/client` explicitly.
 
 ## Team and roles
 
@@ -136,26 +206,42 @@ export default withGuardrail(RootLayout, {
 });
 ```
 
-**Invite emails (Supabase).** Inviting someone creates their account on first
-use and emails them a sign-in link. Three one-time steps in the Supabase
-dashboard, plus one route in your app:
+**Invite emails (Supabase).** Inviting someone emails them a sign-in link
+that creates their account on first use — this works out of the box, no
+route or email template changes needed. A small always-mounted component
+notices the link's tokens (in the URL hash, a `code`, or a `token_hash` —
+whichever style your project's templates happen to produce, including the
+unedited default) and completes the session automatically.
+
+Someone arriving this way has a valid session but no password yet, so they
+get a **Set Password** prompt in place of the usual toolbar — skippable,
+since a magic link works fine on its own indefinitely if they'd rather not.
+The same prompt appears after a password-recovery link.
+
+Two things still worth knowing:
+
+- **Auth → URL Configuration**, in the Supabase dashboard: Site URL and
+  Redirect URLs must actually match wherever your app runs, including in
+  local dev — a mismatch here makes Supabase silently redirect to whatever
+  Site URL *is* configured instead of erroring, which reads exactly like the
+  link "not working" for no visible reason.
+- **Auth → SMTP**: Supabase's built-in mailer allows only a few emails an
+  hour. Configure custom SMTP (Resend, Postmark, SES) before relying on
+  invites. Submitting the same address again re-sends a pending invite.
+
+Prefer a route that verifies server-side rather than relying on client JS to
+notice the redirect? `supabaseConfirmRoute` still works exactly as before —
+mount it and point a custom email template's link at
+`{{ .SiteURL }}/guardrail/confirm?token_hash={{ .TokenHash }}&type=email`:
 
-1. **Route** — `app/guardrail/confirm/route.ts`:
-   ```ts
-   export const GET = supabaseConfirmRoute({ url, anonKey });
-   ```
-2. **Auth → URL Configuration** — set Site URL to your app's origin, and add
-   `<origin>/**` to Redirect URLs.
-3. **Auth → Email Templates** — in both **Confirm signup** and **Magic Link**,
-   point the link at the confirm route using the token hash:
-   ```html
-   <a href="{{ .SiteURL }}/guardrail/confirm?token_hash={{ .TokenHash }}&type=email">Sign in</a>
-   ```
-   The default `{{ .ConfirmationURL }}` uses a PKCE code that only works in
-   the browser that requested it — the admin's, not the invitee's.
-4. **Auth → SMTP** — Supabase's built-in mailer allows only a few emails an
-   hour. Configure custom SMTP (Resend, Postmark, SES) before relying on
-   invites. Submitting the same address again re-sends a pending invite.
+```ts
+// app/guardrail/confirm/route.ts
+export const GET = supabaseConfirmRoute({ url, anonKey });
+```
+
+The default `{{ .ConfirmationURL }}` uses a PKCE code that only works in the
+browser that requested it — the admin's, not the invitee's — so a custom
+template needs the token hash form above either way.
 
 **Bootstrapping.** A site with no members has nobody who can add members, and
 there is deliberately no in-app way to grant yourself a role — that would mean
@@ -378,18 +464,33 @@ const clerkAuth: GRAuthAdapter = {
 };
 ```
 
+`completeAuthRedirect` and `setPassword` are optional too, and go together —
+an adapter with no concept of a redirect-carried session (an OAuth provider
+whose own SDK already handles its callback route, say) omits both, and links
+of that kind pass through untouched. Implement `completeAuthRedirect` to
+support them, returning `needsPassword: true` for a session that has none
+yet; `setPassword` is what the resulting prompt calls.
+
 `getSession()` is the sole authorization check for writes. It must validate the
 session against the provider — never trust the presence of a cookie.
 
+`listOverrides(siteId, { prefix, limit })` is optional. It's what lets `<GRail>`
+work inside Client Components (see above): one round trip returning the site's rows
+and whether the list was cut off at `limit`. An adapter without it still works
+fully for Server Components — client-rendered fields just show their JSX fallback.
+
 `getOverrides(pathKeys, siteId)` is batched by design — it receives every key a
 render pass needs, already deduplicated. Adapters map their own storage naming
 at this boundary; core speaks `pathKey` / `siteId` only.
 
 ## Performance
 
-Fields are resolved through a request-scoped batching loader: every `<GRail>`
-rendered in the same pass is collected and fetched in a single query. Set
-`GUARDRAIL_DEBUG=1` to log how many keys each batch resolved.
+Fields are resolved through a request-scoped loader. By default it preloads the
+site's content in one query and every `<GRail>` — server or client — reads from
+that, so a request issues a single content query however many fields it renders.
+Anything outside the preload (a `prefetch.prefix` scope, or a site past the row
+ceiling) falls back to a batched lookup by key. Set `GUARDRAIL_DEBUG=1` to log
+what each query resolved.
 
 ## Known limitations
 

package/dist/adapters/supabase/auth.js

@@ -1,4 +1,5 @@
 import { anonClient, assertCredentials, sessionClient } from "./client";
+const NEEDS_PASSWORD_TYPES = /* @__PURE__ */ new Set(["invite", "recovery", "magiclink"]);
 function supabaseAuth(creds) {
   assertCredentials(creds);
   return {
@@ -48,6 +49,55 @@ function supabaseAuth(creds) {
     async logout() {
       const client = await sessionClient(creds);
       await client.auth.signOut();
+    },
+    /**
+     * Whichever of hash/code/tokenHash is present decides the exchange —
+     * these correspond to Supabase's three redirect styles (legacy implicit
+     * grant, PKCE, and the token_hash style Guardrail's own confirm route
+     * already used), so this handles a link regardless of which one a
+     * project's email templates happen to produce, including the
+     * unconfigured default (implicit grant, hash-based — what an unedited
+     * Supabase project actually sends).
+     *
+     * Goes through sessionClient(), the same cookie-writing client
+     * everything else in this adapter uses — setSession/exchangeCodeForSession/
+     * verifyOtp all persist the resulting session through its existing
+     * getAll/setAll bridge, so this needs no browser-side Supabase client of
+     * its own.
+     */
+    async completeAuthRedirect({ hash, code, tokenHash, type }) {
+      const client = await sessionClient(creds);
+      if (hash) {
+        const hashParams = new URLSearchParams(hash);
+        const access_token = hashParams.get("access_token");
+        const refresh_token = hashParams.get("refresh_token");
+        const hashType = hashParams.get("type") ?? type;
+        if (!access_token || !refresh_token) {
+          return { success: false, error: "Redirect link is missing its tokens." };
+        }
+        const { error } = await client.auth.setSession({ access_token, refresh_token });
+        if (error) return { success: false, error: error.message };
+        return { success: true, needsPassword: NEEDS_PASSWORD_TYPES.has(hashType ?? "") };
+      }
+      if (code) {
+        const { error } = await client.auth.exchangeCodeForSession(code);
+        if (error) return { success: false, error: error.message };
+        return { success: true, needsPassword: NEEDS_PASSWORD_TYPES.has(type ?? "") };
+      }
+      if (tokenHash && type) {
+        const { error } = await client.auth.verifyOtp({
+          type,
+          token_hash: tokenHash
+        });
+        if (error) return { success: false, error: error.message };
+        return { success: true, needsPassword: NEEDS_PASSWORD_TYPES.has(type) };
+      }
+      return { success: false, error: "No redirect data to complete." };
+    },
+    async setPassword(password) {
+      const client = await sessionClient(creds);
+      const { error } = await client.auth.updateUser({ password });
+      return error ? { success: false, error: error.message } : { success: true };
     }
   };
 }

package/dist/adapters/supabase/auth.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/adapters/supabase/auth.ts"],"sourcesContent":["import { anonClient, assertCredentials, sessionClient } from \"./client\";\nimport type { SupabaseCredentials } from \"./client\";\nimport type { GRAuthAdapter, GRSession } from \"../../core/adapter-types\";\n\nexport function supabaseAuth(creds: SupabaseCredentials): GRAuthAdapter {\n  assertCredentials(creds);\n\n  return {\n    async authenticate(email, password) {\n      const client = await sessionClient(creds);\n      const { data, error } = await client.auth.signInWithPassword({\n        email,\n        password,\n      });\n\n      if (error) return { success: false, error: error.message };\n      if (!data.user) return { success: false, error: \"User not found.\" };\n\n      return {\n        success: true,\n        session: { userId: data.user.id, email: data.user.email },\n      };\n    },\n\n    /**\n     * Uses getUser(), which revalidates the JWT against the Supabase auth\n     * server. getSession() only decodes the cookie, so it would trust a forged\n     * token.\n     */\n    async getSession(): Promise<GRSession | null> {\n      const client = await sessionClient(creds);\n      const { data, error } = await client.auth.getUser();\n      if (error || !data.user) return null;\n      return { userId: data.user.id, email: data.user.email };\n    },\n\n    /**\n     * Sends a sign-in link that creates the account on first use.\n     *\n     * Requested through the cookie-free client on purpose. A session client\n     * would use PKCE and drop the code verifier into the *admin's* browser,\n     * so the link would fail when the invitee opened it anywhere else. The\n     * email template must point at the confirm route with {{ .TokenHash }},\n     * which verifies server-side and needs no verifier.\n     */\n    async inviteUser(email, options) {\n      const { error } = await anonClient(creds).auth.signInWithOtp({\n        email,\n        options: {\n          shouldCreateUser: true,\n          ...(options?.redirectTo ? { emailRedirectTo: options.redirectTo } : {}),\n        },\n      });\n      return error\n        ? { success: false, error: error.message }\n        : { success: true };\n    },\n\n    async logout() {\n      const client = await sessionClient(creds);\n      await client.auth.signOut();\n    },\n  };\n}\n"],"mappings":"AAAA,SAAS,YAAY,mBAAmB,qBAAqB;AAItD,SAAS,aAAa,OAA2C;AACtE,oBAAkB,KAAK;AAEvB,SAAO;AAAA,IACL,MAAM,aAAa,OAAO,UAAU;AAClC,YAAM,SAAS,MAAM,cAAc,KAAK;AACxC,YAAM,EAAE,MAAM,MAAM,IAAI,MAAM,OAAO,KAAK,mBAAmB;AAAA,QAC3D;AAAA,QACA;AAAA,MACF,CAAC;AAED,UAAI,MAAO,QAAO,EAAE,SAAS,OAAO,OAAO,MAAM,QAAQ;AACzD,UAAI,CAAC,KAAK,KAAM,QAAO,EAAE,SAAS,OAAO,OAAO,kBAAkB;AAElE,aAAO;AAAA,QACL,SAAS;AAAA,QACT,SAAS,EAAE,QAAQ,KAAK,KAAK,IAAI,OAAO,KAAK,KAAK,MAAM;AAAA,MAC1D;AAAA,IACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAOA,MAAM,aAAwC;AAC5C,YAAM,SAAS,MAAM,cAAc,KAAK;AACxC,YAAM,EAAE,MAAM,MAAM,IAAI,MAAM,OAAO,KAAK,QAAQ;AAClD,UAAI,SAAS,CAAC,KAAK,KAAM,QAAO;AAChC,aAAO,EAAE,QAAQ,KAAK,KAAK,IAAI,OAAO,KAAK,KAAK,MAAM;AAAA,IACxD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAWA,MAAM,WAAW,OAAO,SAAS;AAC/B,YAAM,EAAE,MAAM,IAAI,MAAM,WAAW,KAAK,EAAE,KAAK,cAAc;AAAA,QAC3D;AAAA,QACA,SAAS;AAAA,UACP,kBAAkB;AAAA,UAClB,GAAI,SAAS,aAAa,EAAE,iBAAiB,QAAQ,WAAW,IAAI,CAAC;AAAA,QACvE;AAAA,MACF,CAAC;AACD,aAAO,QACH,EAAE,SAAS,OAAO,OAAO,MAAM,QAAQ,IACvC,EAAE,SAAS,KAAK;AAAA,IACtB;AAAA,IAEA,MAAM,SAAS;AACb,YAAM,SAAS,MAAM,cAAc,KAAK;AACxC,YAAM,OAAO,KAAK,QAAQ;AAAA,IAC5B;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../../../src/adapters/supabase/auth.ts"],"sourcesContent":["import type { EmailOtpType } from \"@supabase/supabase-js\";\nimport { anonClient, assertCredentials, sessionClient } from \"./client\";\nimport type { SupabaseCredentials } from \"./client\";\nimport type {\n  AuthRedirectParams,\n  GRAuthAdapter,\n  GRSession,\n} from \"../../core/adapter-types\";\n\n// \"invite\" covers Supabase's own admin-API invite flow; \"recovery\" is\n// forgot-password. \"magiclink\" belongs here too — deliberately, not an\n// oversight — because inviteUser() below sends one (see its own comment for\n// why) rather than an \"invite\"-typed email, so this is the type Guardrail's\n// actual, real invite flow produces. A returning magic-link user who already\n// has a password sees this redundantly, but it's skippable, and the\n// alternative — never prompting the person this feature exists for — isn't\n// an acceptable trade to avoid that.\nconst NEEDS_PASSWORD_TYPES = new Set([\"invite\", \"recovery\", \"magiclink\"]);\n\nexport function supabaseAuth(creds: SupabaseCredentials): GRAuthAdapter {\n  assertCredentials(creds);\n\n  return {\n    async authenticate(email, password) {\n      const client = await sessionClient(creds);\n      const { data, error } = await client.auth.signInWithPassword({\n        email,\n        password,\n      });\n\n      if (error) return { success: false, error: error.message };\n      if (!data.user) return { success: false, error: \"User not found.\" };\n\n      return {\n        success: true,\n        session: { userId: data.user.id, email: data.user.email },\n      };\n    },\n\n    /**\n     * Uses getUser(), which revalidates the JWT against the Supabase auth\n     * server. getSession() only decodes the cookie, so it would trust a forged\n     * token.\n     */\n    async getSession(): Promise<GRSession | null> {\n      const client = await sessionClient(creds);\n      const { data, error } = await client.auth.getUser();\n      if (error || !data.user) return null;\n      return { userId: data.user.id, email: data.user.email };\n    },\n\n    /**\n     * Sends a sign-in link that creates the account on first use.\n     *\n     * Requested through the cookie-free client on purpose. A session client\n     * would use PKCE and drop the code verifier into the *admin's* browser,\n     * so the link would fail when the invitee opened it anywhere else. The\n     * email template must point at the confirm route with {{ .TokenHash }},\n     * which verifies server-side and needs no verifier.\n     */\n    async inviteUser(email, options) {\n      const { error } = await anonClient(creds).auth.signInWithOtp({\n        email,\n        options: {\n          shouldCreateUser: true,\n          ...(options?.redirectTo ? { emailRedirectTo: options.redirectTo } : {}),\n        },\n      });\n      return error\n        ? { success: false, error: error.message }\n        : { success: true };\n    },\n\n    async logout() {\n      const client = await sessionClient(creds);\n      await client.auth.signOut();\n    },\n\n    /**\n     * Whichever of hash/code/tokenHash is present decides the exchange —\n     * these correspond to Supabase's three redirect styles (legacy implicit\n     * grant, PKCE, and the token_hash style Guardrail's own confirm route\n     * already used), so this handles a link regardless of which one a\n     * project's email templates happen to produce, including the\n     * unconfigured default (implicit grant, hash-based — what an unedited\n     * Supabase project actually sends).\n     *\n     * Goes through sessionClient(), the same cookie-writing client\n     * everything else in this adapter uses — setSession/exchangeCodeForSession/\n     * verifyOtp all persist the resulting session through its existing\n     * getAll/setAll bridge, so this needs no browser-side Supabase client of\n     * its own.\n     */\n    async completeAuthRedirect({ hash, code, tokenHash, type }: AuthRedirectParams) {\n      const client = await sessionClient(creds);\n\n      if (hash) {\n        const hashParams = new URLSearchParams(hash);\n        const access_token = hashParams.get(\"access_token\");\n        const refresh_token = hashParams.get(\"refresh_token\");\n        const hashType = hashParams.get(\"type\") ?? type;\n        if (!access_token || !refresh_token) {\n          return { success: false, error: \"Redirect link is missing its tokens.\" };\n        }\n        const { error } = await client.auth.setSession({ access_token, refresh_token });\n        if (error) return { success: false, error: error.message };\n        return { success: true, needsPassword: NEEDS_PASSWORD_TYPES.has(hashType ?? \"\") };\n      }\n\n      if (code) {\n        const { error } = await client.auth.exchangeCodeForSession(code);\n        if (error) return { success: false, error: error.message };\n        return { success: true, needsPassword: NEEDS_PASSWORD_TYPES.has(type ?? \"\") };\n      }\n\n      if (tokenHash && type) {\n        const { error } = await client.auth.verifyOtp({\n          type: type as EmailOtpType,\n          token_hash: tokenHash,\n        });\n        if (error) return { success: false, error: error.message };\n        return { success: true, needsPassword: NEEDS_PASSWORD_TYPES.has(type) };\n      }\n\n      return { success: false, error: \"No redirect data to complete.\" };\n    },\n\n    async setPassword(password: string) {\n      const client = await sessionClient(creds);\n      const { error } = await client.auth.updateUser({ password });\n      return error ? { success: false, error: error.message } : { success: true };\n    },\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/adapters/supabase/db.js

@@ -20,6 +20,17 @@ function supabaseDB(creds) {
       }
       return (data ?? []).map(toOverrideRow);
     },
+    async listOverrides(siteId, { prefix, limit }) {
+      let query = anonClient(creds).schema(GR_SCHEMA).from(GR_TABLE).select("id, path_key, value").eq("site_id", siteId).order("path_key").limit(limit + 1);
+      if (prefix?.length) {
+        const quote = (p) => `"${p.replace(/["\\]/g, "\\$&")}"`;
+        query = query.or(prefix.map((p) => `path_key.like.${quote(`${p}*`)}`).join(","));
+      }
+      const { data, error } = await query;
+      if (error) throw new Error(error.message);
+      const rows = (data ?? []).map(toOverrideRow);
+      return { rows: rows.slice(0, limit), truncated: rows.length > limit };
+    },
     async setOverride(row) {
       const client = await sessionClient(creds);
       const { error } = await client.schema(GR_SCHEMA).from(GR_TABLE).upsert(

package/dist/adapters/supabase/db.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/adapters/supabase/db.ts"],"sourcesContent":["import { anonClient, assertCredentials, sessionClient } from \"./client\";\nimport type { SupabaseCredentials } from \"./client\";\nimport { GR_SCHEMA, GR_TABLE } from \"../../core/defs\";\nimport type { GRDBAdapter, GRStorageRow } from \"../../core/adapter-types\";\nimport type { OverrideRow, OverrideValue } from \"../../core/types\";\n\n/** Shape as stored in Postgres. Column naming stops at this boundary. */\ninterface ContentRow {\n  id: string;\n  path_key: string;\n  value: OverrideValue | string;\n}\n\nfunction toOverrideRow(row: ContentRow): OverrideRow {\n  return {\n    id: row.id,\n    pathKey: row.path_key,\n    // Some drivers hand back jsonb columns as strings.\n    value:\n      typeof row.value === \"string\"\n        ? (JSON.parse(row.value) as OverrideValue)\n        : row.value,\n  };\n}\n\nexport function supabaseDB(creds: SupabaseCredentials): GRDBAdapter {\n  assertCredentials(creds);\n\n  return {\n    async getOverrides(pathKeys, siteId) {\n      if (pathKeys.length === 0) return [];\n\n      // Anon client keeps the read path cookie-free so routes stay static.\n      const { data, error } = await anonClient(creds)\n        .schema(GR_SCHEMA)\n        .from(GR_TABLE)\n        .select(\"id, path_key, value\")\n        .eq(\"site_id\", siteId)\n        .in(\"path_key\", pathKeys);\n\n      if (error) {\n        console.error(\"Guardrail (Supabase): read failed\", error.message);\n        return [];\n      }\n      return ((data ?? []) as ContentRow[]).map(toOverrideRow);\n    },\n\n    async setOverride(row: GRStorageRow) {\n      const client = await sessionClient(creds);\n      const { error } = await client\n        .schema(GR_SCHEMA)\n        .from(GR_TABLE)\n        .upsert(\n          {\n            path_key: row.pathKey,\n            site_id: row.siteId,\n            type: row.type,\n            value: row.value,\n            updated_at: new Date().toISOString(),\n          },\n          { onConflict: \"path_key,site_id\" },\n        );\n      return error\n        ? { success: false, error: error.message }\n        : { success: true };\n    },\n\n    async deleteOverrides(pathKeyPrefix: string, siteId: string) {\n      const client = await sessionClient(creds);\n      const { error } = await client\n        .schema(GR_SCHEMA)\n        .from(GR_TABLE)\n        .delete()\n        .eq(\"site_id\", siteId)\n        .like(\"path_key\", `${pathKeyPrefix}%`);\n      if (error) {\n        console.error(\"Guardrail (Supabase): deleteOverrides failed\", error.message);\n      }\n    },\n  };\n}\n"],"mappings":"AAAA,SAAS,YAAY,mBAAmB,qBAAqB;AAE7D,SAAS,WAAW,gBAAgB;AAWpC,SAAS,cAAc,KAA8B;AACnD,SAAO;AAAA,IACL,IAAI,IAAI;AAAA,IACR,SAAS,IAAI;AAAA;AAAA,IAEb,OACE,OAAO,IAAI,UAAU,WAChB,KAAK,MAAM,IAAI,KAAK,IACrB,IAAI;AAAA,EACZ;AACF;AAEO,SAAS,WAAW,OAAyC;AAClE,oBAAkB,KAAK;AAEvB,SAAO;AAAA,IACL,MAAM,aAAa,UAAU,QAAQ;AACnC,UAAI,SAAS,WAAW,EAAG,QAAO,CAAC;AAGnC,YAAM,EAAE,MAAM,MAAM,IAAI,MAAM,WAAW,KAAK,EAC3C,OAAO,SAAS,EAChB,KAAK,QAAQ,EACb,OAAO,qBAAqB,EAC5B,GAAG,WAAW,MAAM,EACpB,GAAG,YAAY,QAAQ;AAE1B,UAAI,OAAO;AACT,gBAAQ,MAAM,qCAAqC,MAAM,OAAO;AAChE,eAAO,CAAC;AAAA,MACV;AACA,cAAS,QAAQ,CAAC,GAAoB,IAAI,aAAa;AAAA,IACzD;AAAA,IAEA,MAAM,YAAY,KAAmB;AACnC,YAAM,SAAS,MAAM,cAAc,KAAK;AACxC,YAAM,EAAE,MAAM,IAAI,MAAM,OACrB,OAAO,SAAS,EAChB,KAAK,QAAQ,EACb;AAAA,QACC;AAAA,UACE,UAAU,IAAI;AAAA,UACd,SAAS,IAAI;AAAA,UACb,MAAM,IAAI;AAAA,UACV,OAAO,IAAI;AAAA,UACX,aAAY,oBAAI,KAAK,GAAE,YAAY;AAAA,QACrC;AAAA,QACA,EAAE,YAAY,mBAAmB;AAAA,MACnC;AACF,aAAO,QACH,EAAE,SAAS,OAAO,OAAO,MAAM,QAAQ,IACvC,EAAE,SAAS,KAAK;AAAA,IACtB;AAAA,IAEA,MAAM,gBAAgB,eAAuB,QAAgB;AAC3D,YAAM,SAAS,MAAM,cAAc,KAAK;AACxC,YAAM,EAAE,MAAM,IAAI,MAAM,OACrB,OAAO,SAAS,EAChB,KAAK,QAAQ,EACb,OAAO,EACP,GAAG,WAAW,MAAM,EACpB,KAAK,YAAY,GAAG,aAAa,GAAG;AACvC,UAAI,OAAO;AACT,gBAAQ,MAAM,gDAAgD,MAAM,OAAO;AAAA,MAC7E;AAAA,IACF;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../../../src/adapters/supabase/db.ts"],"sourcesContent":["import { anonClient, assertCredentials, sessionClient } from \"./client\";\nimport type { SupabaseCredentials } from \"./client\";\nimport { GR_SCHEMA, GR_TABLE } from \"../../core/defs\";\nimport type { GRDBAdapter, GRStorageRow } from \"../../core/adapter-types\";\nimport type { OverrideRow, OverrideValue } from \"../../core/types\";\n\n/** Shape as stored in Postgres. Column naming stops at this boundary. */\ninterface ContentRow {\n  id: string;\n  path_key: string;\n  value: OverrideValue | string;\n}\n\nfunction toOverrideRow(row: ContentRow): OverrideRow {\n  return {\n    id: row.id,\n    pathKey: row.path_key,\n    // Some drivers hand back jsonb columns as strings.\n    value:\n      typeof row.value === \"string\"\n        ? (JSON.parse(row.value) as OverrideValue)\n        : row.value,\n  };\n}\n\nexport function supabaseDB(creds: SupabaseCredentials): GRDBAdapter {\n  assertCredentials(creds);\n\n  return {\n    async getOverrides(pathKeys, siteId) {\n      if (pathKeys.length === 0) return [];\n\n      // Anon client keeps the read path cookie-free so routes stay static.\n      const { data, error } = await anonClient(creds)\n        .schema(GR_SCHEMA)\n        .from(GR_TABLE)\n        .select(\"id, path_key, value\")\n        .eq(\"site_id\", siteId)\n        .in(\"path_key\", pathKeys);\n\n      if (error) {\n        console.error(\"Guardrail (Supabase): read failed\", error.message);\n        return [];\n      }\n      return ((data ?? []) as ContentRow[]).map(toOverrideRow);\n    },\n\n    async listOverrides(siteId, { prefix, limit }) {\n      let query = anonClient(creds)\n        .schema(GR_SCHEMA)\n        .from(GR_TABLE)\n        .select(\"id, path_key, value\")\n        .eq(\"site_id\", siteId)\n        // Ordered so that truncation, when it happens, is deterministic.\n        .order(\"path_key\")\n        // One past the ceiling, purely to learn whether anything was cut off.\n        .limit(limit + 1);\n\n      if (prefix?.length) {\n        // Quoted so a prefix containing PostgREST's own separators (comma,\n        // parens) can't be read as filter syntax.\n        const quote = (p: string) => `\"${p.replace(/[\"\\\\]/g, \"\\\\$&\")}\"`;\n        query = query.or(prefix.map((p) => `path_key.like.${quote(`${p}*`)}`).join(\",\"));\n      }\n\n      const { data, error } = await query;\n      // Thrown, not swallowed to []: an empty list here would read as \"this\n      // site has no content\" and short-circuit every field's own lookup.\n      if (error) throw new Error(error.message);\n\n      const rows = ((data ?? []) as ContentRow[]).map(toOverrideRow);\n      return { rows: rows.slice(0, limit), truncated: rows.length > limit };\n    },\n\n    async setOverride(row: GRStorageRow) {\n      const client = await sessionClient(creds);\n      const { error } = await client\n        .schema(GR_SCHEMA)\n        .from(GR_TABLE)\n        .upsert(\n          {\n            path_key: row.pathKey,\n            site_id: row.siteId,\n            type: row.type,\n            value: row.value,\n            updated_at: new Date().toISOString(),\n          },\n          { onConflict: \"path_key,site_id\" },\n        );\n      return error\n        ? { success: false, error: error.message }\n        : { success: true };\n    },\n\n    async deleteOverrides(pathKeyPrefix: string, siteId: string) {\n      const client = await sessionClient(creds);\n      const { error } = await client\n        .schema(GR_SCHEMA)\n        .from(GR_TABLE)\n        .delete()\n        .eq(\"site_id\", siteId)\n        .like(\"path_key\", `${pathKeyPrefix}%`);\n      if (error) {\n        console.error(\"Guardrail (Supabase): deleteOverrides failed\", error.message);\n      }\n    },\n  };\n}\n"],"mappings":"AAAA,SAAS,YAAY,mBAAmB,qBAAqB;AAE7D,SAAS,WAAW,gBAAgB;AAWpC,SAAS,cAAc,KAA8B;AACnD,SAAO;AAAA,IACL,IAAI,IAAI;AAAA,IACR,SAAS,IAAI;AAAA;AAAA,IAEb,OACE,OAAO,IAAI,UAAU,WAChB,KAAK,MAAM,IAAI,KAAK,IACrB,IAAI;AAAA,EACZ;AACF;AAEO,SAAS,WAAW,OAAyC;AAClE,oBAAkB,KAAK;AAEvB,SAAO;AAAA,IACL,MAAM,aAAa,UAAU,QAAQ;AACnC,UAAI,SAAS,WAAW,EAAG,QAAO,CAAC;AAGnC,YAAM,EAAE,MAAM,MAAM,IAAI,MAAM,WAAW,KAAK,EAC3C,OAAO,SAAS,EAChB,KAAK,QAAQ,EACb,OAAO,qBAAqB,EAC5B,GAAG,WAAW,MAAM,EACpB,GAAG,YAAY,QAAQ;AAE1B,UAAI,OAAO;AACT,gBAAQ,MAAM,qCAAqC,MAAM,OAAO;AAChE,eAAO,CAAC;AAAA,MACV;AACA,cAAS,QAAQ,CAAC,GAAoB,IAAI,aAAa;AAAA,IACzD;AAAA,IAEA,MAAM,cAAc,QAAQ,EAAE,QAAQ,MAAM,GAAG;AAC7C,UAAI,QAAQ,WAAW,KAAK,EACzB,OAAO,SAAS,EAChB,KAAK,QAAQ,EACb,OAAO,qBAAqB,EAC5B,GAAG,WAAW,MAAM,EAEpB,MAAM,UAAU,EAEhB,MAAM,QAAQ,CAAC;AAElB,UAAI,QAAQ,QAAQ;AAGlB,cAAM,QAAQ,CAAC,MAAc,IAAI,EAAE,QAAQ,UAAU,MAAM,CAAC;AAC5D,gBAAQ,MAAM,GAAG,OAAO,IAAI,CAAC,MAAM,iBAAiB,MAAM,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,GAAG,CAAC;AAAA,MACjF;AAEA,YAAM,EAAE,MAAM,MAAM,IAAI,MAAM;AAG9B,UAAI,MAAO,OAAM,IAAI,MAAM,MAAM,OAAO;AAExC,YAAM,QAAS,QAAQ,CAAC,GAAoB,IAAI,aAAa;AAC7D,aAAO,EAAE,MAAM,KAAK,MAAM,GAAG,KAAK,GAAG,WAAW,KAAK,SAAS,MAAM;AAAA,IACtE;AAAA,IAEA,MAAM,YAAY,KAAmB;AACnC,YAAM,SAAS,MAAM,cAAc,KAAK;AACxC,YAAM,EAAE,MAAM,IAAI,MAAM,OACrB,OAAO,SAAS,EAChB,KAAK,QAAQ,EACb;AAAA,QACC;AAAA,UACE,UAAU,IAAI;AAAA,UACd,SAAS,IAAI;AAAA,UACb,MAAM,IAAI;AAAA,UACV,OAAO,IAAI;AAAA,UACX,aAAY,oBAAI,KAAK,GAAE,YAAY;AAAA,QACrC;AAAA,QACA,EAAE,YAAY,mBAAmB;AAAA,MACnC;AACF,aAAO,QACH,EAAE,SAAS,OAAO,OAAO,MAAM,QAAQ,IACvC,EAAE,SAAS,KAAK;AAAA,IACtB;AAAA,IAEA,MAAM,gBAAgB,eAAuB,QAAgB;AAC3D,YAAM,SAAS,MAAM,cAAc,KAAK;AACxC,YAAM,EAAE,MAAM,IAAI,MAAM,OACrB,OAAO,SAAS,EAChB,KAAK,QAAQ,EACb,OAAO,EACP,GAAG,WAAW,MAAM,EACpB,KAAK,YAAY,GAAG,aAAa,GAAG;AACvC,UAAI,OAAO;AACT,gBAAQ,MAAM,gDAAgD,MAAM,OAAO;AAAA,MAC7E;AAAA,IACF;AAAA,EACF;AACF;","names":[]}

package/dist/cli/init-db.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli/init-db.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import {
+  existsSync,
+  mkdirSync,
+  copyFileSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync
+} from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+function commandExists(cmd) {
+  const res = process.platform === "win32" ? spawnSync("where", [cmd]) : spawnSync("which", [cmd]);
+  return res.status === 0;
+}
+function run(cmd, args) {
+  const res = spawnSync(cmd, args, { stdio: "inherit" });
+  if (res.status !== 0) {
+    throw new Error(`${cmd} ${args.join(" ")} exited with code ${res.status}`);
+  }
+}
+function fail(message) {
+  console.error(`
+${message}
+`);
+  process.exit(1);
+}
+const USAGE = `Usage:
+  guardrail-init-db [--push]
+
+Copies Guardrail's migration(s) from this package into ./supabase/migrations/
+(skipping any already present there), runs \`supabase init\` if this project
+has no supabase/config.toml yet, and adds "guardrail" to its exposed schemas
+for local dev.
+
+--push  Also run \`supabase db push\` once the files are in place. Without it,
+        the migration is copied but not applied \u2014 run \`supabase db push\`
+        yourself (after \`supabase link\`, if this project isn't linked yet).`;
+function patchExposedSchemas(configPath) {
+  const content = readFileSync(configPath, "utf8");
+  const patched = content.replace(
+    /(\[api\][\s\S]*?schemas\s*=\s*\[)([^\]]*)(\])/,
+    (match, pre, inner, post) => {
+      if (inner.includes('"guardrail"')) return match;
+      const trimmed = inner.trimEnd();
+      const sep = trimmed === "" || trimmed.endsWith(",") ? " " : ", ";
+      return `${pre}${inner}${sep}"guardrail"${post}`;
+    }
+  );
+  if (patched === content && !content.includes('"guardrail"')) {
+    console.warn(
+      'Could not find the [api] schemas setting in supabase/config.toml to patch automatically \u2014 add "guardrail" to it yourself before `supabase start`.'
+    );
+    return;
+  }
+  writeFileSync(configPath, patched);
+}
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log(USAGE);
+    return;
+  }
+  const push = args.includes("--push");
+  const __dirname = path.dirname(fileURLToPath(import.meta.url));
+  const pkgRoot = path.join(__dirname, "..", "..");
+  const srcDir = path.join(pkgRoot, "supabase", "migrations");
+  if (!existsSync(srcDir)) {
+    fail(`No bundled migrations found at ${srcDir} \u2014 is @guard-rail/core installed correctly?`);
+  }
+  const destDir = path.join(process.cwd(), "supabase", "migrations");
+  mkdirSync(destDir, { recursive: true });
+  const existing = new Set(readdirSync(destDir));
+  const copied = [];
+  for (const file of readdirSync(srcDir)) {
+    if (existing.has(file)) continue;
+    copyFileSync(path.join(srcDir, file), path.join(destDir, file));
+    copied.push(file);
+  }
+  if (copied.length === 0) {
+    console.log("supabase/migrations/ is already up to date \u2014 nothing to copy.");
+  } else {
+    console.log(`Copied ${copied.length} migration${copied.length === 1 ? "" : "s"}:`);
+    for (const file of copied) console.log(`  supabase/migrations/${file}`);
+  }
+  if (!commandExists("supabase")) {
+    console.log(
+      "\nSupabase CLI not found \u2014 apply the migration yourself (paste it into the SQL editor, or install the CLI and run `supabase db push`)."
+    );
+    return;
+  }
+  const configPath = path.join(process.cwd(), "supabase", "config.toml");
+  if (!existsSync(configPath)) {
+    try {
+      run("supabase", ["init"]);
+    } catch {
+      console.warn("\n`supabase init` failed \u2014 you can run it yourself.");
+      return;
+    }
+  }
+  if (existsSync(configPath)) patchExposedSchemas(configPath);
+  if (!push) {
+    console.log(
+      "\nRun `guardrail-init-db --push` (or `supabase db push` yourself) to apply it."
+    );
+    return;
+  }
+  try {
+    run("supabase", ["db", "push"]);
+  } catch {
+    console.warn(
+      "\n`supabase db push` failed \u2014 if this project isn't linked yet, run `supabase link` first, then `supabase db push`."
+    );
+  }
+}
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});
+//# sourceMappingURL=init-db.js.map

package/dist/cli/init-db.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/cli/init-db.ts"],"sourcesContent":["#!/usr/bin/env node\n/**\n * Copies Guardrail's SQL migration(s) into the current project's own\n * supabase/migrations/, then (optionally) applies them — the step\n * create-guardrail already automates for a brand-new scaffold (see\n * copyMigration()/maybeLinkAndPush() in that package), but has no\n * equivalent for an existing Next.js + Supabase app that just ran\n * `npm install @guard-rail/core`. Until now, postinstall.mjs pointed at\n * doing this by hand: \"Copy\n * node_modules/@guard-rail/core/supabase/migrations/*.sql into your own\n * supabase/migrations/, then `supabase db push`.\"\n *\n * Copies by filename, skipping anything already present in the destination\n * — safe to re-run after upgrading the package: it only ever adds\n * migrations this version ships that a prior run didn't already copy, and\n * never overwrites one that's already there.\n *\n * Deliberately non-interactive (flags only, no prompts), unlike\n * create-guardrail's wizard-style prompts — this is meant to be a single\n * command a developer (or a script) runs once against a project that\n * already exists, not a guided setup flow.\n */\nimport { spawnSync } from \"node:child_process\";\nimport {\n  existsSync,\n  mkdirSync,\n  copyFileSync,\n  readdirSync,\n  readFileSync,\n  writeFileSync,\n} from \"node:fs\";\nimport path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\n\nfunction commandExists(cmd: string): boolean {\n  // See create-guardrail's util.ts for why `which`/`where` over `command -v`\n  // with shell:true — no shell needed, no Node deprecation warning.\n  const res =\n    process.platform === \"win32\" ? spawnSync(\"where\", [cmd]) : spawnSync(\"which\", [cmd]);\n  return res.status === 0;\n}\n\n/** Throws with the failing command's name — every call site decides whether that's fatal. */\nfunction run(cmd: string, args: string[]): void {\n  const res = spawnSync(cmd, args, { stdio: \"inherit\" });\n  if (res.status !== 0) {\n    throw new Error(`${cmd} ${args.join(\" \")} exited with code ${res.status}`);\n  }\n}\n\nfunction fail(message: string): never {\n  console.error(`\\n${message}\\n`);\n  process.exit(1);\n}\n\nconst USAGE = `Usage:\n  guardrail-init-db [--push]\n\nCopies Guardrail's migration(s) from this package into ./supabase/migrations/\n(skipping any already present there), runs \\`supabase init\\` if this project\nhas no supabase/config.toml yet, and adds \"guardrail\" to its exposed schemas\nfor local dev.\n\n--push  Also run \\`supabase db push\\` once the files are in place. Without it,\n        the migration is copied but not applied — run \\`supabase db push\\`\n        yourself (after \\`supabase link\\`, if this project isn't linked yet).`;\n\n/**\n * Idempotent by design (a no-op if \"guardrail\" is already listed) — safe to\n * run on every invocation rather than only the first, including against a\n * config.toml a developer has since hand-edited.\n */\nfunction patchExposedSchemas(configPath: string): void {\n  const content = readFileSync(configPath, \"utf8\");\n  const patched = content.replace(\n    /(\\[api\\][\\s\\S]*?schemas\\s*=\\s*\\[)([^\\]]*)(\\])/,\n    (match, pre: string, inner: string, post: string) => {\n      if (inner.includes('\"guardrail\"')) return match;\n      const trimmed = inner.trimEnd();\n      const sep = trimmed === \"\" || trimmed.endsWith(\",\") ? \" \" : \", \";\n      return `${pre}${inner}${sep}\"guardrail\"${post}`;\n    },\n  );\n\n  if (patched === content && !content.includes('\"guardrail\"')) {\n    console.warn(\n      'Could not find the [api] schemas setting in supabase/config.toml to patch ' +\n        'automatically — add \"guardrail\" to it yourself before `supabase start`.',\n    );\n    return;\n  }\n  writeFileSync(configPath, patched);\n}\n\nasync function main() {\n  const args = process.argv.slice(2);\n  if (args.includes(\"--help\") || args.includes(\"-h\")) {\n    console.log(USAGE);\n    return;\n  }\n  const push = args.includes(\"--push\");\n\n  // This file's own location, not the invoking project's node_modules —\n  // resolves the migrations this installed package version ships,\n  // regardless of how the command was invoked (npx, a package.json script,\n  // a workspace link).\n  const __dirname = path.dirname(fileURLToPath(import.meta.url));\n  const pkgRoot = path.join(__dirname, \"..\", \"..\");\n  const srcDir = path.join(pkgRoot, \"supabase\", \"migrations\");\n  if (!existsSync(srcDir)) {\n    fail(`No bundled migrations found at ${srcDir} — is @guard-rail/core installed correctly?`);\n  }\n\n  const destDir = path.join(process.cwd(), \"supabase\", \"migrations\");\n  mkdirSync(destDir, { recursive: true });\n  const existing = new Set(readdirSync(destDir));\n\n  const copied: string[] = [];\n  for (const file of readdirSync(srcDir)) {\n    if (existing.has(file)) continue;\n    copyFileSync(path.join(srcDir, file), path.join(destDir, file));\n    copied.push(file);\n  }\n\n  if (copied.length === 0) {\n    console.log(\"supabase/migrations/ is already up to date — nothing to copy.\");\n  } else {\n    console.log(`Copied ${copied.length} migration${copied.length === 1 ? \"\" : \"s\"}:`);\n    for (const file of copied) console.log(`  supabase/migrations/${file}`);\n  }\n\n  if (!commandExists(\"supabase\")) {\n    console.log(\n      \"\\nSupabase CLI not found — apply the migration yourself (paste it into the SQL \" +\n        \"editor, or install the CLI and run `supabase db push`).\",\n    );\n    return;\n  }\n\n  const configPath = path.join(process.cwd(), \"supabase\", \"config.toml\");\n  if (!existsSync(configPath)) {\n    try {\n      run(\"supabase\", [\"init\"]);\n    } catch {\n      console.warn(\"\\n`supabase init` failed — you can run it yourself.\");\n      return;\n    }\n  }\n  if (existsSync(configPath)) patchExposedSchemas(configPath);\n\n  if (!push) {\n    console.log(\n      \"\\nRun `guardrail-init-db --push` (or `supabase db push` yourself) to apply it.\",\n    );\n    return;\n  }\n\n  try {\n    run(\"supabase\", [\"db\", \"push\"]);\n  } catch {\n    console.warn(\n      \"\\n`supabase db push` failed — if this project isn't linked yet, run `supabase \" +\n        \"link` first, then `supabase db push`.\",\n    );\n  }\n}\n\nmain().catch((err) => {\n  console.error(err);\n  process.exit(1);\n});\n"],"mappings":"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","names":[]}

package/dist/core/adapter-types.d.ts

@@ -30,6 +30,30 @@ interface GRDBAdapter {
      * row is still removed, just not its old field values.
      */
     deleteOverrides?: (pathKeyPrefix: string, siteId: string) => Promise<void>;
+    /**
+     * List a site's rows without naming keys — what makes <GRail> usable inside
+     * Client Components, which cannot await a per-field query. One round trip.
+     *
+     * Optional: an adapter without it still works fully for Server Components;
+     * client-rendered fields just show their JSX fallback. `limit` is a ceiling,
+     * not a page size — return `truncated: true` if rows beyond it existed, so
+     * the caller knows the list is partial. `prefix`, when given, restricts to
+     * keys starting with any of those strings.
+     */
+    listOverrides?: (siteId: string, opts: {
+        prefix?: string[];
+        limit: number;
+    }) => Promise<{
+        rows: OverrideRow[];
+        truncated: boolean;
+    }>;
+}
+/** How much content to preload for <GRail>s inside Client Components. */
+interface GRPrefetch {
+    /** Only preload keys starting with one of these (e.g. `["home.", "header."]`). */
+    prefix?: string[];
+    /** Ceiling on preloaded rows. Default 500. */
+    limit?: number;
 }
 /** Identity of a signed-in editor, as verified by the auth adapter. */
 interface GRSession {
@@ -73,6 +97,48 @@ interface GRAuthAdapter {
      */
     getSession: () => Promise<GRSession | null>;
     logout: () => Promise<void>;
+    /**
+     * Completes a session that arrived via a redirect link — an invite, magic
+     * link, or password-recovery email — rather than the normal sign-in form.
+     * Optional: an adapter with no such concept (an OAuth provider whose own
+     * SDK already handles its callback route, say) simply omits it, and links
+     * of this kind pass through Guardrail untouched.
+     *
+     * Whatever the client found in the URL is handed through as-is — which of
+     * `hash`/`code`/`tokenHash` is present depends on the provider's own
+     * redirect style, not a choice Guardrail's core makes. `needsPassword` in
+     * the result tells the caller to prompt for one: an invited or
+     * password-recovering person has a valid session but no password yet.
+     */
+    completeAuthRedirect?: (params: AuthRedirectParams) => Promise<{
+        success: boolean;
+        needsPassword?: boolean;
+        error?: string;
+    }>;
+    /**
+     * Sets the current session's password — the other half of
+     * `completeAuthRedirect`'s `needsPassword`. Optional for the same reason
+     * `authenticate` is: only meaningful for a password-based adapter.
+     */
+    setPassword?: (password: string) => Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+}
+/**
+ * Raw redirect data as the browser found it — see completeAuthRedirect.
+ * Hash-based tokens never reach the server on their own; the browser has to
+ * read them and hand them here.
+ */
+interface AuthRedirectParams {
+    /** window.location.hash, minus its leading '#' (the implicit-grant style). */
+    hash?: string;
+    /** The `code` query param (the PKCE style). */
+    code?: string;
+    /** The `token_hash` query param (Guardrail's own documented confirm-route style, detected here too so that route stays opt-in rather than required). */
+    tokenHash?: string;
+    /** Accompanies `code` or `tokenHash` — e.g. "invite", "recovery", "magiclink". */
+    type?: string;
 }
 type AuthResult = {
     success: true;
@@ -207,6 +273,16 @@ interface GRConfig {
      * an already-resolved element, not a function.
      */
     toolbarExtra?: ReactNode;
+    /**
+     * Content preloaded for <GRail>s inside Client Components. On by default
+     * with a row ceiling and no scoping: zero config, and one query per request
+     * total, since server-rendered fields read from the same preload instead of
+     * issuing their own. Scope it with `prefix` if a site outgrows the ceiling
+     * (a dev-mode warning says when), or pass `false` to turn it off — client
+     * fields then render their JSX fallback and server fields query per batch as
+     * before.
+     */
+    prefetch?: false | GRPrefetch;
 }
 
-export type { AuthResult, GRAuthAdapter, GRConfig, GRDBAdapter, GRInviteEvent, GRMembershipAdapter, GRRepeaterAdapter, GRSession, GRStorageAdapter, GRStorageRow, GRUploadTarget };
+export type { AuthRedirectParams, AuthResult, GRAuthAdapter, GRConfig, GRDBAdapter, GRInviteEvent, GRMembershipAdapter, GRPrefetch, GRRepeaterAdapter, GRSession, GRStorageAdapter, GRStorageRow, GRUploadTarget };

package/dist/core/config.d.ts

@@ -21,7 +21,13 @@ declare function getMembers(): GRMembershipAdapter;
 declare function getStorage(): GRStorageAdapter | undefined;
 /** Throws with a clear message if no page on this site uses <GRepeater>. */
 declare function getRepeaters(): GRRepeaterAdapter;
+declare const DEFAULT_PREFETCH_LIMIT = 500;
+/** Normalized preload settings, or null when preloading is off. */
+declare function getPrefetch(): {
+    prefix?: string[];
+    limit: number;
+} | null;
 declare function getInviteHandler(): GRConfig["onInvite"];
 declare function resolveSiteId(): Promise<string>;
 
-export { configureGuardrail, getAuth, getDB, getInviteHandler, getMembers, getRepeaters, getStorage, resolveSiteId };
+export { DEFAULT_PREFETCH_LIMIT, configureGuardrail, getAuth, getDB, getInviteHandler, getMembers, getPrefetch, getRepeaters, getStorage, resolveSiteId };

package/dist/core/config.js

@@ -26,6 +26,15 @@ function getStorage() {
 function getRepeaters() {
   return required("repeaters");
 }
+const DEFAULT_PREFETCH_LIMIT = 500;
+function getPrefetch() {
+  const p = _config?.prefetch;
+  if (p === false) return null;
+  return {
+    ...p?.prefix?.length ? { prefix: p.prefix } : {},
+    limit: p?.limit ?? DEFAULT_PREFETCH_LIMIT
+  };
+}
 function getInviteHandler() {
   return _config?.onInvite;
 }
@@ -34,11 +43,13 @@ async function resolveSiteId() {
   return typeof sid === "function" ? await sid() : sid || "default";
 }
 export {
+  DEFAULT_PREFETCH_LIMIT,
   configureGuardrail,
   getAuth,
   getDB,
   getInviteHandler,
   getMembers,
+  getPrefetch,
   getRepeaters,
   getStorage,
   resolveSiteId