@thatopen/services 0.20.0 → 0.22.0

package/docs/ai-quickstart.md

@@ -352,7 +352,36 @@ is the reply. The full walkthrough (typed contracts, collaboration events,
 presence) is `node_modules/@thatopen/services/src/core/examples/channel.ts`,
 indexed in the client API index you already loaded.
 
-## 5c. The desktop MCP server: `thatopen mcp`
+## 5c. History and recipes: documents, versions, change requests
+
+Three sentences hold the whole model. Every connected document (a Revit model,
+an AutoCAD drawing) has its version history: who synced, when, what changed.
+Nobody writes in somebody else's document: changes arrive as SUGGESTIONS
+(create/modify/delete native data) that the owner accepts or dismisses in the
+native app. A RECIPE is a script that writes suggestions in an application's
+own language, from whatever input.
+
+```ts
+const history = client.history(projectId);
+const docs = await history.docs();                 // the connected documents
+const doc = history.doc('revit', docs[0].docId);
+const timeline = await doc.timeline();             // versions, oldest first
+const pending = await doc.pendingSuggestions();    // waiting for the owner
+
+client.recipes.register(myRecipe);                 // manifest + one run()
+await client.recipes.run('my-recipe', {            // only QUEUES a suggestion:
+  projectId, target: { source: 'revit', docId },   // trying is always safe
+  input, settings, author,
+});
+```
+
+This surface is the only supported way in: the storage underneath is private
+and will move. Never list or write the `bimterop` files directly. The full
+walkthrough (manifest fields, StaleHistoryError on concurrent syncs, payloads)
+is `node_modules/@thatopen/services/src/core/examples/history.ts`, indexed in
+the client API index you already loaded.
+
+## 5d. The desktop MCP server: `thatopen mcp`
 
 The raw socket above is for tools you write. For an LLM on the desktop (Claude
 Desktop, Claude Code, anything that speaks MCP), the CLI ships the same bridge

package/docs/flow-plugin-guide.md

@@ -3,6 +3,13 @@
 The concrete contract. [The architecture notes](https://raw.githubusercontent.com/ThatOpen/platform_services/main/docs/flow-architecture.md) say why any of this is
 shaped the way it is; this says what the bytes look like.
 
+> **Plug-ins only.** Since `@thatopen/services` 0.20, apps and scripts do not write this layout by
+> hand: `client.history(projectId)` reads and writes documents, version timelines and proposals,
+> and `client.recipes` runs the scripts that author them — see `src/core/examples/history.ts` in
+> the package. The bytes below are the contract for NATIVE PLUG-INS (which carry their own client),
+> and the reference for what the API does underneath. Anything else touching these files directly
+> will break when the layout moves behind the API, which is the plan.
+
 Nothing here is aspirational. Every rule below is what the Revit and Rhino plugins already do, and
 was written from their implementation rather than ahead of it — which is why the awkward parts are
 stated as plainly as the tidy ones. Where a rule exists because something broke, it says so.

package/docs/rhino-interop-quickstart.md

@@ -195,11 +195,17 @@ happened.
 Points count as items without geometry. That is correct: they are the data the converter reads, not
 something to draw.
 
-## 5. The converter
+## 5. The converter (a recipe)
 
 This is the part that is **not** in either plug-in, and should not be. It reads the published
 `.frag`, decides what it means, and queues a proposal.
 
+> A converter is one kind of **recipe**: a script that writes proposals in the target program's
+> own words. Since `@thatopen/services` 0.20, write it against the SDK instead of the raw files:
+> `client.history(projectId)` reads the queue and the timeline and queues the proposal
+> (`doc.suggest`), and `client.recipes` is the registry/runner apps use to list it, render its
+> settings form and run it safely. The four steps below are unchanged.
+
 The worked example is `RhinoColumnsConverter`: points on a named layer become Revit columns of a
 given family and type. It is written to be read and then rewritten — the next person wants walls
 from curves, or louvres from blocks — but four steps survive any rewrite:

package/package.json

@@ -15,7 +15,7 @@
     "access": "public"
   },
   "private": false,
-  "version": "0.20.0",
+  "version": "0.22.0",
   "main": "dist/index.cjs.js",
   "module": "dist/index.es.js",
   "types": "dist/index.d.ts",