@spacelr/sdk 0.9.2 → 0.10.1

package/dist/index.d.mts

@@ -516,6 +516,28 @@ declare class SpacelrEmailVerificationRequiredError extends SpacelrError {
 }
 
 type ConnectionState = 'connected' | 'reconnecting' | 'disconnected';
+/** A single primitive `where` candidate. */
+type WhereScalar = string | number | boolean;
+/**
+ * Multi-value `where` operators (Firestore-style) for realtime subscriptions:
+ * - `in`: the document field is a **scalar** equal to any candidate.
+ * - `array-contains-any`: the document field is an **array** sharing at least
+ *   one element with the candidates.
+ *
+ * The single-value form (`where: { field: scalar }`) stays polymorphic — it
+ * matches a scalar field by equality OR an array field by element membership.
+ *
+ * Mirrors the server definition in `@spacelr-workspace/shared-types`
+ * (`realtime-where.ts`); the two must stay structurally identical.
+ */
+type WhereOperator = {
+    in: WhereScalar[];
+} | {
+    'array-contains-any': WhereScalar[];
+};
+type WhereValue = WhereScalar | WhereOperator;
+/** A realtime subscription `where` filter: field name → scalar or operator. */
+type WhereFilter = Record<string, WhereValue>;
 interface DatabaseChangeEvent {
     type: 'insert' | 'update' | 'delete';
     projectId: string;
@@ -553,7 +575,7 @@ interface StreamSubscriptionOptions {
     projectId: string;
     collectionName: string;
     sinceId?: string;
-    where?: Record<string, string | number | boolean>;
+    where?: WhereFilter;
     /**
      * Called for each delivered event. Awaited — the cursor does NOT advance
      * until this resolves. If the callback throws, the cursor is NOT advanced
@@ -575,6 +597,10 @@ declare class RealtimeClient {
     private subscriptions;
     private connecting;
     private roomWhereMap;
+    private roomErrorMap;
+    private roomGeneration;
+    private subEpoch;
+    private resubscribingRooms;
     private unsubscribeFromTokenRefreshed;
     private onVisibilityChange;
     private onOnline;
@@ -584,7 +610,9 @@ declare class RealtimeClient {
     private connectionStateListeners;
     private streamSubscriptions;
     constructor(config: RealtimeConfig);
-    subscribe(projectId: string, collectionName: string, callback: (event: DatabaseChangeEvent) => void, onError?: (error: Error) => void, where?: Record<string, string | number | boolean>): Promise<() => void>;
+    subscribe(projectId: string, collectionName: string, callback: (event: DatabaseChangeEvent) => void, onError?: (error: Error & {
+        code?: string;
+    }) => void, where?: WhereFilter): Promise<() => void>;
     /**
      * Subscribe to a stream-mode collection using Redis Streams replay +
      * cursor-based delivery. Parallel to `subscribe()` (which targets
@@ -676,6 +704,31 @@ declare class RealtimeClient {
     private ensureWakeListeners;
     private detachWakeListeners;
     private resubscribeAll;
+    /**
+     * Parse a pubsub room key back into its projectId + collectionName.
+     * Room format: `db:{projectId}:{collectionName}` or that base plus `?filter`.
+     * Returns null for anything that isn't a well-formed `db:` room.
+     */
+    private parseRoom;
+    /** Build an Error carrying the gateway's typed `errorCode` (if any) as `.code`. */
+    private toSubscribeError;
+    /** Call every subscriber's error handler registered for `room` (#661). */
+    private notifyRoomError;
+    /**
+     * Re-run the subscribe handshake for one already-tracked room. Shared by
+     * reconnect resubscription (`resubscribeAll`) and the #661
+     * `subscription-invalidated` handler.
+     *
+     * - Deduped per room via `resubscribingRooms` so the duplicate invalidation
+     *   events the gateway emits (one per evicted room) collapse to one handshake.
+     * - Snapshots the room's generation; the ack acts only if it is still current,
+     *   so a late ack cannot clobber an unsubscribe/re-subscribe that happened in
+     *   the meantime — and a success that arrives after the room was removed emits
+     *   a compensating `unsubscribe` so no ghost server room is left behind.
+     * - On a genuine denial the subscription is evicted and its stored `onError`
+     *   is called (with the typed `.code`), instead of silently going quiet.
+     */
+    private resubscribeRoom;
     private emitSubscribeEvents;
     private buildStreamPayload;
     private unsubscribeStream;
@@ -1089,16 +1142,18 @@ interface SubscribeWithSnapshotOptions<T> {
      * **Snapshot semantics** (full MongoDB query): supports operators like
      * `{ status: { $in: [...] } }`, `{ ts: { $gt: ... } }`, etc.
      *
-     * **Live-stream semantics** (gateway-side equality only): the stream
-     * filter only honours top-level primitive equality
-     * (`string | number | boolean` values). Operator-shaped values are
-     * silently dropped from the stream filter at handshake time — the
-     * remaining primitive entries still apply, so a typical chat-style
-     * `{ chatId: 'c1' }` filter works identically on both sides. If you
-     * pass a mixed `{ chatId: 'c1', status: { $in: [...] } }`, the
-     * snapshot is fully filtered but the live stream filters by `chatId`
-     * only; you may receive `onChange` events for documents whose `status`
-     * is outside your `$in` set. Re-check in the handler if needed.
+     * **Live-stream semantics** (top-level primitives only): this helper
+     * forwards only top-level primitive values (`string | number | boolean`)
+     * from the Mongo-query `where` to the live filter. MongoDB operators
+     * (`$in`, `$gt`, …) are silently dropped at handshake time and are NOT
+     * translated into the gateway's realtime `in` / `array-contains-any`
+     * operators — the remaining primitive entries still apply, so a typical
+     * chat-style `{ chatId: 'c1' }` filter works identically on both sides. If
+     * you pass a mixed `{ chatId: 'c1', status: { $in: [...] } }`, the snapshot
+     * is fully filtered but the live stream filters by `chatId` only; you may
+     * receive `onChange` events for documents whose `status` is outside your
+     * `$in` set. Re-check in the handler, or use `subscribeEvents()` directly
+     * with a realtime `{ status: { in: [...] } }` operator for live filtering.
      */
     where?: Record<string, unknown>;
     sort?: Record<string, 1 | -1>;
@@ -1159,7 +1214,7 @@ interface SubscribeWithSnapshotOptions<T> {
 interface SubscribeEventsHandlers<T = Record<string, unknown>> {
     /** Cursor to resume from. Undefined = fresh subscription, deliver only new events. */
     sinceId?: string;
-    where?: Record<string, string | number | boolean>;
+    where?: WhereFilter;
     /**
      * Optional resume-cursor store. When set, the SDK loads the previous cursor
      * before subscribing and persists the new cursor after each delivered
@@ -1216,7 +1271,7 @@ interface StreamSubscription {
     getCursor(): string | undefined;
 }
 interface SubscribeHandlers<T = Record<string, unknown>> {
-    where?: Record<string, string | number | boolean>;
+    where?: WhereFilter;
     onInsert?: (doc: T & {
         _id: string;
     }) => void;
@@ -1546,6 +1601,11 @@ interface FunctionInvokeOptions {
      *
      * If `true` but the user is not signed in, the header is simply omitted —
      * safe for `public` invokeMode.
+     *
+     * Note: for `authenticated`/`hybrid` invokeMode, the server additionally
+     * requires the token's user to be a member of the target project — this
+     * flag only controls whether the header is attached, not who the server
+     * accepts.
      */
     authenticated?: boolean;
     payload?: Record<string, unknown>;
@@ -1564,10 +1624,14 @@ declare class FunctionsModule {
      * `config.apiUrl` (which already carries the `/api/v1` prefix).
      *
      * Auth defaults, based on `invokeMode` semantics:
-     *  - webhook:       pass `secret` → Authorization is NOT attached
-     *  - authenticated: pass nothing  → Authorization IS attached (from token manager)
-     *  - public:        pass nothing  → Authorization is attached if logged in, else omitted
-     *  - hybrid:        pass both `secret` and `authenticated: true`
+     *  - webhook:                 pass `secret` → Authorization is NOT attached
+     *  - authenticated:           pass nothing  → Authorization IS attached (from token manager);
+     *                             caller must be a member of the target project
+     *  - public:                  pass nothing  → Authorization is attached if logged in, else omitted
+     *  - hybrid:                  pass both `secret` and `authenticated: true`; JWT path
+     *                             requires project membership like `authenticated`
+     *  - platform-authenticated:  pass nothing  → Authorization IS attached (from token manager);
+     *                             any signed-in user is accepted, still just attaches the bearer token
      *
      * To force a specific behaviour, set `authenticated` explicitly — it wins
      * over the `secret`-based default.
@@ -1763,4 +1827,4 @@ interface SpacelrClient {
 }
 declare function createClient(config: SpacelrClientConfig): SpacelrClient;
 
-export { type ApiResponse, type AuthLostReason, type AuthState, type AuthStateListener, type AuthorizationUrlParams, BrowserTokenStorage, CodeChallengeMethod, type ConnectionState, CursorInvalidError, type CursorStorage, type DatabaseChangeEvent, type DownloadUrlResponse, type ExchangeCodeParams, type FileInfo, type FileListResponse, FileVisibility, ForbiddenError, type FunctionInvokeOptions, type FunctionInvokeResult, type GapReason, GrantType, type InitMultipartUploadParams, type InitMultipartUploadResponse, type JWK, type JWKSResponse, type ListFilesParams, type LoginParams, type LoginResponse, MemoryTokenStorage, NotFoundError, type OpenIDConfiguration, type PKCEChallenge, type PartEtag, type PasskeyAuthenticationOptionsJSON, type PasskeyAuthenticationResponseJSON, type PasskeyCredential, type PasskeyCredentialDescriptorJSON, type PasskeyLoginResponse, type PasskeyRegistrationOptionsJSON, type PasskeyRegistrationResponseJSON, type PasskeyRegistrationResult, type PushSubscriptionInfo, type QuotaInfo, type RegisterParams, type RegisterResponse, type Schedule, type ScheduleInvokeOptions, type ScheduleListOptions, type ScheduleStatus, type SearchOptions, ServerConfigError, type ShareFileParams, SharePermission, SpacelrAuthError, type SpacelrClient, type SpacelrClientConfig, SpacelrEmailVerificationRequiredError, SpacelrError, SpacelrNetworkError, SpacelrSearchFilterRequiredError, SpacelrTimeoutError, SpacelrTwoFactorRequiredError, type StoredTokens, type StreamGapInfo, type StreamSubscription, type SubscribeEventsHandlers, type SubscribeHandlers, type SubscribeWithSnapshotOptions, type TimelineAndFilter, TimelineError, type TimelineFieldFilter, type TimelineFilter, type TimelineLeafFilter, TimelineModule, type TimelineOrderBy, type TimelineQueryOptions, type TimelineQueryResponse, type TimelineScalar, type TimelineSourceStats, TimeoutError, type TokenResponse, type TokenStorage, type TwoFactorResponse, type TwoFactorVerifyParams, type UnshareFileParams, type UploadFileParams, type UploadLargeFileParams, type UploadProgress, type UserInfo, type UserProfile, ValidationError, type VapidKeyResponse, createClient, generatePKCEChallenge, localStorageCursorStorage, memoryCursorStorage };
+export { type ApiResponse, type AuthLostReason, type AuthState, type AuthStateListener, type AuthorizationUrlParams, BrowserTokenStorage, CodeChallengeMethod, type ConnectionState, CursorInvalidError, type CursorStorage, type DatabaseChangeEvent, type DownloadUrlResponse, type ExchangeCodeParams, type FileInfo, type FileListResponse, FileVisibility, ForbiddenError, type FunctionInvokeOptions, type FunctionInvokeResult, type GapReason, GrantType, type InitMultipartUploadParams, type InitMultipartUploadResponse, type JWK, type JWKSResponse, type ListFilesParams, type LoginParams, type LoginResponse, MemoryTokenStorage, NotFoundError, type OpenIDConfiguration, type PKCEChallenge, type PartEtag, type PasskeyAuthenticationOptionsJSON, type PasskeyAuthenticationResponseJSON, type PasskeyCredential, type PasskeyCredentialDescriptorJSON, type PasskeyLoginResponse, type PasskeyRegistrationOptionsJSON, type PasskeyRegistrationResponseJSON, type PasskeyRegistrationResult, type PushSubscriptionInfo, type QuotaInfo, type RegisterParams, type RegisterResponse, type Schedule, type ScheduleInvokeOptions, type ScheduleListOptions, type ScheduleStatus, type SearchOptions, ServerConfigError, type ShareFileParams, SharePermission, SpacelrAuthError, type SpacelrClient, type SpacelrClientConfig, SpacelrEmailVerificationRequiredError, SpacelrError, SpacelrNetworkError, SpacelrSearchFilterRequiredError, SpacelrTimeoutError, SpacelrTwoFactorRequiredError, type StoredTokens, type StreamGapInfo, type StreamSubscription, type SubscribeEventsHandlers, type SubscribeHandlers, type SubscribeWithSnapshotOptions, type TimelineAndFilter, TimelineError, type TimelineFieldFilter, type TimelineFilter, type TimelineLeafFilter, TimelineModule, type TimelineOrderBy, type TimelineQueryOptions, type TimelineQueryResponse, type TimelineScalar, type TimelineSourceStats, TimeoutError, type TokenResponse, type TokenStorage, type TwoFactorResponse, type TwoFactorVerifyParams, type UnshareFileParams, type UploadFileParams, type UploadLargeFileParams, type UploadProgress, type UserInfo, type UserProfile, ValidationError, type VapidKeyResponse, type WhereFilter, type WhereOperator, type WhereScalar, type WhereValue, createClient, generatePKCEChallenge, localStorageCursorStorage, memoryCursorStorage };

package/dist/index.d.ts

@@ -516,6 +516,28 @@ declare class SpacelrEmailVerificationRequiredError extends SpacelrError {
 }
 
 type ConnectionState = 'connected' | 'reconnecting' | 'disconnected';
+/** A single primitive `where` candidate. */
+type WhereScalar = string | number | boolean;
+/**
+ * Multi-value `where` operators (Firestore-style) for realtime subscriptions:
+ * - `in`: the document field is a **scalar** equal to any candidate.
+ * - `array-contains-any`: the document field is an **array** sharing at least
+ *   one element with the candidates.
+ *
+ * The single-value form (`where: { field: scalar }`) stays polymorphic — it
+ * matches a scalar field by equality OR an array field by element membership.
+ *
+ * Mirrors the server definition in `@spacelr-workspace/shared-types`
+ * (`realtime-where.ts`); the two must stay structurally identical.
+ */
+type WhereOperator = {
+    in: WhereScalar[];
+} | {
+    'array-contains-any': WhereScalar[];
+};
+type WhereValue = WhereScalar | WhereOperator;
+/** A realtime subscription `where` filter: field name → scalar or operator. */
+type WhereFilter = Record<string, WhereValue>;
 interface DatabaseChangeEvent {
     type: 'insert' | 'update' | 'delete';
     projectId: string;
@@ -553,7 +575,7 @@ interface StreamSubscriptionOptions {
     projectId: string;
     collectionName: string;
     sinceId?: string;
-    where?: Record<string, string | number | boolean>;
+    where?: WhereFilter;
     /**
      * Called for each delivered event. Awaited — the cursor does NOT advance
      * until this resolves. If the callback throws, the cursor is NOT advanced
@@ -575,6 +597,10 @@ declare class RealtimeClient {
     private subscriptions;
     private connecting;
     private roomWhereMap;
+    private roomErrorMap;
+    private roomGeneration;
+    private subEpoch;
+    private resubscribingRooms;
     private unsubscribeFromTokenRefreshed;
     private onVisibilityChange;
     private onOnline;
@@ -584,7 +610,9 @@ declare class RealtimeClient {
     private connectionStateListeners;
     private streamSubscriptions;
     constructor(config: RealtimeConfig);
-    subscribe(projectId: string, collectionName: string, callback: (event: DatabaseChangeEvent) => void, onError?: (error: Error) => void, where?: Record<string, string | number | boolean>): Promise<() => void>;
+    subscribe(projectId: string, collectionName: string, callback: (event: DatabaseChangeEvent) => void, onError?: (error: Error & {
+        code?: string;
+    }) => void, where?: WhereFilter): Promise<() => void>;
     /**
      * Subscribe to a stream-mode collection using Redis Streams replay +
      * cursor-based delivery. Parallel to `subscribe()` (which targets
@@ -676,6 +704,31 @@ declare class RealtimeClient {
     private ensureWakeListeners;
     private detachWakeListeners;
     private resubscribeAll;
+    /**
+     * Parse a pubsub room key back into its projectId + collectionName.
+     * Room format: `db:{projectId}:{collectionName}` or that base plus `?filter`.
+     * Returns null for anything that isn't a well-formed `db:` room.
+     */
+    private parseRoom;
+    /** Build an Error carrying the gateway's typed `errorCode` (if any) as `.code`. */
+    private toSubscribeError;
+    /** Call every subscriber's error handler registered for `room` (#661). */
+    private notifyRoomError;
+    /**
+     * Re-run the subscribe handshake for one already-tracked room. Shared by
+     * reconnect resubscription (`resubscribeAll`) and the #661
+     * `subscription-invalidated` handler.
+     *
+     * - Deduped per room via `resubscribingRooms` so the duplicate invalidation
+     *   events the gateway emits (one per evicted room) collapse to one handshake.
+     * - Snapshots the room's generation; the ack acts only if it is still current,
+     *   so a late ack cannot clobber an unsubscribe/re-subscribe that happened in
+     *   the meantime — and a success that arrives after the room was removed emits
+     *   a compensating `unsubscribe` so no ghost server room is left behind.
+     * - On a genuine denial the subscription is evicted and its stored `onError`
+     *   is called (with the typed `.code`), instead of silently going quiet.
+     */
+    private resubscribeRoom;
     private emitSubscribeEvents;
     private buildStreamPayload;
     private unsubscribeStream;
@@ -1089,16 +1142,18 @@ interface SubscribeWithSnapshotOptions<T> {
      * **Snapshot semantics** (full MongoDB query): supports operators like
      * `{ status: { $in: [...] } }`, `{ ts: { $gt: ... } }`, etc.
      *
-     * **Live-stream semantics** (gateway-side equality only): the stream
-     * filter only honours top-level primitive equality
-     * (`string | number | boolean` values). Operator-shaped values are
-     * silently dropped from the stream filter at handshake time — the
-     * remaining primitive entries still apply, so a typical chat-style
-     * `{ chatId: 'c1' }` filter works identically on both sides. If you
-     * pass a mixed `{ chatId: 'c1', status: { $in: [...] } }`, the
-     * snapshot is fully filtered but the live stream filters by `chatId`
-     * only; you may receive `onChange` events for documents whose `status`
-     * is outside your `$in` set. Re-check in the handler if needed.
+     * **Live-stream semantics** (top-level primitives only): this helper
+     * forwards only top-level primitive values (`string | number | boolean`)
+     * from the Mongo-query `where` to the live filter. MongoDB operators
+     * (`$in`, `$gt`, …) are silently dropped at handshake time and are NOT
+     * translated into the gateway's realtime `in` / `array-contains-any`
+     * operators — the remaining primitive entries still apply, so a typical
+     * chat-style `{ chatId: 'c1' }` filter works identically on both sides. If
+     * you pass a mixed `{ chatId: 'c1', status: { $in: [...] } }`, the snapshot
+     * is fully filtered but the live stream filters by `chatId` only; you may
+     * receive `onChange` events for documents whose `status` is outside your
+     * `$in` set. Re-check in the handler, or use `subscribeEvents()` directly
+     * with a realtime `{ status: { in: [...] } }` operator for live filtering.
      */
     where?: Record<string, unknown>;
     sort?: Record<string, 1 | -1>;
@@ -1159,7 +1214,7 @@ interface SubscribeWithSnapshotOptions<T> {
 interface SubscribeEventsHandlers<T = Record<string, unknown>> {
     /** Cursor to resume from. Undefined = fresh subscription, deliver only new events. */
     sinceId?: string;
-    where?: Record<string, string | number | boolean>;
+    where?: WhereFilter;
     /**
      * Optional resume-cursor store. When set, the SDK loads the previous cursor
      * before subscribing and persists the new cursor after each delivered
@@ -1216,7 +1271,7 @@ interface StreamSubscription {
     getCursor(): string | undefined;
 }
 interface SubscribeHandlers<T = Record<string, unknown>> {
-    where?: Record<string, string | number | boolean>;
+    where?: WhereFilter;
     onInsert?: (doc: T & {
         _id: string;
     }) => void;
@@ -1546,6 +1601,11 @@ interface FunctionInvokeOptions {
      *
      * If `true` but the user is not signed in, the header is simply omitted —
      * safe for `public` invokeMode.
+     *
+     * Note: for `authenticated`/`hybrid` invokeMode, the server additionally
+     * requires the token's user to be a member of the target project — this
+     * flag only controls whether the header is attached, not who the server
+     * accepts.
      */
     authenticated?: boolean;
     payload?: Record<string, unknown>;
@@ -1564,10 +1624,14 @@ declare class FunctionsModule {
      * `config.apiUrl` (which already carries the `/api/v1` prefix).
      *
      * Auth defaults, based on `invokeMode` semantics:
-     *  - webhook:       pass `secret` → Authorization is NOT attached
-     *  - authenticated: pass nothing  → Authorization IS attached (from token manager)
-     *  - public:        pass nothing  → Authorization is attached if logged in, else omitted
-     *  - hybrid:        pass both `secret` and `authenticated: true`
+     *  - webhook:                 pass `secret` → Authorization is NOT attached
+     *  - authenticated:           pass nothing  → Authorization IS attached (from token manager);
+     *                             caller must be a member of the target project
+     *  - public:                  pass nothing  → Authorization is attached if logged in, else omitted
+     *  - hybrid:                  pass both `secret` and `authenticated: true`; JWT path
+     *                             requires project membership like `authenticated`
+     *  - platform-authenticated:  pass nothing  → Authorization IS attached (from token manager);
+     *                             any signed-in user is accepted, still just attaches the bearer token
      *
      * To force a specific behaviour, set `authenticated` explicitly — it wins
      * over the `secret`-based default.
@@ -1763,4 +1827,4 @@ interface SpacelrClient {
 }
 declare function createClient(config: SpacelrClientConfig): SpacelrClient;
 
-export { type ApiResponse, type AuthLostReason, type AuthState, type AuthStateListener, type AuthorizationUrlParams, BrowserTokenStorage, CodeChallengeMethod, type ConnectionState, CursorInvalidError, type CursorStorage, type DatabaseChangeEvent, type DownloadUrlResponse, type ExchangeCodeParams, type FileInfo, type FileListResponse, FileVisibility, ForbiddenError, type FunctionInvokeOptions, type FunctionInvokeResult, type GapReason, GrantType, type InitMultipartUploadParams, type InitMultipartUploadResponse, type JWK, type JWKSResponse, type ListFilesParams, type LoginParams, type LoginResponse, MemoryTokenStorage, NotFoundError, type OpenIDConfiguration, type PKCEChallenge, type PartEtag, type PasskeyAuthenticationOptionsJSON, type PasskeyAuthenticationResponseJSON, type PasskeyCredential, type PasskeyCredentialDescriptorJSON, type PasskeyLoginResponse, type PasskeyRegistrationOptionsJSON, type PasskeyRegistrationResponseJSON, type PasskeyRegistrationResult, type PushSubscriptionInfo, type QuotaInfo, type RegisterParams, type RegisterResponse, type Schedule, type ScheduleInvokeOptions, type ScheduleListOptions, type ScheduleStatus, type SearchOptions, ServerConfigError, type ShareFileParams, SharePermission, SpacelrAuthError, type SpacelrClient, type SpacelrClientConfig, SpacelrEmailVerificationRequiredError, SpacelrError, SpacelrNetworkError, SpacelrSearchFilterRequiredError, SpacelrTimeoutError, SpacelrTwoFactorRequiredError, type StoredTokens, type StreamGapInfo, type StreamSubscription, type SubscribeEventsHandlers, type SubscribeHandlers, type SubscribeWithSnapshotOptions, type TimelineAndFilter, TimelineError, type TimelineFieldFilter, type TimelineFilter, type TimelineLeafFilter, TimelineModule, type TimelineOrderBy, type TimelineQueryOptions, type TimelineQueryResponse, type TimelineScalar, type TimelineSourceStats, TimeoutError, type TokenResponse, type TokenStorage, type TwoFactorResponse, type TwoFactorVerifyParams, type UnshareFileParams, type UploadFileParams, type UploadLargeFileParams, type UploadProgress, type UserInfo, type UserProfile, ValidationError, type VapidKeyResponse, createClient, generatePKCEChallenge, localStorageCursorStorage, memoryCursorStorage };
+export { type ApiResponse, type AuthLostReason, type AuthState, type AuthStateListener, type AuthorizationUrlParams, BrowserTokenStorage, CodeChallengeMethod, type ConnectionState, CursorInvalidError, type CursorStorage, type DatabaseChangeEvent, type DownloadUrlResponse, type ExchangeCodeParams, type FileInfo, type FileListResponse, FileVisibility, ForbiddenError, type FunctionInvokeOptions, type FunctionInvokeResult, type GapReason, GrantType, type InitMultipartUploadParams, type InitMultipartUploadResponse, type JWK, type JWKSResponse, type ListFilesParams, type LoginParams, type LoginResponse, MemoryTokenStorage, NotFoundError, type OpenIDConfiguration, type PKCEChallenge, type PartEtag, type PasskeyAuthenticationOptionsJSON, type PasskeyAuthenticationResponseJSON, type PasskeyCredential, type PasskeyCredentialDescriptorJSON, type PasskeyLoginResponse, type PasskeyRegistrationOptionsJSON, type PasskeyRegistrationResponseJSON, type PasskeyRegistrationResult, type PushSubscriptionInfo, type QuotaInfo, type RegisterParams, type RegisterResponse, type Schedule, type ScheduleInvokeOptions, type ScheduleListOptions, type ScheduleStatus, type SearchOptions, ServerConfigError, type ShareFileParams, SharePermission, SpacelrAuthError, type SpacelrClient, type SpacelrClientConfig, SpacelrEmailVerificationRequiredError, SpacelrError, SpacelrNetworkError, SpacelrSearchFilterRequiredError, SpacelrTimeoutError, SpacelrTwoFactorRequiredError, type StoredTokens, type StreamGapInfo, type StreamSubscription, type SubscribeEventsHandlers, type SubscribeHandlers, type SubscribeWithSnapshotOptions, type TimelineAndFilter, TimelineError, type TimelineFieldFilter, type TimelineFilter, type TimelineLeafFilter, TimelineModule, type TimelineOrderBy, type TimelineQueryOptions, type TimelineQueryResponse, type TimelineScalar, type TimelineSourceStats, TimeoutError, type TokenResponse, type TokenStorage, type TwoFactorResponse, type TwoFactorVerifyParams, type UnshareFileParams, type UploadFileParams, type UploadLargeFileParams, type UploadProgress, type UserInfo, type UserProfile, ValidationError, type VapidKeyResponse, type WhereFilter, type WhereOperator, type WhereScalar, type WhereValue, createClient, generatePKCEChallenge, localStorageCursorStorage, memoryCursorStorage };

package/dist/index.js

@@ -657,6 +657,57 @@ var PERMANENT_STREAM_ACK_ERRORS = /* @__PURE__ */ new Set([
   "Not a member of this project",
   "Subscribe denied"
 ]);
+function isWhereScalar(value) {
+  const t = typeof value;
+  return t === "string" || t === "number" || t === "boolean";
+}
+function isWhereOperator(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const keys = Object.keys(value);
+  if (keys.length !== 1) return false;
+  const op = keys[0];
+  if (op !== "in" && op !== "array-contains-any") return false;
+  const candidates = value[op];
+  return Array.isArray(candidates) && candidates.every(isWhereScalar);
+}
+var WHERE_PATH_ABSENT = /* @__PURE__ */ Symbol("where-path-absent");
+var WHERE_PATH_UNRESOLVABLE = /* @__PURE__ */ Symbol("where-path-unresolvable");
+var RESERVED_PATH_SEGMENTS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+var MAX_WHERE_PATH_SEGMENTS = 16;
+function resolveWherePath(document2, key) {
+  const segments = key.split(".");
+  if (segments.length > MAX_WHERE_PATH_SEGMENTS) return WHERE_PATH_ABSENT;
+  let cur = document2;
+  for (const segment of segments) {
+    if (RESERVED_PATH_SEGMENTS.has(segment)) return WHERE_PATH_ABSENT;
+    if (cur === null || cur === void 0) return WHERE_PATH_ABSENT;
+    if (Array.isArray(cur)) return WHERE_PATH_UNRESOLVABLE;
+    if (typeof cur !== "object") return WHERE_PATH_ABSENT;
+    if (!Object.prototype.hasOwnProperty.call(cur, segment)) {
+      return WHERE_PATH_ABSENT;
+    }
+    cur = cur[segment];
+  }
+  return cur === void 0 ? WHERE_PATH_ABSENT : cur;
+}
+function whereValueMatches(actual, expected) {
+  if (actual === WHERE_PATH_ABSENT || actual === WHERE_PATH_UNRESOLVABLE) {
+    return false;
+  }
+  if (isWhereOperator(expected)) {
+    if ("in" in expected) {
+      if (Array.isArray(actual)) return false;
+      return expected.in.includes(actual);
+    }
+    if (!Array.isArray(actual)) return false;
+    const candidates = expected["array-contains-any"];
+    return actual.some((el) => candidates.includes(el));
+  }
+  if (Array.isArray(actual)) return actual.includes(expected);
+  return actual === expected;
+}
 var RealtimeClient = class {
   constructor(config) {
     this.socket = null;
@@ -664,6 +715,21 @@ var RealtimeClient = class {
     this.connecting = null;
     // Store original where objects per room for reconnect resubscription
     this.roomWhereMap = /* @__PURE__ */ new Map();
+    // Per-room, per-callback error handlers so EVERY subscriber to a room (not
+    // just the first) is notified on a denial, and a departed subscriber's handler
+    // is never left dangling for its still-active siblings (#661).
+    this.roomErrorMap = /* @__PURE__ */ new Map();
+    // Per-room generation stamp, taken from a global monotonic counter each time a
+    // room becomes active. A re-subscribe snapshots the room's stamp and acts on
+    // the ack only if it is still current — so a late ack cannot notify or clean
+    // up after the app has unsubscribed/re-subscribed (#661). Entries are deleted
+    // on last-unsubscribe (bounded); the global counter guarantees a re-subscribe
+    // always gets a strictly higher stamp, so there is no ABA hole.
+    this.roomGeneration = /* @__PURE__ */ new Map();
+    this.subEpoch = 0;
+    // Rooms with a re-subscribe handshake in flight — dedupes the duplicate
+    // `subscription-invalidated` events the gateway emits per evicted room (#661).
+    this.resubscribingRooms = /* @__PURE__ */ new Set();
     this.unsubscribeFromTokenRefreshed = null;
     // Wake-up listeners (browser only) — recover from long OS suspends where
     // socket.io's internal reconnect loop may have already given up.
@@ -692,7 +758,17 @@ var RealtimeClient = class {
     }
     const callbacks = this.subscriptions.get(room);
     callbacks?.add(callback);
+    if (onError) {
+      let handlers = this.roomErrorMap.get(room);
+      if (!handlers) {
+        handlers = /* @__PURE__ */ new Map();
+        this.roomErrorMap.set(room, handlers);
+      }
+      handlers.set(callback, onError);
+    }
     if (callbacks?.size === 1) {
+      const generation = ++this.subEpoch;
+      this.roomGeneration.set(room, generation);
       if (where && Object.keys(where).length > 0) {
         this.roomWhereMap.set(room, where);
       }
@@ -704,8 +780,8 @@ var RealtimeClient = class {
         "subscribe",
         payload,
         (response) => {
-          if (response.error && onError) {
-            onError(new Error(response.error));
+          if (response.error && this.roomGeneration.get(room) === generation) {
+            this.notifyRoomError(room, this.toSubscribeError(response));
           }
         }
       );
@@ -714,9 +790,12 @@ var RealtimeClient = class {
       const callbacks2 = this.subscriptions.get(room);
       if (callbacks2) {
         callbacks2.delete(callback);
+        this.roomErrorMap.get(room)?.delete(callback);
         if (callbacks2.size === 0) {
           this.subscriptions.delete(room);
           this.roomWhereMap.delete(room);
+          this.roomErrorMap.delete(room);
+          this.roomGeneration.delete(room);
           const payload = { projectId, collectionName };
           if (where && Object.keys(where).length > 0) {
             payload["where"] = where;
@@ -869,6 +948,9 @@ var RealtimeClient = class {
     }
     this.subscriptions.clear();
     this.roomWhereMap.clear();
+    this.roomErrorMap.clear();
+    this.roomGeneration.clear();
+    this.resubscribingRooms.clear();
     this.streamSubscriptions.clear();
     this.connecting = null;
   }
@@ -1018,6 +1100,18 @@ var RealtimeClient = class {
           }
         }
       });
+      this.socket.on(
+        "subscription-invalidated",
+        (payload) => {
+          if (!payload?.projectId || !payload?.collectionName) return;
+          const base = `db:${payload.projectId}:${payload.collectionName}`;
+          for (const room of this.subscriptions.keys()) {
+            if (room === base || room.startsWith(`${base}?`)) {
+              this.resubscribeRoom(room);
+            }
+          }
+        }
+      );
       this.socket.on("event", (payload) => {
         this.dispatchStreamEvent(payload).catch(() => void 0);
       });
@@ -1045,12 +1139,7 @@ var RealtimeClient = class {
     if (!where) return false;
     if (!event.document) return false;
     for (const [key, value] of Object.entries(where)) {
-      const docValue = event.document[key];
-      if (Array.isArray(docValue)) {
-        if (!docValue.includes(value)) {
-          return false;
-        }
-      } else if (docValue !== value) {
+      if (!whereValueMatches(resolveWherePath(event.document, key), value)) {
         return false;
       }
     }
@@ -1124,31 +1213,88 @@ var RealtimeClient = class {
     this.onOnline = null;
   }
   resubscribeAll() {
+    this.resubscribingRooms.clear();
     for (const [room] of this.subscriptions) {
-      const queryIdx = room.indexOf("?");
-      const basePart = queryIdx >= 0 ? room.substring(0, queryIdx) : room;
-      const parts = basePart.split(":");
-      if (parts.length >= 3) {
-        const projectId = parts[1];
-        const collectionName = parts.slice(2).join(":");
-        const payload = { projectId, collectionName };
-        const where = this.roomWhereMap.get(room);
-        if (where) {
-          payload["where"] = where;
-        }
-        this.socket?.emit(
-          "subscribe",
-          payload,
-          (response) => {
-            if (response?.error) {
-              this.subscriptions.delete(room);
-              this.roomWhereMap.delete(room);
-            }
-          }
-        );
+      this.resubscribeRoom(room);
+    }
+  }
+  /**
+   * Parse a pubsub room key back into its projectId + collectionName.
+   * Room format: `db:{projectId}:{collectionName}` or that base plus `?filter`.
+   * Returns null for anything that isn't a well-formed `db:` room.
+   */
+  parseRoom(room) {
+    const queryIdx = room.indexOf("?");
+    const basePart = queryIdx >= 0 ? room.substring(0, queryIdx) : room;
+    const parts = basePart.split(":");
+    if (parts.length < 3 || parts[0] !== "db") return null;
+    return { projectId: parts[1], collectionName: parts.slice(2).join(":") };
+  }
+  /** Build an Error carrying the gateway's typed `errorCode` (if any) as `.code`. */
+  toSubscribeError(response) {
+    const err = new Error(response.error ?? "Subscribe denied");
+    if (response.errorCode) err.code = response.errorCode;
+    return err;
+  }
+  /** Call every subscriber's error handler registered for `room` (#661). */
+  notifyRoomError(room, error) {
+    const handlers = this.roomErrorMap.get(room);
+    if (!handlers) return;
+    for (const handler of handlers.values()) {
+      try {
+        handler(error);
+      } catch {
       }
     }
   }
+  /**
+   * Re-run the subscribe handshake for one already-tracked room. Shared by
+   * reconnect resubscription (`resubscribeAll`) and the #661
+   * `subscription-invalidated` handler.
+   *
+   * - Deduped per room via `resubscribingRooms` so the duplicate invalidation
+   *   events the gateway emits (one per evicted room) collapse to one handshake.
+   * - Snapshots the room's generation; the ack acts only if it is still current,
+   *   so a late ack cannot clobber an unsubscribe/re-subscribe that happened in
+   *   the meantime — and a success that arrives after the room was removed emits
+   *   a compensating `unsubscribe` so no ghost server room is left behind.
+   * - On a genuine denial the subscription is evicted and its stored `onError`
+   *   is called (with the typed `.code`), instead of silently going quiet.
+   */
+  resubscribeRoom(room) {
+    if (!this.socket) return;
+    if (this.resubscribingRooms.has(room)) return;
+    if (!this.subscriptions.has(room)) return;
+    const parsed = this.parseRoom(room);
+    if (!parsed) return;
+    const { projectId, collectionName } = parsed;
+    const where = this.roomWhereMap.get(room);
+    const generation = this.roomGeneration.get(room) ?? 0;
+    const payload = { projectId, collectionName };
+    if (where) payload["where"] = where;
+    this.resubscribingRooms.add(room);
+    this.socket.emit(
+      "subscribe",
+      payload,
+      (response) => {
+        this.resubscribingRooms.delete(room);
+        if ((this.roomGeneration.get(room) ?? 0) !== generation) {
+          if (!this.subscriptions.has(room) && !response?.error) {
+            this.socket?.emit("unsubscribe", payload);
+          }
+          return;
+        }
+        if (response?.error) {
+          const error = this.toSubscribeError(response);
+          this.notifyRoomError(room, error);
+          this.subscriptions.delete(room);
+          this.roomWhereMap.delete(room);
+          this.roomErrorMap.delete(room);
+          this.roomGeneration.delete(room);
+        }
+      }
+    );
+  }
   emitSubscribeEvents(state) {
     return new Promise((resolve) => {
       if (!this.socket) {
@@ -3011,10 +3157,14 @@ var FunctionsModule = class {
    * `config.apiUrl` (which already carries the `/api/v1` prefix).
    *
    * Auth defaults, based on `invokeMode` semantics:
-   *  - webhook:       pass `secret` → Authorization is NOT attached
-   *  - authenticated: pass nothing  → Authorization IS attached (from token manager)
-   *  - public:        pass nothing  → Authorization is attached if logged in, else omitted
-   *  - hybrid:        pass both `secret` and `authenticated: true`
+   *  - webhook:                 pass `secret` → Authorization is NOT attached
+   *  - authenticated:           pass nothing  → Authorization IS attached (from token manager);
+   *                             caller must be a member of the target project
+   *  - public:                  pass nothing  → Authorization is attached if logged in, else omitted
+   *  - hybrid:                  pass both `secret` and `authenticated: true`; JWT path
+   *                             requires project membership like `authenticated`
+   *  - platform-authenticated:  pass nothing  → Authorization IS attached (from token manager);
+   *                             any signed-in user is accepted, still just attaches the bearer token
    *
    * To force a specific behaviour, set `authenticated` explicitly — it wins
    * over the `secret`-based default.