@spacelr/sdk 0.5.0 → 0.5.1

package/dist/index.mjs

@@ -1784,6 +1784,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) {
@@ -1967,6 +2105,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);
   }
@@ -2001,6 +2149,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({
@@ -2010,6 +2161,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) {
@@ -2039,6 +2197,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",
@@ -2474,6 +2639,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);
@@ -2783,9 +2949,13 @@ function createClient(config) {
 export {
   BrowserTokenStorage,
   CodeChallengeMethod,
+  CursorInvalidError,
   FileVisibility,
+  ForbiddenError,
   GrantType,
   MemoryTokenStorage,
+  NotFoundError,
+  ServerConfigError,
   SharePermission,
   SpacelrAuthError,
   SpacelrEmailVerificationRequiredError,
@@ -2794,6 +2964,10 @@ export {
   SpacelrSearchFilterRequiredError,
   SpacelrTimeoutError,
   SpacelrTwoFactorRequiredError,
+  TimelineError,
+  TimelineModule,
+  TimeoutError,
+  ValidationError,
   createClient,
   generatePKCEChallenge,
   localStorageCursorStorage,