@isardsat/editorial-server 6.13.2 → 6.15.0

package/dist/lib/schema.d.ts

@@ -2,12 +2,16 @@ export declare function createSchema(configDirectory: string): Promise<Record<st
     displayName: string;
     fields: Record<string, {
         [x: string]: unknown;
-        type: "string" | "number" | "boolean" | "url" | "date" | "datetime" | "markdown" | "color" | "select";
+        type: "string" | "number" | "boolean" | "url" | "date" | "datetime" | "markdown" | "color" | "select" | "multiselect";
         displayName: string;
         optional: boolean;
         displayExtra?: string | undefined;
         placeholder?: string | undefined;
         showInSummary?: boolean | undefined;
+        options?: string[] | undefined;
+        maxSelectedOptions?: number | undefined;
+        minSelectedOptions?: number | undefined;
+        isUploadedFile?: boolean | undefined;
     }>;
     filterBy?: string | undefined;
     singleton?: boolean | undefined;

package/dist/lib/storage.d.ts

@@ -4,12 +4,16 @@ export declare function createStorage(dataDirectory: string): {
         displayName: string;
         fields: Record<string, {
             [x: string]: unknown;
-            type: "string" | "number" | "boolean" | "url" | "date" | "datetime" | "markdown" | "color" | "select";
+            type: "string" | "number" | "boolean" | "url" | "date" | "datetime" | "markdown" | "color" | "select" | "multiselect";
             displayName: string;
             optional: boolean;
             displayExtra?: string | undefined;
             placeholder?: string | undefined;
             showInSummary?: boolean | undefined;
+            options?: string[] | undefined;
+            maxSelectedOptions?: number | undefined;
+            minSelectedOptions?: number | undefined;
+            isUploadedFile?: boolean | undefined;
         }>;
         filterBy?: string | undefined;
         singleton?: boolean | undefined;

package/dist/lib/utils/meta-schema.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/utils/meta-schema.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/utils/schema.d.ts

@@ -0,0 +1,30 @@
+type GenerateMetaSchemaOptions = {
+    /**
+     * Fields that exist in the Editorial's schema but should not be validated by the schema.
+     * These fields will be allowed without causing validation errors.
+     */
+    allowedExtraFields?: string[];
+};
+export declare function generateMetaSchema(options?: GenerateMetaSchemaOptions): {
+    $schema: string;
+    title: string;
+    type: string;
+    additionalProperties: {
+        $ref: string;
+    };
+    definitions: {
+        SchemaItem: {
+            type: string;
+            properties: Record<string, any>;
+            required: string[];
+            additionalProperties: boolean;
+        };
+        Field: {
+            type: string;
+            properties: Record<string, any>;
+            required: string[];
+            additionalProperties: boolean;
+        };
+    };
+};
+export {};

package/dist/lib/utils/schema.js

@@ -0,0 +1,105 @@
+import { EditorialSchemaItemFieldSchema, EditorialSchemaItemFieldType, EditorialSchemaItemSchema, } from "@isardsat/editorial-common";
+import { z } from "zod";
+export function generateMetaSchema(options = {}) {
+    const { allowedExtraFields = [] } = options;
+    function generateDefinition(schema) {
+        const fieldShape = schema.shape;
+        const properties = {};
+        const required = [];
+        for (const key in fieldShape) {
+            const zodField = fieldShape[key];
+            // Handle the "type" field separately since it's an enum with specific options
+            if (key === "type") {
+                properties[key] = {
+                    type: "string",
+                    enum: EditorialSchemaItemFieldType.options,
+                };
+                required.push(key);
+                continue;
+            }
+            // Unwrap ALL wrappers to get the inner type
+            let innerField = zodField;
+            let isOptional = false;
+            let defaultValue = undefined;
+            // Loop to unwrap all layers (ZodDefault, ZodOptional, ZodNullable, etc.)
+            while (innerField) {
+                if (innerField instanceof z.ZodOptional) {
+                    isOptional = true;
+                    innerField = innerField.unwrap();
+                }
+                else if (innerField instanceof z.ZodDefault) {
+                    isOptional = true; // Un camp amb default és efectivament opcional
+                    defaultValue = innerField._def.defaultValue;
+                    innerField = innerField._def.innerType;
+                }
+                else if (innerField instanceof z.ZodNullable) {
+                    innerField = innerField.unwrap();
+                }
+                else {
+                    // No more wrappers, exit loop
+                    break;
+                }
+            }
+            // Check the actual base type
+            if (innerField instanceof z.ZodString) {
+                properties[key] = { type: "string" };
+            }
+            else if (innerField instanceof z.ZodBoolean) {
+                properties[key] = {
+                    type: "boolean",
+                    ...(defaultValue !== undefined && { default: defaultValue }),
+                };
+            }
+            else if (innerField instanceof z.ZodNumber) {
+                properties[key] = {
+                    type: "number",
+                    ...(defaultValue !== undefined && { default: defaultValue }),
+                };
+            }
+            else if (innerField instanceof z.ZodArray) {
+                properties[key] = { type: "array", items: { type: "string" } };
+            }
+            else if (innerField instanceof z.ZodEnum) {
+                properties[key] = {
+                    type: "string",
+                    enum: innerField.options,
+                };
+            }
+            else {
+                console.warn(`Unknown Zod type for field "${key}"`);
+                properties[key] = {};
+            }
+            // Add to required if not optional
+            if (!isOptional) {
+                required.push(key);
+            }
+        }
+        for (const field of allowedExtraFields) {
+            if (!(field in properties)) {
+                properties[field] = {}; // Allow any value
+            }
+        }
+        return {
+            type: "object",
+            properties,
+            required,
+            additionalProperties: false,
+        };
+    }
+    const fieldDefinition = generateDefinition(EditorialSchemaItemFieldSchema);
+    const schemaItemDefinition = generateDefinition(EditorialSchemaItemSchema);
+    schemaItemDefinition.properties.fields = {
+        type: "object",
+        additionalProperties: { $ref: "#/definitions/Field" },
+    };
+    return {
+        $schema: "http://json-schema.org/draft-07/schema#",
+        title: "Editorial Schema",
+        type: "object",
+        additionalProperties: { $ref: "#/definitions/SchemaItem" },
+        definitions: {
+            SchemaItem: schemaItemDefinition,
+            Field: fieldDefinition,
+        },
+    };
+}

package/dist/routes/actions.js

@@ -7,6 +7,7 @@ export function createActionRoutes(storage, hooks) {
     app.openapi(createRoute({
         method: "post",
         path: "/publish",
+        summary: "Trigger the publishing process",
         request: {
             body: {
                 content: {
@@ -26,6 +27,7 @@ export function createActionRoutes(storage, hooks) {
                 description: "Trigger the publishing process",
             },
         },
+        tags: ["Actions"],
     }), 
     // TODO: Don't async, let the promises run in the background.
     async (c) => {
@@ -62,6 +64,7 @@ export function createActionRoutes(storage, hooks) {
     app.openapi(createRoute({
         method: "post",
         path: "/pull",
+        summary: "Trigger the pull process",
         request: {
             body: {
                 content: {
@@ -76,6 +79,7 @@ export function createActionRoutes(storage, hooks) {
                 description: "Trigger the pull process",
             },
         },
+        tags: ["Actions"],
     }), async (c) => {
         const { author } = c.req.valid("json");
         await hooks.onPull(author);
@@ -84,6 +88,7 @@ export function createActionRoutes(storage, hooks) {
     app.openapi(createRoute({
         method: "post",
         path: "/push",
+        summary: "Trigger the push process",
         request: {
             body: {
                 content: {
@@ -98,6 +103,7 @@ export function createActionRoutes(storage, hooks) {
                 description: "Trigger the push process",
             },
         },
+        tags: ["Actions"],
     }), async (c) => {
         const { author } = c.req.valid("json");
         await hooks.onPush(author);

package/dist/routes/admin.js

@@ -1,8 +1,7 @@
 import { serveStatic } from "@hono/node-server/serve-static";
-import { OpenAPIHono } from "@hono/zod-openapi";
+import { OpenAPIHono, z } from "@hono/zod-openapi";
 import { createRequire } from "node:module";
 import path from "path";
-import { z } from "@hono/zod-openapi";
 export function createAdminRoutes(config) {
     const app = new OpenAPIHono();
     // TODO: This is package manager dependent
@@ -20,7 +19,8 @@ export function createAdminRoutes(config) {
                 content: {
                     "application/json": {
                         schema: z.object({
-                            firebase: z.object({
+                            firebase: z
+                                .object({
                                 apiKey: z.string(),
                                 authDomain: z.string(),
                                 databaseURL: z.string(),
@@ -28,13 +28,15 @@ export function createAdminRoutes(config) {
                                 storageBucket: z.string(),
                                 messagingSenderId: z.string(),
                                 dbUsersPath: z.string(),
-                            }).optional(),
+                            })
+                                .optional(),
                         }),
                     },
                 },
                 description: "Firebase configuration for admin",
             },
         },
+        tags: ["Admin"],
     }, (c) => {
         return c.json({ firebase: config.firebase });
     });

package/dist/routes/config.js

@@ -16,6 +16,7 @@ export function createConfigRoutes(config) {
                 description: "Editorial configuration",
             },
         },
+        tags: ["Config"],
     }, (c) => {
         return c.json(config);
     });

package/dist/routes/data.js

@@ -1,5 +1,6 @@
 import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
-import { EditorialDataItemSchema, EditorialDataSchema, EditorialSchemaSchema, } from "@isardsat/editorial-common";
+import { EditorialDataItemSchema, EditorialDataSchema, EditorialSchemaSchema, getOptionsReference, } from "@isardsat/editorial-common";
+import { generateMetaSchema } from "../lib/utils/schema.js";
 function createCache() {
     let schemaCache = null;
     const contentCache = new Map();
@@ -36,6 +37,86 @@ function createCache() {
         },
     };
 }
+/**
+ * Resolves uploaded file paths to full URLs for an item.
+ */
+function resolveFileUrls(item, schema, itemType, origin) {
+    const resolvedItem = { ...item };
+    const itemSchema = schema[itemType];
+    if (!itemSchema)
+        return resolvedItem;
+    for (const [key, value] of Object.entries(resolvedItem)) {
+        if (!itemSchema.fields[key]?.isUploadedFile)
+            continue;
+        if (typeof value !== "string")
+            continue;
+        if (value.startsWith("http"))
+            continue;
+        resolvedItem[key] = `${origin}/${value}`;
+    }
+    return resolvedItem;
+}
+/**
+ * Resolves referenced fields in an item, replacing IDs with full objects.
+ * Recursively resolves nested references.
+ */
+function resolveReferences(item, schema, itemType, content, origin, resolvedIds = new Set()) {
+    const itemIdentifier = `${itemType}:${item.id}`;
+    // Prevent circular references
+    if (resolvedIds.has(itemIdentifier)) {
+        return resolveFileUrls(item, schema, itemType, origin);
+    }
+    resolvedIds.add(itemIdentifier);
+    // First resolve file URLs for the current item
+    let resolvedItem = resolveFileUrls(item, schema, itemType, origin);
+    const itemSchema = schema[itemType];
+    if (!itemSchema)
+        return resolvedItem;
+    for (const [fieldKey, fieldConfig] of Object.entries(itemSchema.fields)) {
+        if (fieldConfig.type !== "select" && fieldConfig.type !== "multiselect") {
+            continue;
+        }
+        const referencedType = getOptionsReference(fieldConfig.options);
+        if (!referencedType)
+            continue;
+        const referencedCollection = content[referencedType];
+        if (!referencedCollection)
+            continue;
+        const fieldValue = item[fieldKey];
+        if (fieldConfig.type === "select" && typeof fieldValue === "string") {
+            // Single reference - replace ID with full object
+            const referencedItem = referencedCollection[fieldValue];
+            if (referencedItem) {
+                // Recursively resolve nested references
+                resolvedItem[fieldKey] = resolveReferences(referencedItem, schema, referencedType, content, origin, new Set(resolvedIds));
+            }
+        }
+        else if (fieldConfig.type === "multiselect" &&
+            Array.isArray(fieldValue)) {
+            // Multiple references - replace IDs with full objects
+            resolvedItem[fieldKey] = fieldValue
+                .map((id) => {
+                const referencedItem = referencedCollection[id];
+                if (!referencedItem)
+                    return null;
+                // Recursively resolve nested references
+                return resolveReferences(referencedItem, schema, referencedType, content, origin, new Set(resolvedIds));
+            })
+                .filter(Boolean);
+        }
+    }
+    return resolvedItem;
+}
+/**
+ * Resolves all references in a collection.
+ */
+function resolveCollectionReferences(collection, schema, itemType, content, origin) {
+    const resolvedCollection = {};
+    for (const [itemKey, item] of Object.entries(collection)) {
+        resolvedCollection[itemKey] = resolveReferences(item, schema, itemType, content, origin);
+    }
+    return resolvedCollection;
+}
 export function createDataRoutes(config, storage) {
     const app = new OpenAPIHono();
     const cache = createCache();
@@ -43,6 +124,7 @@ export function createDataRoutes(config, storage) {
     app.openapi(createRoute({
         method: "get",
         path: "/schema",
+        summary: "Get Editorial schema",
         responses: {
             200: {
                 content: {
@@ -53,6 +135,7 @@ export function createDataRoutes(config, storage) {
                 description: "Get Editorial schema",
             },
         },
+        tags: ["Schema"],
     }), async (c) => {
         const schema = await cache.getSchema(storage);
         return c.json(schema);
@@ -60,6 +143,7 @@ export function createDataRoutes(config, storage) {
     app.openapi(createRoute({
         method: "get",
         path: "/data",
+        summary: "Get all Editorial data",
         request: {
             query: z.object({
                 lang: z
@@ -70,6 +154,13 @@ export function createDataRoutes(config, storage) {
                     example: "es_ES",
                 }),
                 preview: z.string().optional(),
+                resolve: z
+                    .string()
+                    .optional()
+                    .openapi({
+                    param: { name: "resolve", in: "query" },
+                    description: "Resolve referenced fields to full objects",
+                }),
             }),
         },
         responses: {
@@ -82,14 +173,26 @@ export function createDataRoutes(config, storage) {
                 description: "Get all Editorial data",
             },
         },
+        tags: ["Data"],
     }), async (c) => {
-        const { preview } = c.req.valid("query");
+        const { preview, resolve } = c.req.valid("query");
         const content = await cache.getContent(storage, { production: !preview });
-        return c.json(content);
+        if (!resolve) {
+            return c.json(content);
+        }
+        const origin = preview ? new URL(c.req.url).origin : publicFilesUrl;
+        // Resolve references for all collections
+        const schema = await cache.getSchema(storage);
+        const resolvedContent = {};
+        for (const [itemType, collection] of Object.entries(content)) {
+            resolvedContent[itemType] = resolveCollectionReferences(collection, schema, itemType, content, origin);
+        }
+        return c.json(resolvedContent);
     });
     app.openapi(createRoute({
         method: "get",
         path: "/data/{itemType}",
+        summary: "Get objects data by type",
         request: {
             params: z.object({
                 itemType: z.string().openapi({
@@ -106,6 +209,13 @@ export function createDataRoutes(config, storage) {
                     example: "es_ES",
                 }),
                 preview: z.string().optional(),
+                resolve: z
+                    .string()
+                    .optional()
+                    .openapi({
+                    param: { name: "resolve", in: "query" },
+                    description: "Resolve referenced fields to full objects",
+                }),
             }),
         },
         responses: {
@@ -121,9 +231,10 @@ export function createDataRoutes(config, storage) {
                 description: "Collection not found",
             },
         },
+        tags: ["Data"],
     }), async (c) => {
         const { itemType } = c.req.valid("param");
-        const { lang, preview } = c.req.valid("query");
+        const { lang, preview, resolve } = c.req.valid("query");
         const origin = preview ? new URL(c.req.url).origin : publicFilesUrl;
         const content = await cache.getContent(storage, {
             production: !preview,
@@ -149,6 +260,11 @@ export function createDataRoutes(config, storage) {
                 }
             }
         }
+        // Resolve references if requested (includes file URL resolution)
+        if (resolve) {
+            return c.json(resolveCollectionReferences(collection, schema, itemType, content, origin));
+        }
+        // Apply file URL resolution for non-resolved requests
         for (const [itemKey, itemValue] of Object.entries(collection)) {
             for (const [key, value] of Object.entries(itemValue)) {
                 if (!schema[itemType].fields[key]?.isUploadedFile)
@@ -163,6 +279,7 @@ export function createDataRoutes(config, storage) {
     app.openapi(createRoute({
         method: "get",
         path: "/data/{itemType}/ids",
+        summary: "Get object ids by type",
         request: {
             params: z.object({
                 itemType: z.string().openapi({
@@ -187,6 +304,7 @@ export function createDataRoutes(config, storage) {
                 description: "Item not found",
             },
         },
+        tags: ["Data"],
     }), async (c) => {
         const { itemType } = c.req.valid("param");
         const { preview } = c.req.valid("query");
@@ -199,6 +317,7 @@ export function createDataRoutes(config, storage) {
     app.openapi(createRoute({
         method: "get",
         path: "/data/{itemType}/{id}",
+        summary: "Get object data by type and id",
         request: {
             params: z.object({
                 itemType: z.string().openapi({
@@ -219,6 +338,13 @@ export function createDataRoutes(config, storage) {
                     example: "es_ES",
                 }),
                 preview: z.string().optional(),
+                resolve: z
+                    .string()
+                    .optional()
+                    .openapi({
+                    param: { name: "resolve", in: "query" },
+                    description: "Resolve referenced fields to full objects",
+                }),
             }),
         },
         responses: {
@@ -234,9 +360,10 @@ export function createDataRoutes(config, storage) {
                 description: "Collection or item not found",
             },
         },
+        tags: ["Data"],
     }), async (c) => {
         const { itemType, id } = c.req.valid("param");
-        const { lang, preview } = c.req.valid("query");
+        const { lang, preview, resolve } = c.req.valid("query");
         const origin = preview ? new URL(c.req.url).origin : publicFilesUrl;
         const content = await cache.getContent(storage, {
             production: !preview,
@@ -247,7 +374,7 @@ export function createDataRoutes(config, storage) {
         if (!collection) {
             return c.notFound();
         }
-        const item = collection[id];
+        let item = collection[id];
         if (!item) {
             return c.notFound();
         }
@@ -261,6 +388,12 @@ export function createDataRoutes(config, storage) {
                 }
             }
         }
+        // Resolve references if requested (includes file URL resolution)
+        if (resolve) {
+            item = resolveReferences(item, schema, itemType, content, origin);
+            return c.json(item);
+        }
+        // Apply file URL resolution for non-resolved requests
         for (const [key, value] of Object.entries(item)) {
             if (!schema[itemType].fields[key]?.isUploadedFile)
                 continue;
@@ -273,6 +406,7 @@ export function createDataRoutes(config, storage) {
     app.openapi(createRoute({
         method: "put",
         path: "/data/{itemType}/{id}",
+        summary: "Create or update object data by type and id",
         request: {
             params: z.object({
                 itemType: z.string().openapi({
@@ -303,6 +437,7 @@ export function createDataRoutes(config, storage) {
                 description: "Create a new object",
             },
         },
+        tags: ["Data"],
     }), async (c) => {
         const itemAtts = await c.req.json();
         const newItem = await storage.createItem(itemAtts);
@@ -312,6 +447,7 @@ export function createDataRoutes(config, storage) {
     app.openapi(createRoute({
         method: "patch",
         path: "/data/{itemType}/{id}",
+        summary: "Update object data by type and id",
         request: {
             params: z.object({
                 itemType: z.string().openapi({
@@ -342,6 +478,7 @@ export function createDataRoutes(config, storage) {
                 description: "Update object",
             },
         },
+        tags: ["Data"],
     }), async (c) => {
         const itemAtts = await c.req.json();
         const newItem = await storage.updateItem(itemAtts);
@@ -351,6 +488,7 @@ export function createDataRoutes(config, storage) {
     app.openapi(createRoute({
         method: "delete",
         path: "/data/{itemType}/{id}",
+        summary: "Delete object by type and id",
         request: {
             params: z.object({
                 itemType: z.string().openapi({
@@ -373,11 +511,47 @@ export function createDataRoutes(config, storage) {
                 description: "Delete object",
             },
         },
+        tags: ["Data"],
     }), async (c) => {
         const { itemType, id } = c.req.valid("param");
         await storage.deleteItem({ type: itemType, id });
         cache.invalidateContent();
         return c.json(true, 200);
     });
+    app.openapi(createRoute({
+        method: "get",
+        path: "/meta-schema",
+        summary: "Get Editorial meta-schema",
+        request: {
+            query: z.object({
+                allowedExtraFields: z
+                    .string()
+                    .optional()
+                    .openapi({
+                    param: { name: "allowedExtraFields", in: "query" },
+                    example: "customField,legacyField",
+                    description: "Comma-separated list of extra field names that exist in the Editorial's schema but should not cause validation errors",
+                }),
+            }),
+        },
+        responses: {
+            200: {
+                content: {
+                    "application/json": {
+                        schema: z.record(z.string(), z.any()),
+                    },
+                },
+                description: "JSON Schema meta-schema for the Editorial configuration",
+            },
+        },
+        tags: ["Schema"],
+    }), async (c) => {
+        const { allowedExtraFields: allowedExtraFieldsParam } = c.req.valid("query");
+        const allowedExtraFields = allowedExtraFieldsParam
+            ? allowedExtraFieldsParam.split(",").map((f) => f.trim())
+            : [];
+        const metaSchema = generateMetaSchema({ allowedExtraFields });
+        return c.json(metaSchema);
+    });
     return app;
 }

package/dist/routes/files.js

@@ -14,6 +14,7 @@ export async function createFilesRoutes(config) {
     app.openapi(createRoute({
         method: "get",
         path: "/files",
+        summary: "Get tree of public files with total size",
         request: {
             query: z.object({
                 preview: z.string().optional(),
@@ -29,6 +30,7 @@ export async function createFilesRoutes(config) {
                 description: "Get tree of public files with total size",
             },
         },
+        tags: ["Files"],
     }), 
     // TODO: Index large files from bucket.
     async (c) => {
@@ -109,6 +111,7 @@ export async function createFilesRoutes(config) {
     app.openapi(createRoute({
         method: "delete",
         path: "/files",
+        summary: "Delete a file or directory (moved to deleted folder)",
         request: {
             body: {
                 content: {
@@ -146,6 +149,7 @@ export async function createFilesRoutes(config) {
                 description: "Server error",
             },
         },
+        tags: ["Files"],
     }), async (c) => {
         const { path: relativePathInput } = c.req.valid("json");
         try {
@@ -174,6 +178,7 @@ export async function createFilesRoutes(config) {
     app.openapi(createRoute({
         method: "put",
         path: "/files",
+        summary: "Upload files to a specified directory",
         request: {
             body: {
                 content: {
@@ -217,6 +222,7 @@ export async function createFilesRoutes(config) {
                 description: "Server error",
             },
         },
+        tags: ["Files"],
     }), async (c) => {
         try {
             const body = await c.req.parseBody();
@@ -257,6 +263,7 @@ export async function createFilesRoutes(config) {
     app.openapi(createRoute({
         method: "post",
         path: "/files/directory",
+        summary: "Create a new directory",
         request: {
             body: {
                 content: {
@@ -314,6 +321,7 @@ export async function createFilesRoutes(config) {
                 description: "Server error",
             },
         },
+        tags: ["Files"],
     }), async (c) => {
         try {
             const { path, name } = c.req.valid("json");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isardsat/editorial-server",
-  "version": "6.13.2",
+  "version": "6.15.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -14,8 +14,8 @@
     "hono": "^4.9.8",
     "yaml": "^2.8.1",
     "zod": "^4.1.11",
-    "@isardsat/editorial-admin": "^6.13.2",
-    "@isardsat/editorial-common": "^6.13.2"
+    "@isardsat/editorial-admin": "^6.15.0",
+    "@isardsat/editorial-common": "^6.15.0"
   },
   "devDependencies": {
     "@tsconfig/node22": "^22.0.0",