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

package/README.md

@@ -3,11 +3,15 @@
 `@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.7
+npm install @yargote/artifacts-contracts@0.1.0-beta.8
 ```
 
 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. `ArtifactRead` and the HTTP summary schema include `slug`, and `ArtifactErrorCode` includes `slug_conflict`.
+
 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yargote/artifacts-contracts",
-  "version": "0.1.0-beta.7",
+  "version": "0.1.0-beta.8",
   "private": false,
   "type": "module",
   "description": "Shared schemas and contracts for Artifacts clients.",

package/src/http.d.ts

@@ -52,6 +52,7 @@ 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;
@@ -97,6 +98,7 @@ export declare const artifactSummarySchema: z.ZodObject<{
     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;
@@ -110,6 +112,7 @@ export declare const listResultSchema: z.ZodObject<{
         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;
@@ -208,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

@@ -10,7 +10,7 @@ export const revisionSummarySchema = revisionSchema.omit({ snapshot: true }).ext
     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(), 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) });
@@ -26,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

@@ -59,6 +59,7 @@ export type Canvas = {
 };
 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<{
@@ -87,12 +88,13 @@ export declare const createSchema: z.ZodObject<{
         }, 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<{
@@ -100,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;
@@ -304,6 +316,7 @@ export type ArtifactSummary = {
     headRevisionId: string;
     createdAt: string;
     project: string | null;
+    slug: string | null;
     publication: Publication | null;
 };
 export type ProjectSummary = {
@@ -327,7 +340,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>;
@@ -381,6 +394,7 @@ export declare const artifactReadSchema: z.ZodObject<{
     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;

package/src/index.js

@@ -122,8 +122,14 @@ export function parseCanvas(snapshot) {
 }
 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 });
-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() });
@@ -167,6 +173,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, project: z.string().nullable(), 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(),