@anchrd/intel-contract 0.14.0 → 0.16.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/flow.d.ts

@@ -709,6 +709,15 @@ export declare const ArchiveFlowInput: z.ZodObject<{
     idempotencyKey: z.ZodString;
 }, z.core.$strict>;
 export type ArchiveFlowInput = z.infer<typeof ArchiveFlowInput>;
+export declare const PurgeFlowInput: z.ZodObject<{
+    flowId: z.ZodString;
+}, z.core.$strict>;
+export type PurgeFlowInput = z.infer<typeof PurgeFlowInput>;
+export declare const PurgeFlowResult: z.ZodObject<{
+    purged: z.ZodLiteral<true>;
+    title: z.ZodString;
+}, z.core.$strict>;
+export type PurgeFlowResult = z.infer<typeof PurgeFlowResult>;
 export declare const ListFlowsInput: z.ZodObject<{
     parentId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     includeArchived: z.ZodOptional<z.ZodBoolean>;

package/dist/contract/flow.js

@@ -292,6 +292,16 @@ export const ArchiveFlowInput = z.strictObject({
         .describe("`true` archives the flow, `false` restores it. Nothing is deleted and every version stays readable."),
     idempotencyKey: IdempotencyKey,
 });
+// ⚠️ The flow half of the one irreversible act in Intel (#457). No `baseUpdatedAt`, no
+// `idempotencyKey`, for the same two reasons the node's has neither: an archived flow is not being
+// edited, and a replay has nothing to replay — deleting twice deletes once and then answers 404.
+export const PurgeFlowInput = z.strictObject({
+    flowId: IntelId.describe("Flow to delete for good. It must already be archived — a living flow has no path into nothing."),
+});
+export const PurgeFlowResult = z.strictObject({
+    purged: z.literal(true),
+    title: z.string(),
+});
 // Three answers, not two: an absent `parentId` lists every visible flow (the search dialog asks
 // that), `null` lists the root of the shared tree and an ID lists one folder (the sidebar tree asks
 // per level, which is what keeps the tree off the N+1 it used to load with).

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;
@@ -105,6 +105,15 @@ export declare const ArchiveNodeInput: z.ZodObject<{
     idempotencyKey: z.ZodString;
 }, z.core.$strict>;
 export type ArchiveNodeInput = z.infer<typeof ArchiveNodeInput>;
+export declare const PurgeNodeInput: z.ZodObject<{
+    nodeId: z.ZodString;
+}, z.core.$strict>;
+export type PurgeNodeInput = z.infer<typeof PurgeNodeInput>;
+export declare const PurgeNodeResult: z.ZodObject<{
+    purged: z.ZodLiteral<true>;
+    title: z.ZodString;
+}, z.core.$strict>;
+export type PurgeNodeResult = z.infer<typeof PurgeNodeResult>;
 export declare const NodeList: z.ZodObject<{
     items: z.ZodArray<z.ZodObject<{
         id: 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)
@@ -157,6 +181,24 @@ export const ArchiveNodeInput = z.strictObject({
         .describe("`true` archives the node, `false` restores it. Archiving hides a node from listings and search; nothing is deleted and every version stays readable."),
     idempotencyKey: IdempotencyKey,
 });
+// ⚠️ The one input in this contract that describes an IRREVERSIBLE act (#457). Everything else
+// called "delete" in Intel means `archived_at`.
+//
+// It carries no `baseUpdatedAt` and no `idempotencyKey`, and both absences are decisions:
+//   · There is nothing to conflict with. The node must already be archived — an archived node is
+//     not being edited by anybody, and a restore between the read and the call is caught by the
+//     statement itself rather than by a timestamp the caller had to carry.
+//   · A replay has nothing to replay. Deleting twice is deleting once and then a 404, which is the
+//     honest answer: the second caller really did not delete anything.
+export const PurgeNodeInput = z.strictObject({
+    nodeId: IntelId.describe("Node to delete for good. It must already be archived — a living node has no path into nothing."),
+});
+// The title travels back because after this call nothing can look it up any more — not the row, not
+// a version, not the index. A caller that wants to say what it just deleted has this one chance.
+export const PurgeNodeResult = z.strictObject({
+    purged: z.literal(true),
+    title: z.string(),
+});
 // ⚠️ `withChildren` belongs to the LEVEL, not to the node (#59). Whether something has children
 // THIS reader may see is not a property of the thing — two readers get different answers. As a
 // field on the node, every other place that returns a node would have to compute it as well or

package/package.json

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