@thatopen/services 0.28.2 → 0.29.0

package/dist/cli.js

@@ -6960,6 +6960,14 @@ class ProjectDocuments {
       projectId: this.projectId
     });
   }
+  /**
+   * The document's DRAFTS: each user's working copy, kept so that closing the
+   * browser never loses work. A draft is not a version — it never enters the
+   * history and never shows in the CDE. See {@link DocumentDrafts}.
+   */
+  drafts(folderId) {
+    return new DocumentDrafts(this.client, () => this.#descriptorFile(folderId));
+  }
   /**
    * The legacy `derivedFileId` link, read from the newest version metadata
    * that carries one. Only `fromFile` looks at it, to migrate the link into
@@ -6990,6 +6998,120 @@ class ProjectDocuments {
     return found ? { id: idOf$1(found) } : void 0;
   }
 }
+const DRAFT_TAG = "draft:";
+const DRAFT_MAGIC = "TODRAFT1";
+class DocumentDrafts {
+  constructor(client, holder) {
+    this.client = client;
+    this.holder = holder;
+  }
+  /** Every user's latest draft, without downloading any. Newest first. */
+  async list() {
+    const holder = await this.holder();
+    if (!holder) return [];
+    const latest = /* @__PURE__ */ new Map();
+    for (const entry of await this.#entries(holder.id)) {
+      const known = latest.get(entry.userId);
+      if (!known || entry.savedAt > known.savedAt)
+        latest.set(entry.userId, { userId: entry.userId, savedAt: entry.savedAt });
+    }
+    return [...latest.values()].sort((a, b) => +b.savedAt - +a.savedAt);
+  }
+  /**
+   * One user's draft, downloaded — or, without `userId`, the newest of anyone.
+   * Null when there is none.
+   */
+  async get(options) {
+    const holder = await this.holder();
+    if (!holder) return null;
+    const entries = (await this.#entries(holder.id)).filter((e) => !options?.userId || e.userId === options.userId).sort((a, b) => +b.savedAt - +a.savedAt);
+    const newest = entries[0];
+    if (!newest) return null;
+    const response = await this.client.downloadHiddenFile(newest.hiddenId);
+    const { meta, blob } = await unwrapDraft(await response.blob());
+    return { userId: newest.userId, savedAt: newest.savedAt, meta, blob };
+  }
+  /**
+   * Stores this user's draft, replacing their previous one: only the latest is
+   * kept. Needs the document to have a descriptor (convert loose files first
+   * with `fromFile`).
+   */
+  async put(blob, options) {
+    const holder = await this.holder();
+    if (!holder) {
+      throw new Error("This folder is not a document (no document.json): drafts need one.");
+    }
+    const tag = draftTag(options.userId);
+    const previous = (await this.#entries(holder.id)).filter((e) => e.userId === options.userId);
+    const created = await this.client.createHiddenFile(
+      await wrapDraft(blob, options.meta ?? {}),
+      holder.id,
+      tag
+    );
+    const hiddenId = created.hiddenFileId;
+    if (!hiddenId) throw new Error("The draft upload answered without a hiddenFileId.");
+    await this.#deleteAll(previous.map((e) => e.hiddenId));
+    return { userId: options.userId, savedAt: savedAtOf(hiddenId) };
+  }
+  /** Deletes every draft of this user (on an explicit save, typically). */
+  async delete(options) {
+    const holder = await this.holder();
+    if (!holder) return;
+    const mine = (await this.#entries(holder.id)).filter((e) => e.userId === options.userId);
+    await this.#deleteAll(mine.map((e) => e.hiddenId));
+  }
+  async #entries(holderId) {
+    const hidden = await this.client.getHiddenFilesByParent(holderId);
+    return hidden.filter((h) => typeof h.tag === "string" && h.tag.startsWith(DRAFT_TAG)).map((h) => {
+      const hiddenId = String(h._id);
+      return {
+        hiddenId,
+        userId: h.tag.slice(DRAFT_TAG.length),
+        savedAt: savedAtOf(hiddenId)
+      };
+    });
+  }
+  async #deleteAll(hiddenIds) {
+    for (const id2 of hiddenIds) {
+      try {
+        await this.client.deleteHiddenFile(id2);
+      } catch {
+      }
+    }
+  }
+}
+function draftTag(userId) {
+  const tag = `${DRAFT_TAG}${userId}`;
+  if (!/^[A-Za-z0-9][A-Za-z0-9:._-]{0,49}$/.test(tag)) {
+    throw new Error(`A draft cannot be tagged for user "${userId}": ids must be letters, digits or :._- and short.`);
+  }
+  return tag;
+}
+function savedAtOf(objectId) {
+  const seconds = parseInt(objectId.slice(0, 8), 16);
+  return new Date(Number.isFinite(seconds) ? seconds * 1e3 : 0);
+}
+async function wrapDraft(blob, meta) {
+  const metaBytes = new TextEncoder().encode(JSON.stringify(meta));
+  const length = new Uint8Array(4);
+  new DataView(length.buffer).setUint32(0, metaBytes.length, true);
+  return new Blob([new TextEncoder().encode(DRAFT_MAGIC), length, metaBytes, blob]);
+}
+async function unwrapDraft(blob) {
+  const head = new Uint8Array(await blob.slice(0, DRAFT_MAGIC.length + 4).arrayBuffer());
+  if (new TextDecoder().decode(head.slice(0, DRAFT_MAGIC.length)) !== DRAFT_MAGIC) {
+    return { meta: {}, blob };
+  }
+  const length = new DataView(head.buffer).getUint32(DRAFT_MAGIC.length, true);
+  const start = DRAFT_MAGIC.length + 4;
+  const metaText = await blob.slice(start, start + length).text();
+  let meta = {};
+  try {
+    meta = JSON.parse(metaText);
+  } catch {
+  }
+  return { meta, blob: blob.slice(start + length) };
+}
 function formatOf(fileName, extension) {
   const fromExt = (extension ?? "").replace(/^\./, "").toLowerCase();
   if (fromExt) return fromExt;