@palbase/web 2.0.1 → 4.0.0

package/dist/next/client.d.cts

@@ -5,7 +5,7 @@ import { S as SessionStorageAdapter } from '../storage-BPaeSG8K.cjs';
  * PersistedSession (access token + expiry ride along) so hydration adopts
  * the full session without a refresh round-trip.
  */
-declare function cookieSessionStorage(endpointRef: string): SessionStorageAdapter;
+declare function cookieSessionStorage(environmentRef: string): SessionStorageAdapter;
 /**
  * One-liner for a client component/provider: re-configure the already-loaded
  * gen config (palbe.gen.ts must be imported first — throws the guided

package/dist/next/client.d.ts

@@ -5,7 +5,7 @@ import { S as SessionStorageAdapter } from '../storage-BPaeSG8K.js';
  * PersistedSession (access token + expiry ride along) so hydration adopts
  * the full session without a refresh round-trip.
  */
-declare function cookieSessionStorage(endpointRef: string): SessionStorageAdapter;
+declare function cookieSessionStorage(environmentRef: string): SessionStorageAdapter;
 /**
  * One-liner for a client component/provider: re-configure the already-loaded
  * gen config (palbe.gen.ts must be imported first — throws the guided

package/dist/next/client.js

@@ -2,13 +2,12 @@ import {
   clearedSessionCookieNames,
   decodeSessionCookies,
   encodeSessionCookies
-} from "../chunk-VJXFABBW.js";
+} from "../chunk-6VGKMNXO.js";
 import {
   __configure,
-  endpointRefFromApiKey,
   getRuntime
-} from "../chunk-AIPUO4QX.js";
-import "../chunk-PZ5AY32C.js";
+} from "../chunk-NP4NIY7A.js";
+import "../chunk-S7NAY3MW.js";
 
 // src/next/client.ts
 var SESSION_MAX_AGE_S = 2592e3;
@@ -26,12 +25,12 @@ function cookieJar() {
 function deleteCookie(name) {
   document.cookie = `${name}=; ${WRITE_ATTRS}; Max-Age=0`;
 }
-function cookieSessionStorage(endpointRef) {
+function cookieSessionStorage(environmentRef) {
   return {
     load() {
       if (typeof document === "undefined") return null;
       const jar = cookieJar();
-      const stored = decodeSessionCookies((name) => jar.get(name), endpointRef);
+      const stored = decodeSessionCookies((name) => jar.get(name), environmentRef);
       if (!stored) return null;
       return stored.accessToken && stored.expiresAt > 0 ? {
         refreshToken: stored.refreshToken,
@@ -42,10 +41,10 @@ function cookieSessionStorage(endpointRef) {
     save(session) {
       if (typeof document === "undefined") return;
       const jar = cookieJar();
-      for (const name of clearedSessionCookieNames(endpointRef, (n) => jar.has(n))) {
+      for (const name of clearedSessionCookieNames(environmentRef, (n) => jar.has(n))) {
         deleteCookie(name);
       }
-      const { set, clear } = encodeSessionCookies(endpointRef, {
+      const { set, clear } = encodeSessionCookies(environmentRef, {
         accessToken: session.accessToken ?? "",
         refreshToken: session.refreshToken,
         expiresAt: session.expiresAt ?? 0
@@ -58,7 +57,7 @@ function cookieSessionStorage(endpointRef) {
     clear() {
       if (typeof document === "undefined") return;
       const jar = cookieJar();
-      for (const name of clearedSessionCookieNames(endpointRef, (n) => jar.has(n))) {
+      for (const name of clearedSessionCookieNames(environmentRef, (n) => jar.has(n))) {
         deleteCookie(name);
       }
     }
@@ -67,7 +66,10 @@ function cookieSessionStorage(endpointRef) {
 function setupPalbeNext() {
   if (typeof document === "undefined") return;
   const config = getRuntime().config;
-  __configure({ ...config, storage: cookieSessionStorage(endpointRefFromApiKey(config.apiKey)) });
+  __configure({
+    ...config,
+    storage: cookieSessionStorage(config.environmentRef)
+  });
 }
 export {
   cookieSessionStorage,

package/dist/next/client.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/next/client.ts"],"sourcesContent":["/**\n * '@palbase/web/next/client' — the browser half of the Next.js adapter. This entry\n * must NEVER import 'next' (it runs in plain client bundles); the cookie jar\n * is document.cookie itself, written with the shared codec so the server\n * side (pbServer / middleware / callback) reads the same bytes.\n */\nimport { __configure, getRuntime } from '../internal.js';\nimport type { PersistedSession, SessionStorageAdapter } from '../storage.js';\nimport {\n  clearedSessionCookieNames,\n  decodeSessionCookies,\n  encodeSessionCookies,\n  endpointRefFromApiKey,\n} from './cookie-codec.js';\n\n/** 30 days — the refresh-token TTL (P3 design contract). */\nconst SESSION_MAX_AGE_S = 2_592_000;\n\n// Secure is unconditional, INCLUDING http://localhost: browsers treat\n// localhost as a potentially-trustworthy origin, so document.cookie accepts\n// Secure cookies there — no dev-mode special case needed. KNOWN LIMITATION:\n// plain-http origins OTHER than localhost — e.g. LAN-IP device testing on\n// http://192.168.x.x — are NOT trustworthy, so the browser silently DROPS\n// these Secure cookie writes and the session won't persist; use https (or a\n// localhost tunnel/port-forward) for on-device testing. NOT HttpOnly by\n// design: the browser SDK must read/write the session (Supabase-paradigm\n// tradeoff, documented in the P3 plan).\nconst WRITE_ATTRS = 'Path=/; SameSite=Lax; Secure';\n\n/** Parse document.cookie (\"a=1; b=2\") into a name → raw-value map. */\nfunction cookieJar(): Map<string, string> {\n  const jar = new Map<string, string>();\n  for (const part of document.cookie.split(';')) {\n    const eq = part.indexOf('=');\n    if (eq === -1) continue;\n    const name = part.slice(0, eq).trim();\n    if (name) jar.set(name, part.slice(eq + 1).trim());\n  }\n  return jar;\n}\n\nfunction deleteCookie(name: string): void {\n  // biome-ignore lint/suspicious/noDocumentCookie: SessionStorageAdapter is a SYNC contract; the async Cookie Store API can't back it (and isn't universal).\n  document.cookie = `${name}=; ${WRITE_ATTRS}; Max-Age=0`;\n}\n\n/**\n * document.cookie-backed SessionStorageAdapter. `load` returns the EXTENDED\n * PersistedSession (access token + expiry ride along) so hydration adopts\n * the full session without a refresh round-trip.\n */\nexport function cookieSessionStorage(endpointRef: string): SessionStorageAdapter {\n  return {\n    load(): PersistedSession | null {\n      if (typeof document === 'undefined') return null;\n      const jar = cookieJar();\n      const stored = decodeSessionCookies((name) => jar.get(name), endpointRef);\n      if (!stored) return null;\n      // A refresh-only save round-trips as a:'' / e:0 — normalize back to\n      // the legacy shape so hydration takes the expired-trick path cleanly.\n      return stored.accessToken && stored.expiresAt > 0\n        ? {\n            refreshToken: stored.refreshToken,\n            accessToken: stored.accessToken,\n            expiresAt: stored.expiresAt,\n          }\n        : { refreshToken: stored.refreshToken };\n    },\n    save(session: PersistedSession): void {\n      if (typeof document === 'undefined') return;\n      const jar = cookieJar();\n      // Delete every currently-present session cookie first (stale chunks of\n      // a previously-larger session, or a stale base when the new write\n      // chunks), then set the new cookie(s).\n      for (const name of clearedSessionCookieNames(endpointRef, (n) => jar.has(n))) {\n        deleteCookie(name);\n      }\n      const { set, clear } = encodeSessionCookies(endpointRef, {\n        accessToken: session.accessToken ?? '',\n        refreshToken: session.refreshToken,\n        expiresAt: session.expiresAt ?? 0,\n      });\n      for (const { name, value } of set) {\n        // biome-ignore lint/suspicious/noDocumentCookie: SessionStorageAdapter is a SYNC contract; the async Cookie Store API can't back it (and isn't universal).\n        document.cookie = `${name}=${value}; ${WRITE_ATTRS}; Max-Age=${SESSION_MAX_AGE_S}`;\n      }\n      // Overflow guard (codec contract): delete one-past-the-end so a stale\n      // orphan chunk behind a gap can never join a future chunk run.\n      for (const name of clear) deleteCookie(name);\n    },\n    clear(): void {\n      if (typeof document === 'undefined') return;\n      const jar = cookieJar();\n      for (const name of clearedSessionCookieNames(endpointRef, (n) => jar.has(n))) {\n        deleteCookie(name);\n      }\n    },\n  };\n}\n\n/**\n * One-liner for a client component/provider: re-configure the already-loaded\n * gen config (palbe.gen.ts must be imported first — throws the guided\n * notConfigured error otherwise) with cookie-backed session storage so the\n * browser and the server share the session. Calling it again simply\n * re-configures (safe, e.g. under fast refresh). When Next evaluates the\n * client component module server-side there is no document — no-op.\n */\nexport function setupPalbeNext(): void {\n  if (typeof document === 'undefined') return;\n  const config = getRuntime().config;\n  __configure({ ...config, storage: cookieSessionStorage(endpointRefFromApiKey(config.apiKey)) });\n}\n"],"mappings":";;;;;;;;;;;;;AAgBA,IAAM,oBAAoB;AAW1B,IAAM,cAAc;AAGpB,SAAS,YAAiC;AACxC,QAAM,MAAM,oBAAI,IAAoB;AACpC,aAAW,QAAQ,SAAS,OAAO,MAAM,GAAG,GAAG;AAC7C,UAAM,KAAK,KAAK,QAAQ,GAAG;AAC3B,QAAI,OAAO,GAAI;AACf,UAAM,OAAO,KAAK,MAAM,GAAG,EAAE,EAAE,KAAK;AACpC,QAAI,KAAM,KAAI,IAAI,MAAM,KAAK,MAAM,KAAK,CAAC,EAAE,KAAK,CAAC;AAAA,EACnD;AACA,SAAO;AACT;AAEA,SAAS,aAAa,MAAoB;AAExC,WAAS,SAAS,GAAG,IAAI,MAAM,WAAW;AAC5C;AAOO,SAAS,qBAAqB,aAA4C;AAC/E,SAAO;AAAA,IACL,OAAgC;AAC9B,UAAI,OAAO,aAAa,YAAa,QAAO;AAC5C,YAAM,MAAM,UAAU;AACtB,YAAM,SAAS,qBAAqB,CAAC,SAAS,IAAI,IAAI,IAAI,GAAG,WAAW;AACxE,UAAI,CAAC,OAAQ,QAAO;AAGpB,aAAO,OAAO,eAAe,OAAO,YAAY,IAC5C;AAAA,QACE,cAAc,OAAO;AAAA,QACrB,aAAa,OAAO;AAAA,QACpB,WAAW,OAAO;AAAA,MACpB,IACA,EAAE,cAAc,OAAO,aAAa;AAAA,IAC1C;AAAA,IACA,KAAK,SAAiC;AACpC,UAAI,OAAO,aAAa,YAAa;AACrC,YAAM,MAAM,UAAU;AAItB,iBAAW,QAAQ,0BAA0B,aAAa,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,GAAG;AAC5E,qBAAa,IAAI;AAAA,MACnB;AACA,YAAM,EAAE,KAAK,MAAM,IAAI,qBAAqB,aAAa;AAAA,QACvD,aAAa,QAAQ,eAAe;AAAA,QACpC,cAAc,QAAQ;AAAA,QACtB,WAAW,QAAQ,aAAa;AAAA,MAClC,CAAC;AACD,iBAAW,EAAE,MAAM,MAAM,KAAK,KAAK;AAEjC,iBAAS,SAAS,GAAG,IAAI,IAAI,KAAK,KAAK,WAAW,aAAa,iBAAiB;AAAA,MAClF;AAGA,iBAAW,QAAQ,MAAO,cAAa,IAAI;AAAA,IAC7C;AAAA,IACA,QAAc;AACZ,UAAI,OAAO,aAAa,YAAa;AACrC,YAAM,MAAM,UAAU;AACtB,iBAAW,QAAQ,0BAA0B,aAAa,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,GAAG;AAC5E,qBAAa,IAAI;AAAA,MACnB;AAAA,IACF;AAAA,EACF;AACF;AAUO,SAAS,iBAAuB;AACrC,MAAI,OAAO,aAAa,YAAa;AACrC,QAAM,SAAS,WAAW,EAAE;AAC5B,cAAY,EAAE,GAAG,QAAQ,SAAS,qBAAqB,sBAAsB,OAAO,MAAM,CAAC,EAAE,CAAC;AAChG;","names":[]}
+{"version":3,"sources":["../../src/next/client.ts"],"sourcesContent":["/**\n * '@palbase/web/next/client' — the browser half of the Next.js adapter. This entry\n * must NEVER import 'next' (it runs in plain client bundles); the cookie jar\n * is document.cookie itself, written with the shared codec so the server\n * side (pbServer / middleware / callback) reads the same bytes.\n */\nimport { __configure, getRuntime } from '../internal.js';\nimport type { PersistedSession, SessionStorageAdapter } from '../storage.js';\nimport {\n  clearedSessionCookieNames,\n  decodeSessionCookies,\n  encodeSessionCookies,\n} from './cookie-codec.js';\n\n/** 30 days — the refresh-token TTL (P3 design contract). */\nconst SESSION_MAX_AGE_S = 2_592_000;\n\n// Secure is unconditional, INCLUDING http://localhost: browsers treat\n// localhost as a potentially-trustworthy origin, so document.cookie accepts\n// Secure cookies there — no dev-mode special case needed. KNOWN LIMITATION:\n// plain-http origins OTHER than localhost — e.g. LAN-IP device testing on\n// http://192.168.x.x — are NOT trustworthy, so the browser silently DROPS\n// these Secure cookie writes and the session won't persist; use https (or a\n// localhost tunnel/port-forward) for on-device testing. NOT HttpOnly by\n// design: the browser SDK must read/write the session (Supabase-paradigm\n// tradeoff, documented in the P3 plan).\nconst WRITE_ATTRS = 'Path=/; SameSite=Lax; Secure';\n\n/** Parse document.cookie (\"a=1; b=2\") into a name → raw-value map. */\nfunction cookieJar(): Map<string, string> {\n  const jar = new Map<string, string>();\n  for (const part of document.cookie.split(';')) {\n    const eq = part.indexOf('=');\n    if (eq === -1) continue;\n    const name = part.slice(0, eq).trim();\n    if (name) jar.set(name, part.slice(eq + 1).trim());\n  }\n  return jar;\n}\n\nfunction deleteCookie(name: string): void {\n  // biome-ignore lint/suspicious/noDocumentCookie: SessionStorageAdapter is a SYNC contract; the async Cookie Store API can't back it (and isn't universal).\n  document.cookie = `${name}=; ${WRITE_ATTRS}; Max-Age=0`;\n}\n\n/**\n * document.cookie-backed SessionStorageAdapter. `load` returns the EXTENDED\n * PersistedSession (access token + expiry ride along) so hydration adopts\n * the full session without a refresh round-trip.\n */\nexport function cookieSessionStorage(environmentRef: string): SessionStorageAdapter {\n  return {\n    load(): PersistedSession | null {\n      if (typeof document === 'undefined') return null;\n      const jar = cookieJar();\n      const stored = decodeSessionCookies((name) => jar.get(name), environmentRef);\n      if (!stored) return null;\n      // A refresh-only save round-trips as a:'' / e:0 — normalize back to\n      // the legacy shape so hydration takes the expired-trick path cleanly.\n      return stored.accessToken && stored.expiresAt > 0\n        ? {\n            refreshToken: stored.refreshToken,\n            accessToken: stored.accessToken,\n            expiresAt: stored.expiresAt,\n          }\n        : { refreshToken: stored.refreshToken };\n    },\n    save(session: PersistedSession): void {\n      if (typeof document === 'undefined') return;\n      const jar = cookieJar();\n      // Delete every currently-present session cookie first (stale chunks of\n      // a previously-larger session, or a stale base when the new write\n      // chunks), then set the new cookie(s).\n      for (const name of clearedSessionCookieNames(environmentRef, (n) => jar.has(n))) {\n        deleteCookie(name);\n      }\n      const { set, clear } = encodeSessionCookies(environmentRef, {\n        accessToken: session.accessToken ?? '',\n        refreshToken: session.refreshToken,\n        expiresAt: session.expiresAt ?? 0,\n      });\n      for (const { name, value } of set) {\n        // biome-ignore lint/suspicious/noDocumentCookie: SessionStorageAdapter is a SYNC contract; the async Cookie Store API can't back it (and isn't universal).\n        document.cookie = `${name}=${value}; ${WRITE_ATTRS}; Max-Age=${SESSION_MAX_AGE_S}`;\n      }\n      // Overflow guard (codec contract): delete one-past-the-end so a stale\n      // orphan chunk behind a gap can never join a future chunk run.\n      for (const name of clear) deleteCookie(name);\n    },\n    clear(): void {\n      if (typeof document === 'undefined') return;\n      const jar = cookieJar();\n      for (const name of clearedSessionCookieNames(environmentRef, (n) => jar.has(n))) {\n        deleteCookie(name);\n      }\n    },\n  };\n}\n\n/**\n * One-liner for a client component/provider: re-configure the already-loaded\n * gen config (palbe.gen.ts must be imported first — throws the guided\n * notConfigured error otherwise) with cookie-backed session storage so the\n * browser and the server share the session. Calling it again simply\n * re-configures (safe, e.g. under fast refresh). When Next evaluates the\n * client component module server-side there is no document — no-op.\n */\nexport function setupPalbeNext(): void {\n  if (typeof document === 'undefined') return;\n  const config = getRuntime().config;\n  __configure({\n    ...config,\n    storage: cookieSessionStorage(config.environmentRef),\n  });\n}\n"],"mappings":";;;;;;;;;;;;AAeA,IAAM,oBAAoB;AAW1B,IAAM,cAAc;AAGpB,SAAS,YAAiC;AACxC,QAAM,MAAM,oBAAI,IAAoB;AACpC,aAAW,QAAQ,SAAS,OAAO,MAAM,GAAG,GAAG;AAC7C,UAAM,KAAK,KAAK,QAAQ,GAAG;AAC3B,QAAI,OAAO,GAAI;AACf,UAAM,OAAO,KAAK,MAAM,GAAG,EAAE,EAAE,KAAK;AACpC,QAAI,KAAM,KAAI,IAAI,MAAM,KAAK,MAAM,KAAK,CAAC,EAAE,KAAK,CAAC;AAAA,EACnD;AACA,SAAO;AACT;AAEA,SAAS,aAAa,MAAoB;AAExC,WAAS,SAAS,GAAG,IAAI,MAAM,WAAW;AAC5C;AAOO,SAAS,qBAAqB,gBAA+C;AAClF,SAAO;AAAA,IACL,OAAgC;AAC9B,UAAI,OAAO,aAAa,YAAa,QAAO;AAC5C,YAAM,MAAM,UAAU;AACtB,YAAM,SAAS,qBAAqB,CAAC,SAAS,IAAI,IAAI,IAAI,GAAG,cAAc;AAC3E,UAAI,CAAC,OAAQ,QAAO;AAGpB,aAAO,OAAO,eAAe,OAAO,YAAY,IAC5C;AAAA,QACE,cAAc,OAAO;AAAA,QACrB,aAAa,OAAO;AAAA,QACpB,WAAW,OAAO;AAAA,MACpB,IACA,EAAE,cAAc,OAAO,aAAa;AAAA,IAC1C;AAAA,IACA,KAAK,SAAiC;AACpC,UAAI,OAAO,aAAa,YAAa;AACrC,YAAM,MAAM,UAAU;AAItB,iBAAW,QAAQ,0BAA0B,gBAAgB,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,GAAG;AAC/E,qBAAa,IAAI;AAAA,MACnB;AACA,YAAM,EAAE,KAAK,MAAM,IAAI,qBAAqB,gBAAgB;AAAA,QAC1D,aAAa,QAAQ,eAAe;AAAA,QACpC,cAAc,QAAQ;AAAA,QACtB,WAAW,QAAQ,aAAa;AAAA,MAClC,CAAC;AACD,iBAAW,EAAE,MAAM,MAAM,KAAK,KAAK;AAEjC,iBAAS,SAAS,GAAG,IAAI,IAAI,KAAK,KAAK,WAAW,aAAa,iBAAiB;AAAA,MAClF;AAGA,iBAAW,QAAQ,MAAO,cAAa,IAAI;AAAA,IAC7C;AAAA,IACA,QAAc;AACZ,UAAI,OAAO,aAAa,YAAa;AACrC,YAAM,MAAM,UAAU;AACtB,iBAAW,QAAQ,0BAA0B,gBAAgB,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,GAAG;AAC/E,qBAAa,IAAI;AAAA,MACnB;AAAA,IACF;AAAA,EACF;AACF;AAUO,SAAS,iBAAuB;AACrC,MAAI,OAAO,aAAa,YAAa;AACrC,QAAM,SAAS,WAAW,EAAE;AAC5B,cAAY;AAAA,IACV,GAAG;AAAA,IACH,SAAS,qBAAqB,OAAO,cAAc;AAAA,EACrD,CAAC;AACH;","names":[]}

