@palbase/web 2.0.1 → 4.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-ChlBRcLZ.d.cts → analytics-facade-DwOtlXPP.d.cts}

@@ -1,4 +1,3 @@
-import { Room, ExternalE2EEKeyProvider } from 'livekit-client';
 import { S as SessionStorageAdapter } from './storage-BPaeSG8K.cjs';
 import { F } from './pooled-flags-4GtDtsiu.js';
 
@@ -79,8 +78,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 +167,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. */
@@ -535,12 +532,9 @@ declare class Call {
     private readonly _listeners;
     private readonly _room;
     private readonly _keyProvider;
-    /** @internal — obtain via PalbeCalls.start() / .accept() */
-    constructor(callId: string, room: Room, keyProvider: ExternalE2EEKeyProvider);
     get state(): CallState;
     /** Snapshot of current remote participants (does NOT include the local participant). */
     get participants(): readonly CallParticipant[];
-    get localParticipant(): Room['localParticipant'];
     /**
      * Subscribe to call changes (state + participant updates).
      * Returns an `Unsubscribe` function — matches the SDK's flags/auth pattern.
@@ -553,7 +547,7 @@ declare class Call {
     /**
      * 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.
@@ -561,13 +555,13 @@ declare class Call {
      * TODO(SP-1-web): wire this to MLS-derived key on session join.
      */
     setMediaKey(key: ArrayBuffer): Promise<void>;
-    /** Leave the call and disconnect from the LiveKit room. */
+    /** Leave the call and disconnect from the media room. */
     leave(): Promise<void>;
     private _setState;
     private _emit;
     private _upsertParticipant;
     private _attachTrack;
-    private _wireRoomEvents;
+    private _wireMediaEvents;
 }
 declare class PalbeCalls {
     private readonly rt;
@@ -577,9 +571,9 @@ declare class PalbeCalls {
      *
      * @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)
      */
@@ -622,19 +616,13 @@ interface PalbeConfig {
     apiKey: string;
     /** Registered app identity persisted by `palbase web link`. */
     appId: string;
+    /** Stable reference of the linked Palbase Environment. */
+    environmentRef: string;
+    oauth?: PalbeOAuthConfig;
     /**
-     * The ENVIRONMENT this config targets — informational only.
-     *
-     * `url` and `apiKey` ALREADY identify the environment (the ref is the host
-     * label and is embedded in the key), so nothing at runtime reads this: it is
-     * here so a developer looking at the generated file can see WHICH runtime it
-     * points at. It replaces the old `branch` field — the Palbase branch is gone
-     * as a resource, and a second, drift-prone name for the same runtime is
-     * exactly how a build ends up talking to production from a staging checkout.
+     * Refresh-token persistence. Default: environment-scoped localStorage in
+     * browsers, memory elsewhere.
      */
-    environmentRef?: string;
-    oauth?: PalbeOAuthConfig;
-    /** Refresh-token persistence. Default: endpoint-scoped localStorage in browsers, memory elsewhere. */
     storage?: SessionStorageAdapter;
     /** Extra headers on every request. */
     headers?: Record<string, string>;
@@ -654,7 +642,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 {
@@ -928,19 +916,6 @@ interface MentionRange {
     length: number;
     mentionedUserId: string;
 }
-interface ReactionPayload {
-    targetClientMsgId: string;
-    emoji: string;
-    op: 'add' | 'remove';
-}
-interface EditPayload {
-    targetClientMsgId: string;
-    newText: string;
-}
-interface DeletePayload {
-    targetClientMsgId: string;
-    scope: string;
-}
 /** Per-message TTL spec (decoded). senderSendTs present iff start === 'send'. */
 interface ExpirySpec {
     v: number;
@@ -949,51 +924,6 @@ interface ExpirySpec {
     senderSendTs: number | null;
 }
 
-/** A decoded incoming message handed to chat listeners. */
-interface IncomingMessage {
-    kind: 'application' | 'commit' | 'proposal' | 'welcome';
-    group: MessagingGroup;
-    text: string | null;
-    senderDeviceId: string | null;
-    epoch: number;
-    serverSeq: number;
-    receivedAt: Date;
-    /** The client-minted idempotency id from the decoded envelope (empty string for legacy/system). */
-    clientMsgId: string;
-    /** The decoded reply reference, if present in the envelope. */
-    replyRef: ReplyRef | null;
-    /**
-     * The decoded envelope discriminator (`'text'`/`'reaction'`/`'media'`/…).
-     * Defaults to `'text'` at every existing call site — only the reaction branch
-     * sets `'reaction'`, so the Chat can route a reaction into its fold instead of
-     * appending a visible bubble. Optional for forward-compat with old emitters.
-     */
-    envelopeType?: string;
-    /** The decoded reaction payload, present only when `envelopeType === 'reaction'`. */
-    reaction?: ReactionPayload | null;
-    /** The decoded edit payload, present only when `envelopeType === 'edit'`. Lets
-     * the Chat route an edit into its EditFold instead of appending a visible bubble. */
-    edit?: EditPayload | null;
-    /** The decoded delete payload, present only when `envelopeType === 'delete'`. Lets
-     * the Chat route a delete-for-everyone tombstone into its DeleteFold instead of
-     * appending a visible bubble. */
-    delete?: DeletePayload | null;
-    /** The decoded mention ranges (raw, un-normalized). Present on a `'text'` bubble
-     * with `body_ranges` OR on an `'edit'` (the edit's replacement ranges). The Chat
-     * normalizes + resolves roster names → `ChatMessage.mentions` (mentions T6). */
-    bodyRanges?: MentionRange[] | null;
-    /** The decoded `timer_set` payload, present only when `envelopeType === 'timer_set'`
-     * (disappearing T10). Lets the Chat route a chat-default timer into its TimerFold
-     * instead of appending a visible bubble. */
-    timer?: {
-        ttlSeconds: number | null;
-        start: 'send' | 'read';
-    } | null;
-    /** The decoded per-message TTL spec, present only on a `'text'` bubble that carried an
-     * `expiry` (disappearing T10). Lets the Chat arm the message's purge on first display. */
-    expiry?: ExpirySpec | null;
-}
-
 /** The intended participants of a draft chat (held until the first send). */
 interface ChatDraft {
     mode: {
@@ -1171,16 +1101,6 @@ declare class Chat {
      * the SDK guarantees the DECISION, not the buzz. Mirrors iOS `Chat.onMentionElevation`.
      */
     onMentionElevation?: (message: ChatMessage) => void;
-    /** @internal — obtain via pb.messaging.directChat / groupChat / chat(id). */
-    constructor(args: {
-        group: MessagingGroup;
-        kind: ChatKind;
-        backend: ChatBackend;
-    } | {
-        draft: ChatDraft;
-        kind: ChatKind;
-        backend: ChatBackend;
-    });
     /** Subscribe to any change in this chat (messages/members/typing/state). */
     onChange(cb: () => void): Unsubscribe$1;
     private emit;
@@ -1220,8 +1140,6 @@ declare class Chat {
     private loadElevated;
     private hydrateHistory;
     private mergeHistory;
-    /** @internal — called by the backend's live subscription. */
-    ingestLive(incoming: IncomingMessage): Promise<void>;
     /** Normalize a decoded `IncomingMessage.expiry` / `StoredMessage.expiry` into the
      * `ExpirySpec` the arm path consumes (or null when absent). */
     private toExpirySpec;
@@ -1319,8 +1237,6 @@ declare class Chat {
      * history fold) is preserved. PRESERVES reactions + replyTo.
      */
     private applyEditOverlay;
-    /** @internal — called by the backend's conv subscription. */
-    applyConv(event: string, payload: Record<string, unknown>): void;
     private kindOf;
     private internalKey;
     private publicId;
@@ -1636,8 +1552,6 @@ declare class RealtimeChannel {
     /** The app-defined channel name (bare sub-topic, no "realtime:" prefix). */
     readonly name: string;
     private readonly owner;
-    /** @internal — obtain channels via `pb.realtime.channel(name)`. */
-    constructor(name: string, owner: PalbeRealtime);
     /**
      * Subscribe `handler` to `event` on this channel. Fire-and-forget: the
      * join rides the shared socket asynchronously. Hold the returned
@@ -1673,10 +1587,6 @@ declare class PalbeRealtime {
     destroy(): void;
     /** The observable connection status. Safe to read anywhere (reports `idle` until a socket exists). */
     get status(): RealtimeStatus;
-    /** @internal */
-    subscribe(topic: string, event: string, handler: RealtimeHandler): RealtimeSubscription;
-    /** @internal */
-    send(topic: string, event: string, payload: RealtimePayload): void;
     /** Lazily build + start the shared socket on first subscription/send. */
     private ensureSocket;
     private route;

package/dist/{analytics-facade-G0il4NrT.d.ts → analytics-facade-Nk6J9Ncm.d.ts}

@@ -1,4 +1,3 @@
-import { Room, ExternalE2EEKeyProvider } from 'livekit-client';
 import { S as SessionStorageAdapter } from './storage-BPaeSG8K.js';
 import { F } from './pooled-flags-4GtDtsiu.js';
 
@@ -79,8 +78,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 +167,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. */
@@ -535,12 +532,9 @@ declare class Call {
     private readonly _listeners;
     private readonly _room;
     private readonly _keyProvider;
-    /** @internal — obtain via PalbeCalls.start() / .accept() */
-    constructor(callId: string, room: Room, keyProvider: ExternalE2EEKeyProvider);
     get state(): CallState;
     /** Snapshot of current remote participants (does NOT include the local participant). */
     get participants(): readonly CallParticipant[];
-    get localParticipant(): Room['localParticipant'];
     /**
      * Subscribe to call changes (state + participant updates).
      * Returns an `Unsubscribe` function — matches the SDK's flags/auth pattern.
@@ -553,7 +547,7 @@ declare class Call {
     /**
      * 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.
@@ -561,13 +555,13 @@ declare class Call {
      * TODO(SP-1-web): wire this to MLS-derived key on session join.
      */
     setMediaKey(key: ArrayBuffer): Promise<void>;
-    /** Leave the call and disconnect from the LiveKit room. */
+    /** Leave the call and disconnect from the media room. */
     leave(): Promise<void>;
     private _setState;
     private _emit;
     private _upsertParticipant;
     private _attachTrack;
-    private _wireRoomEvents;
+    private _wireMediaEvents;
 }
 declare class PalbeCalls {
     private readonly rt;
@@ -577,9 +571,9 @@ declare class PalbeCalls {
      *
      * @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)
      */
@@ -622,19 +616,13 @@ interface PalbeConfig {
     apiKey: string;
     /** Registered app identity persisted by `palbase web link`. */
     appId: string;
+    /** Stable reference of the linked Palbase Environment. */
+    environmentRef: string;
+    oauth?: PalbeOAuthConfig;
     /**
-     * The ENVIRONMENT this config targets — informational only.
-     *
-     * `url` and `apiKey` ALREADY identify the environment (the ref is the host
-     * label and is embedded in the key), so nothing at runtime reads this: it is
-     * here so a developer looking at the generated file can see WHICH runtime it
-     * points at. It replaces the old `branch` field — the Palbase branch is gone
-     * as a resource, and a second, drift-prone name for the same runtime is
-     * exactly how a build ends up talking to production from a staging checkout.
+     * Refresh-token persistence. Default: environment-scoped localStorage in
+     * browsers, memory elsewhere.
      */
-    environmentRef?: string;
-    oauth?: PalbeOAuthConfig;
-    /** Refresh-token persistence. Default: endpoint-scoped localStorage in browsers, memory elsewhere. */
     storage?: SessionStorageAdapter;
     /** Extra headers on every request. */
     headers?: Record<string, string>;
@@ -654,7 +642,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 {
@@ -928,19 +916,6 @@ interface MentionRange {
     length: number;
     mentionedUserId: string;
 }
-interface ReactionPayload {
-    targetClientMsgId: string;
-    emoji: string;
-    op: 'add' | 'remove';
-}
-interface EditPayload {
-    targetClientMsgId: string;
-    newText: string;
-}
-interface DeletePayload {
-    targetClientMsgId: string;
-    scope: string;
-}
 /** Per-message TTL spec (decoded). senderSendTs present iff start === 'send'. */
 interface ExpirySpec {
     v: number;
@@ -949,51 +924,6 @@ interface ExpirySpec {
     senderSendTs: number | null;
 }
 
-/** A decoded incoming message handed to chat listeners. */
-interface IncomingMessage {
-    kind: 'application' | 'commit' | 'proposal' | 'welcome';
-    group: MessagingGroup;
-    text: string | null;
-    senderDeviceId: string | null;
-    epoch: number;
-    serverSeq: number;
-    receivedAt: Date;
-    /** The client-minted idempotency id from the decoded envelope (empty string for legacy/system). */
-    clientMsgId: string;
-    /** The decoded reply reference, if present in the envelope. */
-    replyRef: ReplyRef | null;
-    /**
-     * The decoded envelope discriminator (`'text'`/`'reaction'`/`'media'`/…).
-     * Defaults to `'text'` at every existing call site — only the reaction branch
-     * sets `'reaction'`, so the Chat can route a reaction into its fold instead of
-     * appending a visible bubble. Optional for forward-compat with old emitters.
-     */
-    envelopeType?: string;
-    /** The decoded reaction payload, present only when `envelopeType === 'reaction'`. */
-    reaction?: ReactionPayload | null;
-    /** The decoded edit payload, present only when `envelopeType === 'edit'`. Lets
-     * the Chat route an edit into its EditFold instead of appending a visible bubble. */
-    edit?: EditPayload | null;
-    /** The decoded delete payload, present only when `envelopeType === 'delete'`. Lets
-     * the Chat route a delete-for-everyone tombstone into its DeleteFold instead of
-     * appending a visible bubble. */
-    delete?: DeletePayload | null;
-    /** The decoded mention ranges (raw, un-normalized). Present on a `'text'` bubble
-     * with `body_ranges` OR on an `'edit'` (the edit's replacement ranges). The Chat
-     * normalizes + resolves roster names → `ChatMessage.mentions` (mentions T6). */
-    bodyRanges?: MentionRange[] | null;
-    /** The decoded `timer_set` payload, present only when `envelopeType === 'timer_set'`
-     * (disappearing T10). Lets the Chat route a chat-default timer into its TimerFold
-     * instead of appending a visible bubble. */
-    timer?: {
-        ttlSeconds: number | null;
-        start: 'send' | 'read';
-    } | null;
-    /** The decoded per-message TTL spec, present only on a `'text'` bubble that carried an
-     * `expiry` (disappearing T10). Lets the Chat arm the message's purge on first display. */
-    expiry?: ExpirySpec | null;
-}
-
 /** The intended participants of a draft chat (held until the first send). */
 interface ChatDraft {
     mode: {
@@ -1171,16 +1101,6 @@ declare class Chat {
      * the SDK guarantees the DECISION, not the buzz. Mirrors iOS `Chat.onMentionElevation`.
      */
     onMentionElevation?: (message: ChatMessage) => void;
-    /** @internal — obtain via pb.messaging.directChat / groupChat / chat(id). */
-    constructor(args: {
-        group: MessagingGroup;
-        kind: ChatKind;
-        backend: ChatBackend;
-    } | {
-        draft: ChatDraft;
-        kind: ChatKind;
-        backend: ChatBackend;
-    });
     /** Subscribe to any change in this chat (messages/members/typing/state). */
     onChange(cb: () => void): Unsubscribe$1;
     private emit;
@@ -1220,8 +1140,6 @@ declare class Chat {
     private loadElevated;
     private hydrateHistory;
     private mergeHistory;
-    /** @internal — called by the backend's live subscription. */
-    ingestLive(incoming: IncomingMessage): Promise<void>;
     /** Normalize a decoded `IncomingMessage.expiry` / `StoredMessage.expiry` into the
      * `ExpirySpec` the arm path consumes (or null when absent). */
     private toExpirySpec;
@@ -1319,8 +1237,6 @@ declare class Chat {
      * history fold) is preserved. PRESERVES reactions + replyTo.
      */
     private applyEditOverlay;
-    /** @internal — called by the backend's conv subscription. */
-    applyConv(event: string, payload: Record<string, unknown>): void;
     private kindOf;
     private internalKey;
     private publicId;
@@ -1636,8 +1552,6 @@ declare class RealtimeChannel {
     /** The app-defined channel name (bare sub-topic, no "realtime:" prefix). */
     readonly name: string;
     private readonly owner;
-    /** @internal — obtain channels via `pb.realtime.channel(name)`. */
-    constructor(name: string, owner: PalbeRealtime);
     /**
      * Subscribe `handler` to `event` on this channel. Fire-and-forget: the
      * join rides the shared socket asynchronously. Hold the returned
@@ -1673,10 +1587,6 @@ declare class PalbeRealtime {
     destroy(): void;
     /** The observable connection status. Safe to read anywhere (reports `idle` until a socket exists). */
     get status(): RealtimeStatus;
-    /** @internal */
-    subscribe(topic: string, event: string, handler: RealtimeHandler): RealtimeSubscription;
-    /** @internal */
-    send(topic: string, event: string, payload: RealtimePayload): void;
     /** Lazily build + start the shared socket on first subscription/send. */
     private ensureSocket;
     private route;

package/dist/{chunk-VJXFABBW.js → chunk-6VGKMNXO.js}

@@ -6,11 +6,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 })
   );
@@ -29,15 +29,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 = "";
@@ -71,8 +71,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++) {
@@ -91,4 +91,4 @@ export {
   decodeSessionCookies,
   clearedSessionCookieNames
 };
-//# sourceMappingURL=chunk-VJXFABBW.js.map
+//# sourceMappingURL=chunk-6VGKMNXO.js.map

package/dist/chunk-6VGKMNXO.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/next/cookie-codec.ts"],"sourcesContent":["/**\n * Session-cookie codec shared by EVERY palbe/next surface (browser storage\n * adapter, pbServer cookie adapter, middleware, auth callback). Pure\n * functions — no 'next' imports, no palbe runtime imports — so both sides\n * provably read and write the SAME bytes.\n *\n * Format (P3 design contract):\n * - name: `palbe-session-<environmentRef>`; overflow chunk names append `.0`,\n *   `.1`, … (cookie names otherwise avoid dots — tooling friendliness).\n * - value: `encodeURIComponent(JSON.stringify({ a, r, e }))` with a=access\n *   token, r=refresh token, e=expiry (ms epoch).\n * - one cookie when the encoded value fits MAX_COOKIE_VALUE chars, else\n *   chunks ONLY (the base name must not coexist with chunks — callers clear\n *   stale names via clearedSessionCookieNames before writing, then honor the\n *   encode result's `clear` overflow guard after writing).\n */\n\nexport { environmentRefFromApiKey } from '../api-key.js';\n\nexport interface StoredSession {\n  accessToken: string;\n  refreshToken: string;\n  /** ms epoch */\n  expiresAt: number;\n}\n\n/** Browsers cap a cookie at ~4096 bytes incl. name + attributes; 3500 leaves headroom. */\nconst MAX_COOKIE_VALUE = 3500;\n\n/**\n * The P3 cookie contract attributes, shared by every server-side writer\n * (pbServer adapter, middleware, callback); the browser writer mirrors them\n * in document.cookie string form (next/client.ts). NOT HttpOnly by design —\n * the browser SDK must read/write the session (Supabase-paradigm tradeoff);\n * Max-Age = 30d = the refresh-token TTL.\n */\nexport const SESSION_COOKIE_ATTRS = {\n  path: '/',\n  sameSite: 'lax',\n  secure: true,\n  maxAge: 2_592_000,\n} as const;\n\nexport function sessionCookieName(environmentRef: string): string {\n  return `palbe-session-${environmentRef}`;\n}\n\nexport interface SessionCookieWrite {\n  /** Cookies to SET, in order. */\n  set: Array<{ name: string; value: string }>;\n  /**\n   * Names to DELETE alongside the set: the one-past-the-end OVERFLOW GUARD\n   * (base write → `.0`; chunks `.0..n` → `.(n+1)`). Decode stops at the\n   * first missing chunk, so deleting exactly one-past-the-end guarantees a\n   * stale orphan chunk (left behind a gap, where presence-probing cleanup\n   * cannot see it) can never concatenate into the freshly written run.\n   * Writers MUST honor both lists.\n   */\n  clear: string[];\n}\n\nexport function encodeSessionCookies(\n  environmentRef: string,\n  session: StoredSession,\n): SessionCookieWrite {\n  const name = sessionCookieName(environmentRef);\n  const value = encodeURIComponent(\n    JSON.stringify({ a: session.accessToken, r: session.refreshToken, e: session.expiresAt }),\n  );\n  if (value.length <= MAX_COOKIE_VALUE) {\n    return { set: [{ name, value }], clear: [`${name}.0`] };\n  }\n  const chunks: Array<{ name: string; value: string }> = [];\n  // Chunk WITHOUT splitting a %XX escape (every '%' in the encoded value\n  // starts one — encodeURIComponent never emits a bare '%'). Next's cookie\n  // layer percent-DECODES values on read and silently DROPS a cookie whose\n  // value is an invalid escape sequence, so a split escape would lose that\n  // chunk server-side; independent decodability also lets\n  // encodeSessionCookiesDecoded mirror this run byte-exactly.\n  for (let start = 0; start < value.length; ) {\n    let end = Math.min(start + MAX_COOKIE_VALUE, value.length);\n    if (end < value.length) {\n      if (value[end - 1] === '%') end -= 1;\n      else if (value[end - 2] === '%') end -= 2;\n    }\n    chunks.push({ name: `${name}.${chunks.length}`, value: value.slice(start, end) });\n    start = end;\n  }\n  return { set: chunks, clear: [`${name}.${chunks.length}`] };\n}\n\n/**\n * encodeSessionCookies for percent-ENCODING cookie stores. Next's request\n * and response cookie APIs apply encodeURIComponent to values when\n * serializing (and decodeURIComponent on read) — handing them the codec's\n * already-encoded values would DOUBLE-encode the wire bytes and break the\n * browser-side reader. This variant returns the same cookie run with\n * DECODED values: `encodeURIComponent(value)` reproduces the\n * encodeSessionCookies bytes exactly (chunk boundaries never split an\n * escape), so an encoding store writes byte-identical cookies to a raw\n * writer like document.cookie.\n */\nexport function encodeSessionCookiesDecoded(\n  environmentRef: string,\n  session: StoredSession,\n): SessionCookieWrite {\n  const { set, clear } = encodeSessionCookies(environmentRef, session);\n  return {\n    set: set.map(({ name, value }) => ({ name, value: decodeURIComponent(value) })),\n    clear,\n  };\n}\n\n/**\n * Read the session back from a cookie getter: the base name wins; otherwise\n * `.0`, `.1`, … are concatenated until the first missing chunk. Tolerant:\n * malformed URI escapes / JSON / shape → null (treated as \"no session\").\n *\n * Accepts BOTH value forms. Next's cookie stores percent-DECODE values once\n * on read, so server-side callers (pbServer adapter, middleware) hand us the\n * already-decoded JSON; raw readers (document.cookie) hand us the encoded\n * form. The raw (already-decoded) parse runs FIRST because it is\n * unambiguous — an encoded value can never raw-parse as JSON\n * (encodeURIComponent escapes `{` itself, so it starts with `%7B`) — whereas\n * decode-first would silently corrupt a literal `%XX` run inside a token\n * (decodeURIComponent('%41') → 'A', no throw) or throw on an invalid escape.\n */\nexport function decodeSessionCookies(\n  get: (name: string) => string | undefined,\n  environmentRef: string,\n): StoredSession | null {\n  const base = sessionCookieName(environmentRef);\n  let encoded = get(base);\n  if (encoded === undefined) {\n    let joined = '';\n    for (let i = 0; ; i++) {\n      const part = get(`${base}.${i}`);\n      if (part === undefined) break;\n      joined += part;\n    }\n    if (joined === '') return null;\n    encoded = joined;\n  }\n  const raw = parseStoredSession(encoded);\n  if (raw !== null) return raw;\n  try {\n    return parseStoredSession(decodeURIComponent(encoded));\n  } catch {\n    return null;\n  }\n}\n\n/** JSON-parse + shape-check one candidate value; malformed → null. */\nfunction parseStoredSession(json: string): StoredSession | null {\n  try {\n    const parsed: unknown = JSON.parse(json);\n    if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {\n      const obj = parsed as Record<string, unknown>;\n      if (typeof obj.a === 'string' && typeof obj.r === 'string' && typeof obj.e === 'number') {\n        return { accessToken: obj.a, refreshToken: obj.r, expiresAt: obj.e };\n      }\n    }\n    return null;\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Names a writer must delete before/while writing: the base name (when\n * present) plus every existing `.N` chunk, probed in order until the first\n * missing one (writes are always a contiguous `.0..n` run, so a gap means\n * the end of palbe-owned chunks).\n */\nexport function clearedSessionCookieNames(\n  environmentRef: string,\n  present: (name: string) => boolean,\n): string[] {\n  const base = sessionCookieName(environmentRef);\n  const names: string[] = [];\n  if (present(base)) names.push(base);\n  for (let i = 0; ; i++) {\n    const chunk = `${base}.${i}`;\n    if (!present(chunk)) break;\n    names.push(chunk);\n  }\n  return names;\n}\n\n/**\n * Parse the canonical chunk index out of `palbe-session-<ref>.N`; non-chunk\n * names (the bare base, a foreign ref, junk suffixes like `.x` / `.01` /\n * `.-1`) → null. The index is a non-negative integer with NO leading zeros\n * (the encoder emits `.0`, `.1`, … verbatim), so `String(n) === suffix`\n * round-trips it exactly.\n */\nfunction chunkIndex(base: string, name: string): number | null {\n  if (!name.startsWith(`${base}.`)) return null;\n  const suffix = name.slice(base.length + 1);\n  if (!/^\\d+$/.test(suffix)) return null;\n  const idx = Number.parseInt(suffix, 10);\n  return String(idx) === suffix ? idx : null;\n}\n\n/**\n * getAll-powered orphan sweep — the deletion list a writer with the FULL\n * cookie jar should clear, catching crash-orphans that presence-probing\n * (clearedSessionCookieNames, which stops at the first gap) CANNOT see.\n *\n * Given every cookie name in the jar, returns the `palbe-session-<ref>`-family\n * names that are NOT part of a single valid session:\n * - A valid session is EITHER the bare base alone, OR the contiguous chunk\n *   run `.0, .1, …, n` (starting at `.0`, no gaps).\n * - Any `.N` beyond the first gap from `.0` is an orphan (incl. ALL chunks\n *   when `.0` is absent — no run exists).\n * - The base coexisting with ANY chunk is inconsistent (the contract forbids\n *   it; decode lets the base win and silently strands the chunks): the base\n *   is kept, the chunks are swept (a fresh write replaces the base in place).\n *\n * Only canonical `.N` names count; foreign refs and malformed suffixes are\n * ignored. Output order: base (if inconsistent) first, then chunks ascending.\n */\nexport function orphanSessionCookieNames(environmentRef: string, allNames: string[]): string[] {\n  const base = sessionCookieName(environmentRef);\n  const hasBase = allNames.includes(base);\n  const indices = new Set<number>();\n  for (const name of allNames) {\n    const idx = chunkIndex(base, name);\n    if (idx !== null) indices.add(idx);\n  }\n  if (indices.size === 0) return []; // unchunked (base alone) or no palbe cookies\n\n  // Length of the contiguous run from .0 (0 when .0 is missing).\n  let runLen = 0;\n  while (indices.has(runLen)) runLen++;\n\n  const orphans: string[] = [];\n  // Base coexisting with chunks: base wins on decode → chunks are stale.\n  // Sweep the base too only when there are NO chunks behind the run to keep\n  // (the contract forbids the mix; clearing chunks alone resolves it, but if\n  // the run itself is invalid—no .0—the base is the real session and stays).\n  // Decision: when base coexists with ANY chunk, the chunks are orphans; the\n  // base is the live session and is kept — UNLESS the chunk set forms a valid\n  // run AND there is also a gap-orphan, in which case both base+gap-orphan are\n  // inconsistent leftovers. Concretely: keep it simple and SAFE — the base is\n  // only swept when it sits alongside a partial/gapped chunk set (a crash mid\n  // base→chunk migration), never when chunks form a clean run the base shadows.\n  const everyChunkContiguous = indices.size === runLen && runLen > 0;\n  if (hasBase && !everyChunkContiguous) orphans.push(base);\n\n  for (const idx of [...indices].sort((a, b) => a - b)) {\n    if (idx >= runLen) orphans.push(`${base}.${idx}`);\n  }\n  // Base + clean contiguous run: base wins on decode, chunks are stranded.\n  if (hasBase && everyChunkContiguous) {\n    for (let i = 0; i < runLen; i++) orphans.push(`${base}.${i}`);\n  }\n  return orphans;\n}\n"],"mappings":"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","names":[]}