@vardum/shared 0.3.0 → 0.4.1

package/README.md

@@ -1,18 +1,41 @@
 # @vardum/shared
 
-Wire types and the accepted-format tables shared by the Vardum API, dashboard,
+Wire types and accepted-format tables shared by the Vardum API, dashboard,
 CLI and MCP server. Published because `@vardum/cli` and `@vardum/mcp` depend on
 it at runtime; it carries no dependencies of its own.
 
-This README describes shared **0.3.0**. It adds the exported `mediaStem` and `mediaOutputPath`
-helpers used by the CLI and API for consistent media names and output suffixes.
-The published client baseline uses shared **0.2.0**; see
-[release compatibility](https://github.com/f-tuma/vardum/blob/main/docs/npm-release.md#compatibility)
-for the corresponding CLI/MCP versions and unreleased candidates.
+This README describes [shared **0.4.1**](https://www.npmjs.com/package/@vardum/shared/v/0.4.1),
+used by CLI **0.8.1** and MCP **0.4.1**. This patch makes the package documentation
+self-contained; it does not change the wire types or client snapshot schema.
 
-CLI 0.7.0 and MCP 0.3.0 retain `workspace:^` dependencies in source; the release
-archives require `@vardum/shared: ^0.3.0`, which npm resolves transitively.
+Shared 0.4.0 adds the guarded-editor wire contract: `VardEditorDefinition`
+requires the opaque `revision` and each manual item's literal nullable
+`pinnedVersionId`; `VardEditorItemInput` requires an existing mapping `id` or
+`null`, plus an explicit nullable `versionId`. Keep saved pins separate from
+resolved delivery versions. It retains `mediaStem`, `mediaOutputPath`, format
+tables. This client batch keeps CLI schema 2 snapshots; the wire manifest remains
+schema 1. It does not introduce schema 3.
+
+CLI 0.8.1 and MCP 0.4.1 retain `workspace:^` dependencies in source; their release
+archives require `@vardum/shared: ^0.4.1`, which npm resolves transitively.
+
+For a direct consumer, pin **shared 0.4.1**:
+
+```sh
+npm install --save-exact @vardum/shared@0.4.1
+```
 
 ```ts
-import { mimeForFilename, supportedMimeTypes, type VardManifest } from "@vardum/shared";
+import { mimeForFilename, supportedMimeTypes, type VardEditorDefinition } from "@vardum/shared";
 ```
+
+Types alone do not enable backend features. Editable Vard reads and mutations
+require a server advertising `vardEditRevision: 1` at `GET /api/capabilities`
+and implementing the guarded `/editor` endpoints. Folder-upload mutation requires
+`folderUploadResume: 1`; importing uploaded files into a Vard also requires
+`folderVardImport: 1`. The upload backend needs migrations through
+`0015_upload_request_checksum.sql` and ready-version checksum metadata.
+
+Private delivery still needs a workspace read key. Keep API keys out of source
+control and client-side applications; this package contains no authentication,
+credential storage or server upgrades.

package/dist/wire.d.ts

@@ -17,6 +17,8 @@ export type VardItem = {
     outputPath: string;
     writable: boolean;
     pinned: boolean;
+    /** Literal saved pin, supplied by the guarded editor even when the version is unavailable. */
+    pinnedVersionId?: string | null;
     transformation: Transformation | null;
     versionId: string | null;
     sourceChecksum: string | null;
@@ -44,6 +46,24 @@ export type VardFolderRule = {
 /** Editable configuration: items are manual mappings only, never expanded outputs. */
 export type VardDefinition = VardManifest & {
     folderRules: VardFolderRule[];
+    /** Opaque state-equivalence token supplied by guarded editor endpoints. */
+    revision?: string;
+};
+/** The dedicated editor always supplies its revision and literal pin IDs. */
+export type VardEditorDefinition = VardDefinition & {
+    revision: string;
+    items: (VardItem & {
+        pinnedVersionId: string | null;
+    })[];
+};
+export type VardEditorItemInput = {
+    /** Existing manual mapping ID, or null to allocate a new mapping. */
+    id: string | null;
+    assetId: string;
+    versionId: string | null;
+    outputPath: string;
+    transformation: Transformation | null;
+    writable: boolean;
 };
 export type SyncAsset = {
     id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vardum/shared",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Shared Vardum wire types and accepted-format tables",
   "license": "MIT",
   "type": "module",
@@ -25,7 +25,7 @@
     "url": "git+https://github.com/f-tuma/vardum.git",
     "directory": "packages/shared"
   },
-  "homepage": "https://github.com/f-tuma/vardum/tree/main/packages/shared#readme",
+  "homepage": "https://vardum.com",
   "bugs": {
     "url": "https://github.com/f-tuma/vardum/issues"
   },