@thatopen/services 0.19.0 → 0.21.0

package/dist/core/client.d.ts

@@ -1,3 +1,5 @@
+import { ProjectHistory } from './history';
+import { Recipes } from './recipes';
 import { ExecutionEntity, ExecutionSuscriptionReturnType } from '../types/execution';
 import { AppVersionProps, ComponentVersionProps, ComponentItem, AppItem, Item, ItemFolder, ItemVersion, ItemWithVersions } from '../types/items';
 import { CreateItemResponse, UpdateItemResponse } from '../types/response';
@@ -629,6 +631,18 @@ 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 history of connected documents (Revit models, AutoCAD
+     * drawings…): their version timelines and their change requests. See
+     * `src/core/history.ts` — this surface is the only supported way to read
+     * or write it; the storage underneath is private and will move.
+     */
+    history(projectId: string): ProjectHistory;
+    /**
+     * The recipe registry and runner: scripts that write change requests in a
+     * native application's language. See `src/core/recipes.ts`.
+     */
+    get recipes(): Recipes;
     /**
      * Creates a hidden file attached to a parent item (e.g., dependencies, assets).
      * @param file - The file to upload.

package/dist/core/examples/history.d.ts

@@ -0,0 +1,4 @@
+import { EngineServicesClient } from '../client';
+
+export declare function readTheProjectHistory(client: EngineServicesClient, projectId: string): Promise<void>;
+export declare function runARecipe(client: EngineServicesClient, projectId: string): Promise<void>;

package/dist/core/history.d.ts

@@ -0,0 +1,212 @@
+import { EngineServicesClient } from './client';
+
+/** One element mutation inside a version. Wire-compatible with the plugins. */
+export interface FlowChange {
+    /** create | update | delete. */
+    type: 'create' | 'update' | 'delete' | string;
+    /** The native application's own id for the element (Revit UniqueId, AutoCAD handle). */
+    uniqueId: string;
+}
+/** Per-version change tallies. */
+export interface FlowCounts {
+    added: number;
+    modified: number;
+    removed: number;
+}
+/**
+ * One sync of a document. Field names are the wire format the plugins write
+ * (`revitflow_history.json`); do not rename them.
+ */
+export interface FlowVersion {
+    /** Identity, minted by the writer. */
+    guid: string;
+    /** The versions this one was built on; absent on a root. First entry is the continued line. */
+    parents?: string[] | null;
+    /** The CDE's storage version number, when there is one. Data, never identity. */
+    version?: number;
+    /** What the author said it was for, when they said anything. */
+    message?: string;
+    author: string;
+    /** Which application wrote it: 'revit', 'autocad', 'rhino'… */
+    source: string;
+    /** ISO UTC. */
+    timestamp: string;
+    changes: FlowChange[];
+    counts: FlowCounts;
+    /** Hidden-file id of the delta .frag; absent on the baseline and geometry-less versions. */
+    deltaId?: string;
+    /** Hidden-file id of the per-element geometry fingerprints, when the writer keeps them. */
+    geomId?: string;
+    /** Platform user id of the committer, when the writer knew it. */
+    userId?: string;
+    /** This version re-exported the whole model (the visible .frag shows it as of here). */
+    full?: boolean;
+    compact?: boolean;
+    /** Suggestions this version applied (their opIds). */
+    appliedOps?: string[];
+    /** Position in the timeline, derived from the parent graph when read. Never stored. */
+    ordinal?: number;
+}
+/**
+ * A change request queued for a document. Wire-compatible with
+ * `revitflow_ops.json` (schema `revitflow/ops@1`).
+ */
+export interface FlowSuggestion {
+    opId: string;
+    /** Groups the suggestions one authored action produced across several docs. */
+    batchId?: string;
+    /** Hidden-file id of the payload .frag (envelope `revitflow/op@2`). */
+    fragId?: string;
+    title?: string;
+    /** add | set | remove | mixed. */
+    verb?: string;
+    author?: string;
+    userId?: string;
+    createdAt?: string;
+    /** The version this was authored against, by guid. */
+    baseCommitGuid?: string;
+    /** The storage version that version landed in, when known. Data only. */
+    baseCommit?: number;
+    /** How many elements it targets. */
+    targets?: number;
+    state?: 'pending' | 'applied' | 'discarded' | string;
+    /** The native version that materialised it, once applied (storage version number). */
+    appliedInCommit?: number | null;
+    /** Native ids it touched or created, written by the plugin when it applied. */
+    affectedIds?: string[];
+}
+/** A connected document, as listed from the project. */
+export interface FlowDocInfo {
+    /** The native application that owns it: 'revit', 'autocad'… */
+    source: string;
+    /** The document's own id within that application. */
+    docId: string;
+    /** The visible model file's name, when one exists yet. */
+    modelName?: string;
+}
+/** What `sync` needs: the change list plus whatever the writer knows. */
+export interface SyncInput {
+    author: string;
+    /** Which application/tool is writing: 'revit', 'rhino', 'recipe'… */
+    source: string;
+    changes: FlowChange[];
+    message?: string;
+    /** Delta geometry for this version, uploaded as a hidden file. */
+    delta?: Blob;
+    /** Re-upload of the whole model; marks the version `full`. */
+    model?: Blob;
+    /** Platform user id, when known. */
+    userId?: string;
+    /** Suggestions this version applied. */
+    appliedOps?: string[];
+    /**
+     * The head you built on. When given and the stored head differs, `sync`
+     * refuses with {@link StaleHistoryError} instead of forking silently.
+     */
+    expectedLatestGuid?: string;
+}
+/** What `suggest` needs. */
+export interface SuggestInput {
+    /**
+     * The suggestion's id, when the caller minted it up front — a payload
+     * (envelope `revitflow/op@2`) carries the opId INSIDE, so whoever builds
+     * one needs the id before this call. Minted here when absent.
+     */
+    opId?: string;
+    title: string;
+    /** add | set | remove | mixed. */
+    verb: string;
+    author: string;
+    /** The suggestion's .frag payload (envelope `revitflow/op@2`), when it has one. */
+    payload?: Blob;
+    targets?: number;
+    batchId?: string;
+    userId?: string;
+    /** The version it was authored against. */
+    baseCommitGuid?: string;
+}
+/** The head moved while a writer prepared its version. Re-read and retry. */
+export declare class StaleHistoryError extends Error {
+    readonly expectedGuid: string;
+    readonly actualGuid: string | undefined;
+    constructor(expectedGuid: string, actualGuid: string | undefined);
+}
+/**
+ * The history of one project. Get it from {@link EngineServicesClient.history}.
+ */
+export declare class ProjectHistory {
+    #private;
+    private readonly client;
+    readonly projectId: string;
+    constructor(client: EngineServicesClient, projectId: string);
+    /** The project's connected documents. */
+    docs(): Promise<FlowDocInfo[]>;
+    /** One document's history. `source` and `docId` as {@link docs} lists them. */
+    doc(source: string, docId: string): FlowDoc;
+    /** @internal The `bimterop` folder id, resolved once. */
+    rootFolderId(create?: boolean): Promise<string | undefined>;
+}
+/**
+ * One connected document: its timeline, its model, and its suggestions.
+ */
+export declare class FlowDoc {
+    #private;
+    private readonly client;
+    private readonly project;
+    readonly source: string;
+    readonly docId: string;
+    constructor(client: EngineServicesClient, project: ProjectHistory, source: string, docId: string);
+    /**
+     * The document's versions, oldest first, ordered by the parent graph (not
+     * by array position, which concurrent writers do not keep meaningful).
+     * Each version gets its `ordinal` filled in.
+     */
+    timeline(): Promise<FlowVersion[]>;
+    /** The head of the timeline, or null before the first sync. */
+    latest(): Promise<FlowVersion | null>;
+    /**
+     * A version's delta geometry as a .frag. The baseline (`full`) versions have
+     * no delta: their geometry IS the model file — use {@link model}.
+     */
+    delta(version: FlowVersion): Promise<Blob>;
+    /** The visible model .frag as last fully exported. */
+    model(): Promise<Blob>;
+    /**
+     * Appends one version: uploads the geometry it carries, then the updated
+     * history. Give `expectedLatestGuid` whenever you built on a head you read,
+     * so a concurrent writer surfaces as {@link StaleHistoryError} instead of a
+     * silent fork.
+     */
+    sync(input: SyncInput): Promise<FlowVersion>;
+    /** Every suggestion in the document's queue, pending or resolved. */
+    suggestions(): Promise<FlowSuggestion[]>;
+    /** The suggestions still waiting for the owner, oldest first. */
+    pendingSuggestions(): Promise<FlowSuggestion[]>;
+    /**
+     * Queues a change request for this document. The payload, when given, is
+     * uploaded as a hidden file under the suggestions index.
+     */
+    suggest(input: SuggestInput): Promise<FlowSuggestion>;
+    /** A suggestion's .frag payload. */
+    suggestionPayload(suggestion: FlowSuggestion): Promise<Blob>;
+    /**
+     * Marks a suggestion applied (naming the version that materialised it) or
+     * discarded. The native plugins do this themselves when they apply; apps
+     * use it for `discarded`.
+     */
+    resolveSuggestion(opId: string, outcome: {
+        state: 'applied';
+        appliedInCommit?: number;
+        affectedIds?: string[];
+    } | {
+        state: 'discarded';
+    }): Promise<FlowSuggestion>;
+}
+/**
+ * Orders versions by walking the parent graph from the root along first
+ * parents, breaking forks by timestamp — array position is not meaningful
+ * once more than one application writes. Fills `ordinal`.
+ */
+export declare function orderByGraph(versions: FlowVersion[]): FlowVersion[];
+/** A random v4 guid, for version guids and suggestion opIds. */
+export declare function mintGuid(): string;

