@thatopen/services 0.22.0 → 0.24.0

package/dist/core/client.d.ts

@@ -1,3 +1,4 @@
+import { ProjectDocuments } from './documents';
 import { ProjectHistory } from './history';
 import { Recipes } from './recipes';
 import { ExecutionEntity, ExecutionSuscriptionReturnType } from '../types/execution';
@@ -631,6 +632,12 @@ export declare class EngineServicesClient {
      * @param onUpdateCallback - Callback invoked on each progress/result event.
      */
     onExecutionProgress(executionId: string, onUpdateCallback: (data: ExecutionSuscriptionReturnType) => void): Promise<void>;
+    /**
+     * A project's documents. Every document is a FOLDER holding its files plus
+     * a `document.json` descriptor naming the document, its native form and its
+     * renderable views. See `src/core/documents.ts` for the model and schema.
+     */
+    documents(projectId: string): ProjectDocuments;
     /**
      * A project's history of connected documents (Revit models, AutoCAD
      * drawings…): their version timelines and their change requests. See

package/dist/core/documents.d.ts

@@ -0,0 +1,59 @@
+import { EngineServicesClient } from './client';
+
+/** One renderable representation of a document. */
+export interface DocumentView {
+    /** The view file's item id — ids survive renames, names do not. */
+    fileId: string;
+    /** Lowercase format name: 'frag', 'ifc', 'potree', 'pdf'… */
+    format: string;
+}
+/** The wire shape of `document.json`, schema `thatopen/document@1`. */
+export interface DocumentDescriptor {
+    schema: typeof DOCUMENT_SCHEMA;
+    /** The document's own name — what a row shows. Not any file's name. */
+    name: string;
+    /**
+     * The native form, when the document has one (a .rvt, a .3dm). A document
+     * born on the platform (a loose .frag) may not.
+     */
+    native?: {
+        fileId: string;
+        format: string;
+    };
+    /** The renderable representations, in no particular order. */
+    views: DocumentView[];
+}
+export declare const DOCUMENT_SCHEMA = "thatopen/document@1";
+export declare const DOCUMENT_FILE = "document.json";
+/**
+ * Documents of one project. Get it from {@link EngineServicesClient.documents}.
+ * Every method takes the document's FOLDER id — the id interfaces know the
+ * document by.
+ */
+export declare class ProjectDocuments {
+    #private;
+    private readonly client;
+    readonly projectId: string;
+    constructor(client: EngineServicesClient, projectId: string);
+    /**
+     * The document's descriptor, read and validated, or null when the folder
+     * has none yet (an old folder, or a plain folder that is not a document).
+     */
+    descriptor(folderId: string): Promise<DocumentDescriptor | null>;
+    /**
+     * The first view whose format appears in `formats` — searched in the ORDER
+     * OF THE LIST, so the caller's preference wins (ask `['frag', 'ifc']` and a
+     * document carrying both answers the frag). Null when none matches: that is
+     * where an interface offers "Process".
+     */
+    view(folderId: string, formats: string[]): Promise<DocumentView | null>;
+    /**
+     * Registers a renderable representation — a processor's last act. One view
+     * per format: an existing view of the same format is replaced (a re-run
+     * processor updates, it does not accumulate). The descriptor must exist;
+     * create it first with {@link setDescriptor}.
+     */
+    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>;
+}

package/dist/core/history.d.ts

@@ -1,4 +1,5 @@
 import { EngineServicesClient } from './client';
+import { DocumentDescriptor, DocumentView } from './documents';
 
 /** One element mutation inside a version. Wire-compatible with the plugins. */
 export interface FlowChange {
@@ -53,6 +54,13 @@ export interface FlowVersion {
  */
 export interface FlowSuggestion {
     opId: string;
+    /**
+     * The application that receives and executes it: 'revit', 'autocad', or a
+     * platform app like 'designer'. A suggestion without a recipient is not a
+     * suggestion; absent only in entries written before this field existed,
+     * where the recipient is the document's own source.
+     */
+    to?: string;
     /** Groups the suggestions one authored action produced across several docs. */
     batchId?: string;
     /** Hidden-file id of the payload .frag (envelope `revitflow/op@2`). */
@@ -81,6 +89,11 @@ export interface FlowDocInfo {
     source: string;
     /** The document's own id within that application. */
     docId: string;
+    /**
+     * The document folder's item id — the id the CDE and the documents API
+     * ({@link EngineServicesClient.documents}) know this document by.
+     */
+    folderId: string;
     /** The visible model file's name, when one exists yet. */
     modelName?: string;
     /**
@@ -91,6 +104,19 @@ export interface FlowDocInfo {
      */
     empty?: boolean;
 }
+/**
+ * One person's current hold on a document's elements, read from the lock
+ * registry the native plugins arbitrate through. Element keys are the native
+ * application's own ids (Revit UniqueIds). Workset-level ownership lives in
+ * Revit's own binary worksharing files (the ownership mirror) and is not
+ * readable here — what IS here is every element-level claim.
+ */
+export interface FlowOwner {
+    /** The native application's user name, as the plugin claimed with. */
+    owner: string;
+    /** The element keys this person currently holds, arbitration applied. */
+    elements: string[];
+}
 /** What `sync` needs: the change list plus whatever the writer knows. */
 export interface SyncInput {
     author: string;
@@ -114,6 +140,11 @@ export interface SyncInput {
 }
 /** What `suggest` needs. */
 export interface SuggestInput {
+    /**
+     * The application that receives and executes it. Defaults to the document's
+     * own source — the native app that owns the document.
+     */
+    to?: string;
     /**
      * The suggestion's id, when the caller minted it up front — a payload
      * (envelope `revitflow/op@2`) carries the opId INSIDE, so whoever builds
@@ -178,6 +209,33 @@ export declare class FlowDoc {
     delta(version: FlowVersion): Promise<Blob>;
     /** The visible model .frag as last fully exported. */
     model(): Promise<Blob>;
+    /** The document folder's item id — the id the CDE knows this document by. */
+    folderId(): Promise<string>;
+    /**
+     * The document descriptor (`document.json`), or null when the folder does
+     * not carry one yet — an old folder from before descriptors existed.
+     */
+    descriptor(): Promise<DocumentDescriptor | null>;
+    /**
+     * The first view whose format appears in `formats`, searched in the order
+     * of the list (the caller's preference wins). Falls back to the visible
+     * model .frag on a descriptor-less folder, so old documents keep viewing.
+     */
+    view(formats: string[]): Promise<DocumentView | null>;
+    /**
+     * Registers a renderable representation, creating the descriptor when the
+     * folder predates them (named after the model file, or the folder itself).
+     * One view per format: a same-format view is replaced, not accumulated.
+     */
+    addView(view: DocumentView): Promise<void>;
+    /**
+     * Who currently holds which elements, read from the lock registry the
+     * native plugins arbitrate through. Read-only: claiming and releasing stay
+     * with the plugins. Empty when nobody holds anything (or the document has
+     * no lock anchor yet). Arbitration is applied: a key contested by two
+     * claims counts only for the earliest one, matching the plugins' rule.
+     */
+    ownership(): Promise<FlowOwner[]>;
     /**
      * Appends one version: uploads the geometry it carries, then the updated
      * history. Give `expectedLatestGuid` whenever you built on a head you read,

package/dist/core/op-builder.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Authors an interoperability OPERATION — a set of deferred edits for one
+ * document — and hands back the bytes to upload as a suggestion's payload.
+ *
+ * WHY THIS EXISTS AND WHY IT LOOKS LIKE THIS. An operation is carried as a
+ * .frag with no geometry at all: the envelope in `Model.metadata`, and one
+ * geometry-less item per change whose attributes ARE the change. That was
+ * cheap on the C# side, which already had a writer, and it is the reason a
+ * converter had to be a console tool once: nothing in the browser could
+ * produce one. So the format stayed, and this builds it here instead.
+ *
+ * Nothing above this class needs to know any of that. You say add / set /
+ * remove and get bytes for {@link FlowDoc.suggest} or a recipe's result.
+ *
+ * WHAT IT DOES NOT DO. It does not translate. Attributes are written exactly
+ * as given, in the TARGET application's own terms and units, because data
+ * that gets translated on the way in has to be untranslated on the way out
+ * and the day somebody forgets a field nothing complains. Deciding what a
+ * Rhino layer means in Revit is the recipe's job; this only carries the
+ * answer.
+ *
+ * DEPENDENCIES, loaded at build() time and declared as OPTIONAL PEERS:
+ * `@thatopen/fragments` (the .frag schema) and `flatbuffers`. An app that
+ * authors operations has both already; everything else in this package works
+ * without them.
+ */
+/** The schema this writes. An applier that speaks a different one must refuse rather than guess. */
+export declare const OP_SCHEMA = "revitflow/op@2";
+export interface OperationTarget {
+    /** Platform project id. */
+    project: string;
+    /** Document name within the project — the model these edits are for. */
+    document: string;
+    /**
+     * The commit this was authored against. The elements named here existed
+     * then; by the time somebody applies it they may not, and the applier
+     * reports what it could not resolve.
+     */
+    baseCommit: number;
+    /** Who authored it, for the history. */
+    author?: string;
+    /** Platform user id, so the same person is not two names depending on which tool wrote it. */
+    userId?: string;
+    /** Groups the operations one authored action produced across several models. */
+    batchId?: string;
+    title?: string;
+}
+/** Where an added item goes, and how it is turned, in the target's own terms. */
+export interface Placement {
+    /** [x, y, z] in the TARGET model's own units and axes. Not converted here. */
+    position?: [number, number, number];
+    /** Degrees about Z, in the target's convention. */
+    rotationDeg?: number;
+    /**
+     * The id of the object that caused this change, in the AUTHOR's own terms —
+     * a Rhino guid, a row of a spreadsheet, whatever proposed it. Optional, and
+     * only useful to whoever wrote it: pass it when you expect to come back and
+     * find what you created.
+     */
+    source?: string;
+}
+export declare class OperationBuilder {
+    private readonly target;
+    private readonly changes;
+    constructor(target: OperationTarget);
+    /** How many changes are queued. An operation with none is refused by `build`. */
+    get length(): number;
+    get batchId(): string | undefined;
+    get title(): string;
+    get author(): string;
+    get userId(): string | undefined;
+    get baseCommit(): number;
+    /**
+     * Create something. There is no id yet: the attributes describe what it is,
+     * the placement says where it goes, and the operation answers with the id
+     * it got.
+     */
+    add(attrs: Record<string, string>, placement?: Placement): this;
+    /** Write attributes onto an item that already exists, named by the id the target published. */
+    set(item: string, attrs: Record<string, string>, placement?: Placement): this;
+    /** Delete an item. Whatever the target cascades along with it is reported, not guessed at here. */
+    remove(item: string): this;
+    /**
+     * A label for what this operation mostly does. Derived, never read to
+     * decide anything: one operation may add, set and remove at once and still
+     * be atomic, so what each change does is written on the change.
+     */
+    get summary(): 'add' | 'set' | 'remove' | 'mixed';
+    /**
+     * The .frag bytes, zlib-deflated, ready to upload as the operation's
+     * payload.
+     *
+     * `opId` is taken rather than generated so the caller can put the same id
+     * in the queue entry it writes next ({@link Recipes} mints it before the
+     * run); an id this class invented and did not return would have to be dug
+     * back out of the bytes.
+     */
+    build(opId: string): Promise<Uint8Array>;
+    /** Placement rides in the attributes, in the same string form the target published. */
+    private pack;
+    private requireId;
+    /**
+     * The buffer itself.
+     *
+     * Laid out exactly as the C# writer lays it out, because the add-in's
+     * reader is the one that has to accept both: items first and the container
+     * after, ids handed out by one monotonic counter, attributes as
+     * `[name, value, type]` JSON triples, and a Meshes table that exists but is
+     * empty.
+     *
+     * Empty rather than absent: the reader asks for it unconditionally, and a
+     * model that draws nothing is still a model. Nothing here gets a sample —
+     * an item with no triangles must not have one, because a sample's bounding
+     * box would then have no size and the reader turns a box into a "dimension"
+     * and rejects a falsy one.
+     */
+    private flatbuffer;
+}