@spacelr/sdk 0.4.0 → 0.5.1

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,6 +1280,7 @@ 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>;
 }
@@ -1269,12 +1389,127 @@ declare class FunctionsModule {
     invoke(projectId: string, functionId: string, options?: FunctionInvokeOptions): Promise<FunctionInvokeResult>;
 }
 
+type ScheduleStatus = 'scheduled' | 'fired' | 'failed' | 'cancelled';
+interface Schedule {
+    id: string;
+    projectId: string;
+    functionId: string;
+    payload: Record<string, unknown>;
+    executeAt: string;
+    idempotencyKey: string | null;
+    status: ScheduleStatus;
+    bullJobId: string | null;
+    firedAt: string | null;
+    executionId: string | null;
+    attemptNumber: number;
+    maxAttempts: number;
+    lastError: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface ScheduleInvokeOptions {
+    /** 24-char hex function id to invoke when the schedule fires. */
+    functionId: string;
+    /** Arbitrary JSON payload surfaced to the function as `event.payload`. */
+    payload?: Record<string, unknown>;
+    /**
+     * When to fire. Accepts a `Date`, an ISO-8601 string, or epoch ms.
+     * Server-side applies a 5-second past-skew tolerance and rejects anything
+     * beyond `SCHEDULE_MAX_DELAY_DAYS` (default 90 days).
+     */
+    executeAt: Date | string | number;
+    /**
+     * Dedup key. Repeating the call with the same key in the same project for
+     * the same function returns the existing schedule unchanged.
+     */
+    idempotencyKey?: string;
+    /**
+     * Maximum retry attempts after a failed execution (0–10, default 3).
+     * Counts only retries — the initial fire is always attempted.
+     */
+    maxAttempts?: number;
+}
+interface ScheduleListOptions {
+    functionId?: string;
+    status?: ScheduleStatus;
+    limit?: number;
+    offset?: number;
+}
+declare class ScheduleModule {
+    private readonly http;
+    private readonly projectId;
+    constructor(http: HttpClient, projectId: string);
+    /**
+     * Schedule a one-shot function invocation. Returns the existing handle
+     * unchanged if `idempotencyKey` matches a prior invoke in this project
+     * for this function.
+     */
+    invoke(options: ScheduleInvokeOptions): Promise<Schedule>;
+    get(scheduleId: string): Promise<Schedule>;
+    list(options?: ScheduleListOptions): Promise<{
+        items: Schedule[];
+        total: number;
+    }>;
+    cancel(scheduleId: string): Promise<Schedule>;
+    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;
     readonly db: DatabaseModule;
     readonly notifications: NotificationsModule;
     readonly functions: FunctionsModule;
+    readonly schedule: ScheduleModule;
     /**
      * Store auth tokens externally (e.g. obtained via the auth-components
      * library that bypasses the SDK). Makes the tokens available to HTTP +
@@ -1326,4 +1561,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 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,6 +1280,7 @@ 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>;
 }
@@ -1269,12 +1389,127 @@ declare class FunctionsModule {
     invoke(projectId: string, functionId: string, options?: FunctionInvokeOptions): Promise<FunctionInvokeResult>;
 }
 
+type ScheduleStatus = 'scheduled' | 'fired' | 'failed' | 'cancelled';
+interface Schedule {
+    id: string;
+    projectId: string;
+    functionId: string;
+    payload: Record<string, unknown>;
+    executeAt: string;
+    idempotencyKey: string | null;
+    status: ScheduleStatus;
+    bullJobId: string | null;
+    firedAt: string | null;
+    executionId: string | null;
+    attemptNumber: number;
+    maxAttempts: number;
+    lastError: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface ScheduleInvokeOptions {
+    /** 24-char hex function id to invoke when the schedule fires. */
+    functionId: string;
+    /** Arbitrary JSON payload surfaced to the function as `event.payload`. */
+    payload?: Record<string, unknown>;
+    /**
+     * When to fire. Accepts a `Date`, an ISO-8601 string, or epoch ms.
+     * Server-side applies a 5-second past-skew tolerance and rejects anything
+     * beyond `SCHEDULE_MAX_DELAY_DAYS` (default 90 days).
+     */
+    executeAt: Date | string | number;
+    /**
+     * Dedup key. Repeating the call with the same key in the same project for
+     * the same function returns the existing schedule unchanged.
+     */
+    idempotencyKey?: string;
+    /**
+     * Maximum retry attempts after a failed execution (0–10, default 3).
+     * Counts only retries — the initial fire is always attempted.
+     */
+    maxAttempts?: number;
+}
+interface ScheduleListOptions {
+    functionId?: string;
+    status?: ScheduleStatus;
+    limit?: number;
+    offset?: number;
+}
+declare class ScheduleModule {
+    private readonly http;
+    private readonly projectId;
+    constructor(http: HttpClient, projectId: string);
+    /**
+     * Schedule a one-shot function invocation. Returns the existing handle
+     * unchanged if `idempotencyKey` matches a prior invoke in this project
+     * for this function.
+     */
+    invoke(options: ScheduleInvokeOptions): Promise<Schedule>;
+    get(scheduleId: string): Promise<Schedule>;
+    list(options?: ScheduleListOptions): Promise<{
+        items: Schedule[];
+        total: number;
+    }>;
+    cancel(scheduleId: string): Promise<Schedule>;
+    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;
     readonly db: DatabaseModule;
     readonly notifications: NotificationsModule;
     readonly functions: FunctionsModule;
+    readonly schedule: ScheduleModule;
     /**
      * Store auth tokens externally (e.g. obtained via the auth-components
      * library that bypasses the SDK). Makes the tokens available to HTTP +
@@ -1326,4 +1561,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 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 };