package/dist/core/recipes.d.ts

@@ -0,0 +1,150 @@
+import { EngineServicesClient } from './client';
+import { FlowDoc, FlowSuggestion } from './history';
+
+/**
+ * How a settings property says "this names something that EXISTS". Put it on
+ * the property as `x-existing` inside {@link RecipeManifest.settingsSchema}:
+ * the app resolves the candidates and renders a list — people pick, they
+ * never type the name of a thing that exists.
+ *
+ * Resolving the candidates is the APP's job today (reading `doc.model()` of
+ * the target, or the declared source file, takes the fragments toolkit, which
+ * the SDK does not carry). The kinds are stable so nothing changes for
+ * recipes when a shared reader lands in that toolkit.
+ */
+export interface ExistingLookup {
+    /** What kind of existing thing: 'document' | 'family-type' | 'level' | 'layer' | 'workset'… */
+    of: string;
+    /** Where it exists: the target document, or the declared source. Default 'target'. */
+    from?: 'target' | 'source';
+}
+/** What a recipe declares about itself. Shown in catalogs, checked by apps. */
+export interface RecipeManifest {
+    /** Machine name, unique in a catalog: 'rhino-points-to-revit-columns'. */
+    name: string;
+    /** The human name a card shows: 'Rhino points to Revit columns'. */
+    title?: string;
+    /** The one sentence a non-programmer reads: what it converts into what. */
+    description: string;
+    /** The long-form explanation an app renders, as markdown. */
+    doc?: string;
+    /** The native application whose language it writes: 'revit', 'autocad'… */
+    to: string;
+    /** The input kinds it understands: 'rhino-model', 'platform-elements', 'points', 'csv'… */
+    inputs: string[];
+    /**
+     * What the app should offer as the input picker, when the input is a thing
+     * of the project rather than inline data: another connected document, or a
+     * project file (then `extensions` narrows the listing). The picked value is
+     * what arrives as `input`, and what `x-existing: { from: 'source' }`
+     * lookups read.
+     */
+    source?: {
+        kind: 'document';
+        source?: string;
+    } | {
+        kind: 'project-file';
+        extensions?: string[];
+    };
+    /** Where it runs by default. Browser unless it must run unattended. */
+    runtime?: 'browser' | 'cloud';
+    /**
+     * JSON Schema for `settings`. Apps generate the settings form from it, so
+     * anything that names an EXISTING thing (a target document, a family, a
+     * level) carries `x-existing` ({@link ExistingLookup}) and renders as a
+     * list the app fills — people pick, they never type names of things that
+     * exist. Free text is only for what a person invents.
+     */
+    settingsSchema?: Record<string, unknown>;
+    /**
+     * The self-documentation an app renders: a "reads → proposes" table whose
+     * rows are RULES (not objects), so a dry run can fill it with real tallies.
+     */
+    rules?: {
+        reads: string;
+        proposes: string;
+    }[];
+}
+/** Everything a recipe's `run` gets to work with. */
+export interface RecipeContext<Settings = Record<string, unknown>> {
+    client: EngineServicesClient;
+    projectId: string;
+    /** The document the suggestion is for. Read its timeline/model if needed. */
+    targetDoc: FlowDoc;
+    /**
+     * The suggestion's id, minted BEFORE the run: the payload envelope
+     * (`revitflow/op@2`) carries the opId inside, so the builder needs it.
+     * When the run is only a plan, nothing is queued and the id is discarded.
+     */
+    opId: string;
+    /** The declared input, already fetched by the caller (bytes, ids, rows…). */
+    input: unknown;
+    settings: Settings;
+}
+/** What a recipe's `run` returns: the suggestion, ready to queue. */
+export interface RecipeResult {
+    title: string;
+    /** add | set | remove | mixed. */
+    verb: string;
+    /** The .frag payload (envelope `revitflow/op@2`), when the recipe builds one. */
+    payload?: Blob;
+    targets?: number;
+    /** Per-rule tallies matching `manifest.rules`, filled by the run. */
+    ruleTallies?: {
+        read: number;
+        proposed: number;
+    }[];
+}
+/** A recipe: its manifest plus the function that writes the suggestion. */
+export interface Recipe<Settings = Record<string, unknown>> extends RecipeManifest {
+    run(context: RecipeContext<Settings>): Promise<RecipeResult>;
+}
+/** What {@link Recipes.run} returns: the queued suggestion plus the tallies. */
+export interface RecipeRunOutcome {
+    suggestion: FlowSuggestion;
+    result: RecipeResult;
+}
+/**
+ * The local recipe registry and runner. Reach it as `client.recipes`.
+ */
+export declare class Recipes {
+    #private;
+    private readonly client;
+    constructor(client: EngineServicesClient);
+    /** Registers a recipe. One per name; a second with the same name throws. */
+    register<S>(recipe: Recipe<S>): void;
+    /** The registered recipes, optionally filtered by target application. */
+    list(filter?: {
+        to?: string;
+        input?: string;
+    }): RecipeManifest[];
+    /** 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.
+     */
+    plan<S>(name: string, options: RecipeRunOptions<S>): Promise<RecipeResult>;
+    /**
+     * Runs a recipe and queues its suggestion on the target document. Safe to
+     * call freely: nothing touches the native application until its owner
+     * accepts the suggestion there. Use {@link plan} first when the app wants
+     * to show the tallies before queueing.
+     */
+    run<S>(name: string, options: RecipeRunOptions<S>): Promise<RecipeRunOutcome>;
+}
+/** The options {@link Recipes.plan} and {@link Recipes.run} share. */
+export interface RecipeRunOptions<S = Record<string, unknown>> {
+    projectId: string;
+    /** The target document, as `client.history(projectId).docs()` lists it. */
+    target: {
+        source: string;
+        docId: string;
+    };
+    input?: unknown;
+    settings?: S;
+    author: string;
+    userId?: string;
+}