@exposify/supabase 0.2.0 → 0.3.1

package/README.md

@@ -26,7 +26,10 @@ From your Supabase project's root (the directory containing `supabase/`):
 npx exposify-supabase init
 ```
 
-This writes two things and never overwrites an existing function file:
+This is safe to re-run — it never overwrites an existing function file, and
+never scaffolds a second copy of the migration if one's already there
+(checked by filename, not content: migrations are meant to be immutable
+once written, so a re-run skips rather than rewrites). It writes:
 
 - `supabase/migrations/<timestamp>_exposify_meta.sql` — a SQL migration that
   adds `exposify_meta()`, a `SECURITY DEFINER` function returning, per table,
@@ -39,6 +42,10 @@ This writes two things and never overwrites an existing function file:
 - `supabase/functions/mcp/docs/` — an empty directory for optional bundled
   docs (see "Knowledge base" below).
 
+If you run it somewhere that doesn't look like a Supabase project root (no
+`supabase/config.toml`), it warns but still proceeds — worth double-checking
+you're in the directory you think you are before continuing.
+
 `init` is interactive from there (skips straight to the old fixed behavior
 below if stdin isn't a real terminal — CI, a script, piped input). If the
 Supabase CLI is on your `PATH`, it asks:
@@ -97,10 +104,11 @@ you to hand-edit `writes`/`rpc`/comments yourself:
 If `supabase/functions/mcp/index.ts` already exists, none of this touches
 it — your selections are printed as a config snippet to merge in by hand
 instead, and the documentation migration still gets written either way.
-Connects using `SUPABASE_URL`/`SUPABASE_ANON_KEY` (env vars or `--url`/`--key`
-flags) — without those, `init` can't reach anything to introspect and falls
-back to the fixed scaffold-and-ask-to-deploy flow above, same as before this
-wizard existed.
+Connects using `SUPABASE_URL`/`SUPABASE_SERVICE_ROLE_KEY` (env vars or
+`--url`/`--key` flags — **the service role key, not the anon key**; see the
+note on introspection below) — without those, `init` can't reach anything to
+introspect and falls back to the fixed scaffold-and-ask-to-deploy flow above,
+same as before this wizard existed.
 
 ## 2. Decide what's exposed
 
@@ -159,7 +167,34 @@ Other options you can pass to `aiReady()`:
 | `docsAuth` | `"public"` | `"required"` hides `search_docs` until the caller sends *any* `Authorization` header (presence-only, not validated) |
 | `maxRows` | `100` | Hard cap applied to every `query_<table>` call |
 | `rateLimit` / `rateWindowMs` | `60` / `60000` | In-memory, per-instance, best-effort rate limit — **not** distributed across edge instances; real limits belong to Supabase's own gateway |
-| `supabaseUrl` / `anonKey` | read from `SUPABASE_URL` / `SUPABASE_ANON_KEY` env vars | Override for local dev/testing; in a deployed function the env vars are automatic |
+| `supabaseUrl` / `anonKey` / `serviceRoleKey` | read from `SUPABASE_URL` / `SUPABASE_ANON_KEY` / `SUPABASE_SERVICE_ROLE_KEY` env vars | Override for local dev/testing; in a deployed function all three env vars are automatic. `serviceRoleKey` is used only for schema introspection — see below. |
+
+### Why introspection needs the service role key
+
+Every actual data call (`query_<table>`, `insert_<table>`, `rpc_<fn>`, ...)
+uses the caller's own forwarded JWT, or the anon key as its fallback for an
+unauthenticated caller — **that part is unaffected by any of this** and is
+still what makes RLS the real authorization layer.
+
+Schema introspection is different: fetching PostgREST's OpenAPI document (the
+one-time-per-instance call that discovers which tables/columns exist) has to
+use `SUPABASE_SERVICE_ROLE_KEY`. Supabase's gateway rejects that specific
+request outright for an anon or publishable-tier key —
+`{"message":"Invalid API key","hint":"Only the service_role API key can be
+used for this endpoint."}` — regardless of RLS policies or table grants, and
+regardless of whether you're using a legacy JWT-format anon key or a newer
+`sb_publishable_...` key. This isn't documented anywhere in Supabase's own
+docs as far as we've found; it was discovered by deploying this SDK against
+a real project. The service role key never leaves the function and is never
+used for anything except this schema-shape discovery — it doesn't touch row
+data, and RLS still fully governs every actual tool call.
+
+If you deploy with `supabase functions deploy` this just works — Supabase
+auto-injects `SUPABASE_SERVICE_ROLE_KEY` into every edge function already.
+The only place you'd ever need to supply it yourself is local dev/testing
+(the `serviceRoleKey` option above) or the CLI's `init`/`generate` (see
+their own sections), which run outside the deployed function and need it
+passed explicitly.
 
 ## 3. Apply the migration and deploy
 
