@anchrd/intel-contract 0.14.0 → 0.15.0

package/README.md

@@ -26,6 +26,86 @@ Mutation inputs are strict: an unknown field is rejected rather than silently dr
 a client never becomes a value that quietly fails to apply. Types are inferred from the schemas, so
 `z.infer` gives you the same shape the server validates against.
 
+Each domain has its own subpath — `/node`, `/table`, `/share`, `/tool`, `/flow`, `/flow-run`,
+`/bundle` — and the root export carries only the shared primitives. Import from the narrowest
+subpath that has the symbol.
+
+## Six things that cost a first-time caller an afternoon
+
+Every one of these was found by somebody writing against the real API and guessing.
+
+### A refusal hides in one of two fields, never both
+
+Intel answers failures as RFC 9457 problem details, and **which field carries the sentence depends
+on who refused**:
+
+| Kind of refusal | `title` | `detail` |
+|---|---|---|
+| Intel itself — a permission, a conflict, an invalid flow graph | the actual reason | absent |
+| Schema validation — a bad or missing field | `Request validation failed` | the actual reason, field by field |
+
+A client that logs only `detail` sees nothing for the first kind; one that logs only `title` sees
+`Request validation failed` and nothing about which field. **Read both.** `code` is the stable
+machine-readable half and is always present.
+
+### `baseVersionId` takes `null`, and it is still required
+
+Fields declared `nullable()` and not `optional()` are **required**: `null` is a value they take, and
+leaving them out is refused. That is deliberate everywhere a write names the version it was made
+against — `SaveNodeVersionInput`, `SaveAttachmentInput`, `SaveFlowVersionInput`. `null` is the only
+way to write the first content of a node that has none, and the field stays required so a caller who
+simply forgot it is refused instead of overwriting whatever somebody else wrote in between.
+
+Neither `undefined` nor `""` works. Send the `currentVersionId` from `node_get`, or `null`.
+
+### `mediaType` decides whether the browser can open what you wrote
+
+`SaveNodeVersionInput.mediaType` defaults to `text/markdown`, and for plain text that is right. It is
+**wrong for anything the node editor should be able to open**: the editor stores and reads
+`BlockNoteMediaType` (`application/vnd.anchrd.intel.blocknote+json`) with a `BlockNoteDocument` body.
+
+Content in any other shape is stored intact, indexed and searchable — and the editor opens **empty**
+on it, because it cannot parse it. Nothing reports an error, and a save from that empty editor
+replaces what was written. If a person is meant to edit the document afterwards, write it as a
+`BlockNoteDocument`:
+
+```ts
+import { BlockNoteDocument, BlockNoteMediaType } from "@anchrd/intel-contract/node";
+
+const content = JSON.stringify(
+  BlockNoteDocument.parse({ format: "blocknote", schemaVersion: 1, blocks, markdown }),
+);
+// … then save with mediaType: BlockNoteMediaType
+```
+
+### In a flow graph, a tool is a link, not a step
+
+Flow nodes sit in three layers. `trigger` and `output` are markers, `instruction`, `condition` and
+`subflow` are steps — and `folder`, `document`, `upload`, `table` and `tool` are **links**.
+
+A link never stands in the chain of work. It hangs off an `instruction` or a `condition` — not off a
+marker and not off a `subflow` — and the edge that attaches it must carry `kind: "context"`:
+
+```jsonc
+{ "source": "<instruction id>", "target": "<tool id>", "kind": "context" }
+```
+
+⚠️ `FlowEdge.kind` **defaults to `"flow"`**, so an edge written without it becomes an order-of-work
+edge and the tool ends up in the chain. The graph is then refused with
+`Node <id> is a link and must be attached to a step` — in `title`, per the first item above. A step
+may hold several links; one link belongs to exactly one step.
+
+### A flow is not a node, and carries no grants of its own
+
+`node_grant_create` addresses nodes. A flow has no grants; it inherits those of the folder it lives
+in. To change who reaches a flow, share its folder — or move the flow.
+
+### Import takes its idempotency key as a header
+
+Every mutation in this contract carries an `idempotencyKey` field. Bundle import is the one
+exception, because its **body is the zip**: the key travels as the `idempotency-key` HTTP header
+instead, and a request without it is refused.
+
 ## License
 
 Proprietary. Published publicly for installation convenience; this is not an open-source license and