package/dist/next/index.cjs

@@ -35,7 +35,7 @@ __export(next_exports, {
   decodeSessionCookies: () => decodeSessionCookies,
   encodeSessionCookies: () => encodeSessionCookies,
   encodeSessionCookiesDecoded: () => encodeSessionCookiesDecoded,
-  endpointRefFromApiKey: () => endpointRefFromApiKey,
+  environmentRefFromApiKey: () => environmentRefFromApiKey,
   handleAuthCallback: () => handleAuthCallback,
   palbeMiddleware: () => palbeMiddleware,
   pbServer: () => pbServer,
@@ -57,11 +57,16 @@ function asWireAuthResult(raw) {
 }
 
 // src/api-key.ts
-var API_KEY_RE = /^pb_([^_]+)_[cs][A-Za-z0-9]{20}$/;
-function endpointRefFromApiKey(apiKey) {
+var API_KEY_RE = /^pb_([a-z0-9]+)_[cs][A-Za-z0-9]{20}$/;
+var PUBLISHABLE_API_KEY_RE = /^pb_([a-z0-9]+)_c[A-Za-z0-9]{20}$/;
+function environmentRefFromApiKey(apiKey) {
   const m = API_KEY_RE.exec(apiKey);
   return m ? m[1] ?? "" : "";
 }
+function environmentRefFromPublishableApiKey(apiKey) {
+  const match = PUBLISHABLE_API_KEY_RE.exec(apiKey);
+  return match ? match[1] ?? "" : "";
+}
 
 // src/next/cookie-codec.ts
 var MAX_COOKIE_VALUE = 3500;
@@ -71,11 +76,11 @@ var SESSION_COOKIE_ATTRS = {
   secure: true,
   maxAge: 2592e3
 };
-function sessionCookieName(endpointRef) {
-  return `palbe-session-${endpointRef}`;
+function sessionCookieName(environmentRef) {
+  return `palbe-session-${environmentRef}`;
 }
-function encodeSessionCookies(endpointRef, session) {
-  const name = sessionCookieName(endpointRef);
+function encodeSessionCookies(environmentRef, session) {
+  const name = sessionCookieName(environmentRef);
   const value = encodeURIComponent(
     JSON.stringify({ a: session.accessToken, r: session.refreshToken, e: session.expiresAt })
   );
@@ -94,15 +99,15 @@ function encodeSessionCookies(endpointRef, session) {
   }
   return { set: chunks, clear: [`${name}.${chunks.length}`] };
 }
-function encodeSessionCookiesDecoded(endpointRef, session) {
-  const { set, clear } = encodeSessionCookies(endpointRef, session);
+function encodeSessionCookiesDecoded(environmentRef, session) {
+  const { set, clear } = encodeSessionCookies(environmentRef, session);
   return {
     set: set.map(({ name, value }) => ({ name, value: decodeURIComponent(value) })),
     clear
   };
 }
-function decodeSessionCookies(get, endpointRef) {
-  const base = sessionCookieName(endpointRef);
+function decodeSessionCookies(get, environmentRef) {
+  const base = sessionCookieName(environmentRef);
   let encoded = get(base);
   if (encoded === void 0) {
     let joined = "";
@@ -136,8 +141,8 @@ function parseStoredSession(json) {
     return null;
   }
 }
-function clearedSessionCookieNames(endpointRef, present) {
-  const base = sessionCookieName(endpointRef);
+function clearedSessionCookieNames(environmentRef, present) {
+  const base = sessionCookieName(environmentRef);
   const names = [];
   if (present(base)) names.push(base);
   for (let i = 0; ; i++) {
@@ -163,18 +168,9 @@ var PalbaseError = class extends Error {
   }
 };
 var PALBASE_DEFAULT_HOST = "api.palbase.studio";
-var REF_LEN = 8;
-var BASE62_RE = /^[0-9A-Za-z]+$/;
-function parseProjectRef(apiKey) {
-  if (apiKey.length < 13) return null;
-  if (!apiKey.startsWith("pb_")) return null;
-  if (apiKey[11] !== "_") return null;
-  const ref = apiKey.slice(3, 11);
-  if (ref.length !== REF_LEN) return null;
-  if (!BASE62_RE.test(ref)) return null;
-  const scope = apiKey[12];
-  if (scope !== "c") return null;
-  return ref;
+var API_KEY_RE2 = /^pb_([a-z0-9]+)_c[A-Za-z0-9]{20}$/;
+function parseEnvironmentRef(apiKey) {
+  return API_KEY_RE2.exec(apiKey)?.[1] ?? null;
 }
 var MAX_RETRIES = 3;
 var INITIAL_BACKOFF_MS = 200;
@@ -204,8 +200,7 @@ var HttpClient = class _HttpClient {
    * with the parent at runtime — later changes on the parent propagate to
    * the scope and vice versa.
    *
-   * Typical use: tagging admin calls with `x-palbase-project: <ref>` so the
-   * gateway can route them to the correct project's data plane.
+   * Typical use: adding an Environment-routing header for an admin call.
    */
   withHeaders(extra) {
     const mergedHeaders = { ...this.options?.headers ?? {}, ...extra };
@@ -246,10 +241,10 @@ var HttpClient = class _HttpClient {
     if (this.options?.url) {
       return this.options.url;
     }
-    if (this.apiKey && parseProjectRef(this.apiKey) === null) {
+    if (this.apiKey && parseEnvironmentRef(this.apiKey) === null) {
       throw new PalbaseError(
         "invalid_api_key",
-        'Invalid API key format. Expected pb_{ref}_{scope}{random}. For dev/staging pass `url: "https://api.dev.palbase.studio"` via options.',
+        'Invalid API key format. Expected pb_{environment_ref}_c{20_base62_chars}. For dev/staging pass `url: "https://api.dev.palbase.studio"` via options.',
         0
       );
     }
@@ -262,10 +257,6 @@ var HttpClient = class _HttpClient {
     const effectiveKey = this.apiKey;
     if (effectiveKey) {
       headers["apikey"] = effectiveKey;
-      const ref = parseProjectRef(effectiveKey);
-      if (ref) {
-        headers["X-Project-Ref"] = ref;
-      }
     }
     const token = this.tokenManager?.getAccessToken();
     if (token) {
@@ -1245,7 +1236,7 @@ var AnalyticsState = class {
   idKey;
   optOutKey;
   constructor(rt) {
-    const ref = endpointRefFromApiKey(rt.config.apiKey);
+    const ref = rt.config.environmentRef;
     this.idKey = ref ? `palbe.analytics.id.${ref}` : "palbe.analytics.id";
     this.optOutKey = ref ? `palbe.analytics.optout.${ref}` : "palbe.analytics.optout";
     rt.auth.onAuthEvent((event) => {
@@ -1793,19 +1784,29 @@ var PalbeAuth = class {
 
 // src/calls/facade.ts
 var import_livekit_client = require("livekit-client");
-var Call = class {
+var Call = class _Call {
   id;
   _state = "connecting";
   _participants = /* @__PURE__ */ new Map();
   _listeners = /* @__PURE__ */ new Set();
   _room;
   _keyProvider;
-  /** @internal — obtain via PalbeCalls.start() / .accept() */
+  // PRIVATE constructor + `@internal` factory: the media-engine types (`Room`,
+  // `ExternalE2EEKeyProvider`) appear ONLY on a private constructor and an
+  // `@internal` static factory, both of which `stripInternal` (set in this
+  // package's tsconfig) removes from the emitted public `.d.ts`. So no engine type
+  // ever reaches the public API surface — the same "no engine type in the public
+  // interface" contract the iOS SDK enforces. Consumers obtain a `Call` only
+  // through `pb.calls.start()` / `.accept()`.
   constructor(callId, room, keyProvider) {
     this.id = callId;
     this._room = room;
     this._keyProvider = keyProvider;
-    this._wireRoomEvents();
+    this._wireMediaEvents();
+  }
+  /** @internal — facade-only factory; stripped from the public `.d.ts`. */
+  static _create(callId, room, keyProvider) {
+    return new _Call(callId, room, keyProvider);
   }
   // ─── State ──────────────────────────────────────────────────────────────
   get state() {
@@ -1815,9 +1816,9 @@ var Call = class {
   get participants() {
     return Array.from(this._participants.values());
   }
-  get localParticipant() {
-    return this._room.localParticipant;
-  }
+  // (No `localParticipant` accessor: it would return a raw media-engine participant
+  // object and leak the engine type onto the public API. Local mic/camera control is
+  // exposed engine-agnostically via `mute()` / `setCamera()` below.)
   // ─── Subscribe ──────────────────────────────────────────────────────────
   /**
    * Subscribe to call changes (state + participant updates).
@@ -1841,7 +1842,7 @@ var Call = class {
   /**
    * Set a raw frame encryption key (ArrayBuffer) for this call.
    * Design seam for SP-1.x web-MLS: call this with the MLS exporter secret
-   * to enable frame-level E2EE via ExternalE2EEKeyProvider.
+   * to enable frame-level E2EE via the media engine's external key provider.
    *
    * NOTE: The room must have been opened with `e2ee` options for this to take
    * effect. Currently calls connect WITHOUT e2ee — see module docstring.
@@ -1851,7 +1852,7 @@ var Call = class {
   async setMediaKey(key) {
     await this._keyProvider.setKey(key);
   }
-  /** Leave the call and disconnect from the LiveKit room. */
+  /** Leave the call and disconnect from the media room. */
   async leave() {
     await this._room.disconnect();
     this._setState("ended");
@@ -1893,7 +1894,7 @@ var Call = class {
     }
     this._emit();
   }
-  _wireRoomEvents() {
+  _wireMediaEvents() {
     this._room.on(import_livekit_client.RoomEvent.Connected, () => {
       this._setState("active");
     }).on(
@@ -1934,9 +1935,9 @@ var PalbeCalls = class {
    *
    * @param groupId  - Messaging group display-id (`grp_<uuidv7>`)
    * @param media    - Which media tracks to publish (default: audio + video)
-   * @returns        A `Call` in `connecting` state; transitions to `active` once LiveKit connects.
+   * @returns        A `Call` in `connecting` state; transitions to `active` once the media room connects.
    *
-   * @throws BackendError('network', { code: 'call_service_unavailable' })  if LiveKit SFU is down (503)
+   * @throws BackendError('network', { code: 'call_service_unavailable' })  if the SFU is down (503)
    * @throws BackendError('forbidden', { code: 'not_group_member' })       if the caller is not a member (403)
    * @throws BackendError('conflict', { code: 'call_room_full' })          if the room is full (409)
    */
@@ -1993,7 +1994,7 @@ var PalbeCalls = class {
       adaptiveStream: true,
       dynacast: true
     });
-    const call = new Call(callId, room, keyProvider);
+    const call = Call._create(callId, room, keyProvider);
     await room.connect(edgeUrl, token);
     if (media.includes("audio")) {
       await room.localParticipant.setMicrophoneEnabled(true);
@@ -2586,7 +2587,7 @@ var PalbeFlags = class {
   constructor(rt) {
     this.transport = new FlagsClient(rt.http);
     const browser = typeof document !== "undefined";
-    const ref = endpointRefFromApiKey(rt.config.apiKey);
+    const ref = rt.config.environmentRef;
     const options = {
       auth: palbeAuthAdapter(rt.auth),
       ...ref ? { storageKey: `palbe.flags.${ref}` } : {},
@@ -8326,7 +8327,7 @@ var AnonTokenProvider = class {
   }
   /**
    * Raw fetch, deliberately NOT through HttpClient/palbeRequest: the mint
-   * must carry the project apikey and NEVER a Bearer (iOS keeps
+   * must carry the Environment API key and NEVER a Bearer (iOS keeps
    * `/auth/anonymous` on the unauthenticated-path list), and HttpClient's
    * pre-flight would try to refresh a stale session before an anon mint —
    * exactly the entanglement this provider exists to avoid.
@@ -8983,10 +8984,25 @@ function defaultSessionStorage(key) {
 }
 
 // src/version.ts
-var VERSION = "2.0.1";
+var VERSION = "4.0.0";
 
 // src/runtime.ts
 function buildRuntime(config) {
+  const keyEnvironmentRef = environmentRefFromPublishableApiKey(config.apiKey);
+  if (keyEnvironmentRef === "") {
+    throw new Error("PalbeConfig.apiKey does not contain a valid publishable Environment identity");
+  } else if (config.environmentRef !== keyEnvironmentRef) {
+    throw new Error("PalbeConfig.environmentRef must match the Environment identity in apiKey");
+  }
+  let runtimeURL;
+  try {
+    runtimeURL = new URL(config.url);
+  } catch {
+    throw new Error("PalbeConfig.url must be a valid URL");
+  }
+  if (runtimeURL.hostname.endsWith(".palbase.studio") && runtimeURL.hostname.split(".")[0] !== config.environmentRef) {
+    throw new Error("PalbeConfig.url must match environmentRef for palbase.studio");
+  }
   const http = new HttpClient(config.apiKey, {
     url: config.url,
     headers: { "X-Client-Info": `palbe-web/${VERSION}`, ...config.headers }
@@ -8995,7 +9011,7 @@ function buildRuntime(config) {
   const tokenManager = new TokenManager();
   http.tokenManager = tokenManager;
   const authClient = new AuthClient(http, tokenManager);
-  const ref = endpointRefFromApiKey(config.apiKey);
+  const ref = config.environmentRef;
   const storage = config.storage ?? defaultSessionStorage(ref ? `palbe.session.${ref}` : void 0);
   const persisted = storage.load();
   if (persisted) {
@@ -9449,7 +9465,7 @@ function handleAuthCallback(opts) {
     const wire = asWireAuthResult(raw);
     if (!wire) return redirect(fallback, { auth_error: "oauth_exchange_failed" });
     const response = redirect(safeNextPath(params.get("next"), request.nextUrl.origin) ?? fallback);
-    const write = encodeSessionCookiesDecoded(endpointRefFromApiKey(config.apiKey), {
+    const write = encodeSessionCookiesDecoded(config.environmentRef, {
       accessToken: wire.access_token,
       refreshToken: wire.refresh_token,
       expiresAt: Date.now() + wire.expires_in * 1e3
@@ -9512,7 +9528,7 @@ async function palbeMiddleware(request, opts) {
   );
   const { NextResponse } = await importNextServer("palbeMiddleware");
   const passThrough = () => opts?.response ?? NextResponse.next({ request });
-  const ref = endpointRefFromApiKey(config.apiKey);
+  const ref = config.environmentRef;
   const session = decodeSessionCookies((name) => request.cookies.get(name)?.value, ref);
   if (!session) return passThrough();
   if (session.expiresAt - Date.now() > (opts?.refreshMarginMs ?? DEFAULT_REFRESH_MARGIN_MS)) {
@@ -9582,11 +9598,11 @@ function removeCookie(store, name) {
   } catch {
   }
 }
-function serverCookieAdapter(store, endpointRef) {
+function serverCookieAdapter(store, environmentRef) {
   const present = (name) => store.get(name) !== void 0;
   return {
     load() {
-      const stored = decodeSessionCookies((name) => store.get(name)?.value, endpointRef);
+      const stored = decodeSessionCookies((name) => store.get(name)?.value, environmentRef);
       if (!stored) return null;
       return stored.accessToken && stored.expiresAt > 0 ? {
         refreshToken: stored.refreshToken,
@@ -9596,10 +9612,10 @@ function serverCookieAdapter(store, endpointRef) {
     },
     save(session) {
       if (!session.accessToken || !session.expiresAt) return;
-      for (const name of clearedSessionCookieNames(endpointRef, present)) {
+      for (const name of clearedSessionCookieNames(environmentRef, present)) {
         removeCookie(store, name);
       }
-      const { set, clear } = encodeSessionCookiesDecoded(endpointRef, {
+      const { set, clear } = encodeSessionCookiesDecoded(environmentRef, {
         accessToken: session.accessToken,
         refreshToken: session.refreshToken,
         expiresAt: session.expiresAt
@@ -9613,7 +9629,7 @@ function serverCookieAdapter(store, endpointRef) {
       for (const name of clear) removeCookie(store, name);
     },
     clear() {
-      for (const name of clearedSessionCookieNames(endpointRef, present)) {
+      for (const name of clearedSessionCookieNames(environmentRef, present)) {
         removeCookie(store, name);
       }
     }
@@ -9624,7 +9640,7 @@ async function pbServer(opts) {
     "import the generated palbe.gen.ts once in app/layout.tsx \u2014 the root-layout import configures Server Components and Route Handlers too."
   );
   const store = opts?.cookies ?? await nextCookieStore();
-  const ref = endpointRefFromApiKey(config.apiKey);
+  const ref = config.environmentRef;
   const rt = buildRuntime({ ...config, storage: serverCookieAdapter(store, ref) });
   return createBoundClient(rt);
 }
@@ -9635,7 +9651,7 @@ async function pbServer(opts) {
   decodeSessionCookies,
   encodeSessionCookies,
   encodeSessionCookiesDecoded,
-  endpointRefFromApiKey,
+  environmentRefFromApiKey,
   handleAuthCallback,
   palbeMiddleware,
   pbServer,