@@ -224,15 +259,16 @@ project (local `supabase start` or linked):
 
 ```bash
 SUPABASE_URL=http://localhost:54321 \
-SUPABASE_ANON_KEY=<anon-key> \
+SUPABASE_SERVICE_ROLE_KEY=<service-role-key> \
 npx exposify-supabase generate
 ```
 
-Uses the **anon key**, deliberately the same key runtime introspection
-itself uses (see "Fallback ladder" above) — a service-role key would see
-tables/columns the `anon`/`authenticated` roles can't actually reach,
-producing a fallback manifest that offers tools live introspection never
-would.
+Uses the **service role key**, deliberately the same key runtime
+introspection itself uses (see "Why introspection needs the service role
+key" above, and "Fallback ladder" below) — the anon key can't fetch
+PostgREST's OpenAPI document at all, so `generate` needs the same
+privileged key runtime introspection does. Nothing from the service role
+key ends up in the generated manifest — it's just table/column metadata.
 
 This writes `supabase/functions/mcp/exposify.manifest.json`. Load it in
 `aiReady({ manifest: ... })` — since the function runs on Deno, import it
@@ -272,9 +308,20 @@ the function.
 
 **`init` just scaffolds and asks to deploy — it never asks about writes/RPCs/
 documentation.** The wizard only runs when `init` can actually reach the
-project (`SUPABASE_URL`/`SUPABASE_ANON_KEY` env vars, or `--url`/`--key`
-flags, pointing at a project where the migration is already applied). On a
+project (`SUPABASE_URL`/`SUPABASE_SERVICE_ROLE_KEY` env vars, or `--url`/`--key`
+flags — the service role key, not the anon key, for the same reason described
+above — pointing at a project where the migration is already applied). On a
 brand-new project's first `init`, that's not true yet — say yes to the
 deploy prompt (or run `supabase db push` yourself) and the wizard picks up
 automatically once the migration is live, in the same run if you said yes,
 or on your next `exposify-supabase init` otherwise.
+
+**`PostgREST OpenAPI fetch failed: HTTP 401`, and the error body (if you
+curl it directly) says `"Only the service_role API key can be used for this
+endpoint"`.** This is expected if `SUPABASE_SERVICE_ROLE_KEY` isn't
+reaching the function — see "Why introspection needs the service role key"
+above. On a deployed function this should be automatic; if you're still
+seeing this after a `supabase functions deploy`, check `supabase secrets
+list` for a stale explicit `SUPABASE_SERVICE_ROLE_KEY` override, and confirm
+you're not accidentally passing an anon/publishable key as `serviceRoleKey`
+in local dev.

package/dist/cli.js

@@ -1,19 +1,26 @@
 #!/usr/bin/env node
 
 // bin/cli.ts
-import { mkdir, readFile, writeFile, access } from "fs/promises";
+import { mkdir, readFile, writeFile, access, readdir } from "fs/promises";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
 import { execFileSync } from "child_process";
 import { createInterface } from "readline/promises";
 
 // src/fetch-openapi.ts
+var WRONG_KEY_TIER_RE = /service_role|secret api key/i;
 async function fetchOpenApi(postgrestUrl, headers, fetchImpl) {
   const res = await fetchImpl(postgrestUrl, {
     headers: { ...Object.fromEntries(headers), accept: "application/openapi+json" }
   });
   if (!res.ok) {
-    throw new Error(`PostgREST OpenAPI fetch failed: HTTP ${res.status}`);
+    const body = await res.text().catch(() => "");
+    if (res.status === 401 && WRONG_KEY_TIER_RE.test(body)) {
+      throw new Error(
+        `PostgREST OpenAPI fetch failed: HTTP 401 -- Supabase rejected this request because it wasn't made with the service role key (response: "${body.trim()}"). Schema introspection always needs SUPABASE_SERVICE_ROLE_KEY, never the anon key -- see this package's README, "Why introspection needs the service role key". In a deployed function this is auto-injected automatically; for local dev/testing pass { serviceRoleKey } explicitly (or --key for the CLI).`
+      );
+    }
+    throw new Error(`PostgREST OpenAPI fetch failed: HTTP ${res.status}${body ? `: ${body}` : ""}`);
   }
   return await res.json();
 }
@@ -218,10 +225,41 @@ function buildFunctionTemplate(opts = {}) {
   );
   return lines.join("\n");
 }
