@thatopen/services 0.28.2 → 0.29.1

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;
@@ -33556,6 +33678,9 @@ function projectIdFrom(input) {
   if (/^[0-9a-f]{24}$/i.test(trimmed)) return trimmed;
   return trimmed.match(/projects?\/([0-9a-f]{24})/i)?.[1] ?? null;
 }
+function appIdFrom(input) {
+  return input.trim().match(/apps\/([0-9a-f]{24})/i)?.[1];
+}
 class ChannelConnection {
   constructor(credentials) {
     this.credentials = credentials;
@@ -33716,12 +33841,12 @@ async function startMcpServer() {
   );
   server.tool(
     "send-app-command",
-    "Sends a command to a running That Open app through the platform channel and returns its reply. The app must be open in a browser tab and listening (apps scaffolded by `thatopen create` handle `ping` and `get-loaded-models` out of the box; apps declare their own commands in src/setups/channel.ts). While the user iterates with `thatopen serve`, omit app_id — the dev channel is keyed to the account; pass it once the app is published. `delivered: 0` means no tab of the app has the channel joined, usually because the app is simply not open — ask the user to open or reload the app tab.",
+    "Sends a command to a running That Open app through the platform channel and returns its reply. To USE an app the person has open (rather than build one), pass the URL of their app tab as `project` and send `help` first: the app answers with its own commands and how to use them, and that is the manual to follow. The app must be open in a browser tab and listening (apps scaffolded by `thatopen create` handle `ping` and `get-loaded-models` out of the box; apps declare their own commands in src/setups/channel.ts). While the user iterates with `thatopen serve`, omit app_id — the dev channel is keyed to the account; pass it once the app is published. `delivered: 0` means no tab of the app has the channel joined, usually because the app is simply not open — ask the user to open or reload the app tab.",
     {
-      project: stringType().describe("The project id (24 hex characters), or the project's dashboard URL."),
+      project: stringType().describe("The project id (24 hex characters), or the dashboard URL of the app tab: a URL with `/apps/<id>` gives the app_id too."),
       command: stringType().describe('The command name the app handles, e.g. "ping" or "get-loaded-models".'),
       payload: unknownType().optional().describe("JSON payload for the command, if it takes one."),
-      app_id: stringType().regex(/^[0-9a-f]{24}$/i).optional().describe("The published app's id. Omit while the app runs under `thatopen serve`."),
+      app_id: stringType().regex(/^[0-9a-f]{24}$/i).optional().describe("The published app's id. Omit while the app runs under `thatopen serve`, or when `project` is a URL that carries it."),
       wait_for_reply: booleanType().optional().describe("Default true. Set false for fire-and-forget notifications."),
       timeout_ms: numberType().int().min(1e3).max(MAX_REPLY_TIMEOUT_MS).optional().describe(`How long to wait for the app's reply. Default ${DEFAULT_REPLY_TIMEOUT_MS}.`)
     },
@@ -33734,7 +33859,7 @@ async function startMcpServer() {
       }
       const result = await connect2().send({
         projectId,
-        appId: args.app_id,
+        appId: args.app_id ?? appIdFrom(args.project),
         type: args.command,
         payload: args.payload,
         waitForReply: args.wait_for_reply !== false,