@yargote/artifacts-contracts 0.1.0-beta.5 → 0.1.0-beta.7

package/README.md

@@ -3,7 +3,7 @@
 `@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.5
+npm install @yargote/artifacts-contracts@0.1.0-beta.7
 ```
 
 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.
@@ -11,3 +11,5 @@ The root export contains domain schemas and types. `/workflow` contains `prepare
 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.5",
+  "version": "0.1.0-beta.7",
   "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>;
@@ -74,6 +75,7 @@ export declare const compactArtifactReadSchema: z.ZodObject<{
                 text: "text";
                 html: "html";
                 markdown: "markdown";
+                design: "design";
             }>;
             utf8Bytes: z.ZodNumber;
         }, z.core.$strict>;
@@ -146,6 +148,7 @@ export declare const historyResultSchema: z.ZodObject<{
                     text: "text";
                     html: "html";
                     markdown: "markdown";
+                    design: "design";
                 }>;
                 text: z.ZodString;
             }, z.core.$strict>;
@@ -181,6 +184,7 @@ export declare const summaryHistoryResultSchema: z.ZodObject<{
                 text: "text";
                 html: "html";
                 markdown: "markdown";
+                design: "design";
             }>;
             utf8Bytes: z.ZodNumber;
         }, z.core.$strict>;

package/src/http.js

@@ -1,12 +1,12 @@
 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 });

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,16 @@ 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 createSchema: z.ZodObject<{
     requestId: z.ZodString;
@@ -37,6 +72,7 @@ export declare const createSchema: z.ZodObject<{
                 text: "text";
                 html: "html";
                 markdown: "markdown";
+                design: "design";
             }>;
             text: z.ZodString;
         }, z.core.$strict>;
@@ -79,6 +115,7 @@ export declare const updateSchema: z.ZodObject<{
                 text: "text";
                 html: "html";
                 markdown: "markdown";
+                design: "design";
             }>;
             text: z.ZodString;
         }, z.core.$strict>;
@@ -124,6 +161,63 @@ export declare const moveResultSchema: z.ZodObject<{
     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;
@@ -197,6 +291,13 @@ 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;
@@ -260,6 +361,7 @@ export declare const revisionSchema: z.ZodObject<{
                 text: "text";
                 html: "html";
                 markdown: "markdown";
+                design: "design";
             }>;
             text: z.ZodString;
         }, z.core.$strict>;
@@ -303,6 +405,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,7 +76,50 @@ 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, project: projectNameSchema.optional(), response });
@@ -32,6 +130,17 @@ export const deleteSchema = z.strictObject({ requestId, artifactId: identifier,
 export const deleteResultSchema = z.strictObject({ artifactId: identifier });
 export const moveSchema = z.strictObject({ requestId, artifactId: identifier, project: projectNameSchema.nullable() });
 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 libraryQuerySchema = z.strictObject({
@@ -59,4 +168,5 @@ 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, project: 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 });