+function findExistingMigration(filenames, suffix) {
+  const matches = filenames.filter((f) => f.endsWith(suffix)).sort();
+  return matches[0] ?? null;
+}
+function uniqueMigrationFilename(existing, desired) {
+  if (!existing.includes(desired)) return desired;
+  const dot = desired.lastIndexOf(".");
+  const base = dot === -1 ? desired : desired.slice(0, dot);
+  const ext = dot === -1 ? "" : desired.slice(dot);
+  let i = 2;
+  let candidate = `${base}-${i}${ext}`;
+  while (existing.includes(candidate)) candidate = `${base}-${++i}${ext}`;
+  return candidate;
+}
+function partialConnectionWarning(url, key) {
+  if (url && !key) return "SUPABASE_URL is set but SUPABASE_SERVICE_ROLE_KEY (or --key) is not -- both are required to introspect.";
+  if (!url && key) return "SUPABASE_SERVICE_ROLE_KEY (or --key) is set but SUPABASE_URL is not -- both are required to introspect.";
+  return null;
+}
 
 // bin/cli.ts
 var PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 var FUNCTION_DIR = "supabase/functions/mcp";
+var MIGRATIONS_DIR = "supabase/migrations";
+var FETCH_TIMEOUT_MS = 1e4;
+function fetchWithTimeout(input, init) {
+  return fetch(input, { ...init, signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+}
+async function listFilesOrEmpty(dir) {
+  try {
+    return await readdir(dir);
+  } catch {
+    return [];
+  }
+}
 async function exists(path) {
   try {
     await access(path);
@@ -274,27 +312,33 @@ function pushAndDeploy() {
 }
 function resolveConnectionInfo() {
   const url = process.env.SUPABASE_URL ?? argValue("--url");
-  const anonKey = process.env.SUPABASE_ANON_KEY ?? argValue("--key");
-  if (!url || !anonKey) return null;
-  return { url, anonKey };
+  const serviceRoleKey = process.env.SUPABASE_SERVICE_ROLE_KEY ?? argValue("--key");
+  if (!url || !serviceRoleKey) return null;
+  return { url, serviceRoleKey };
 }
 async function tryIntrospect(conn) {
   try {
     const postgrestUrl = `${conn.url.replace(/\/+$/, "")}/rest/v1`;
-    const headers = new Headers({ authorization: `Bearer ${conn.anonKey}`, apikey: conn.anonKey });
+    const headers = new Headers({ authorization: `Bearer ${conn.serviceRoleKey}`, apikey: conn.serviceRoleKey });
     const [openapi, metaRows] = await Promise.all([
-      fetchOpenApi(postgrestUrl, headers, fetch),
-      fetchExposifyMeta(postgrestUrl, headers, fetch)
+      fetchOpenApi(postgrestUrl, headers, fetchWithTimeout),
+      fetchExposifyMeta(postgrestUrl, headers, fetchWithTimeout)
     ]);
     return { tables: introspectTables(openapi, metaRows), openapi };
-  } catch {
+  } catch (err) {
+    if (!(err instanceof MissingExposifyMetaError)) {
+      console.log(`
+Couldn't introspect the project: ${err instanceof Error ? err.message : String(err)}`);
+    }
     return null;
   }
 }
 async function tryDetectAnonymousSignIn(conn) {
   try {
     const url = `${conn.url.replace(/\/+$/, "")}/auth/v1/settings`;
-    const res = await fetch(url, { headers: { apikey: conn.anonKey, authorization: `Bearer ${conn.anonKey}` } });
+    const res = await fetchWithTimeout(url, {
+      headers: { apikey: conn.serviceRoleKey, authorization: `Bearer ${conn.serviceRoleKey}` }
+    });
     if (!res.ok) return null;
     return parseAnonymousSignInSetting(await res.json());
   } catch {
@@ -369,23 +413,44 @@ ${missing.length} table(s) are missing documentation MCP tools would otherwise s
 async function writeCommentsMigration(entries) {
   const sql = buildCommentStatements(entries);
   if (!sql) return null;
-  const migrationsDir = "supabase/migrations";
-  await mkdir(migrationsDir, { recursive: true });
-  const path = join(migrationsDir, `${timestamp()}_exposify_comments.sql`);
+  await mkdir(MIGRATIONS_DIR, { recursive: true });
+  const existing = await listFilesOrEmpty(MIGRATIONS_DIR);
+  const filename = uniqueMigrationFilename(existing, `${timestamp()}_exposify_comments.sql`);
+  const path = join(MIGRATIONS_DIR, filename);
   await writeFile(path, sql);
   return path;
 }
-async function cmdInit() {
+async function ensureMetaMigration() {
+  await mkdir(MIGRATIONS_DIR, { recursive: true });
+  const existing = await listFilesOrEmpty(MIGRATIONS_DIR);
+  const found = findExistingMigration(existing, "_exposify_meta.sql");
+  if (found) return { path: join(MIGRATIONS_DIR, found), wasNew: false };
   const migrationSql = await readFile(join(PACKAGE_ROOT, "sql/exposify_meta.sql"), "utf8");
-  const migrationsDir = "supabase/migrations";
-  await mkdir(migrationsDir, { recursive: true });
-  const migrationPath = join(migrationsDir, `${timestamp()}_exposify_meta.sql`);
-  await writeFile(migrationPath, migrationSql);
-  console.log(`Wrote ${migrationPath}`);
+  const filename = uniqueMigrationFilename(existing, `${timestamp()}_exposify_meta.sql`);
+  const path = join(MIGRATIONS_DIR, filename);
+  await writeFile(path, migrationSql);
+  return { path, wasNew: true };
+}
+async function warnIfNotSupabaseProject() {
+  if (!await exists("supabase/config.toml")) {
+    console.warn(
+      "warn: no supabase/config.toml found here -- this doesn't look like a Supabase project root (or you haven't run `supabase init` yet). Continuing, but double-check you're in the right directory."
+    );
+  }
+}
+async function cmdInit() {
+  await warnIfNotSupabaseProject();
+  const { path: migrationPath, wasNew } = await ensureMetaMigration();
+  console.log(wasNew ? `Wrote ${migrationPath}` : `Skipped ${migrationPath} (already scaffolded)`);
   await mkdir(FUNCTION_DIR, { recursive: true });
   const functionPath = join(FUNCTION_DIR, "index.ts");
   const functionExists = await exists(functionPath);
   await mkdir(join(FUNCTION_DIR, "docs"), { recursive: true });
+  const connWarning = partialConnectionWarning(
+    process.env.SUPABASE_URL ?? argValue("--url"),
+    process.env.SUPABASE_SERVICE_ROLE_KEY ?? argValue("--key")
+  );
+  if (connWarning) console.warn(`warn: ${connWarning}`);
   const rl = openInteractiveReadline();
   if (!rl) {
     if (!functionExists) {
@@ -435,7 +500,7 @@ Supabase CLI command failed: ${result2.error instanceof Error ? result2.error.me
       introspection = conn ? await tryIntrospect(conn) : null;
       if (!introspection) {
         console.log(
-          "\nDeployed, but couldn't reach the project to introspect tables (no SUPABASE_URL/SUPABASE_ANON_KEY or --url/--key available). Re-run `exposify-supabase init` with those set to configure writes, RPCs, and documentation interactively."
+          "\nDeployed, but couldn't reach the project to introspect tables (no SUPABASE_URL/SUPABASE_SERVICE_ROLE_KEY or --url/--key available). Re-run `exposify-supabase init` with those set to configure writes, RPCs, and documentation interactively."
         );
         console.log("\nDone. Paste the function URL + a user JWT into an MCP client to try it.");
         return;
@@ -490,16 +555,19 @@ async function cmdGenerate() {
   const conn = resolveConnectionInfo();
   if (!conn) {
     console.error(
-      "generate needs SUPABASE_URL and SUPABASE_ANON_KEY (env vars, or --url/--key flags) pointing at a running local or linked project (e.g. `supabase start`)."
+      "generate needs SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY (env vars, or --url/--key flags) pointing at a running local or linked project (e.g. `supabase start`). The service role key is used only for this one-time introspection call, matching what runtime introspection itself uses -- never written into the generated manifest."
     );
     process.exitCode = 1;
     return;
   }
   const postgrestUrl = `${conn.url.replace(/\/+$/, "")}/rest/v1`;
-  const headers = new Headers({ authorization: `Bearer ${conn.anonKey}`, apikey: conn.anonKey });
+  const headers = new Headers({
+    authorization: `Bearer ${conn.serviceRoleKey}`,
+    apikey: conn.serviceRoleKey
+  });
   const [openapi, metaRows] = await Promise.all([
-    fetchOpenApi(postgrestUrl, headers, fetch),
-    fetchExposifyMeta(postgrestUrl, headers, fetch)
+    fetchOpenApi(postgrestUrl, headers, fetchWithTimeout),
+    fetchExposifyMeta(postgrestUrl, headers, fetchWithTimeout)
   ]);
   const manifest = buildManifest(openapi, metaRows, (/* @__PURE__ */ new Date()).toISOString());
   const outPath = join(FUNCTION_DIR, "exposify.manifest.json");
@@ -520,10 +588,10 @@ async function main() {
   const [, , cmd] = process.argv;
   if (cmd === "init") return cmdInit();
   if (cmd === "generate") return cmdGenerate();
-  console.log("Usage: exposify-supabase <init|generate> [--url <url>] [--key <anon-key>]");
+  console.log("Usage: exposify-supabase <init|generate> [--url <url>] [--key <service-role-key>]");
   console.log("  init      Scaffold the exposify_meta() migration + supabase/functions/mcp/index.ts.");
   console.log("            Interactively offers to run `supabase db push` + `functions deploy`; if a");
-  console.log("            project is reachable (SUPABASE_URL/SUPABASE_ANON_KEY env vars, or --url/--key),");
+  console.log("            project is reachable (SUPABASE_URL/SUPABASE_SERVICE_ROLE_KEY env vars, or --url/--key),");
   console.log("            also walks through anonymous sign-in, per-table writes, RPC exposure, and");
   console.log("            documentation for tables/columns missing a comment.");
   console.log("  generate  Build exposify.manifest.json from a running local/linked project");

package/dist/index.cjs

@@ -162,12 +162,19 @@ function createPostgrestClient(postgrestUrl, headers, fetchImpl) {
 }
 
 // src/fetch-openapi.ts
+var WRONG_KEY_TIER_RE = /service_role|secret api key/i;
 async function fetchOpenApi(postgrestUrl, headers, fetchImpl) {
   const res = await fetchImpl(postgrestUrl, {
     headers: { ...Object.fromEntries(headers), accept: "application/openapi+json" }
   });
   if (!res.ok) {
-    throw new Error(`PostgREST OpenAPI fetch failed: HTTP ${res.status}`);
+    const body = await res.text().catch(() => "");
+    if (res.status === 401 && WRONG_KEY_TIER_RE.test(body)) {
+      throw new Error(
+        `PostgREST OpenAPI fetch failed: HTTP 401 -- Supabase rejected this request because it wasn't made with the service role key (response: "${body.trim()}"). Schema introspection always needs SUPABASE_SERVICE_ROLE_KEY, never the anon key -- see this package's README, "Why introspection needs the service role key". In a deployed function this is auto-injected automatically; for local dev/testing pass { serviceRoleKey } explicitly (or --key for the CLI).`
+      );
+    }
+    throw new Error(`PostgREST OpenAPI fetch failed: HTTP ${res.status}${body ? `: ${body}` : ""}`);
   }
   return await res.json();
 }
@@ -638,6 +645,7 @@ function aiReady(options = {}) {
   const env = denoEnv();
   const supabaseUrl = options.supabaseUrl ?? env?.get("SUPABASE_URL");
   const anonKey = options.anonKey ?? env?.get("SUPABASE_ANON_KEY") ?? "";
+  const serviceRoleKey = options.serviceRoleKey ?? env?.get("SUPABASE_SERVICE_ROLE_KEY") ?? "";
   let kbPromise = null;
   const getKb = () => {
     kbPromise ??= (async () => {
@@ -655,7 +663,7 @@ function aiReady(options = {}) {
   const getLadder = (postgrestUrl) => {
     ladderPromise ??= resolveTableSchemas({
       postgrestUrl,
-      headers: buildPostgrestHeaders(new Headers(), anonKey),
+      headers: buildPostgrestHeaders(new Headers(), serviceRoleKey),
       fetchImpl,
       manifest: options.manifest
     }).then((ladder) => {

package/dist/index.d.cts

@@ -60,6 +60,18 @@ interface AgentifySupabaseOptions {
     /** Overrides for local/CI use -- production reads these from the Deno env automatically. */
     supabaseUrl?: string;
     anonKey?: string;
+    /**
+     * Used ONLY for schema introspection (fetching PostgREST's OpenAPI document
+     * + calling `exposify_meta()`) -- never for per-request data access, which
+     * always uses the caller's forwarded JWT (or the anon key as its fallback).
+     * Required because Supabase's gateway rejects the OpenAPI-discovery route
+     * for anon/publishable-tier keys outright (`Invalid API key` / `Only the
+     * service_role API key can be used for this endpoint`), regardless of key
+     * format -- discovered via a real deployment, not documented anywhere at
+     * design time. Auto-injected as `SUPABASE_SERVICE_ROLE_KEY` in every
+     * deployed edge function; this option exists for local dev/testing only.
+     */
+    serviceRoleKey?: string;
     /** Injectable for tests; defaults to global `fetch`. */
     fetchImpl?: typeof fetch;
     /** Bundled fallback manifest (from `exposify-supabase generate`), used when runtime introspection fails. */
@@ -156,7 +168,15 @@ declare class MissingExposifyMetaError extends Error {
  */
 declare function fetchExposifyMeta(postgrestUrl: string, headers: Headers, fetchImpl: typeof fetch): Promise<MetaRow[]>;
 
-/** PostgREST serves its OpenAPI document at the API root when asked for it explicitly. */
+/**
+ * PostgREST serves its OpenAPI document at the API root when asked for it
+ * explicitly. This is the one call in the whole SDK most likely to fail for
+ * a specific, fixable reason (the wrong key tier -- see decisions journal
+ * §9), so unlike a generic fetch wrapper this one reads the body on failure
+ * and turns that one known failure mode into a self-diagnosing message
+ * naming the exact fix, the same pattern `meta.ts` already uses for a
+ * missing `exposify_meta()` migration.
+ */
 declare function fetchOpenApi(postgrestUrl: string, headers: Headers, fetchImpl: typeof fetch): Promise<PostgrestOpenApiDoc>;
 
 /**

package/dist/index.d.ts

@@ -60,6 +60,18 @@ interface AgentifySupabaseOptions {
     /** Overrides for local/CI use -- production reads these from the Deno env automatically. */
     supabaseUrl?: string;
     anonKey?: string;
+    /**
+     * Used ONLY for schema introspection (fetching PostgREST's OpenAPI document
+     * + calling `exposify_meta()`) -- never for per-request data access, which
+     * always uses the caller's forwarded JWT (or the anon key as its fallback).
+     * Required because Supabase's gateway rejects the OpenAPI-discovery route
+     * for anon/publishable-tier keys outright (`Invalid API key` / `Only the
+     * service_role API key can be used for this endpoint`), regardless of key
+     * format -- discovered via a real deployment, not documented anywhere at
+     * design time. Auto-injected as `SUPABASE_SERVICE_ROLE_KEY` in every
+     * deployed edge function; this option exists for local dev/testing only.
+     */
+    serviceRoleKey?: string;
     /** Injectable for tests; defaults to global `fetch`. */
     fetchImpl?: typeof fetch;
     /** Bundled fallback manifest (from `exposify-supabase generate`), used when runtime introspection fails. */
@@ -156,7 +168,15 @@ declare class MissingExposifyMetaError extends Error {
  */
 declare function fetchExposifyMeta(postgrestUrl: string, headers: Headers, fetchImpl: typeof fetch): Promise<MetaRow[]>;
 
-/** PostgREST serves its OpenAPI document at the API root when asked for it explicitly. */
+/**
+ * PostgREST serves its OpenAPI document at the API root when asked for it
+ * explicitly. This is the one call in the whole SDK most likely to fail for
+ * a specific, fixable reason (the wrong key tier -- see decisions journal
+ * §9), so unlike a generic fetch wrapper this one reads the body on failure
+ * and turns that one known failure mode into a self-diagnosing message
+ * naming the exact fix, the same pattern `meta.ts` already uses for a
+ * missing `exposify_meta()` migration.
+ */
 declare function fetchOpenApi(postgrestUrl: string, headers: Headers, fetchImpl: typeof fetch): Promise<PostgrestOpenApiDoc>;
 
 /**

package/dist/index.js

@@ -129,12 +129,19 @@ function createPostgrestClient(postgrestUrl, headers, fetchImpl) {
 }
 
 // src/fetch-openapi.ts
+var WRONG_KEY_TIER_RE = /service_role|secret api key/i;
 async function fetchOpenApi(postgrestUrl, headers, fetchImpl) {
   const res = await fetchImpl(postgrestUrl, {
     headers: { ...Object.fromEntries(headers), accept: "application/openapi+json" }
   });
   if (!res.ok) {
-    throw new Error(`PostgREST OpenAPI fetch failed: HTTP ${res.status}`);
+    const body = await res.text().catch(() => "");
+    if (res.status === 401 && WRONG_KEY_TIER_RE.test(body)) {
+      throw new Error(
+        `PostgREST OpenAPI fetch failed: HTTP 401 -- Supabase rejected this request because it wasn't made with the service role key (response: "${body.trim()}"). Schema introspection always needs SUPABASE_SERVICE_ROLE_KEY, never the anon key -- see this package's README, "Why introspection needs the service role key". In a deployed function this is auto-injected automatically; for local dev/testing pass { serviceRoleKey } explicitly (or --key for the CLI).`
+      );
+    }
+    throw new Error(`PostgREST OpenAPI fetch failed: HTTP ${res.status}${body ? `: ${body}` : ""}`);
   }
   return await res.json();
 }
@@ -608,6 +615,7 @@ function aiReady(options = {}) {
   const env = denoEnv();
   const supabaseUrl = options.supabaseUrl ?? env?.get("SUPABASE_URL");
   const anonKey = options.anonKey ?? env?.get("SUPABASE_ANON_KEY") ?? "";
+  const serviceRoleKey = options.serviceRoleKey ?? env?.get("SUPABASE_SERVICE_ROLE_KEY") ?? "";
   let kbPromise = null;
   const getKb = () => {
     kbPromise ??= (async () => {
@@ -625,7 +633,7 @@ function aiReady(options = {}) {
   const getLadder = (postgrestUrl) => {
     ladderPromise ??= resolveTableSchemas({
       postgrestUrl,
-      headers: buildPostgrestHeaders(new Headers(), anonKey),
+      headers: buildPostgrestHeaders(new Headers(), serviceRoleKey),
       fetchImpl,
       manifest: options.manifest
     }).then((ladder) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exposify/supabase",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -27,7 +27,7 @@
     "prepack": "yarn build"
   },
   "dependencies": {
-    "@exposify/core": "0.2.0",
+    "@exposify/core": "0.3.1",
     "@modelcontextprotocol/sdk": "^1.12.0",
     "zod": "^3.24.0"
   },