package/dist/contract/node.d.ts

@@ -75,7 +75,7 @@ export declare const CreateNodeInput: z.ZodObject<{
 export type CreateNodeInput = z.infer<typeof CreateNodeInput>;
 export declare const SaveNodeVersionInput: z.ZodObject<{
     nodeId: z.ZodString;
-    baseVersionId: z.ZodNullable<z.ZodString>;
+    baseVersionId: z.ZodUnion<readonly [z.ZodString, z.ZodNull]>;
     content: z.ZodString;
     mediaType: z.ZodDefault<z.ZodString>;
     idempotencyKey: z.ZodString;
@@ -83,7 +83,7 @@ export declare const SaveNodeVersionInput: z.ZodObject<{
 export type SaveNodeVersionInput = z.infer<typeof SaveNodeVersionInput>;
 export declare const SaveAttachmentInput: z.ZodObject<{
     nodeId: z.ZodString;
-    baseVersionId: z.ZodNullable<z.ZodString>;
+    baseVersionId: z.ZodUnion<readonly [z.ZodString, z.ZodNull]>;
     contentBase64: z.ZodString;
     mediaType: z.ZodString;
     idempotencyKey: z.ZodString;

package/dist/contract/node.js

@@ -95,9 +95,33 @@ export const CreateNodeInput = z.strictObject({
         .describe("Optional sentence about the node, for readers rather than for search ranking."),
     idempotencyKey: IdempotencyKey,
 });
+/**
+ * The version a write is made against, in the one form both writers of node content take it.
+ *
+ * ⚠️ Nullable and required are not the same thing, and here they stand together (#437). `null` is
+ * how a node that has no version yet is addressed, and it is the only way to write its first
+ * content; leaving the field out says nothing at all and is refused. Whoever leaves it out is
+ * almost always holding a node created one call earlier, and the plain type error they used to get
+ * — "expected string, received undefined" — reads as "this field must be an id", about a field that
+ * cannot have one yet. Both refusals therefore name both ways instead.
+ *
+ * ⚠️ It stays required once a version exists, and that is what it is for: a mismatch is answered
+ * with a `409` rather than by overwriting somebody else's newer version.
+ *
+ * ⚠️ The bounds remain `IntelId`'s. The repeated `min(1)` adds no rule — it only puts the sentence
+ * on the second value that gets tried after `undefined`, the empty string.
+ *
+ * ⚠️ The sentence says what the field TAKES, not what the caller did wrong. It answers a wrong type
+ * as well as an absent field, and "is required" would be false about the first — which would be
+ * this same ticket one corner further on. A value that is merely too long keeps Zod's own `Too
+ * big`: that one is already a true statement about what was sent.
+ */
+function baseVersion(rule) {
+    return z.union([IntelId.min(1, { error: rule }), z.null()], { error: rule });
+}
 export const SaveNodeVersionInput = z.strictObject({
     nodeId: IntelId.describe("Document node to append a version to."),
-    baseVersionId: IntelId.nullable().describe("The version this edit was made against — `currentVersionId` from node_get. If the node has moved on since, the call is refused rather than overwriting the newer version; pass `null` only for a node that has no version yet."),
+    baseVersionId: baseVersion("baseVersionId takes the `currentVersionId` from node_get, or null when the node has no version yet — and it has to be sent.").describe("The version this edit was made against — `currentVersionId` from node_get. If the node has moved on since, the call is refused rather than overwriting the newer version; pass `null` only for a node that has no version yet."),
     content: z
         .string()
         .max(10_000_000)
@@ -112,7 +136,7 @@ export const SaveNodeVersionInput = z.strictObject({
 });
 export const SaveAttachmentInput = z.strictObject({
     nodeId: IntelId.describe("Attachment node to append bytes to."),
-    baseVersionId: IntelId.nullable().describe("The version these bytes replace — `currentVersionId` from node_get, or `null` for the first upload. A stale value is refused rather than overwriting."),
+    baseVersionId: baseVersion("baseVersionId takes the `currentVersionId` from node_get, or null for the first upload — and it has to be sent.").describe("The version these bytes replace — `currentVersionId` from node_get, or `null` for the first upload. A stale value is refused rather than overwriting."),
     contentBase64: z
         .string()
         .min(1)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchrd/intel-contract",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {