@yargote/artifacts-contracts 0.1.0-beta.1 → 0.1.0-beta.10

package/README.md

@@ -3,11 +3,19 @@
 `@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.1
+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,6 @@
 {
   "name": "@yargote/artifacts-contracts",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.10",
   "private": false,
   "type": "module",
   "description": "Shared schemas and contracts for Artifacts clients.",

package/src/http.d.ts

@@ -33,6 +33,7 @@ export declare const revisionSummarySchema: z.ZodObject<{
             text: "text";
             html: "html";
             markdown: "markdown";
+            design: "design";
         }>;
         utf8Bytes: z.ZodNumber;
     }, z.core.$strict>;
@@ -50,6 +51,8 @@ export declare const revisionSummarySchema: z.ZodObject<{
 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;
@@ -73,6 +76,7 @@ export declare const compactArtifactReadSchema: z.ZodObject<{
                 text: "text";
                 html: "html";
                 markdown: "markdown";
+                design: "design";
             }>;
             utf8Bytes: z.ZodNumber;
         }, z.core.$strict>;
@@ -93,6 +97,8 @@ export declare const artifactSummarySchema: z.ZodObject<{
     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;
@@ -105,6 +111,8 @@ export declare const listResultSchema: z.ZodObject<{
         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;
@@ -113,6 +121,16 @@ export declare const listResultSchema: z.ZodObject<{
     }, 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;
@@ -133,6 +151,7 @@ export declare const historyResultSchema: z.ZodObject<{
                     text: "text";
                     html: "html";
                     markdown: "markdown";
+                    design: "design";
                 }>;
                 text: z.ZodString;
             }, z.core.$strict>;
@@ -168,6 +187,7 @@ export declare const summaryHistoryResultSchema: z.ZodObject<{
                 text: "text";
                 html: "html";
                 markdown: "markdown";
+                design: "design";
             }>;
             utf8Bytes: z.ZodNumber;
         }, z.core.$strict>;
@@ -191,5 +211,10 @@ export declare const httpErrorSchema: z.ZodObject<{
     }, 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

@@ -1,17 +1,19 @@
 import { z } from 'zod';
-import { artifactReadSchema, publicationSchema, revisionSchema, snapshotSchema } from "./index.js";
+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: snapshotSchema.shape.content.shape.kind, utf8Bytes: z.number().int().nonnegative() }),
+    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(), publication: publicationSchema.nullable() });
+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()) }) });
@@ -24,6 +26,19 @@ export function canonicalResource(value) {
         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);

package/src/index.d.ts

@@ -1,4 +1,28 @@
 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;
@@ -10,6 +34,7 @@ export declare const snapshotSchema: z.ZodObject<{
             text: "text";
             html: "html";
             markdown: "markdown";
+            design: "design";
         }>;
         text: z.ZodString;
     }, z.core.$strict>;
@@ -23,6 +48,18 @@ export declare const snapshotSchema: z.ZodObject<{
         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<{
@@ -36,6 +73,7 @@ export declare const createSchema: z.ZodObject<{
                 text: "text";
                 html: "html";
                 markdown: "markdown";
+                design: "design";
             }>;
             text: z.ZodString;
         }, z.core.$strict>;
@@ -49,12 +87,14 @@ export declare const createSchema: z.ZodObject<{
             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 readSchema: z.ZodObject<{
+export declare const readByIdSchema: z.ZodObject<{
     artifactId: z.ZodString;
     revisionId: z.ZodOptional<z.ZodString>;
     response: z.ZodOptional<z.ZodEnum<{
@@ -62,6 +102,16 @@ export declare const readSchema: z.ZodObject<{
         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;
@@ -77,6 +127,7 @@ export declare const updateSchema: z.ZodObject<{
                 text: "text";
                 html: "html";
                 markdown: "markdown";
+                design: "design";
             }>;
             text: z.ZodString;
         }, z.core.$strict>;
@@ -101,6 +152,85 @@ export declare const publishSchema: z.ZodObject<{
     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;
@@ -108,7 +238,35 @@ export declare const exportSchema: z.ZodObject<{
 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<{
@@ -117,6 +275,7 @@ export declare const libraryQuerySchema: z.ZodObject<{
         unpublished: "unpublished";
         pending: "pending";
     }>>;
+    project: z.ZodOptional<z.ZodString>;
     cursor: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export declare const historySchema: z.ZodObject<{
@@ -172,13 +331,26 @@ 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[];
@@ -196,7 +368,7 @@ export type Archive = {
     base64: string;
     sha256: string;
 };
-export type ArtifactErrorCode = 'forbidden' | 'not_found' | 'conflict' | 'request_conflict' | 'invalid_grant';
+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>;
@@ -230,6 +402,7 @@ export declare const revisionSchema: z.ZodObject<{
                 text: "text";
                 html: "html";
                 markdown: "markdown";
+                design: "design";
             }>;
             text: z.ZodString;
         }, z.core.$strict>;
@@ -248,6 +421,8 @@ 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;
@@ -272,6 +447,46 @@ export declare const artifactReadSchema: z.ZodObject<{
                     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>;

package/src/index.js

@@ -1,6 +1,7 @@
 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!#$&^_.+-]+$/),
@@ -10,9 +11,63 @@ const fileSchema = z.strictObject({
     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(['html', 'markdown', 'text']), text: z.string().max(1_048_576).refine((text) => text.isWellFormed(), 'Content must contain well-formed Unicode') }),
+    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);
@@ -21,17 +76,92 @@ export const snapshotSchema = z.strictObject({
     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();
-export const createSchema = z.strictObject({ requestId, snapshot: snapshotSchema, response });
-export const readSchema = z.strictObject({ artifactId: identifier, revisionId: identifier.optional(), response });
+// 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() });
+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() });
@@ -52,5 +182,6 @@ export function decodeFile(file) {
 }
 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, publication: publicationSchema.nullable(), revision: revisionSchema });
+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/workflow.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { ArtifactError, artifactReadSchema, createSchema, decodeFile, readSchema, snapshotSchema, updateSchema } from "./index.js";
+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 }) => {
@@ -57,7 +57,7 @@ export async function compareRevisions(before, after) {
     };
 }
 const prepareEditSchema = z.strictObject({
-    artifactId: readSchema.shape.artifactId,
+    artifactId: readByIdSchema.shape.artifactId,
     requestId: createSchema.shape.requestId,
     changes: z.strictObject({
         metadata: snapshotSchema.shape.metadata.partial().optional(),