@yargote/artifacts-contracts 0.0.0-stage → 0.1.0-beta.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yerson Argote
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,21 @@
-# Temporary Holding Version
+# Artifacts contracts
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@yargote/artifacts-contracts` contains strict domain schemas, types, `ArtifactError`, snapshot serialization, and pure retained-edit helpers. It has no database, ZIP, server, or CLI dependency. Node 24 or later is required.
+
+```sh
+npm install @yargote/artifacts-contracts@0.1.0-beta.10
+```
+
+The root export contains domain schemas and types. `/workflow` contains `prepareArtifactEdit`, revision comparison, and compact projections. `/serialization` contains canonical JSON and SHA-256. `/http` contains HTTP response schemas, identity, canonical resource validation, and route URL helpers.
+
+`protectedResourceMetadataSchema` accepts standard protected-resource metadata and an optional `artifacts_rest_resource`. The relation names the exact absolute canonical REST OAuth resource URL. It may name the resource itself or one distinct REST resource. Metadata for the distinct resource may omit the relation or name itself, but cannot name another resource.
+
+`slugSchema` validates page slugs such as `concepts/rag` without normalizing them. `readSchema` takes exactly one of `artifactId` or a `{ project, slug }` locator, and `readByIdSchema` takes only an ID. `moveSchema` takes `project`, `slug`, or both, each optional and nullable. `moveResultSchema` is unchanged. `ArtifactRead` and the HTTP summary schema include `slug`, and `ArtifactErrorCode` includes `slug_conflict`.
+
+`searchSchema` takes a trimmed `query` of 1 to 256 characters, optional `project`, `limit` from 1 to 25 with default 10, and an opaque decimal `cursor`. `searchResultSchema` holds `items` of `searchHitSchema`, `{ artifactId, project, slug, title, snippet, rank }`, and a nullable `nextCursor`.
+
+The existing `@artifacts/artifacts` root, `/contracts`, and `/workflow` exports re-export these implementations. Store and REST packages share one `ArtifactError` runtime.
+
+This package is MIT licensed. The license applies to this package and does not license the private Artifacts application repository.
+
+`shareSchema` accepts optional `notify` and `requireNew: true` without defaults. `shareResultSchema` remains the strict five-field grant shape used by lists. `shareCommandResultSchema` adds an optional immutable notification disposition for commands. Plain and explicit-false requests return the original grant shape. An absent flag and an explicit false remain distinct receipt arguments.

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@yargote/artifacts-contracts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-beta.10",
+  "private": false,
+  "type": "module",
+  "description": "Shared schemas and contracts for Artifacts clients.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yersonargotev/artifacts.git",
+    "directory": "packages/contracts"
+  },
+  "homepage": "https://github.com/yersonargotev",
+  "bugs": {
+    "url": "https://github.com/yersonargotev"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./workflow": "./src/workflow.js",
+    "./serialization": "./src/serialization.js",
+    "./http": "./src/http.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "zod": "4.6.5"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta",
+    "provenance": false
+  }
+}

package/src/http.d.ts

@@ -0,0 +1,220 @@
+import { z } from 'zod';
+export declare const identitySchema: z.ZodObject<{
+    userId: z.ZodString;
+    sessionId: z.ZodString;
+    clientId: z.ZodString;
+    scopes: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type Identity = z.infer<typeof identitySchema>;
+export declare const attachmentSummarySchema: z.ZodObject<{
+    path: z.ZodString;
+    mediaType: z.ZodString;
+    encoding: z.ZodEnum<{
+        utf8: "utf8";
+        base64: "base64";
+    }>;
+    decodedBytes: z.ZodNumber;
+    sha256: z.ZodString;
+}, z.core.$strict>;
+export declare const revisionSummarySchema: z.ZodObject<{
+    id: z.ZodString;
+    createdAt: z.ZodISODateTime;
+    parentRevisionId: z.ZodNullable<z.ZodString>;
+    sequence: z.ZodNumber;
+    authorUserId: z.ZodString;
+    authorClientId: z.ZodString;
+    sha256: z.ZodString;
+    metadata: z.ZodObject<{
+        description: z.ZodString;
+        title: z.ZodString;
+    }, z.core.$strict>;
+    content: z.ZodObject<{
+        kind: z.ZodEnum<{
+            text: "text";
+            html: "html";
+            markdown: "markdown";
+            design: "design";
+        }>;
+        utf8Bytes: z.ZodNumber;
+    }, z.core.$strict>;
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        mediaType: z.ZodString;
+        encoding: z.ZodEnum<{
+            utf8: "utf8";
+            base64: "base64";
+        }>;
+        decodedBytes: z.ZodNumber;
+        sha256: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const compactArtifactReadSchema: z.ZodObject<{
+    ownerId: z.ZodString;
+    headRevisionId: z.ZodString;
+    project: z.ZodNullable<z.ZodString>;
+    slug: z.ZodNullable<z.ZodString>;
+    artifactId: z.ZodString;
+    publication: z.ZodNullable<z.ZodObject<{
+        revisionId: z.ZodString;
+        version: z.ZodNumber;
+        url: z.ZodURL;
+    }, z.core.$strict>>;
+    revision: z.ZodObject<{
+        id: z.ZodString;
+        createdAt: z.ZodISODateTime;
+        parentRevisionId: z.ZodNullable<z.ZodString>;
+        sequence: z.ZodNumber;
+        authorUserId: z.ZodString;
+        authorClientId: z.ZodString;
+        sha256: z.ZodString;
+        metadata: z.ZodObject<{
+            description: z.ZodString;
+            title: z.ZodString;
+        }, z.core.$strict>;
+        content: z.ZodObject<{
+            kind: z.ZodEnum<{
+                text: "text";
+                html: "html";
+                markdown: "markdown";
+                design: "design";
+            }>;
+            utf8Bytes: z.ZodNumber;
+        }, z.core.$strict>;
+        files: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            mediaType: z.ZodString;
+            encoding: z.ZodEnum<{
+                utf8: "utf8";
+                base64: "base64";
+            }>;
+            decodedBytes: z.ZodNumber;
+            sha256: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const artifactSummarySchema: z.ZodObject<{
+    artifactId: z.ZodString;
+    title: z.ZodString;
+    headRevisionId: z.ZodString;
+    createdAt: z.ZodISODateTime;
+    project: z.ZodNullable<z.ZodString>;
+    slug: z.ZodNullable<z.ZodString>;
+    publication: z.ZodNullable<z.ZodObject<{
+        revisionId: z.ZodString;
+        version: z.ZodNumber;
+        url: z.ZodURL;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const listResultSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        artifactId: z.ZodString;
+        title: z.ZodString;
+        headRevisionId: z.ZodString;
+        createdAt: z.ZodISODateTime;
+        project: z.ZodNullable<z.ZodString>;
+        slug: z.ZodNullable<z.ZodString>;
+        publication: z.ZodNullable<z.ZodObject<{
+            revisionId: z.ZodString;
+            version: z.ZodNumber;
+            url: z.ZodURL;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    nextCursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export declare const projectSummarySchema: z.ZodObject<{
+    name: z.ZodString;
+    artifactCount: z.ZodNumber;
+}, z.core.$strict>;
+export declare const projectsResultSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        artifactCount: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const historyResultSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        parentRevisionId: z.ZodNullable<z.ZodString>;
+        sequence: z.ZodNumber;
+        authorUserId: z.ZodString;
+        authorClientId: z.ZodString;
+        createdAt: z.ZodISODateTime;
+        sha256: z.ZodString;
+        snapshot: z.ZodObject<{
+            metadata: z.ZodObject<{
+                title: z.ZodString;
+                description: z.ZodString;
+                custom: z.ZodOptional<z.ZodJSONSchema>;
+            }, z.core.$strict>;
+            content: z.ZodObject<{
+                kind: z.ZodEnum<{
+                    text: "text";
+                    html: "html";
+                    markdown: "markdown";
+                    design: "design";
+                }>;
+                text: z.ZodString;
+            }, z.core.$strict>;
+            files: z.ZodArray<z.ZodObject<{
+                path: z.ZodString;
+                mediaType: z.ZodString;
+                encoding: z.ZodEnum<{
+                    utf8: "utf8";
+                    base64: "base64";
+                }>;
+                data: z.ZodString;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    nextBeforeSequence: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strict>;
+export declare const summaryHistoryResultSchema: z.ZodObject<{
+    nextBeforeSequence: z.ZodNullable<z.ZodNumber>;
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        createdAt: z.ZodISODateTime;
+        parentRevisionId: z.ZodNullable<z.ZodString>;
+        sequence: z.ZodNumber;
+        authorUserId: z.ZodString;
+        authorClientId: z.ZodString;
+        sha256: z.ZodString;
+        metadata: z.ZodObject<{
+            description: z.ZodString;
+            title: z.ZodString;
+        }, z.core.$strict>;
+        content: z.ZodObject<{
+            kind: z.ZodEnum<{
+                text: "text";
+                html: "html";
+                markdown: "markdown";
+                design: "design";
+            }>;
+            utf8Bytes: z.ZodNumber;
+        }, z.core.$strict>;
+        files: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            mediaType: z.ZodString;
+            encoding: z.ZodEnum<{
+                utf8: "utf8";
+                base64: "base64";
+            }>;
+            decodedBytes: z.ZodNumber;
+            sha256: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const httpErrorSchema: z.ZodObject<{
+    error: z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        details: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare function canonicalResource(value: string): string;
+export declare const protectedResourceMetadataSchema: z.ZodObject<{
+    resource: z.ZodString;
+    authorization_servers: z.ZodArray<z.ZodString>;
+    artifacts_rest_resource: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare function protectedResourceMetadataUrl(resource: string): URL;
+export declare function restBase(resource: string): string;

package/src/http.js

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+import { artifactReadSchema, contentKinds, publicationSchema, revisionSchema, snapshotSchema } from "./index.js";
+const identifier = z.string().min(1).max(128);
+const digest = z.string().regex(/^[a-f0-9]{64}$/);
+export const identitySchema = z.strictObject({ userId: identifier, sessionId: identifier, clientId: identifier, scopes: z.array(z.string()) });
+export const attachmentSummarySchema = z.strictObject({ path: z.string(), mediaType: z.string(), encoding: z.enum(['utf8', 'base64']), decodedBytes: z.number().int().nonnegative(), sha256: digest });
+export const revisionSummarySchema = revisionSchema.omit({ snapshot: true }).extend({
+    metadata: snapshotSchema.shape.metadata.pick({ title: true, description: true }),
+    content: z.strictObject({ kind: z.enum(contentKinds), utf8Bytes: z.number().int().nonnegative() }),
+    files: z.array(attachmentSummarySchema).max(32),
+});
+export const compactArtifactReadSchema = artifactReadSchema.omit({ revision: true }).extend({ revision: revisionSummarySchema });
+export const artifactSummarySchema = z.strictObject({ artifactId: identifier, title: z.string(), headRevisionId: identifier, createdAt: z.iso.datetime(), project: z.string().nullable(), slug: z.string().nullable(), publication: publicationSchema.nullable() });
+export const listResultSchema = z.strictObject({ items: z.array(artifactSummarySchema).max(100), nextCursor: identifier.nullable() });
+export const projectSummarySchema = z.strictObject({ name: z.string(), artifactCount: z.number().int().positive() });
+export const projectsResultSchema = z.strictObject({ items: z.array(projectSummarySchema) });
+export const historyResultSchema = z.strictObject({ items: z.array(revisionSchema).max(10), nextBeforeSequence: z.number().int().positive().nullable() });
+export const summaryHistoryResultSchema = historyResultSchema.extend({ items: z.array(revisionSummarySchema).max(10) });
+export const httpErrorSchema = z.strictObject({ error: z.strictObject({ code: z.string().min(1), message: z.string(), details: z.record(z.string(), z.unknown()) }) });
+export function canonicalResource(value) {
+    const url = new URL(value);
+    const loopback = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+    if (url.username || url.password || url.search || url.hash || (url.protocol !== 'https:' && !(loopback && url.protocol === 'http:')))
+        throw new TypeError('The server requires HTTPS, or HTTP on an exact loopback host, without credentials, query, or fragment');
+    if ((url.href !== value && url.href.replace(/\/$/, '') !== value) || (url.pathname !== '/' && url.pathname.endsWith('/')))
+        throw new TypeError('Use the exact canonical resource URL without a trailing slash');
+    return value;
+}
+export const protectedResourceMetadataSchema = z.object({
+    resource: z.string(),
+    authorization_servers: z.array(z.string()).min(1),
+    artifacts_rest_resource: z.string().refine((value) => {
+        try {
+            canonicalResource(value);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }).optional(),
+});
+export function protectedResourceMetadataUrl(resource) {
+    const url = new URL(canonicalResource(resource));
+    return new URL(`/.well-known/oauth-protected-resource${url.pathname === '/' ? '' : url.pathname}`, url.origin);
+}
+export function restBase(resource) {
+    return `${canonicalResource(resource).replace(/\/$/, '')}/v1`;
+}

package/src/index.d.ts

@@ -0,0 +1,510 @@
+import { z } from 'zod';
+export declare const contentKinds: readonly ["html", "markdown", "text", "design"];
+export declare const canvasIndexSchema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    boards: z.ZodPipe<z.ZodUnknown, z.ZodRecord<z.ZodString, z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        w: z.ZodNumber;
+        h: z.ZodNumber;
+        title: z.ZodOptional<z.ZodString>;
+        page: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    order: z.ZodPipe<z.ZodArray<z.ZodUnknown>, z.ZodArray<z.ZodString>>;
+    notes: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodRecord<z.ZodString, z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        text: z.ZodString;
+        w: z.ZodOptional<z.ZodNumber>;
+        page: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>>;
+    pages: z.ZodOptional<z.ZodPipe<z.ZodArray<z.ZodUnknown>, z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strict>>>>;
+}, z.core.$strict>;
+export declare const snapshotSchema: z.ZodObject<{
+    metadata: z.ZodObject<{
+        title: z.ZodString;
+        description: z.ZodString;
+        custom: z.ZodOptional<z.ZodJSONSchema>;
+    }, z.core.$strict>;
+    content: z.ZodObject<{
+        kind: z.ZodEnum<{
+            text: "text";
+            html: "html";
+            markdown: "markdown";
+            design: "design";
+        }>;
+        text: z.ZodString;
+    }, z.core.$strict>;
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        mediaType: z.ZodString;
+        encoding: z.ZodEnum<{
+            utf8: "utf8";
+            base64: "base64";
+        }>;
+        data: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type CanvasIndex = z.infer<typeof canvasIndexSchema>;
+export type CanvasBoard = CanvasIndex['boards'][string] & {
+    path: string;
+    html: string;
+};
+export type Canvas = {
+    index: CanvasIndex;
+    boards: CanvasBoard[];
+};
+export declare function parseCanvas(snapshot: Pick<Snapshot, 'content' | 'files'>): Canvas;
+export declare const projectNameSchema: z.ZodString;
+export declare const slugSchema: z.ZodString;
+export declare const createSchema: z.ZodObject<{
+    requestId: z.ZodString;
+    snapshot: z.ZodObject<{
+        metadata: z.ZodObject<{
+            title: z.ZodString;
+            description: z.ZodString;
+            custom: z.ZodOptional<z.ZodJSONSchema>;
+        }, z.core.$strict>;
+        content: z.ZodObject<{
+            kind: z.ZodEnum<{
+                text: "text";
+                html: "html";
+                markdown: "markdown";
+                design: "design";
+            }>;
+            text: z.ZodString;
+        }, z.core.$strict>;
+        files: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            mediaType: z.ZodString;
+            encoding: z.ZodEnum<{
+                utf8: "utf8";
+                base64: "base64";
+            }>;
+            data: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    project: z.ZodOptional<z.ZodString>;
+    slug: z.ZodOptional<z.ZodString>;
+    response: z.ZodOptional<z.ZodEnum<{
+        full: "full";
+        compact: "compact";
+    }>>;
+}, z.core.$strict>;
+export declare const readByIdSchema: z.ZodObject<{
+    artifactId: z.ZodString;
+    revisionId: z.ZodOptional<z.ZodString>;
+    response: z.ZodOptional<z.ZodEnum<{
+        full: "full";
+        compact: "compact";
+    }>>;
+}, z.core.$strict>;
+export declare const readSchema: z.ZodObject<{
+    artifactId: z.ZodOptional<z.ZodString>;
+    project: z.ZodOptional<z.ZodString>;
+    slug: z.ZodOptional<z.ZodString>;
+    revisionId: z.ZodOptional<z.ZodString>;
+    response: z.ZodOptional<z.ZodEnum<{
+        full: "full";
+        compact: "compact";
+    }>>;
+}, z.core.$strict>;
+export declare const updateSchema: z.ZodObject<{
+    requestId: z.ZodString;
+    artifactId: z.ZodString;
+    expectedRevisionId: z.ZodString;
+    snapshot: z.ZodObject<{
+        metadata: z.ZodObject<{
+            title: z.ZodString;
+            description: z.ZodString;
+            custom: z.ZodOptional<z.ZodJSONSchema>;
+        }, z.core.$strict>;
+        content: z.ZodObject<{
+            kind: z.ZodEnum<{
+                text: "text";
+                html: "html";
+                markdown: "markdown";
+                design: "design";
+            }>;
+            text: z.ZodString;
+        }, z.core.$strict>;
+        files: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            mediaType: z.ZodString;
+            encoding: z.ZodEnum<{
+                utf8: "utf8";
+                base64: "base64";
+            }>;
+            data: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    response: z.ZodOptional<z.ZodEnum<{
+        full: "full";
+        compact: "compact";
+    }>>;
+}, z.core.$strict>;
+export declare const publishSchema: z.ZodObject<{
+    requestId: z.ZodString;
+    artifactId: z.ZodString;
+    revisionId: z.ZodString;
+    expectedPublicationVersion: z.ZodNumber;
+}, z.core.$strict>;
+export declare const deleteSchema: z.ZodObject<{
+    requestId: z.ZodString;
+    artifactId: z.ZodString;
+    expectedRevisionId: z.ZodString;
+    expectedPublicationVersion: z.ZodNumber;
+}, z.core.$strict>;
+export declare const deleteResultSchema: z.ZodObject<{
+    artifactId: z.ZodString;
+}, z.core.$strict>;
+export type DeleteInput = z.infer<typeof deleteSchema>;
+export type DeleteResult = z.infer<typeof deleteResultSchema>;
+export declare const moveSchema: z.ZodObject<{
+    requestId: z.ZodString;
+    artifactId: z.ZodString;
+    project: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    slug: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>;
+export declare const moveResultSchema: z.ZodObject<{
+    artifactId: z.ZodString;
+    project: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type MoveResult = z.infer<typeof moveResultSchema>;
+export declare const shareSchema: z.ZodObject<{
+    requestId: z.ZodString;
+    artifactId: z.ZodString;
+    email: z.ZodPipe<z.ZodString, z.ZodEmail>;
+    notify: z.ZodOptional<z.ZodBoolean>;
+    requireNew: z.ZodOptional<z.ZodLiteral<true>>;
+}, z.core.$strict>;
+export declare const unshareSchema: z.ZodObject<{
+    requestId: z.ZodString;
+    artifactId: z.ZodString;
+    shareId: z.ZodString;
+}, z.core.$strict>;
+export declare const listSharesSchema: z.ZodObject<{
+    artifactId: z.ZodString;
+}, z.core.$strict>;
+export declare const shareResultSchema: z.ZodObject<{
+    shareId: z.ZodString;
+    artifactId: z.ZodString;
+    kind: z.ZodLiteral<"email">;
+    value: z.ZodEmail;
+    createdAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export declare const notificationSchema: z.ZodUnion<readonly [z.ZodObject<{
+    status: z.ZodLiteral<"requested">;
+}, z.core.$strict>, z.ZodObject<{
+    status: z.ZodLiteral<"skipped">;
+    reason: z.ZodLiteral<"disabled">;
+}, z.core.$strict>, z.ZodObject<{
+    status: z.ZodLiteral<"skipped">;
+    reason: z.ZodLiteral<"rate_limited">;
+    retryAt: z.ZodISODateTime;
+}, z.core.$strict>]>;
+export declare const shareCommandResultSchema: z.ZodObject<{
+    shareId: z.ZodString;
+    artifactId: z.ZodString;
+    kind: z.ZodLiteral<"email">;
+    value: z.ZodEmail;
+    createdAt: z.ZodISODateTime;
+    notification: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        status: z.ZodLiteral<"requested">;
+    }, z.core.$strict>, z.ZodObject<{
+        status: z.ZodLiteral<"skipped">;
+        reason: z.ZodLiteral<"disabled">;
+    }, z.core.$strict>, z.ZodObject<{
+        status: z.ZodLiteral<"skipped">;
+        reason: z.ZodLiteral<"rate_limited">;
+        retryAt: z.ZodISODateTime;
+    }, z.core.$strict>]>>;
+}, z.core.$strict>;
+export declare const unshareResultSchema: z.ZodObject<{
+    artifactId: z.ZodString;
+    shareId: z.ZodString;
+}, z.core.$strict>;
+export type Share = z.infer<typeof shareResultSchema>;
+export type ShareResult = z.infer<typeof shareCommandResultSchema>;
+export type Notification = z.infer<typeof notificationSchema>;
+export type UnshareResult = z.infer<typeof unshareResultSchema>;
+export declare const exportSchema: z.ZodObject<{
+    artifactId: z.ZodString;
+    revisionId: z.ZodString;
+}, z.core.$strict>;
+export declare const listSchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodNumber>;
+    cursor: z.ZodOptional<z.ZodString>;
+    project: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const searchSchema: z.ZodObject<{
+    query: z.ZodString;
+    project: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    cursor: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const searchHitSchema: z.ZodObject<{
+    artifactId: z.ZodString;
+    project: z.ZodNullable<z.ZodString>;
+    slug: z.ZodNullable<z.ZodString>;
+    title: z.ZodString;
+    snippet: z.ZodString;
+    rank: z.ZodNumber;
+}, z.core.$strict>;
+export declare const searchResultSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        artifactId: z.ZodString;
+        project: z.ZodNullable<z.ZodString>;
+        slug: z.ZodNullable<z.ZodString>;
+        title: z.ZodString;
+        snippet: z.ZodString;
+        rank: z.ZodNumber;
+    }, z.core.$strict>>;
+    nextCursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type SearchHit = z.infer<typeof searchHitSchema>;
+export type SearchResult = z.infer<typeof searchResultSchema>;
+export declare const libraryQuerySchema: z.ZodObject<{
+    q: z.ZodDefault<z.ZodString>;
+    status: z.ZodDefault<z.ZodEnum<{
+        all: "all";
+        published: "published";
+        unpublished: "unpublished";
+        pending: "pending";
+    }>>;
+    project: z.ZodOptional<z.ZodString>;
+    cursor: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const historySchema: z.ZodObject<{
+    artifactId: z.ZodString;
+    limit: z.ZodDefault<z.ZodNumber>;
+    beforeSequence: z.ZodOptional<z.ZodNumber>;
+    response: z.ZodOptional<z.ZodEnum<{
+        full: "full";
+        summary: "summary";
+    }>>;
+}, z.core.$strict>;
+export declare const issueGrantSchema: z.ZodObject<{
+    artifactId: z.ZodString;
+    state: z.ZodString;
+}, z.core.$strict>;
+export declare const consumeGrantSchema: z.ZodObject<{
+    artifactId: z.ZodString;
+    state: z.ZodString;
+    code: z.ZodString;
+}, z.core.$strict>;
+export declare const viewerSchema: z.ZodObject<{
+    artifactId: z.ZodString;
+    userId: z.ZodString;
+    sessionId: z.ZodString;
+    expiresAt: z.ZodNumber;
+}, z.core.$strict>;
+export type Snapshot = z.infer<typeof snapshotSchema>;
+export type ReadonlyJsonValue = string | number | boolean | null | {
+    readonly [key: string]: ReadonlyJsonValue;
+} | readonly ReadonlyJsonValue[];
+export type UpdateInput = {
+    readonly requestId: string;
+    readonly artifactId: string;
+    readonly expectedRevisionId: string;
+    readonly snapshot: {
+        readonly metadata: {
+            readonly title: string;
+            readonly description: string;
+            readonly custom?: ReadonlyJsonValue;
+        };
+        readonly content: Readonly<Snapshot['content']>;
+        readonly files: readonly Readonly<Snapshot['files'][number]>[];
+    };
+    readonly response?: 'full' | 'compact';
+};
+export type Actor = Readonly<{
+    userId: string;
+    sessionId: string;
+    clientId: string;
+    scopes: readonly string[];
+}>;
+export type Viewer = z.infer<typeof viewerSchema>;
+export type Publication = z.infer<typeof publicationSchema>;
+export type Revision = z.infer<typeof revisionSchema>;
+export type ArtifactRead = z.infer<typeof artifactReadSchema>;
+export type SharedRead = z.infer<typeof sharedReadSchema>;
+export type SharedArtifactSummary = Readonly<{
+    artifactId: string;
+    title: string;
+    ownerName: string;
+    url: string;
+}>;
+export type ArtifactSummary = {
+    artifactId: string;
+    title: string;
+    headRevisionId: string;
+    createdAt: string;
+    project: string | null;
+    slug: string | null;
+    publication: Publication | null;
+};
+export type ProjectSummary = {
+    name: string;
+    artifactCount: number;
+};
+export type ArtifactLibraryQuery = z.infer<typeof libraryQuerySchema>;
+export type ArtifactLibraryPage = {
+    items: ArtifactSummary[];
+    nextCursor: string | null;
+    counts: {
+        all: number;
+        published: number;
+        unpublished: number;
+        pending: number;
+    };
+};
+export type Archive = {
+    filename: string;
+    mediaType: 'application/zip';
+    base64: string;
+    sha256: string;
+};
+export type ArtifactErrorCode = 'forbidden' | 'not_found' | 'conflict' | 'request_conflict' | 'slug_conflict' | 'invalid_grant';
+export declare class ArtifactError extends Error {
+    readonly code: ArtifactErrorCode;
+    readonly details: Record<string, unknown>;
+    constructor(code: ArtifactErrorCode, message: string, details?: Record<string, unknown>);
+}
+export declare function decodeFile(file: {
+    encoding: 'utf8' | 'base64';
+    data: string;
+}): Uint8Array;
+export declare const publicationSchema: z.ZodObject<{
+    revisionId: z.ZodString;
+    version: z.ZodNumber;
+    url: z.ZodURL;
+}, z.core.$strict>;
+export declare const revisionSchema: z.ZodObject<{
+    id: z.ZodString;
+    parentRevisionId: z.ZodNullable<z.ZodString>;
+    sequence: z.ZodNumber;
+    authorUserId: z.ZodString;
+    authorClientId: z.ZodString;
+    createdAt: z.ZodISODateTime;
+    sha256: z.ZodString;
+    snapshot: z.ZodObject<{
+        metadata: z.ZodObject<{
+            title: z.ZodString;
+            description: z.ZodString;
+            custom: z.ZodOptional<z.ZodJSONSchema>;
+        }, z.core.$strict>;
+        content: z.ZodObject<{
+            kind: z.ZodEnum<{
+                text: "text";
+                html: "html";
+                markdown: "markdown";
+                design: "design";
+            }>;
+            text: z.ZodString;
+        }, z.core.$strict>;
+        files: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            mediaType: z.ZodString;
+            encoding: z.ZodEnum<{
+                utf8: "utf8";
+                base64: "base64";
+            }>;
+            data: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const artifactReadSchema: z.ZodObject<{
+    artifactId: z.ZodString;
+    ownerId: z.ZodString;
+    headRevisionId: z.ZodString;
+    project: z.ZodNullable<z.ZodString>;
+    slug: z.ZodNullable<z.ZodString>;
+    publication: z.ZodNullable<z.ZodObject<{
+        revisionId: z.ZodString;
+        version: z.ZodNumber;
+        url: z.ZodURL;
+    }, z.core.$strict>>;
+    revision: z.ZodObject<{
+        id: z.ZodString;
+        parentRevisionId: z.ZodNullable<z.ZodString>;
+        sequence: z.ZodNumber;
+        authorUserId: z.ZodString;
+        authorClientId: z.ZodString;
+        createdAt: z.ZodISODateTime;
+        sha256: z.ZodString;
+        snapshot: z.ZodObject<{
+            metadata: z.ZodObject<{
+                title: z.ZodString;
+                description: z.ZodString;
+                custom: z.ZodOptional<z.ZodJSONSchema>;
+            }, z.core.$strict>;
+            content: z.ZodObject<{
+                kind: z.ZodEnum<{
+                    text: "text";
+                    html: "html";
+                    markdown: "markdown";
+                    design: "design";
+                }>;
+                text: z.ZodString;
+            }, z.core.$strict>;
+            files: z.ZodArray<z.ZodObject<{
+                path: z.ZodString;
+                mediaType: z.ZodString;
+                encoding: z.ZodEnum<{
+                    utf8: "utf8";
+                    base64: "base64";
+                }>;
+                data: z.ZodString;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const sharedReadSchema: z.ZodObject<{
+    artifactId: z.ZodString;
+    ownerName: z.ZodDefault<z.ZodString>;
+    publication: z.ZodObject<{
+        revisionId: z.ZodString;
+        version: z.ZodNumber;
+        url: z.ZodURL;
+    }, z.core.$strict>;
+    revision: z.ZodObject<{
+        id: z.ZodString;
+        createdAt: z.ZodISODateTime;
+        sha256: z.ZodString;
+        snapshot: z.ZodObject<{
+            metadata: z.ZodObject<{
+                title: z.ZodString;
+                description: z.ZodString;
+                custom: z.ZodOptional<z.ZodJSONSchema>;
+            }, z.core.$strict>;
+            content: z.ZodObject<{
+                kind: z.ZodEnum<{
+                    text: "text";
+                    html: "html";
+                    markdown: "markdown";
+                    design: "design";
+                }>;
+                text: z.ZodString;
+            }, z.core.$strict>;
+            files: z.ZodArray<z.ZodObject<{
+                path: z.ZodString;
+                mediaType: z.ZodString;
+                encoding: z.ZodEnum<{
+                    utf8: "utf8";
+                    base64: "base64";
+                }>;
+                data: z.ZodString;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const publishResultSchema: z.ZodObject<{
+    revisionId: z.ZodString;
+    version: z.ZodNumber;
+    url: z.ZodURL;
+    artifactId: z.ZodString;
+}, z.core.$strict>;

package/src/index.js

@@ -0,0 +1,187 @@
+import { z } from 'zod';
+const identifier = z.string().min(1).max(128);
+const requestId = z.string().min(8).max(128);
+export const contentKinds = ['html', 'markdown', 'text', 'design'];
+const fileSchema = z.strictObject({
+    path: z.string().min(1).max(240).refine((path) => path === path.normalize('NFC') && !/[:\\%\x00-\x1f\x7f]/.test(path) && path.split('/').every((part) => part !== '' && part !== '.' && part !== '..'), 'Use a normalized relative file path'),
+    mediaType: z.string().max(128).regex(/^[a-zA-Z0-9!#$&^_.+-]+\/[a-zA-Z0-9!#$&^_.+-]+$/),
+    encoding: z.enum(['utf8', 'base64']),
+    data: z.string().max(1_398_104).refine((data) => data.isWellFormed(), 'File text must contain well-formed Unicode'),
+}).superRefine((file, context) => {
+    if (file.encoding === 'base64' && Buffer.from(file.data, 'base64').toString('base64') !== file.data)
+        context.addIssue({ code: 'custom', path: ['data'], message: 'Use canonical padded base64' });
+});
+const canvasId = z.string().regex(/^[A-Za-z0-9_-]{1,40}$/, 'Use 1 to 40 letters, digits, underscores, or hyphens').refine((id) => id !== '__proto__', 'Use an id other than __proto__');
+const boardPath = z.string().regex(/^boards\/[A-Za-z0-9_][A-Za-z0-9_.-]*\.html$/, 'Use a board path such as boards/Home.html');
+const coordinate = z.number().min(-1_000_000).max(1_000_000);
+const extent = z.number().min(40).max(8000);
+const label = z.string().min(1).max(256);
+// An oversized count or a bad key aborts before any entry is parsed, so an oversized collection reports one issue.
+// Keys are read from the raw object because a zod record skips a __proto__ key without checking it.
+function keyed(key, value, max, noun) {
+    return z.unknown().superRefine((input, context) => {
+        if (typeof input !== 'object' || input === null || Array.isArray(input))
+            return;
+        const keys = Object.keys(input);
+        if (keys.length > max) {
+            context.addIssue({ code: 'too_big', origin: 'object', maximum: max, inclusive: true, input, continue: false, message: `A canvas holds at most ${max} ${noun}` });
+            return;
+        }
+        for (const name of keys) {
+            const result = key.safeParse(name);
+            if (!result.success)
+                context.addIssue({ code: 'invalid_key', origin: 'record', issues: result.error.issues, input: name, path: [name], continue: false, message: result.error.issues[0].message });
+        }
+    }).pipe(z.record(z.string(), value));
+}
+export const canvasIndexSchema = z.strictObject({
+    v: z.literal(1),
+    boards: keyed(boardPath, z.strictObject({ x: coordinate, y: coordinate, w: extent, h: extent, title: label.optional(), page: canvasId.optional() }), 32, 'boards'),
+    order: z.array(z.unknown()).min(1, 'A canvas needs at least one board').max(32, { message: 'A canvas holds at most 32 boards', abort: true }).pipe(z.array(boardPath)),
+    notes: keyed(canvasId, z.strictObject({ x: coordinate, y: coordinate, text: z.string(), w: extent.optional(), page: canvasId.optional() }), 200, 'notes').optional(),
+    pages: z.array(z.unknown()).max(32, { message: 'A canvas holds at most 32 pages', abort: true }).pipe(z.array(z.strictObject({ id: canvasId, name: label }))).optional(),
+}).superRefine((index, context) => {
+    const ordered = new Set();
+    index.order.forEach((path, position) => {
+        if (!Object.hasOwn(index.boards, path))
+            context.addIssue({ code: 'custom', path: ['order', position], message: `Canvas order names ${path}, which is not a board` });
+        else if (ordered.has(path))
+            context.addIssue({ code: 'custom', path: ['order', position], message: `Canvas order lists ${path} more than once` });
+        ordered.add(path);
+    });
+    for (const path of Object.keys(index.boards))
+        if (!ordered.has(path))
+            context.addIssue({ code: 'custom', path: ['order'], message: `Canvas order omits board ${path}` });
+    const pages = new Set();
+    index.pages?.forEach(({ id }, position) => {
+        if (pages.has(id))
+            context.addIssue({ code: 'custom', path: ['pages', position, 'id'], message: `Canvas page ${id} is declared more than once` });
+        pages.add(id);
+    });
+    for (const [path, board] of Object.entries(index.boards))
+        if (board.page !== undefined && !pages.has(board.page))
+            context.addIssue({ code: 'custom', path: ['boards', path, 'page'], message: `Canvas board ${path} names unknown page ${board.page}` });
+    for (const [id, note] of Object.entries(index.notes ?? {}))
+        if (note.page !== undefined && !pages.has(note.page))
+            context.addIssue({ code: 'custom', path: ['notes', id, 'page'], message: `Canvas note ${id} names unknown page ${note.page}` });
+});
+export const snapshotSchema = z.strictObject({
+    metadata: z.strictObject({ title: z.string().min(1).max(256), description: z.string().max(8192), custom: z.json().optional() }),
+    content: z.strictObject({ kind: z.enum(contentKinds), text: z.string().max(1_048_576).refine((text) => text.isWellFormed(), 'Content must contain well-formed Unicode') }),
+    files: z.array(fileSchema).max(32),
+}).superRefine((snapshot, context) => {
+    const paths = snapshot.files.map((file) => file.path);
+    if (paths.some((path, index) => paths.some((other, otherIndex) => index !== otherIndex && (path === other || other.startsWith(`${path}/`)))))
+        context.addIssue({ code: 'custom', path: ['files'], message: 'File paths must be unique and cannot contain another file' });
+    const bytes = Buffer.byteLength(JSON.stringify(snapshot.metadata)) + Buffer.byteLength(snapshot.content.text) + snapshot.files.reduce((total, file) => total + Buffer.byteLength(file.path) + Buffer.byteLength(file.mediaType) + decodeFile(file).length, 0);
+    if (bytes > 1_048_576)
+        context.addIssue({ code: 'custom', message: 'A revision must fit within 1 MiB of decoded content and metadata' });
+    // A request body can reach 8 MiB, so the index of an oversized design is not parsed.
+    if (snapshot.content.kind !== 'design' || bytes > 1_048_576)
+        return;
+    const canvas = readCanvas(snapshot);
+    if (!canvas.success)
+        for (const issue of canvas.issues)
+            context.addIssue({ ...issue });
+});
+function readCanvas({ content, files }) {
+    let value;
+    try {
+        value = JSON.parse(content.text);
+    }
+    catch {
+        return { success: false, issues: [{ code: 'custom', path: ['content', 'text'], message: 'Design content must be a canvas index in JSON' }] };
+    }
+    const index = canvasIndexSchema.safeParse(value);
+    if (!index.success)
+        return { success: false, issues: index.error.issues.map((issue) => ({ ...issue, path: ['content', 'text', ...issue.path] })) };
+    const positions = new Map(files.map((file, position) => [file.path, position]));
+    const boards = [];
+    const issues = [];
+    for (const path of index.data.order) {
+        const position = positions.get(path);
+        if (position === undefined) {
+            issues.push({ code: 'custom', path: ['content', 'text', 'boards', path], message: `Canvas board ${path} has no matching file` });
+            continue;
+        }
+        const file = files[position];
+        if (file.mediaType !== 'text/html' || file.encoding !== 'utf8')
+            issues.push({ code: 'custom', path: ['files', position], message: `Canvas board ${path} must be a text/html file with utf8 encoding` });
+        else
+            boards.push({ ...index.data.boards[path], path, html: file.data });
+    }
+    return issues.length ? { success: false, issues } : { success: true, data: { index: index.data, boards } };
+}
+export function parseCanvas(snapshot) {
+    if (snapshot.content.kind !== 'design')
+        throw new TypeError('Only a design snapshot has a canvas');
+    const canvas = readCanvas(snapshot);
+    if (!canvas.success)
+        throw new z.ZodError(canvas.issues);
+    return canvas.data;
+}
+export const projectNameSchema = z.string().normalize('NFC').trim().min(1).max(80).refine((name) => name.isWellFormed() && !/\p{Cc}/u.test(name), 'Use a project name without control characters');
+const response = z.enum(['full', 'compact']).optional();
+// The .md check aborts so a file-style name gets the suffix hint instead of the generic pattern message.
+export const slugSchema = z.string().min(1).max(160)
+    .refine((slug) => !slug.endsWith('.md'), { message: 'Remove the .md suffix: a slug names a page, not a file', abort: true })
+    .regex(/^[a-z0-9]+(-[a-z0-9]+)*(\/[a-z0-9]+(-[a-z0-9]+)*)*$/, 'Use lowercase kebab-case segments separated by /, such as concepts/rag');
+export const createSchema = z.strictObject({ requestId, snapshot: snapshotSchema, project: projectNameSchema.optional(), slug: slugSchema.optional(), response });
+export const readByIdSchema = z.strictObject({ artifactId: identifier, revisionId: identifier.optional(), response });
+export const readSchema = z.strictObject({ artifactId: identifier.optional(), project: projectNameSchema.optional(), slug: slugSchema.optional(), revisionId: identifier.optional(), response })
+    .refine((input) => (input.artifactId === undefined) !== (input.slug === undefined) && (input.project === undefined || input.slug !== undefined), 'Specify exactly one of artifactId or slug; project applies only with slug');
+export const updateSchema = z.strictObject({ requestId, artifactId: identifier, expectedRevisionId: identifier, snapshot: snapshotSchema, response });
+export const publishSchema = z.strictObject({ requestId, artifactId: identifier, revisionId: identifier, expectedPublicationVersion: z.number().int().nonnegative() });
+export const deleteSchema = z.strictObject({ requestId, artifactId: identifier, expectedRevisionId: identifier, expectedPublicationVersion: z.number().int().nonnegative() });
+export const deleteResultSchema = z.strictObject({ artifactId: identifier });
+export const moveSchema = z.strictObject({ requestId, artifactId: identifier, project: projectNameSchema.nullable().optional(), slug: slugSchema.nullable().optional() })
+    .refine((input) => input.project !== undefined || input.slug !== undefined, 'Specify project, slug, or both; null clears either');
+export const moveResultSchema = z.strictObject({ artifactId: identifier, project: z.string().nullable() });
+export const shareSchema = z.strictObject({ requestId, artifactId: identifier, email: z.string().trim().toLowerCase().pipe(z.email().max(254)).meta({ format: 'email', description: 'Email address, trimmed and lowercased; at most 254 characters after trimming' }), notify: z.boolean().optional(), requireNew: z.literal(true).optional() });
+export const unshareSchema = z.strictObject({ requestId, artifactId: identifier, shareId: identifier });
+export const listSharesSchema = z.strictObject({ artifactId: identifier });
+export const shareResultSchema = z.strictObject({ shareId: identifier, artifactId: identifier, kind: z.literal('email'), value: z.email(), createdAt: z.iso.datetime() });
+export const notificationSchema = z.union([
+    z.strictObject({ status: z.literal('requested') }),
+    z.strictObject({ status: z.literal('skipped'), reason: z.literal('disabled') }),
+    z.strictObject({ status: z.literal('skipped'), reason: z.literal('rate_limited'), retryAt: z.iso.datetime() }),
+]);
+export const shareCommandResultSchema = shareResultSchema.extend({ notification: notificationSchema.optional() });
+export const unshareResultSchema = z.strictObject({ artifactId: identifier, shareId: identifier });
+export const exportSchema = z.strictObject({ artifactId: identifier, revisionId: identifier });
+export const listSchema = z.strictObject({ limit: z.number().int().min(1).max(100).default(25), cursor: identifier.optional(), project: projectNameSchema.optional() });
+export const searchSchema = z.strictObject({
+    query: z.string().trim().min(1).max(256),
+    project: projectNameSchema.optional(),
+    limit: z.number().int().min(1).max(25).default(10),
+    cursor: z.string().regex(/^\d{1,6}$/, 'Use the nextCursor from a previous search').optional(),
+});
+export const searchHitSchema = z.strictObject({ artifactId: identifier, project: z.string().nullable(), slug: z.string().nullable(), title: z.string(), snippet: z.string(), rank: z.number() });
+export const searchResultSchema = z.strictObject({ items: z.array(searchHitSchema).max(25), nextCursor: z.string().nullable() });
+export const libraryQuerySchema = z.strictObject({
+    q: z.string().trim().max(256).default(''),
+    status: z.enum(['all', 'published', 'unpublished', 'pending']).default('all'),
+    project: projectNameSchema.optional(),
+    cursor: identifier.optional(),
+});
+export const historySchema = z.strictObject({ artifactId: identifier, limit: z.number().int().min(1).max(10).default(5), beforeSequence: z.number().int().positive().optional(), response: z.enum(['full', 'summary']).optional() });
+export const issueGrantSchema = z.strictObject({ artifactId: identifier, state: z.string().min(16).max(256) });
+export const consumeGrantSchema = issueGrantSchema.extend({ code: z.string().min(32).max(128) });
+export const viewerSchema = z.strictObject({ artifactId: identifier, userId: identifier, sessionId: identifier, expiresAt: z.number().int().positive() });
+export class ArtifactError extends Error {
+    code;
+    details;
+    constructor(code, message, details = {}) {
+        super(message);
+        this.code = code;
+        this.details = details;
+    }
+}
+export function decodeFile(file) {
+    return Buffer.from(file.data, file.encoding === 'utf8' ? 'utf8' : 'base64');
+}
+export const publicationSchema = z.strictObject({ revisionId: identifier, version: z.number().int().positive(), url: z.url() });
+export const revisionSchema = z.strictObject({ id: identifier, parentRevisionId: identifier.nullable(), sequence: z.number().int().positive(), authorUserId: identifier, authorClientId: identifier, createdAt: z.iso.datetime(), sha256: z.string().regex(/^[a-f0-9]{64}$/), snapshot: snapshotSchema });
+export const artifactReadSchema = z.strictObject({ artifactId: identifier, ownerId: identifier, headRevisionId: identifier, project: z.string().nullable(), slug: z.string().nullable(), publication: publicationSchema.nullable(), revision: revisionSchema });
+export const sharedReadSchema = z.strictObject({ artifactId: identifier, ownerName: z.string().default('Usuario de Artifacts'), publication: publicationSchema, revision: revisionSchema.pick({ id: true, createdAt: true, sha256: true, snapshot: true }) });
+export const publishResultSchema = publicationSchema.extend({ artifactId: identifier });

package/src/serialization.d.ts

@@ -0,0 +1,2 @@
+export declare function canonicalJson(value: unknown): string;
+export declare function sha256(value: string | Uint8Array): Promise<string>;

package/src/serialization.js

@@ -0,0 +1,11 @@
+export function canonicalJson(value) {
+    return JSON.stringify(value, (_key, item) => {
+        if (item && typeof item === 'object' && !Array.isArray(item))
+            return Object.fromEntries(Object.entries(item).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0));
+        return item;
+    });
+}
+export async function sha256(value) {
+    const bytes = typeof value === 'string' ? new TextEncoder().encode(value) : new Uint8Array(value);
+    return Buffer.from(await crypto.subtle.digest('SHA-256', bytes)).toString('hex');
+}

package/src/workflow.d.ts

@@ -0,0 +1,75 @@
+import { type ArtifactRead, type Revision, type Snapshot, type UpdateInput } from './index.ts';
+export type { UpdateInput } from './index.ts';
+export type AttachmentSummary = {
+    path: string;
+    mediaType: string;
+    encoding: 'utf8' | 'base64';
+    decodedBytes: number;
+    sha256: string;
+};
+export type RevisionSummary = Omit<Revision, 'snapshot'> & {
+    metadata: Pick<Snapshot['metadata'], 'title' | 'description'>;
+    content: {
+        kind: Snapshot['content']['kind'];
+        utf8Bytes: number;
+    };
+    files: AttachmentSummary[];
+};
+export type CompactArtifactRead = Omit<ArtifactRead, 'revision'> & {
+    revision: RevisionSummary;
+};
+export type MetadataChange = {
+    field: 'title' | 'description';
+    before: string;
+    after: string;
+} | {
+    field: 'custom';
+    before?: Snapshot['metadata']['custom'];
+    after?: Snapshot['metadata']['custom'];
+};
+export type AttachmentChange = {
+    path: string;
+    change: 'added';
+    before: null;
+    after: AttachmentSummary;
+} | {
+    path: string;
+    change: 'removed';
+    before: AttachmentSummary;
+    after: null;
+} | {
+    path: string;
+    change: 'changed';
+    before: AttachmentSummary;
+    after: AttachmentSummary;
+};
+export type RevisionComparison = {
+    beforeRevisionId: string;
+    afterRevisionId: string;
+    metadata: MetadataChange[];
+    content: {
+        before: Snapshot['content'];
+        after: Snapshot['content'];
+        kindChanged: boolean;
+        textChanged: boolean;
+    };
+    files: AttachmentChange[];
+};
+export declare function summarizeRevision(revision: Revision): Promise<RevisionSummary>;
+export declare function compactArtifactRead(document: ArtifactRead): Promise<CompactArtifactRead>;
+export declare function compareRevisions(before: Revision, after: Revision): Promise<RevisionComparison>;
+export type ArtifactEditClient = {
+    read(input: {
+        artifactId: string;
+    }): Promise<ArtifactRead>;
+};
+export type PrepareArtifactEditInput = {
+    artifactId: string;
+    requestId: string;
+    changes: {
+        metadata?: Partial<Snapshot['metadata']>;
+        content?: Partial<Snapshot['content']>;
+        files?: Snapshot['files'];
+    };
+};
+export declare function prepareArtifactEdit(client: ArtifactEditClient, value: PrepareArtifactEditInput): Promise<UpdateInput>;

package/src/workflow.js

@@ -0,0 +1,97 @@
+import { z } from 'zod';
+import { ArtifactError, artifactReadSchema, createSchema, decodeFile, readByIdSchema, snapshotSchema, updateSchema } from "./index.js";
+import { canonicalJson, sha256 } from "./serialization.js";
+async function summarizeFiles(files) {
+    return Promise.all([...files].sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0).map(async ({ path, mediaType, encoding, data }) => {
+        const bytes = decodeFile({ encoding, data });
+        return { path, mediaType, encoding, decodedBytes: bytes.length, sha256: await sha256(bytes) };
+    }));
+}
+export async function summarizeRevision(revision) {
+    const { snapshot, ...identity } = revision;
+    return {
+        ...identity,
+        metadata: { title: snapshot.metadata.title, description: snapshot.metadata.description },
+        content: { kind: snapshot.content.kind, utf8Bytes: Buffer.byteLength(snapshot.content.text) },
+        files: await summarizeFiles(snapshot.files),
+    };
+}
+export async function compactArtifactRead(document) {
+    const { revision, ...identity } = document;
+    return { ...identity, revision: await summarizeRevision(revision) };
+}
+export async function compareRevisions(before, after) {
+    const metadata = [];
+    for (const field of ['title', 'description']) {
+        if (before.snapshot.metadata[field] !== after.snapshot.metadata[field])
+            metadata.push({ field, before: before.snapshot.metadata[field], after: after.snapshot.metadata[field] });
+    }
+    if (canonicalJson(before.snapshot.metadata.custom) !== canonicalJson(after.snapshot.metadata.custom)) {
+        metadata.push({ field: 'custom', before: structuredClone(before.snapshot.metadata.custom), after: structuredClone(after.snapshot.metadata.custom) });
+    }
+    const [beforeFiles, afterFiles] = await Promise.all([summarizeFiles(before.snapshot.files), summarizeFiles(after.snapshot.files)]);
+    const beforeByPath = new Map(beforeFiles.map((file) => [file.path, file]));
+    const afterByPath = new Map(afterFiles.map((file) => [file.path, file]));
+    const files = [];
+    for (const path of [...new Set([...beforeByPath.keys(), ...afterByPath.keys()])].sort()) {
+        const previous = beforeByPath.get(path);
+        const next = afterByPath.get(path);
+        if (!previous && next)
+            files.push({ path, change: 'added', before: null, after: next });
+        else if (previous && !next)
+            files.push({ path, change: 'removed', before: previous, after: null });
+        else if (previous && next && (previous.sha256 !== next.sha256 || previous.mediaType !== next.mediaType || previous.encoding !== next.encoding))
+            files.push({ path, change: 'changed', before: previous, after: next });
+    }
+    return {
+        beforeRevisionId: before.id,
+        afterRevisionId: after.id,
+        metadata,
+        content: {
+            before: { ...before.snapshot.content },
+            after: { ...after.snapshot.content },
+            kindChanged: before.snapshot.content.kind !== after.snapshot.content.kind,
+            textChanged: before.snapshot.content.text !== after.snapshot.content.text,
+        },
+        files,
+    };
+}
+const prepareEditSchema = z.strictObject({
+    artifactId: readByIdSchema.shape.artifactId,
+    requestId: createSchema.shape.requestId,
+    changes: z.strictObject({
+        metadata: snapshotSchema.shape.metadata.partial().optional(),
+        content: snapshotSchema.shape.content.partial().optional(),
+        files: snapshotSchema.shape.files.optional(),
+    }),
+});
+function freezeJson(value) {
+    if (value && typeof value === 'object') {
+        for (const child of Object.values(value))
+            freezeJson(child);
+        Object.freeze(value);
+    }
+    return value;
+}
+export async function prepareArtifactEdit(client, value) {
+    const input = prepareEditSchema.parse(structuredClone(value));
+    const current = artifactReadSchema.parse(structuredClone(await client.read({ artifactId: input.artifactId })));
+    if (current.artifactId !== input.artifactId)
+        throw new TypeError('Artifact reader returned a different artifact');
+    if (current.revision.id !== current.headRevisionId)
+        throw new ArtifactError('conflict', 'Artifact reader did not return the current head', { currentRevisionId: current.headRevisionId });
+    const snapshot = current.revision.snapshot;
+    const metadata = { ...snapshot.metadata, ...input.changes.metadata };
+    if (Object.hasOwn(input.changes.metadata ?? {}, 'custom') && input.changes.metadata?.custom === undefined)
+        delete metadata.custom;
+    return freezeJson(updateSchema.parse({
+        artifactId: input.artifactId,
+        requestId: input.requestId,
+        expectedRevisionId: current.headRevisionId,
+        snapshot: {
+            metadata,
+            content: { ...snapshot.content, ...input.changes.content },
+            files: input.changes.files ?? snapshot.files,
+        },
+    }));
+}