@thatopen/services 0.26.1 → 0.27.0

package/dist/core/history.d.ts

@@ -117,6 +117,37 @@ export interface FlowOwner {
     /** The element keys this person currently holds, arbitration applied. */
     elements: string[];
 }
+/**
+ * The ordered recipe {@link FlowDoc.modelParts} answers: a baseline plus the
+ * steps that bring it to the asked version. See that method for the
+ * composition rule.
+ */
+export interface FlowModelParts {
+    baseline: {
+        /** The visible model file. */
+        fileId: string;
+        /** The version whose full export it is. */
+        guid: string;
+        /**
+         * True when the visible file's CURRENT content is this baseline. False
+         * when a later publish rewrote it — then download the file at
+         * `storageVersion` (when recorded) instead of its head.
+         */
+        current: boolean;
+        /** The CDE storage version the baseline landed in, when the history recorded it. */
+        storageVersion?: number;
+    };
+    /** One per version after the baseline, oldest first. */
+    steps: {
+        guid: string;
+        /** Hidden-file id of the delta .frag; absent on geometry-less versions. */
+        deltaId?: string;
+        /** Elements this version removed, by the native app's own stable ids. */
+        removedUniqueIds: string[];
+    }[];
+    /** The version the recipe reaches (the asked one, or the head). */
+    at: string;
+}
 /** What `sync` needs: the change list plus whatever the writer knows. */
 export interface SyncInput {
     author: string;
@@ -207,8 +238,37 @@ export declare class FlowDoc {
      * no delta: their geometry IS the model file — use {@link model}.
      */
     delta(version: FlowVersion): Promise<Blob>;
-    /** The visible model .frag as last fully exported. */
+    /**
+     * The visible model .frag AS LAST FULLY EXPORTED — the first commit, or the
+     * last explicit publish. Ordinary syncs only add hidden deltas, so this is
+     * NOT necessarily the head: anything computed on it (a clash run) is as of
+     * the last `full: true` version. For the model at a specific version, read
+     * {@link modelParts} and compose.
+     */
     model(): Promise<Blob>;
+    /**
+     * The ordered recipe for the model AT a version: the baseline full export
+     * at-or-before it, then one step per later version up to it — each step's
+     * delta .frag (absent on geometry-less versions) and the element uniqueIds
+     * it removed. The consumer composes with its geometry engine: load the
+     * baseline, then per step replace elements by uniqueId from the delta and
+     * drop the removed. Composing is NOT done here: writing a merged .frag
+     * takes the fragments engine, which this package deliberately does not
+     * carry.
+     *
+     * UniqueIds are the native application's own stable element ids (a Revit
+     * UniqueId survives syncs, machines and full exports), which is what makes
+     * replace-by-uniqueId the whole composition rule.
+     *
+     * When the baseline is NEWER than the asked version (somebody published
+     * after it), the visible file no longer shows that moment: `baseline`
+     * then carries the older version's `storageVersion` when the history
+     * recorded one, so the consumer can download that stored file version
+     * instead of the current one.
+     */
+    modelParts(options?: {
+        at?: string;
+    }): Promise<FlowModelParts>;
     /** The document folder's item id — the id the CDE knows this document by. */
     folderId(): Promise<string>;
     /**
@@ -228,6 +288,15 @@ export declare class FlowDoc {
      * One view per format: a same-format view is replaced, not accumulated.
      */
     addView(view: DocumentView): Promise<void>;
+    /**
+     * Makes sure the folder carries a descriptor, WRITING one when it predates
+     * them: the visible model .frag becomes the 'frag' view. The explicit form
+     * of what {@link addView} does implicitly — reads like `descriptor()` never
+     * write, so migrating an old folder is this deliberate call. Returns the
+     * descriptor either way, or null when there is nothing to describe yet (no
+     * model file).
+     */
+    ensureDescriptor(): Promise<DocumentDescriptor | null>;
     /**
      * Who currently holds which elements, read from the lock registry the
      * native plugins arbitrate through. Read-only: claiming and releasing stay