@thatopen/services 0.28.1 → 0.29.0

package/dist/core/documents.d.ts

@@ -93,4 +93,63 @@ export declare class ProjectDocuments {
     addView(folderId: string, view: DocumentView): Promise<void>;
     /** Writes the descriptor, creating or replacing `document.json`. */
     setDescriptor(folderId: string, descriptor: Omit<DocumentDescriptor, 'schema'> & Partial<Pick<DocumentDescriptor, 'schema'>>): Promise<void>;
+    /**
+     * 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: string): DocumentDrafts;
+}
+/** One user's draft of a document, as listed — no download involved. */
+export interface DraftInfo {
+    userId: string;
+    /** When the server stored it: read from the hidden file's own id, not a client clock. */
+    savedAt: Date;
+}
+/** One user's draft, downloaded. */
+export interface Draft<Meta = Record<string, unknown>> extends DraftInfo {
+    blob: Blob;
+    /** Whatever the app put next to the bytes: base version, app, app version… */
+    meta: Meta;
+}
+/**
+ * A document's drafts: one working copy per user, stored as a HIDDEN file under
+ * the document's `document.json`. Hidden files are what make this possible —
+ * a visible file cannot be overwritten without becoming a new version, and a
+ * draft written every few seconds must not fill the history or the CDE.
+ *
+ * Hidden files cannot be edited, so `put` uploads the new draft FIRST and then
+ * deletes that user's previous ones: a failure in between leaves two, and
+ * reads take the newest, never none. Every project member can read every draft;
+ * each app decides whose to offer.
+ */
+export declare class DocumentDrafts {
+    #private;
+    private readonly client;
+    private readonly holder;
+    constructor(client: EngineServicesClient, holder: () => Promise<{
+        id: string;
+    } | undefined>);
+    /** Every user's latest draft, without downloading any. Newest first. */
+    list(): Promise<DraftInfo[]>;
+    /**
+     * One user's draft, downloaded — or, without `userId`, the newest of anyone.
+     * Null when there is none.
+     */
+    get<Meta = Record<string, unknown>>(options?: {
+        userId?: string;
+    }): Promise<Draft<Meta> | null>;
+    /**
+     * 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`).
+     */
+    put(blob: Blob, options: {
+        userId: string;
+        meta?: Record<string, unknown>;
+    }): Promise<DraftInfo>;
+    /** Deletes every draft of this user (on an explicit save, typically). */
+    delete(options: {
+        userId: string;
+    }): Promise<void>;
 }