@spacelr/sdk 0.5.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,
@@ -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);
@@ -2819,9 +2993,13 @@ function createClient(config) {
 0 && (module.exports = {
   BrowserTokenStorage,
   CodeChallengeMethod,
+  CursorInvalidError,
   FileVisibility,
+  ForbiddenError,
   GrantType,
   MemoryTokenStorage,
+  NotFoundError,
+  ServerConfigError,
   SharePermission,
   SpacelrAuthError,
   SpacelrEmailVerificationRequiredError,
@@ -2830,6 +3008,10 @@ function createClient(config) {
   SpacelrSearchFilterRequiredError,
   SpacelrTimeoutError,
   SpacelrTwoFactorRequiredError,
+  TimelineError,
+  TimelineModule,
+  TimeoutError,
+  ValidationError,
   createClient,
   generatePKCEChallenge,
   localStorageCursorStorage,