@velora-cms/server 0.11.0

package/dist/routes/published-item.js

@@ -0,0 +1,236 @@
+import { serializeContentData } from "@velora-cms/content-service";
+import { getServerSerializer } from "../plugins/server-serializers.js";
+// Shared by the REST public-content routes (public-api.ts's sendPublishedItem)
+// and the GraphQL resolver (Session 113, Task 2): everything past locale
+// resolution — fetching the pointer version, datatype-serializing the data
+// (Session 111), and preparing the per-contribution serializer context used
+// by both ?format= and extendContentResponse (Session 112's mutation fix).
+// Locale resolution and format dispatch are surface-specific and stay in
+// each caller.
+//
+// Session 114, Task 1 additionally moves in the by-id/by-path locale
+// resolution block (resolveItemNode), the S105 document-type public
+// projection (toPublicDocumentType), the media presign+projection
+// (toPublicMediaFile), and the content-summary projection (toSummaries) —
+// all pure/near-pure REST projections GraphQL (Task 2) reuses verbatim.
+// Same throw-message contract ContentService uses everywhere (e.g.
+// ContentService.getByLocale's not-found Error, and the backoffice content
+// routes' identical check in content.ts).
+export function isNotFoundError(error) {
+    return error instanceof Error && /no (content|version \d+) found/i.test(error.message);
+}
+// Shared by the by-id and by-path routes: apply locale resolution (same
+// contract as the backoffice — fallback is a locale string) and enforce the
+// published-only rule on both the anchor and the resolved node. Returns
+// null on every miss this surface treats as a uniform 404 — unknown/draft
+// anchor, unknown locale/fallback, or an unpublished resolved translation.
+// A non-not-found error from locale resolution is NOT one of those misses
+// (REST doesn't 404 it — the route lets it propagate to a 500), so it
+// still rejects the returned promise rather than resolving to null.
+//
+// Session 116: `options.previewContentId` (a caller-verified preview
+// token's contentId, or null/absent) bypasses the published-only gate,
+// but ONLY for the node whose id exactly equals it — the anchor-level
+// check bypasses when the ANCHOR matches (so a draft anchor with no
+// `locale` query can resolve at all), and the post-locale-walk check
+// bypasses independently when the RESOLVED node matches (so a token
+// minted for one translation can never leak visibility to a sibling
+// translation the locale walk happens to land on instead). A
+// null/absent previewContentId makes both comparisons `x !== undefined`,
+// i.e. always true, so the gate is bit-for-bit today's behavior.
+export async function resolveItemNode(deps, anchor, query, options) {
+    const isPreviewAnchor = anchor !== null && anchor.id === options?.previewContentId;
+    if (!anchor || (anchor.publishedAt === null && !isPreviewAnchor)) {
+        return null;
+    }
+    if (!query.locale) {
+        return anchor;
+    }
+    let node;
+    try {
+        node = await deps.contentService.getByLocale(anchor.translationGroupId, query.locale, {
+            fallback: query.fallback ?? false,
+        });
+    }
+    catch (error) {
+        if (isNotFoundError(error)) {
+            return null;
+        }
+        throw error;
+    }
+    if (node.publishedAt === null && node.id !== options?.previewContentId) {
+        return null;
+    }
+    return node;
+}
+// Shared by REST's GET /api/v1/content search route and the GraphQL
+// `contents` resolver (Session 115, Task 1): resolves a search's `under`
+// anchor id to the materialized-path prefix its subtree filter needs,
+// enforcing the published-only rule on the anchor itself (same rule
+// resolveItemNode applies to its own anchor). Returns null for every miss
+// — unknown id, draft, or an id that simply doesn't match any row (a
+// malformed/non-UUID string never throws here: `getContentNode` is a
+// plain equality lookup, not a typed-column comparison, so it just finds
+// nothing). Each caller maps that null to its own surface's contract —
+// REST 404s it, GraphQL resolves its connection to null.
+export async function resolveSubtreeFilter(adapter, underId) {
+    const anchor = await adapter.getContentNode(underId);
+    if (!anchor || anchor.publishedAt === null) {
+        return null;
+    }
+    return { pathPrefix: anchor.path };
+}
+function toSummary(node) {
+    return {
+        id: node.id,
+        parentId: node.parentId,
+        path: node.path,
+        depth: node.depth,
+        sortOrder: node.sortOrder,
+        documentTypeId: node.documentTypeId,
+        locale: node.locale,
+        publishedAt: node.publishedAt,
+    };
+}
+// publishedOnly guarantees non-null publishedAt; the type-guard filter is
+// belt-and-braces so a future adapter bug can't leak a draft or a null
+// into the response schema.
+export function toSummaries(nodes) {
+    return nodes
+        .filter((node) => node.publishedAt !== null)
+        .map(toSummary);
+}
+// The S105 public document-type projection: tabs/treeRules/defaultTemplateId
+// stripped — introspection for a headless consumer, not the backoffice
+// authoring shape.
+export function toPublicDocumentType(doc) {
+    return {
+        id: doc.id,
+        name: doc.name,
+        icon: doc.icon,
+        kind: doc.kind,
+        fields: doc.fields.map((field) => ({
+            id: field.id,
+            name: field.name,
+            datatypeId: field.datatypeId,
+            ...(field.validation ? { validation: field.validation } : {}),
+        })),
+    };
+}
+// The S105 public media projection, with a FRESH presigned download URL
+// (never cached/stored — same convention as the REST media routes).
+export async function toPublicMediaFile(mediaService, media) {
+    const downloadUrl = await mediaService.getDownloadUrl(media.id);
+    return {
+        id: media.id,
+        filename: media.filename,
+        mimeType: media.mimeType,
+        size: media.size,
+        downloadUrl,
+        uploadedAt: media.uploadedAt,
+    };
+}
+// `node` must already be locale-resolved by the caller (that part is
+// surface-specific — REST does locale fallback, GraphQL may not). A
+// null anchor, or an anchor whose publishedAt is null AND doesn't match
+// `options.previewContentId`, maps to "notFound" here too, so a caller
+// can pass its resolved node straight through without a duplicate guard.
+export async function preparePublishedItem(deps, anchor, options) {
+    const isPreview = anchor !== null && anchor.id === options?.previewContentId;
+    if (!anchor || (anchor.publishedAt === null && !isPreview)) {
+        return { status: "notFound" };
+    }
+    // Reassigning to a fresh const (rather than using the narrowed parameter
+    // directly) keeps `node` non-null-typed inside the buildSerializerContext
+    // closure below, matching the original inline code where `node` was
+    // never `| null` in scope.
+    const node = anchor;
+    const { adapter } = deps;
+    // Preview bypass: serve the newest saved version (the draft an editor
+    // is working on), not the current_version pointer — same read
+    // `GET /api/content/:id/versions/latest` uses on the backoffice
+    // surface. A genuinely missing latest keeps the existing
+    // broken-invariant semantics (falls through to the same 500 below via
+    // the shared `!version` check).
+    const version = isPreview
+        ? await adapter.getLatestContentVersion(node.id)
+        : await adapter.getContentVersion(node.id, node.currentVersion);
+    if (!version) {
+        // Broken invariant, not a caller mistake — same 500 treatment as the
+        // backoffice GET /api/content/:id.
+        return {
+            status: "brokenVersion",
+            message: `current_version (${node.currentVersion}) for ${node.id} has no matching content version`,
+        };
+    }
+    // Session 111: public reads emit datatype-SERIALIZED values through
+    // content-service's shared pipeline. Write responses and backoffice
+    // reads deliberately stay raw — a writer round-trips stored values;
+    // serialization is a read-surface projection. A missing document
+    // type (broken reference) degrades to raw data, matching the
+    // pipeline's own passthrough philosophy.
+    let data = version.data;
+    const documentType = await adapter.getDocumentType(node.documentTypeId);
+    if (documentType) {
+        const configIds = [...new Set(documentType.fields.map((field) => field.datatypeId))];
+        const configs = await Promise.all(configIds.map((id) => adapter.getDataTypeConfig(id)));
+        const byId = new Map(configIds.map((id, i) => [id, configs[i]]));
+        const resolveDataType = (id) => {
+            const config = byId.get(id);
+            return config ? { editorId: config.editorId, settings: config.settings } : null;
+        };
+        data = serializeContentData(version.data, documentType, resolveDataType, getServerSerializer, (report) => deps.warn({ fieldId: report.fieldId, editorId: report.editorId, err: report.error }, "datatype serializer threw; field degraded to stored value"));
+    }
+    const core = {
+        id: node.id,
+        documentTypeId: node.documentTypeId,
+        locale: node.locale,
+        // Passes through as-is — non-null on every existing (non-preview)
+        // call site, since those already guarded `anchor.publishedAt !==
+        // null` above; possibly null when a preview bypass served a
+        // genuinely-draft node's latest version.
+        publishedAt: node.publishedAt,
+        // The version actually served, not the node's current_version
+        // pointer — identical to it on every existing (pointer-version) call
+        // path, but the preview bypass serves `getLatestContentVersion`,
+        // which can be a newer, unpublished version number.
+        version: version.version,
+    };
+    const contributions = deps.listSerializerContributions();
+    // Every contribution gets its OWN context: a structuredClone of `data`
+    // and a fresh `item`/`documentType` object. Contributions run
+    // untrusted, plugin-authored code — if one mutates its context in
+    // place, that must not corrupt the core response (which always sends
+    // the original, un-cloned `data`) and must not poison the input seen
+    // by any other contribution.
+    function buildSerializerContext() {
+        return {
+            item: { ...core },
+            data: structuredClone(data),
+            documentType: documentType
+                ? { id: documentType.id, name: documentType.name }
+                : { id: node.documentTypeId, name: "" },
+        };
+    }
+    return { status: "ok", core, data, contributions, buildSerializerContext };
+}
+// extendContentResponse — additive only, one plugin never affects another
+// or the core response.
+export async function computeExtensions(prepared, warn) {
+    const extensions = {};
+    for (const { pluginId, serializers } of prepared.contributions) {
+        if (!serializers.extendContentResponse)
+            continue;
+        try {
+            const extra = await serializers.extendContentResponse(prepared.buildSerializerContext());
+            if (!extra || typeof extra !== "object" || Array.isArray(extra))
+                continue;
+            JSON.stringify(extra); // S111-handoff guard
+            extensions[pluginId] = extra;
+        }
+        catch (error) {
+            warn({ pluginId, err: error }, "extendContentResponse failed; extension skipped");
+        }
+    }
+    return Object.keys(extensions).length > 0 ? extensions : undefined;
+}

package/dist/routes/setup.d.ts

@@ -0,0 +1,9 @@
+import type { FastifyPluginAsyncZod } from "fastify-type-provider-zod";
+export declare const SETUP_ALREADY_COMPLETED_MESSAGE = "Setup has already been completed.";
+export declare const SETUP_PROBE_FAILED_MESSAGE = "Could not verify whether setup has already been completed. Try again.";
+export declare const SETUP_MISCONFIGURED_DATABASE_URL_MESSAGE = "Setup is misconfigured: the database is reported as configured, but no database URL is set.";
+export declare const SETUP_LOCK_WEDGED_MESSAGE: string;
+export declare const setupRoutes: FastifyPluginAsyncZod<{
+    setupRequired: boolean;
+    databaseConfigured: boolean;
+}>;