@spacelr/sdk 0.5.0 → 0.5.2

package/README.md

@@ -42,9 +42,41 @@ spacelr.db.subscribe('my-collection', {
 | --- | --- |
 | `auth` | Login, registration, OAuth2 PKCE flow, token management, 2FA |
 | `storage` | File upload (including multipart), download, sharing, quota |
-| `db` | Database operations with realtime subscriptions via WebSocket |
+| `db` | Database operations with realtime subscriptions via WebSocket; `db.timeline` for cold-tier history reads |
 | `notifications` | Web Push notification subscription management |
 
+## Cold-tier history (`db.timeline`)
+
+Collections can enable **cold-tier** archival: aged documents are moved to
+object storage and purged from the live (hot) MongoDB tier. The normal query
+methods (`find`, `findById`, `count`, `search`, `paginate`) operate on the **hot
+tier only** — archived documents will not appear in their results.
+
+To read archived history, use the timeline API, which transparently merges hot
+and cold data for a partition (e.g. a chat room) and paginates with an opaque
+cursor:
+
+```ts
+const page = await spacelr.db.timeline.query({
+  collection: 'chat_messages',
+  partitionValue: 'room-123',              // the cold-tier partition (e.g. room id)
+  where: { authorId: { $eq: 'user-1' } },  // optional, allow-listed operators only
+  orderBy: { field: 'createdAt', direction: 'desc' },
+  limit: 50,                               // 1–200, default 50
+});
+
+page.items;        // merged hot + cold documents
+page.nextCursor;   // pass back as `cursor` for the next page (null = end)
+page.sourceStats;  // { hot, cold, segmentsScanned? } — where the rows came from
+```
+
+Notes:
+- Timeline paginates by partition + timestamp, not arbitrary Mongo queries;
+  `where` accepts only the allow-listed operators (`$eq`, `$ne`, `$lt`, `$lte`,
+  `$gt`, `$gte`, `$in`, `$nin`, `$and`).
+- Enabling/configuring cold-tier on a collection is an **admin** operation and
+  is not part of this client SDK.
+
 ## Requirements
 
 - Node.js >= 18

package/dist/index.d.mts

@@ -738,6 +738,98 @@ declare class StorageModule {
     getPublicFileUrl(fileId: string, projectId?: string): Promise<string>;
 }
 
+/**
+ * Scalar values permitted inside a timeline filter. Matches the server
+ * filter allow-list (libs/shared-dtos/.../timeline-filter.dto.ts).
+ */
+type TimelineScalar = string | number | boolean | null;
+/**
+ * Single-field filter expression. Either implicit equality (a scalar) or
+ * an explicit operator object. Mongo-style allow-list — the server rejects
+ * anything outside this set.
+ */
+type TimelineLeafFilter = TimelineScalar | {
+    $eq?: TimelineScalar;
+    $ne?: TimelineScalar;
+    $lt?: TimelineScalar;
+    $lte?: TimelineScalar;
+    $gt?: TimelineScalar;
+    $gte?: TimelineScalar;
+    $in?: TimelineScalar[];
+    $nin?: TimelineScalar[];
+};
+/**
+ * Filter document for a timeline query. Top-level fields apply implicit
+ * equality (or operator expression). $and supports nested filter
+ * composition; $or / $regex / etc. are intentionally NOT exposed and
+ * will be rejected server-side.
+ *
+ * Two named branches in the union so TypeScript doesn't treat `$and` as
+ * just another key under the field index signature — the array shape
+ * needs its own type or downstream usage breaks.
+ */
+interface TimelineAndFilter {
+    $and: TimelineFilter[];
+}
+type TimelineFieldFilter = Record<string, TimelineLeafFilter>;
+type TimelineFilter = TimelineAndFilter | TimelineFieldFilter;
+interface TimelineOrderBy {
+    field: string;
+    direction: 'asc' | 'desc';
+}
+interface TimelineQueryOptions {
+    /** Collection name to read from. */
+    collection: string;
+    /** Partition value (e.g. roomId, documentId — collection-configured). */
+    partitionValue: string;
+    /** Optional filter constraints (allow-listed operators only). */
+    where?: TimelineFilter;
+    /**
+     * Sort order. Defaults to DESC by the collection's configured timeline
+     * field; PR A only supports DESC. Passing direction='asc' is reserved
+     * for a future phase and currently returns BAD_REQUEST.
+     */
+    orderBy?: TimelineOrderBy;
+    /** Page size (1..200). Default 50. */
+    limit?: number;
+    /**
+     * Opaque cursor from a previous response. The SDK does NOT decode this —
+     * pass the value of `nextCursor` from the last response verbatim.
+     */
+    cursor?: string;
+}
+interface TimelineSourceStats {
+    hot: number;
+    cold: number;
+    /** Number of cold archive segments scanned (only present when cold path ran). */
+    segmentsScanned?: number;
+}
+interface TimelineQueryResponse {
+    items: Record<string, unknown>[];
+    /** Opaque continuation token. `null` when the page is the last one. */
+    nextCursor: string | null;
+    sourceStats: TimelineSourceStats;
+}
+
+/**
+ * Low-level timeline SDK module. One method: query(opts) → page.
+ *
+ * The cursor is opaque from the SDK's perspective — it's stored as a
+ * string, never decoded, never inspected. Callers pass the value of
+ * `nextCursor` from the previous response verbatim into the next request.
+ *
+ * Errors thrown from query() extend SpacelrError so they integrate with
+ * the SDK's existing error hierarchy. Use one of the typed subclasses
+ * (CursorInvalidError, ForbiddenError, etc.) to catch specific cases or
+ * `catch (e instanceof TimelineError)` for any timeline-related failure.
+ */
+declare class TimelineModule {
+    private readonly http;
+    constructor(http: HttpClient);
+    query(opts: TimelineQueryOptions): Promise<TimelineQueryResponse>;
+    private translateError;
+}
+
 interface PopulateOption {
     field: string;
     collection: string;
@@ -1106,6 +1198,16 @@ declare class CollectionRef<T = Record<string, unknown>> {
     insertMany(documents: (Partial<T> & {
         _id?: string;
     })[]): Promise<InsertResult>;
+    /**
+     * Query the collection's **hot tier** (live MongoDB).
+     *
+     * **Cold-tier note:** if the collection has cold-tier archival enabled, aged
+     * documents are moved to object storage and purged from the hot tier — they
+     * will NOT appear in `find()` results (nor `findById`, `count`, `search`,
+     * `paginate`, which are all hot-tier only). To read archived history, use
+     * {@link TimelineModule.query} via `db.timeline.query(...)`, which transparently
+     * merges hot and cold results for a partition.
+     */
     find(filter?: Record<string, unknown>): QueryBuilder<T>;
     /**
      * Cursor-based scroll-back helper. Returns a `Paginator` whose `.next()`
@@ -1136,13 +1238,30 @@ declare class CollectionRef<T = Record<string, unknown>> {
      *
      * Limits: `query` 1–200 chars, `fields` 1–10 entries (each matching
      * `/^[a-zA-Z0-9_.]+$/`, max 64 chars), `limit` max 100.
+     *
+     * **Cold-tier note:** searches the hot tier only; archived documents are not
+     * included. See {@link CollectionRef.find} and `db.timeline.query(...)`.
      */
     search(opts: SearchOptions): Promise<SearchResult<T>>;
+    /**
+     * Fetch a single document by `_id` from the **hot tier**.
+     *
+     * **Cold-tier note:** returns null/throws for documents that have been
+     * archived and purged from the hot tier. Archived history is reachable only
+     * via `db.timeline.query(...)`. See {@link CollectionRef.find}.
+     */
     findById(id: string, options?: FindByIdOptions): Promise<T & {
         _id: string;
     }>;
     update(id: string, update: Partial<T>): Promise<UpdateResult>;
     delete(id: string): Promise<DeleteResult>;
+    /**
+     * Count documents in the **hot tier** matching `filter`.
+     *
+     * **Cold-tier note:** counts hot-tier documents only — archived/purged
+     * documents are not included, so this is not a total-history count. See
+     * {@link CollectionRef.find} and `db.timeline.query(...)`.
+     */
     count(filter?: Record<string, unknown>): Promise<number>;
     subscribe(handlers: SubscribeHandlers<T>): () => void;
     subscribeEvents(handlers: SubscribeEventsHandlers<T>): StreamSubscription;
@@ -1161,13 +1280,20 @@ declare class DatabaseModule {
     private http;
     private realtime;
     private projectId;
+    readonly timeline: TimelineModule;
     constructor(http: HttpClient, projectId: string, realtime?: RealtimeClient);
     collection<T = Record<string, unknown>>(name: string): CollectionRef<T>;
 }
 
+/**
+ * Push subscription platform. `web` = VAPID WebPush; `android`/`ios` = native
+ * device tokens; `web-fcm` = a web Firebase Cloud Messaging registration token.
+ * Defined locally so `@spacelr/sdk` stays a standalone, dependency-free package.
+ */
+type PushPlatform = 'web' | 'android' | 'ios' | 'web-fcm';
 interface PushSubscriptionInfo {
     id: string;
-    platform: 'web' | 'android' | 'ios';
+    platform: PushPlatform;
     endpoint?: string;
     deviceToken?: string;
     deviceId?: string;
@@ -1198,9 +1324,9 @@ declare class NotificationsModule {
     private detectDeviceName;
     /** Get the VAPID public key for Web Push setup */
     getVapidPublicKey(): Promise<VapidKeyResponse>;
-    /** Register a push subscription (web, android, or ios) */
+    /** Register a push subscription (web, android, ios, or web-fcm) */
     subscribe(subscription: {
-        platform: 'web' | 'android' | 'ios';
+        platform: PushPlatform;
         endpoint?: string;
         keys?: {
             p256dh: string;
@@ -1209,7 +1335,7 @@ declare class NotificationsModule {
         deviceToken?: string;
     }, deviceName?: string): Promise<PushSubscriptionInfo>;
     /** Unregister a push subscription */
-    unsubscribe(platform: 'web' | 'android' | 'ios', identifier: string): Promise<{
+    unsubscribe(platform: PushPlatform, identifier: string): Promise<{
         deleted: boolean;
     }>;
     /** Get all subscriptions for the current user */
@@ -1224,6 +1350,12 @@ declare class NotificationsModule {
      * Helper: Register a mobile device push token (FCM or APNs).
      */
     registerDevicePush(deviceToken: string, platform: 'android' | 'ios', deviceName?: string): Promise<PushSubscriptionInfo>;
+    /**
+     * Registers a web Firebase Cloud Messaging registration token (obtained via
+     * the Firebase JS SDK `getToken()`), so `notifications.send` delivers to this
+     * browser through the project's FCM provider instead of VAPID WebPush.
+     */
+    registerWebFcm(fcmToken: string, deviceName?: string): Promise<PushSubscriptionInfo>;
     private urlBase64ToUint8Array;
 }
 
@@ -1334,6 +1466,55 @@ declare class ScheduleModule {
     private toIsoString;
 }
 
+/**
+ * Base class for all timeline-related errors thrown by the SDK. Extends
+ * SpacelrError so it fits the SDK's existing `catch (e instanceof
+ * SpacelrError)` pattern. Subclasses give callers fine-grained control
+ * (e.g. catch only `CursorInvalidError` and restart pagination).
+ */
+declare class TimelineError extends SpacelrError {
+    constructor(message: string, opts?: {
+        statusCode?: number;
+        code?: string;
+    });
+}
+declare class CursorInvalidError extends TimelineError {
+    constructor(message: string, opts?: {
+        statusCode?: number;
+        code?: string;
+    });
+}
+declare class ValidationError extends TimelineError {
+    constructor(message: string, opts?: {
+        statusCode?: number;
+        code?: string;
+    });
+}
+declare class ForbiddenError extends TimelineError {
+    constructor(message: string, opts?: {
+        statusCode?: number;
+        code?: string;
+    });
+}
+declare class NotFoundError extends TimelineError {
+    constructor(message: string, opts?: {
+        statusCode?: number;
+        code?: string;
+    });
+}
+declare class ServerConfigError extends TimelineError {
+    constructor(message: string, opts?: {
+        statusCode?: number;
+        code?: string;
+    });
+}
+declare class TimeoutError extends TimelineError {
+    constructor(message: string, opts?: {
+        statusCode?: number;
+        code?: string;
+    });
+}
+
 interface SpacelrClient {
     readonly auth: AuthModule;
     readonly storage: StorageModule;
@@ -1392,4 +1573,4 @@ interface SpacelrClient {
 }
 declare function createClient(config: SpacelrClientConfig): SpacelrClient;
 
-export { type ApiResponse, type AuthLostReason, type AuthState, type AuthStateListener, type AuthorizationUrlParams, BrowserTokenStorage, CodeChallengeMethod, type ConnectionState, type CursorStorage, type DatabaseChangeEvent, type DownloadUrlResponse, type ExchangeCodeParams, type FileInfo, type FileListResponse, FileVisibility, type FunctionInvokeOptions, type FunctionInvokeResult, type GapReason, GrantType, type InitMultipartUploadParams, type InitMultipartUploadResponse, type JWK, type JWKSResponse, type ListFilesParams, type LoginParams, type LoginResponse, MemoryTokenStorage, type OpenIDConfiguration, type PKCEChallenge, type PartEtag, type PushSubscriptionInfo, type QuotaInfo, type RegisterParams, type RegisterResponse, type Schedule, type ScheduleInvokeOptions, type ScheduleListOptions, type ScheduleStatus, type SearchOptions, 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 TokenResponse, type TokenStorage, type TwoFactorResponse, type TwoFactorVerifyParams, type UnshareFileParams, type UploadFileParams, type UploadLargeFileParams, type UploadProgress, type UserInfo, type UserProfile, 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 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 };

package/dist/index.d.ts

@@ -738,6 +738,98 @@ declare class StorageModule {
     getPublicFileUrl(fileId: string, projectId?: string): Promise<string>;
 }
 
+/**
+ * Scalar values permitted inside a timeline filter. Matches the server
+ * filter allow-list (libs/shared-dtos/.../timeline-filter.dto.ts).
+ */
+type TimelineScalar = string | number | boolean | null;
+/**
+ * Single-field filter expression. Either implicit equality (a scalar) or
+ * an explicit operator object. Mongo-style allow-list — the server rejects
+ * anything outside this set.
+ */
+type TimelineLeafFilter = TimelineScalar | {
+    $eq?: TimelineScalar;
+    $ne?: TimelineScalar;
+    $lt?: TimelineScalar;
+    $lte?: TimelineScalar;
+    $gt?: TimelineScalar;
+    $gte?: TimelineScalar;
+    $in?: TimelineScalar[];
+    $nin?: TimelineScalar[];
+};
+/**
+ * Filter document for a timeline query. Top-level fields apply implicit
+ * equality (or operator expression). $and supports nested filter
+ * composition; $or / $regex / etc. are intentionally NOT exposed and
+ * will be rejected server-side.
+ *
+ * Two named branches in the union so TypeScript doesn't treat `$and` as
+ * just another key under the field index signature — the array shape
+ * needs its own type or downstream usage breaks.
+ */
+interface TimelineAndFilter {
+    $and: TimelineFilter[];
+}
+type TimelineFieldFilter = Record<string, TimelineLeafFilter>;
+type TimelineFilter = TimelineAndFilter | TimelineFieldFilter;
+interface TimelineOrderBy {
+    field: string;
+    direction: 'asc' | 'desc';
+}
+interface TimelineQueryOptions {
+    /** Collection name to read from. */
+    collection: string;
+    /** Partition value (e.g. roomId, documentId — collection-configured). */
+    partitionValue: string;
+    /** Optional filter constraints (allow-listed operators only). */
+    where?: TimelineFilter;
+    /**
+     * Sort order. Defaults to DESC by the collection's configured timeline
+     * field; PR A only supports DESC. Passing direction='asc' is reserved
+     * for a future phase and currently returns BAD_REQUEST.
+     */
+    orderBy?: TimelineOrderBy;
+    /** Page size (1..200). Default 50. */
+    limit?: number;
+    /**
+     * Opaque cursor from a previous response. The SDK does NOT decode this —
+     * pass the value of `nextCursor` from the last response verbatim.
+     */
+    cursor?: string;
+}
+interface TimelineSourceStats {
+    hot: number;
+    cold: number;
+    /** Number of cold archive segments scanned (only present when cold path ran). */
+    segmentsScanned?: number;
+}
+interface TimelineQueryResponse {
+    items: Record<string, unknown>[];
+    /** Opaque continuation token. `null` when the page is the last one. */
+    nextCursor: string | null;
+    sourceStats: TimelineSourceStats;
+}
+
+/**
+ * Low-level timeline SDK module. One method: query(opts) → page.
+ *
+ * The cursor is opaque from the SDK's perspective — it's stored as a
+ * string, never decoded, never inspected. Callers pass the value of
+ * `nextCursor` from the previous response verbatim into the next request.
+ *
+ * Errors thrown from query() extend SpacelrError so they integrate with
+ * the SDK's existing error hierarchy. Use one of the typed subclasses
+ * (CursorInvalidError, ForbiddenError, etc.) to catch specific cases or
+ * `catch (e instanceof TimelineError)` for any timeline-related failure.
+ */
+declare class TimelineModule {
+    private readonly http;
+    constructor(http: HttpClient);
+    query(opts: TimelineQueryOptions): Promise<TimelineQueryResponse>;
+    private translateError;
+}
+
 interface PopulateOption {
     field: string;
     collection: string;
@@ -1106,6 +1198,16 @@ declare class CollectionRef<T = Record<string, unknown>> {
     insertMany(documents: (Partial<T> & {
         _id?: string;
     })[]): Promise<InsertResult>;
+    /**
+     * Query the collection's **hot tier** (live MongoDB).
+     *
+     * **Cold-tier note:** if the collection has cold-tier archival enabled, aged
+     * documents are moved to object storage and purged from the hot tier — they
+     * will NOT appear in `find()` results (nor `findById`, `count`, `search`,
+     * `paginate`, which are all hot-tier only). To read archived history, use
+     * {@link TimelineModule.query} via `db.timeline.query(...)`, which transparently
+     * merges hot and cold results for a partition.
+     */
     find(filter?: Record<string, unknown>): QueryBuilder<T>;
     /**
      * Cursor-based scroll-back helper. Returns a `Paginator` whose `.next()`
@@ -1136,13 +1238,30 @@ declare class CollectionRef<T = Record<string, unknown>> {
      *
      * Limits: `query` 1–200 chars, `fields` 1–10 entries (each matching
      * `/^[a-zA-Z0-9_.]+$/`, max 64 chars), `limit` max 100.
+     *
+     * **Cold-tier note:** searches the hot tier only; archived documents are not
+     * included. See {@link CollectionRef.find} and `db.timeline.query(...)`.
      */
     search(opts: SearchOptions): Promise<SearchResult<T>>;
+    /**
+     * Fetch a single document by `_id` from the **hot tier**.
+     *
+     * **Cold-tier note:** returns null/throws for documents that have been
+     * archived and purged from the hot tier. Archived history is reachable only
+     * via `db.timeline.query(...)`. See {@link CollectionRef.find}.
+     */
     findById(id: string, options?: FindByIdOptions): Promise<T & {
         _id: string;
     }>;
     update(id: string, update: Partial<T>): Promise<UpdateResult>;
     delete(id: string): Promise<DeleteResult>;
+    /**
+     * Count documents in the **hot tier** matching `filter`.
+     *
+     * **Cold-tier note:** counts hot-tier documents only — archived/purged
+     * documents are not included, so this is not a total-history count. See
+     * {@link CollectionRef.find} and `db.timeline.query(...)`.
+     */
     count(filter?: Record<string, unknown>): Promise<number>;
     subscribe(handlers: SubscribeHandlers<T>): () => void;
     subscribeEvents(handlers: SubscribeEventsHandlers<T>): StreamSubscription;
@@ -1161,13 +1280,20 @@ declare class DatabaseModule {
     private http;
     private realtime;
     private projectId;
+    readonly timeline: TimelineModule;
     constructor(http: HttpClient, projectId: string, realtime?: RealtimeClient);
     collection<T = Record<string, unknown>>(name: string): CollectionRef<T>;
 }
 
+/**
+ * Push subscription platform. `web` = VAPID WebPush; `android`/`ios` = native
+ * device tokens; `web-fcm` = a web Firebase Cloud Messaging registration token.
+ * Defined locally so `@spacelr/sdk` stays a standalone, dependency-free package.
+ */
+type PushPlatform = 'web' | 'android' | 'ios' | 'web-fcm';
 interface PushSubscriptionInfo {
     id: string;
-    platform: 'web' | 'android' | 'ios';
+    platform: PushPlatform;
     endpoint?: string;
     deviceToken?: string;
     deviceId?: string;
@@ -1198,9 +1324,9 @@ declare class NotificationsModule {
     private detectDeviceName;
     /** Get the VAPID public key for Web Push setup */
     getVapidPublicKey(): Promise<VapidKeyResponse>;
-    /** Register a push subscription (web, android, or ios) */
+    /** Register a push subscription (web, android, ios, or web-fcm) */
     subscribe(subscription: {
-        platform: 'web' | 'android' | 'ios';
+        platform: PushPlatform;
         endpoint?: string;
         keys?: {
             p256dh: string;
@@ -1209,7 +1335,7 @@ declare class NotificationsModule {
         deviceToken?: string;
     }, deviceName?: string): Promise<PushSubscriptionInfo>;
     /** Unregister a push subscription */
-    unsubscribe(platform: 'web' | 'android' | 'ios', identifier: string): Promise<{
+    unsubscribe(platform: PushPlatform, identifier: string): Promise<{
         deleted: boolean;
     }>;
     /** Get all subscriptions for the current user */
@@ -1224,6 +1350,12 @@ declare class NotificationsModule {
      * Helper: Register a mobile device push token (FCM or APNs).
      */
     registerDevicePush(deviceToken: string, platform: 'android' | 'ios', deviceName?: string): Promise<PushSubscriptionInfo>;
+    /**
+     * Registers a web Firebase Cloud Messaging registration token (obtained via
+     * the Firebase JS SDK `getToken()`), so `notifications.send` delivers to this
+     * browser through the project's FCM provider instead of VAPID WebPush.
+     */
+    registerWebFcm(fcmToken: string, deviceName?: string): Promise<PushSubscriptionInfo>;
     private urlBase64ToUint8Array;
 }
 
@@ -1334,6 +1466,55 @@ declare class ScheduleModule {
     private toIsoString;
 }
 
+/**
+ * Base class for all timeline-related errors thrown by the SDK. Extends
+ * SpacelrError so it fits the SDK's existing `catch (e instanceof
+ * SpacelrError)` pattern. Subclasses give callers fine-grained control
+ * (e.g. catch only `CursorInvalidError` and restart pagination).
+ */
+declare class TimelineError extends SpacelrError {
+    constructor(message: string, opts?: {
+        statusCode?: number;
+        code?: string;
+    });
+}
+declare class CursorInvalidError extends TimelineError {
+    constructor(message: string, opts?: {
+        statusCode?: number;
+        code?: string;
+    });
+}
+declare class ValidationError extends TimelineError {
+    constructor(message: string, opts?: {
+        statusCode?: number;
+        code?: string;
+    });
+}
+declare class ForbiddenError extends TimelineError {
+    constructor(message: string, opts?: {
+        statusCode?: number;
+        code?: string;
+    });
+}
+declare class NotFoundError extends TimelineError {
+    constructor(message: string, opts?: {
+        statusCode?: number;
+        code?: string;
+    });
+}
+declare class ServerConfigError extends TimelineError {
+    constructor(message: string, opts?: {
+        statusCode?: number;
+        code?: string;
+    });
+}
+declare class TimeoutError extends TimelineError {
+    constructor(message: string, opts?: {
+        statusCode?: number;
+        code?: string;
+    });
+}
+
 interface SpacelrClient {
     readonly auth: AuthModule;
     readonly storage: StorageModule;
@@ -1392,4 +1573,4 @@ interface SpacelrClient {
 }
 declare function createClient(config: SpacelrClientConfig): SpacelrClient;
 
-export { type ApiResponse, type AuthLostReason, type AuthState, type AuthStateListener, type AuthorizationUrlParams, BrowserTokenStorage, CodeChallengeMethod, type ConnectionState, type CursorStorage, type DatabaseChangeEvent, type DownloadUrlResponse, type ExchangeCodeParams, type FileInfo, type FileListResponse, FileVisibility, type FunctionInvokeOptions, type FunctionInvokeResult, type GapReason, GrantType, type InitMultipartUploadParams, type InitMultipartUploadResponse, type JWK, type JWKSResponse, type ListFilesParams, type LoginParams, type LoginResponse, MemoryTokenStorage, type OpenIDConfiguration, type PKCEChallenge, type PartEtag, type PushSubscriptionInfo, type QuotaInfo, type RegisterParams, type RegisterResponse, type Schedule, type ScheduleInvokeOptions, type ScheduleListOptions, type ScheduleStatus, type SearchOptions, 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 TokenResponse, type TokenStorage, type TwoFactorResponse, type TwoFactorVerifyParams, type UnshareFileParams, type UploadFileParams, type UploadLargeFileParams, type UploadProgress, type UserInfo, type UserProfile, 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 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 };