@thatopen/services 0.21.0 → 0.23.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,8 +89,33 @@ 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;
+    /**
+     * True when the folder exists but holds neither history, model nor
+     * suggestion queue — a document somebody connected and never synced (a
+     * plugin mid-first-publish, or an abandoned start). A legitimate state,
+     * listed rather than hidden; apps decide whether to show it dimmed.
+     */
+    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 {
@@ -107,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
@@ -171,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/recipes.d.ts

@@ -17,6 +17,15 @@ export interface ExistingLookup {
     of: string;
     /** Where it exists: the target document, or the declared source. Default 'target'. */
     from?: 'target' | 'source';
+    /**
+     * Narrows the candidates: attribute equals value, against the attribute
+     * names EXACTLY as the native application publishes them, no case
+     * normalization. Prefer the stable machine fields over display names —
+     * Revit's `Category` text is localized per install ("Armazón estructural"),
+     * so a column filter is `{ CategoryId: '-2001330' }`, never
+     * `{ Category: 'Columns' }`.
+     */
+    where?: Record<string, string>;
 }
 /** What a recipe declares about itself. Shown in catalogs, checked by apps. */
 export interface RecipeManifest {
@@ -104,6 +113,22 @@ export interface RecipeRunOutcome {
     suggestion: FlowSuggestion;
     result: RecipeResult;
 }
+/**
+ * What {@link Recipes.plan} returns: everything needed to queue EXACTLY what
+ * was planned, without running the recipe again — the payload already embeds
+ * this `opId`. Hand it to {@link Recipes.queue} when the person confirms.
+ */
+export interface RecipePlan {
+    opId: string;
+    projectId: string;
+    target: {
+        source: string;
+        docId: string;
+    };
+    /** The head the plan was built against, for the suggestion's base. */
+    baseCommitGuid?: string;
+    result: RecipeResult;
+}
 /**
  * The local recipe registry and runner. Reach it as `client.recipes`.
  */
@@ -121,12 +146,21 @@ export declare class Recipes {
     /** A registered recipe by name, or undefined. */
     get(name: string): RecipeManifest | undefined;
     /**
-     * Runs a recipe WITHOUT queueing anything: the dry pass. Returns the
-     * recipe's result — title, tallies per rule, targets — so an app can show
-     * what would be proposed before anybody confirms. The payload it may have
-     * built is discarded along with its opId.
+     * Runs a recipe WITHOUT queueing anything: the dry pass. Returns a
+     * {@link RecipePlan} — the result to show (title, tallies, targets) plus
+     * everything {@link queue} needs to queue EXACTLY this, payload and opId
+     * included, with no second run. Discard it and the plan never happened.
+     */
+    plan<S>(name: string, options: RecipeRunOptions<S>): Promise<RecipePlan>;
+    /**
+     * Queues exactly what {@link plan} planned: same opId, same payload, no
+     * second execution. The pair plan → confirm → queue is the UI flow; `run`
+     * is the one-shot shortcut.
      */
-    plan<S>(name: string, options: RecipeRunOptions<S>): Promise<RecipeResult>;
+    queue(plan: RecipePlan, options: {
+        author: string;
+        userId?: string;
+    }): Promise<RecipeRunOutcome>;
     /**
      * Runs a recipe and queues its suggestion on the target document. Safe to
      * call freely: nothing touches the native application until its owner