@palbase/web 2.0.0 → 3.0.0

package/README.md

@@ -29,18 +29,20 @@ Then link your project and generate the typed client:
 npx palbase web link
 ```
 
-`palbase web link` writes `palbe.gen.ts` (the typed client config + namespaces),
-wires `import './palbe.gen';` into your app entry, and adds a `predev`/`prebuild`
-hook that keeps the types in sync. **Commit `palbe.gen.ts`** — it's the typed
-client your app imports, not a build artifact.
-
-The generated file calls `__configure(...)` with your project's URL, app ID, and
-anon API key at module load, so importing it once at startup is all the setup
-there is.
+`palbase web link` writes the committed generator inputs
+`Palbase/openapi.json` and `Palbase/palbase-config.json`, runs `palbe-gen` when
+`@palbase/web` is installed, wires `import './palbe.gen';` into your app entry,
+and adds a `predev`/`prebuild` hook that keeps the typed client in sync. Commit
+the `Palbase/` inputs and `palbe.gen.ts`; the generated client is source your app
+imports, not a build artifact.
+
+The generated file calls `__configure(...)` with the linked Environment ref,
+URL, app ID, and publishable API key at module load, so importing it once at
+startup is all the setup there is.
 If you forget to import it, every `pb` call throws a guided `BackendError`
 (`kind: 'notConfigured'`).
 
-> Regenerate any time your backend changes: `npx palbase types` (or just run
+> Regenerate any time your backend changes: `npx palbe-gen` (or just run
 > `dev`/`build` — the hook does it for you).
 
 ---

package/dist/{analytics-facade-ovP0pF2P.d.cts → analytics-facade-BOxQ8IP2.d.cts}

@@ -1,6 +1,6 @@
 import { Room, ExternalE2EEKeyProvider } from 'livekit-client';
 import { S as SessionStorageAdapter } from './storage-BPaeSG8K.cjs';
-import { F } from './pooled-flags-Bwq4usn0.js';
+import { F } from './pooled-flags-4GtDtsiu.js';
 
 declare class PalbaseError$1 extends Error {
     readonly code: string;
@@ -79,8 +79,7 @@ declare class HttpClient$1 {
      * 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: Record<string, string>): HttpClient$1;
     /** Add a request interceptor. Runs before every request. */
@@ -169,8 +168,7 @@ declare 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: Record<string, string>): HttpClient;
     /** Add a request interceptor. Runs before every request. */
@@ -622,10 +620,13 @@ interface PalbeConfig {
     apiKey: string;
     /** Registered app identity persisted by `palbase web link`. */
     appId: string;
-    /** Informational — url+apiKey are already branch-specific (endpointRef embeds the branch slug); gen bakes all three consistently. */
-    branch?: string;
+    /** Stable reference of the linked Palbase Environment. */
+    environmentRef: string;
     oauth?: PalbeOAuthConfig;
-    /** Refresh-token persistence. Default: endpoint-scoped localStorage in browsers, memory elsewhere. */
+    /**
+     * Refresh-token persistence. Default: environment-scoped localStorage in
+     * browsers, memory elsewhere.
+     */
     storage?: SessionStorageAdapter;
     /** Extra headers on every request. */
     headers?: Record<string, string>;
@@ -645,7 +646,7 @@ type FlagsView = Readonly<Record<string, F>>;
  *   one-shot snapshot fetches with zero timers and zero storage access, so a
  *   pbServer request that reads flags pays exactly one HTTP call.
  *
- * localStorage persistence is scoped per endpoint ref (`palbe.flags.<ref>`),
+ * localStorage persistence is scoped per environment ref (`palbe.flags.<ref>`),
  * mirroring the session-storage key convention.
  */
 declare class PalbeFlags {
@@ -679,7 +680,7 @@ declare class PalbeFlags {
      *
      * DEVIATION from iOS sync-cache parity: the platform does not propagate
      * variant metadata into the user-flags snapshot/delta cache, so this is an
-     * ASYNC transport read (`GET /v1/flags/{key}/variant`), not a cache lookup.
+     * ASYNC transport read (derived from `GET /v1/user-flags`), not a cache lookup.
      */
     getVariant(key: string): Promise<string | null>;
     /** Subscribe to any change in the cached flag set. */

package/dist/{analytics-facade-DMtGDGfd.d.ts → analytics-facade-yfMJ69vw.d.ts}

@@ -1,6 +1,6 @@
 import { Room, ExternalE2EEKeyProvider } from 'livekit-client';
 import { S as SessionStorageAdapter } from './storage-BPaeSG8K.js';
-import { F } from './pooled-flags-Bwq4usn0.js';
+import { F } from './pooled-flags-4GtDtsiu.js';
 
 declare class PalbaseError$1 extends Error {
     readonly code: string;
@@ -79,8 +79,7 @@ declare class HttpClient$1 {
      * 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: Record<string, string>): HttpClient$1;
     /** Add a request interceptor. Runs before every request. */
@@ -169,8 +168,7 @@ declare 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: Record<string, string>): HttpClient;
     /** Add a request interceptor. Runs before every request. */
@@ -622,10 +620,13 @@ interface PalbeConfig {
     apiKey: string;
     /** Registered app identity persisted by `palbase web link`. */
     appId: string;
-    /** Informational — url+apiKey are already branch-specific (endpointRef embeds the branch slug); gen bakes all three consistently. */
-    branch?: string;
+    /** Stable reference of the linked Palbase Environment. */
+    environmentRef: string;
     oauth?: PalbeOAuthConfig;
-    /** Refresh-token persistence. Default: endpoint-scoped localStorage in browsers, memory elsewhere. */
+    /**
+     * Refresh-token persistence. Default: environment-scoped localStorage in
+     * browsers, memory elsewhere.
+     */
     storage?: SessionStorageAdapter;
     /** Extra headers on every request. */
     headers?: Record<string, string>;
@@ -645,7 +646,7 @@ type FlagsView = Readonly<Record<string, F>>;
  *   one-shot snapshot fetches with zero timers and zero storage access, so a
  *   pbServer request that reads flags pays exactly one HTTP call.
  *
- * localStorage persistence is scoped per endpoint ref (`palbe.flags.<ref>`),
+ * localStorage persistence is scoped per environment ref (`palbe.flags.<ref>`),
  * mirroring the session-storage key convention.
  */
 declare class PalbeFlags {
@@ -679,7 +680,7 @@ declare class PalbeFlags {
      *
      * DEVIATION from iOS sync-cache parity: the platform does not propagate
      * variant metadata into the user-flags snapshot/delta cache, so this is an
-     * ASYNC transport read (`GET /v1/flags/{key}/variant`), not a cache lookup.
+     * ASYNC transport read (derived from `GET /v1/user-flags`), not a cache lookup.
      */
     getVariant(key: string): Promise<string | null>;
     /** Subscribe to any change in the cached flag set. */

package/dist/{chunk-V6VTX65P.js → chunk-3HVTEZ7N.js}

@@ -1,6 +1,7 @@
 import {
-  __export
-} from "./chunk-PZ5AY32C.js";
+  __export,
+  environmentRefFromPublishableApiKey
+} from "./chunk-S7NAY3MW.js";
 
 // ../core/dist/index.js
 var CACHE_TTL_MS = 5 * 60 * 1e3;
@@ -17,18 +18,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_RE = /^pb_([a-z0-9]+)_c[A-Za-z0-9]{20}$/;
+function parseEnvironmentRef(apiKey) {
+  return API_KEY_RE.exec(apiKey)?.[1] ?? null;
 }
 var MAX_RETRIES = 3;
 var INITIAL_BACKOFF_MS = 200;
@@ -58,8 +50,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 };
@@ -100,10 +91,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
       );
     }
@@ -116,10 +107,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) {
@@ -1125,13 +1112,6 @@ var AuthClient = class {
   }
 };
 
-// src/api-key.ts
-var API_KEY_RE = /^pb_([^_]+)_[cs][A-Za-z0-9]{20}$/;
-function endpointRefFromApiKey(apiKey) {
-  const m = API_KEY_RE.exec(apiKey);
-  return m ? m[1] ?? "" : "";
-}
-
 // src/analytics-facade.ts
 var EVENT_NAME_RE = /^[a-zA-Z$][a-zA-Z0-9_.:$-]{0,63}$/;
 var FLUSH_AT = 20;
@@ -1189,7 +1169,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) => {
@@ -1969,6 +1949,19 @@ var PalbeCalls = class {
 
 // ../modules/flags/dist/index.js
 var FLAG_NAME_RE = /^[a-zA-Z0-9_-]+$/;
+function flagEnabled(value) {
+  if (typeof value === "boolean") return value;
+  return value != null && value !== 0 && value !== "";
+}
+function flagVariant(value) {
+  return typeof value === "string" ? { name: value } : null;
+}
+function mapResponse(res, fn) {
+  if (res.error || res.data == null) {
+    return { ...res, data: null };
+  }
+  return { ...res, data: fn(res.data) };
+}
 var FlagsClient = class {
   httpClient;
   getCurrentUserId;
@@ -1988,10 +1981,11 @@ var FlagsClient = class {
         `Invalid flag name: "${flagName}". Flag names must match ${FLAG_NAME_RE.source}`
       );
     }
-    const params = this.buildContextParams(context);
-    const query = params.toString();
-    const path = `/v1/flags/${flagName}/enabled${query ? `?${query}` : ""}`;
-    return this.httpClient.request("GET", path);
+    const res = await this.httpClient.request(
+      "GET",
+      this.mergedPath(context)
+    );
+    return mapResponse(res, (snap) => flagEnabled(snap.values?.[flagName]));
   }
   async getVariant(flagName, context) {
     if (!FLAG_NAME_RE.test(flagName)) {
@@ -1999,16 +1993,29 @@ var FlagsClient = class {
         `Invalid flag name: "${flagName}". Flag names must match ${FLAG_NAME_RE.source}`
       );
     }
-    const params = this.buildContextParams(context);
-    const query = params.toString();
-    const path = `/v1/flags/${flagName}/variant${query ? `?${query}` : ""}`;
-    return this.httpClient.request("GET", path);
+    const res = await this.httpClient.request(
+      "GET",
+      this.mergedPath(context)
+    );
+    if (res.error || res.data == null) {
+      return { ...res, data: null };
+    }
+    return { ...res, data: flagVariant(res.data.values?.[flagName]) };
   }
   async getAll(context) {
-    const params = this.buildContextParams(context);
-    const query = params.toString();
-    const path = `/v1/flags${query ? `?${query}` : ""}`;
-    return this.httpClient.request("GET", path);
+    const res = await this.httpClient.request(
+      "GET",
+      this.mergedPath(context)
+    );
+    return mapResponse(res, (snap) => {
+      const values = snap.values ?? {};
+      return Object.keys(values).map((name) => {
+        const value = values[name];
+        const flag = { name, enabled: flagEnabled(value) };
+        if (typeof value === "string") flag.variant = { name: value };
+        return flag;
+      });
+    });
   }
   /**
    * Cold-start read: the full merged flag set for the current auth identity.
@@ -2107,15 +2114,16 @@ var FlagsClient = class {
       }
     };
   }
-  buildContextParams(context) {
-    const params = new URLSearchParams();
-    if (context?.userId) {
-      params.set("userId", context.userId);
-    }
-    if (context?.properties) {
-      params.set("properties", JSON.stringify(context.properties));
-    }
-    return params;
+  /**
+   * Resolve the merged-read path for a context. With `context.userId` present the
+   * read targets that specific user's merged view (`/v1/user-flags/users/{id}`, a
+   * privileged cross-user read); otherwise the current auth user's view
+   * (`/v1/user-flags`). `context.properties` has no server-side targeting support
+   * in the user-flags module and is ignored.
+   */
+  mergedPath(context) {
+    const uid = context?.userId;
+    return uid ? `/v1/user-flags/users/${encodeURIComponent(uid)}` : "/v1/user-flags";
   }
 };
 var DEFAULT_POLL_MS = 3e4;
@@ -2520,7 +2528,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}` } : {},
@@ -2577,7 +2585,7 @@ var PalbeFlags = class {
    *
    * DEVIATION from iOS sync-cache parity: the platform does not propagate
    * variant metadata into the user-flags snapshot/delta cache, so this is an
-   * ASYNC transport read (`GET /v1/flags/{key}/variant`), not a cache lookup.
+   * ASYNC transport read (derived from `GET /v1/user-flags`), not a cache lookup.
    */
   async getVariant(key) {
     let res;
@@ -8259,7 +8267,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.
@@ -8916,10 +8924,25 @@ function defaultSessionStorage(key) {
 }
 
 // src/version.ts
-var VERSION = "2.0.0";
+var VERSION = "3.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 }
@@ -8928,7 +8951,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) {
@@ -9305,7 +9328,6 @@ function __reset() {
 }
 
 export {
-  endpointRefFromApiKey,
   BackendError,
   isBackendError,
   PalbeAnalytics,
@@ -9329,4 +9351,4 @@ export {
   pb,
   createBoundClient
 };
-//# sourceMappingURL=chunk-V6VTX65P.js.map
+//# sourceMappingURL=chunk-3HVTEZ7N.js.map