@spacelr/sdk 0.4.0 → 0.5.1

package/dist/index.js

@@ -22,9 +22,13 @@ var index_exports = {};
 __export(index_exports, {
   BrowserTokenStorage: () => BrowserTokenStorage,
   CodeChallengeMethod: () => CodeChallengeMethod,
+  CursorInvalidError: () => CursorInvalidError,
   FileVisibility: () => FileVisibility,
+  ForbiddenError: () => ForbiddenError,
   GrantType: () => GrantType,
   MemoryTokenStorage: () => MemoryTokenStorage,
+  NotFoundError: () => NotFoundError,
+  ServerConfigError: () => ServerConfigError,
   SharePermission: () => SharePermission,
   SpacelrAuthError: () => SpacelrAuthError,
   SpacelrEmailVerificationRequiredError: () => SpacelrEmailVerificationRequiredError,
@@ -33,6 +37,10 @@ __export(index_exports, {
   SpacelrSearchFilterRequiredError: () => SpacelrSearchFilterRequiredError,
   SpacelrTimeoutError: () => SpacelrTimeoutError,
   SpacelrTwoFactorRequiredError: () => SpacelrTwoFactorRequiredError,
+  TimelineError: () => TimelineError,
+  TimelineModule: () => TimelineModule,
+  TimeoutError: () => TimeoutError,
+  ValidationError: () => ValidationError,
   createClient: () => createClient,
   generatePKCEChallenge: () => generatePKCEChallenge,
   localStorageCursorStorage: () => localStorageCursorStorage,
@@ -860,7 +868,7 @@ var RealtimeClient = class {
     if (!where || Object.keys(where).length === 0) {
       return base;
     }
-    const filterStr = Object.keys(where).sort().map((k) => `${k}=${String(where[k])}`).join("&");
+    const filterStr = Object.keys(where).sort().map((k) => `${k}=${JSON.stringify(where[k])}`).join("&");
     return `${base}?${filterStr}`;
   }
   async ensureConnected() {
@@ -1008,15 +1016,15 @@ var RealtimeClient = class {
     if (room === base) return true;
     if (!room.startsWith(`${base}?`)) return false;
     const where = this.roomWhereMap.get(room);
-    if (!where) return true;
+    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.some((item) => String(item) === String(value))) {
+        if (!docValue.includes(value)) {
           return false;
         }
-      } else if (String(docValue) !== String(value)) {
+      } else if (docValue !== value) {
         return false;
       }
     }
@@ -1819,6 +1827,144 @@ var StorageModule = class {
   }
 };
 
+// libs/sdk/src/modules/timeline.errors.ts
+var TimelineError = class extends SpacelrError {
+  constructor(message, opts = {}) {
+    super(message, opts.code ?? "TIMELINE_ERROR", opts.statusCode);
+    this.name = "TimelineError";
+  }
+};
+var CursorInvalidError = class extends TimelineError {
+  constructor(message, opts = {}) {
+    super(message, { statusCode: opts.statusCode ?? 400, code: opts.code ?? "CURSOR_INVALID" });
+    this.name = "CursorInvalidError";
+  }
+};
+var ValidationError = class extends TimelineError {
+  constructor(message, opts = {}) {
+    super(message, { statusCode: opts.statusCode ?? 400, code: opts.code ?? "BAD_REQUEST" });
+    this.name = "ValidationError";
+  }
+};
+var ForbiddenError = class extends TimelineError {
+  constructor(message, opts = {}) {
+    super(message, { statusCode: opts.statusCode ?? 403, code: opts.code ?? "FORBIDDEN" });
+    this.name = "ForbiddenError";
+  }
+};
+var NotFoundError = class extends TimelineError {
+  constructor(message, opts = {}) {
+    super(message, { statusCode: opts.statusCode ?? 404, code: opts.code ?? "NOT_FOUND" });
+    this.name = "NotFoundError";
+  }
+};
+var ServerConfigError = class extends TimelineError {
+  constructor(message, opts = {}) {
+    super(message, { statusCode: opts.statusCode ?? 500, code: opts.code ?? "CONFIG_INVALID" });
+    this.name = "ServerConfigError";
+  }
+};
+var TimeoutError = class extends TimelineError {
+  constructor(message, opts = {}) {
+    super(message, { statusCode: opts.statusCode ?? 504, code: opts.code ?? "TIMEOUT" });
+    this.name = "TimeoutError";
+  }
+};
+function mapTimelineError(statusCode, body) {
+  const code = body?.code;
+  const message = body?.message ?? `Timeline request failed with HTTP ${statusCode}`;
+  if (statusCode === 400) {
+    if (code === "CURSOR_INVALID") {
+      return new CursorInvalidError(message, { statusCode, code });
+    }
+    return new ValidationError(message, { statusCode, code });
+  }
+  if (statusCode === 403) {
+    return new ForbiddenError(message, { statusCode, code });
+  }
+  if (statusCode === 404) {
+    return new NotFoundError(message, { statusCode, code });
+  }
+  if (statusCode === 500) {
+    return new ServerConfigError(message, { statusCode, code });
+  }
+  if (statusCode === 504) {
+    return new TimeoutError(message, { statusCode, code });
+  }
+  return new TimelineError(message, { statusCode, code });
+}
+
+// libs/sdk/src/modules/timeline.module.ts
+var TimelineModule = class {
+  constructor(http) {
+    this.http = http;
+  }
+  async query(opts) {
+    const body = {
+      collection: opts.collection,
+      partitionValue: opts.partitionValue
+    };
+    if (opts.where !== void 0) body["where"] = opts.where;
+    if (opts.orderBy !== void 0) body["orderBy"] = opts.orderBy;
+    if (opts.limit !== void 0) body["limit"] = opts.limit;
+    if (opts.cursor !== void 0) body["cursor"] = opts.cursor;
+    let raw;
+    try {
+      raw = await this.http.request({
+        method: "POST",
+        path: "/db/timeline",
+        body,
+        authenticated: true
+      });
+    } catch (err) {
+      throw this.translateError(err);
+    }
+    if (!isTimelineQueryResponse(raw)) {
+      throw new TimelineError(
+        "Timeline gateway returned a response shape the SDK does not recognise",
+        { statusCode: 500, code: "INVALID_RESPONSE_SHAPE" }
+      );
+    }
+    return raw;
+  }
+  translateError(err) {
+    if (err instanceof SpacelrTimeoutError) {
+      return new TimeoutError(err.message, { statusCode: 504, code: "TIMEOUT" });
+    }
+    if (err instanceof SpacelrAuthError) {
+      if (err.statusCode === 403) {
+        return new ForbiddenError(err.message, { statusCode: 403, code: err.code ?? "FORBIDDEN" });
+      }
+      return err;
+    }
+    if (err instanceof SpacelrNetworkError) {
+      return err;
+    }
+    if (err instanceof SpacelrError) {
+      return mapTimelineError(err.statusCode ?? 0, { code: err.code, message: err.message });
+    }
+    return err;
+  }
+};
+function isTimelineQueryResponse(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  if (!Array.isArray(v["items"])) return false;
+  if (v["nextCursor"] !== null && typeof v["nextCursor"] !== "string") return false;
+  if (!isTimelineSourceStats(v["sourceStats"])) return false;
+  return true;
+}
+function isTimelineSourceStats(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  if (typeof v["hot"] !== "number") return false;
+  if (typeof v["cold"] !== "number") return false;
+  if (v["segmentsScanned"] !== void 0 && typeof v["segmentsScanned"] !== "number") {
+    return false;
+  }
+  return true;
+}
+
 // libs/sdk/src/modules/database.module.ts
 var Paginator = class {
   constructor(http, basePath, opts) {
@@ -2002,6 +2148,16 @@ var CollectionRef = class {
       authenticated: true
     });
   }
+  /**
+   * 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) {
     return new QueryBuilder(this.http, this.basePath, filter);
   }
@@ -2036,6 +2192,9 @@ var CollectionRef = class {
    *
    * 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(...)`.
    */
   async search(opts) {
     return this.http.request({
@@ -2045,6 +2204,13 @@ var CollectionRef = class {
       authenticated: true
     });
   }
+  /**
+   * 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}.
+   */
   async findById(id, options) {
     const query = {};
     if (options?.populate?.length) {
@@ -2074,6 +2240,13 @@ var CollectionRef = class {
       authenticated: true
     });
   }
+  /**
+   * 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(...)`.
+   */
   async count(filter) {
     const result = await this.http.request({
       method: "POST",
@@ -2509,6 +2682,7 @@ var DatabaseModule = class {
     this.http = http;
     this.projectId = projectId;
     this.realtime = realtime ?? null;
+    this.timeline = new TimelineModule(http);
   }
   collection(name) {
     return new CollectionRef(this.http, this.realtime, this.projectId, name);
@@ -2707,6 +2881,65 @@ var FunctionsModule = class {
   }
 };
 
+// libs/sdk/src/modules/schedule.module.ts
+var ScheduleModule = class {
+  constructor(http, projectId) {
+    this.http = http;
+    this.projectId = projectId;
+  }
+  /**
+   * Schedule a one-shot function invocation. Returns the existing handle
+   * unchanged if `idempotencyKey` matches a prior invoke in this project
+   * for this function.
+   */
+  async invoke(options) {
+    return this.http.request({
+      method: "POST",
+      path: `/schedules/${encodeURIComponent(this.projectId)}`,
+      body: {
+        functionId: options.functionId,
+        executeAt: this.toIsoString(options.executeAt),
+        ...options.payload !== void 0 ? { payload: options.payload } : {},
+        ...options.idempotencyKey !== void 0 ? { idempotencyKey: options.idempotencyKey } : {},
+        ...options.maxAttempts !== void 0 ? { maxAttempts: options.maxAttempts } : {}
+      },
+      authenticated: true
+    });
+  }
+  async get(scheduleId) {
+    return this.http.request({
+      method: "GET",
+      path: `/schedules/${encodeURIComponent(this.projectId)}/${encodeURIComponent(scheduleId)}`,
+      authenticated: true
+    });
+  }
+  async list(options = {}) {
+    return this.http.request({
+      method: "GET",
+      path: `/schedules/${encodeURIComponent(this.projectId)}`,
+      query: {
+        functionId: options.functionId,
+        status: options.status,
+        limit: options.limit,
+        offset: options.offset
+      },
+      authenticated: true
+    });
+  }
+  async cancel(scheduleId) {
+    return this.http.request({
+      method: "DELETE",
+      path: `/schedules/${encodeURIComponent(this.projectId)}/${encodeURIComponent(scheduleId)}`,
+      authenticated: true
+    });
+  }
+  toIsoString(input) {
+    if (input instanceof Date) return input.toISOString();
+    if (typeof input === "number") return new Date(input).toISOString();
+    return input;
+  }
+};
+
 // libs/sdk/src/client.ts
 function createClient(config) {
   const tokenStorage = config.tokenStorage ?? (typeof window !== "undefined" && typeof window.localStorage !== "undefined" ? new BrowserTokenStorage() : new MemoryTokenStorage());
@@ -2725,12 +2958,14 @@ function createClient(config) {
   const db = new DatabaseModule(httpClient, config.projectId, realtime);
   const notifications = new NotificationsModule(httpClient);
   const functions = new FunctionsModule(httpClient);
+  const schedule = new ScheduleModule(httpClient, config.projectId);
   return {
     auth,
     storage,
     db,
     notifications,
     functions,
+    schedule,
     setTokens(tokens) {
       return tokenManager.setTokens(tokens);
     },
@@ -2758,9 +2993,13 @@ function createClient(config) {
 0 && (module.exports = {
   BrowserTokenStorage,
   CodeChallengeMethod,
+  CursorInvalidError,
   FileVisibility,
+  ForbiddenError,
   GrantType,
   MemoryTokenStorage,
+  NotFoundError,
+  ServerConfigError,
   SharePermission,
   SpacelrAuthError,
   SpacelrEmailVerificationRequiredError,
@@ -2769,6 +3008,10 @@ function createClient(config) {
   SpacelrSearchFilterRequiredError,
   SpacelrTimeoutError,
   SpacelrTwoFactorRequiredError,
+  TimelineError,
+  TimelineModule,
+  TimeoutError,
+  ValidationError,
   createClient,
   generatePKCEChallenge,
   localStorageCursorStorage,