@lupinum/ginko-content 0.2.0 → 0.2.1

package/compatibility.json

@@ -1,7 +1,7 @@
 {
   "name": "Ginko Content release compatibility",
   "releaseStack": {
-    "@lupinum/ginko-content": "0.2.0",
+    "@lupinum/ginko-content": "0.2.1",
     "@lupinum/ginko-cms": "0.1.2",
     "@lupinum/ginko-cms-convex": "0.1.1",
     "@lupinum/ginko-cms-contract": "0.1.1"

package/dist/module.json

@@ -1,6 +1,6 @@
 {
   "name": "@lupinum/ginko-content",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "configKey": "content",
   "compatibility": {
     "nuxt": ">=4.0.0"

package/dist/module.mjs

@@ -31,7 +31,7 @@ export { agentMetadataFields, defineAgentAppPage, defineAgentMarkdownPolicy, def
 import { collectTopLevelReferenceFieldsByTarget } from '../dist/core/references/schema';
 
 const name = "@lupinum/ginko-content";
-const version = "0.2.0";
+const version = "0.2.1";
 
 const CONFIG_FILES = [
   "content.config.ts",
@@ -274,7 +274,9 @@ const generatedContentServerValueNames = [
   "PROVIDER_QUERY_VERSION",
   "toContentProviderQuery",
   "toContentProviderNavigationQuery",
-  "createContentProviderError"
+  "createContentProviderError",
+  "normalizeProviderDocument",
+  "shapeProviderDocument"
 ];
 const generatedContentServerTypeSpecs = [
   { local: "ContentCacheAdapter", exported: "ContentCacheAdapter" },
@@ -288,6 +290,8 @@ const generatedContentServerTypeSpecs = [
   { local: "ContentProviderResult<T>", exported: "ContentProviderResult<T>" },
   { local: "MaybeContentProviderResult<T>", exported: "MaybeContentProviderResult<T>" },
   { local: "ContentProviderErrorCode", exported: "ContentProviderErrorCode" },
+  { local: "ProviderDocumentInput", exported: "ProviderDocumentInput" },
+  { local: "ShapeProviderDocumentOptions", exported: "ShapeProviderDocumentOptions" },
   { local: "VercelContentCacheOptions", exported: "VercelContentCacheOptions" }
 ];
 const registerRuntimeImports = (resolveRuntimeModule) => {

package/dist/public/provider.d.ts

@@ -12,6 +12,8 @@ export type { ContentProviderQuery, ContentProviderNavigationOptions, ContentQue
 export { PROVIDER_QUERY_VERSION, toContentProviderQuery, toContentProviderNavigationQuery } from './provider-query';
 export { createContentProviderError } from './provider-errors';
 export type { ContentProviderErrorCode } from './provider-errors';
+export { normalizeProviderDocument, shapeProviderDocument } from '../runtime/server/provider-document.js';
+export type { ProviderDocumentInput, ShapeProviderDocumentOptions } from '../runtime/server/provider-document.js';
 export declare const contentProviderResultMarker = "__ginkoContentProviderResult";
 export interface ContentProviderResult<T = unknown> {
     readonly [contentProviderResultMarker]: true;

package/dist/public/provider.js

@@ -1,5 +1,6 @@
 export { PROVIDER_QUERY_VERSION, toContentProviderQuery, toContentProviderNavigationQuery } from "./provider-query.js";
 export { createContentProviderError } from "./provider-errors.js";
+export { normalizeProviderDocument, shapeProviderDocument } from "../runtime/server/provider-document.js";
 export const contentProviderResultMarker = "__ginkoContentProviderResult";
 export const withContentCache = (data, cache) => ({
   [contentProviderResultMarker]: true,

package/dist/testing/provider-contract.d.ts

@@ -28,6 +28,23 @@ export interface AuthorDependencyContractOptions {
         key: string;
     }>;
 }
+export declare const LEGACY_PROVIDER_ENVELOPE_FIELDS: readonly ["_id", "_collection", "_locale", "_path", "_canonicalKey", "_type", "_draft", "_partial", "_source", "_file", "_stem", "_dir", "_basename", "_extension", "_requestedLocale", "_resolvedLocale", "_availableLocales", "_variantPaths", "_requestedPath", "_requestedRef", "_requestedRoute", "_resolvedRefs", "_fallback", "_empty", "_navigation", "_navigationPath", "_navigationKind", "_key", "_output"];
+export declare const unwrapProviderContractResult: <T>(value: T) => T extends {
+    data: infer Data;
+} ? Data : T;
+/**
+ * Assert that a provider operation rejects with the typed
+ * `unsupported_provider_operation` error when its capability is declared false.
+ * The `run` callback may return a promise or throw synchronously.
+ */
+export declare const expectUnsupportedProviderOperation: (run: () => Promise<unknown> | undefined, operation: string) => Promise<void>;
+export declare const expectUnsupportedProviderQueryShape: (run: () => Promise<unknown> | undefined, field: string) => Promise<void>;
+export declare const expectNoLegacyProviderEnvelopeFields: (value: unknown) => void;
+export declare const expectProviderDocumentEnvelope: (document: unknown, options?: {
+    locale?: string;
+    defaultLocale?: string;
+}) => void;
+export declare const expectProviderCapabilities: (provider: ContentProvider, expected: ContentProviderCapabilities) => void;
 export declare const runProviderContractSuite: ({ name, expectedProviderName, loadProvider, createEvent, expectedCapabilities, collectNavPaths }: ProviderContractSuiteOptions) => void;
 export declare const createAuthorDependencyContractProvider: () => {
     fixture: import("./provider-fixture").ProviderFixture;

package/dist/testing/provider-contract.js

@@ -5,17 +5,133 @@ const defaultCollectNavPaths = (items) => items.flatMap((item) => [
   item.unprefixedPath,
   ...defaultCollectNavPaths(item.children || [])
 ].filter(Boolean));
-const unwrapProviderResult = (value) => value && typeof value === "object" && value[contentProviderResultMarker] ? value.data : value;
-const expectUnsupportedOperation = (run, operation) => expect(Promise.resolve().then(run)).rejects.toMatchObject({
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+export const LEGACY_PROVIDER_ENVELOPE_FIELDS = [
+  "_id",
+  "_collection",
+  "_locale",
+  "_path",
+  "_canonicalKey",
+  "_type",
+  "_draft",
+  "_partial",
+  "_source",
+  "_file",
+  "_stem",
+  "_dir",
+  "_basename",
+  "_extension",
+  "_requestedLocale",
+  "_resolvedLocale",
+  "_availableLocales",
+  "_variantPaths",
+  "_requestedPath",
+  "_requestedRef",
+  "_requestedRoute",
+  "_resolvedRefs",
+  "_fallback",
+  "_empty",
+  "_navigation",
+  "_navigationPath",
+  "_navigationKind",
+  "_key",
+  "_output"
+];
+const legacyProviderEnvelopeFieldSet = new Set(LEGACY_PROVIDER_ENVELOPE_FIELDS);
+const collectLegacyProviderEnvelopeFields = (value, path = "$", seen = /* @__PURE__ */ new WeakSet(), matches = []) => {
+  if (!value || typeof value !== "object") {
+    return matches;
+  }
+  if (seen.has(value)) {
+    return matches;
+  }
+  seen.add(value);
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => {
+      collectLegacyProviderEnvelopeFields(item, `${path}[${index}]`, seen, matches);
+    });
+    return matches;
+  }
+  for (const [key, item] of Object.entries(value)) {
+    const itemPath = `${path}.${key}`;
+    if (legacyProviderEnvelopeFieldSet.has(key)) {
+      matches.push(itemPath);
+    }
+    collectLegacyProviderEnvelopeFields(item, itemPath, seen, matches);
+  }
+  return matches;
+};
+export const unwrapProviderContractResult = (value) => value && typeof value === "object" && value[contentProviderResultMarker] ? value.data : value;
+export const expectUnsupportedProviderOperation = (run, operation) => expect(Promise.resolve().then(run)).rejects.toMatchObject({
   statusCode: 400,
   statusMessage: "unsupported_provider_operation",
   data: { code: "unsupported_provider_operation", operation }
 });
-const expectUnsupportedQueryShape = (run, field) => expect(Promise.resolve().then(run)).rejects.toMatchObject({
+export const expectUnsupportedProviderQueryShape = (run, field) => expect(Promise.resolve().then(run)).rejects.toMatchObject({
   statusCode: 400,
   statusMessage: "unsupported_query_shape",
   data: { code: "unsupported_query_shape", field }
 });
+export const expectNoLegacyProviderEnvelopeFields = (value) => {
+  expect(collectLegacyProviderEnvelopeFields(value)).toEqual([]);
+};
+export const expectProviderDocumentEnvelope = (document, options = {}) => {
+  expectNoLegacyProviderEnvelopeFields(document);
+  expect(isRecord(document)).toBe(true);
+  const record = document;
+  expect(record).toEqual(expect.objectContaining({
+    id: expect.any(String),
+    collection: expect.any(String),
+    type: expect.any(String),
+    path: expect.any(String),
+    locale: expect.any(String),
+    canonicalKey: expect.any(String),
+    unprefixedPath: expect.any(String),
+    variants: expect.any(Array),
+    localePaths: expect.any(Object),
+    stem: expect.any(String)
+  }));
+  expect(Object.prototype.hasOwnProperty.call(record, "body")).toBe(true);
+  expect(record.resolved).toEqual(expect.objectContaining({
+    locale: expect.any(String),
+    fallback: expect.any(Boolean),
+    path: expect.any(String)
+  }));
+  if (options.locale !== void 0) {
+    expect(record.locale).toBe(options.locale);
+  }
+  if (options.defaultLocale !== void 0) {
+    expect(record.defaultLocale).toBe(options.defaultLocale);
+  }
+  if (record.file !== void 0) {
+    expect(record.file).toEqual(expect.objectContaining({
+      path: expect.any(String),
+      extension: expect.any(String)
+    }));
+  }
+  if (record.extension !== void 0) {
+    expect(record.extension).toEqual(expect.any(String));
+  }
+  if (record.title !== void 0) {
+    expect(record.title).toEqual(expect.any(String));
+  }
+  if (record.description !== void 0) {
+    expect(record.description).toEqual(expect.any(String));
+  }
+};
+export const expectProviderCapabilities = (provider, expected) => {
+  expect(provider.capabilities).toMatchObject({
+    ...expected,
+    query: {
+      limit: expected.query.limit,
+      skip: expected.query.skip,
+      count: expected.query.count
+    }
+  });
+  expect(provider.capabilities.query.operators).toEqual(
+    expect.arrayContaining(expected.query.operators)
+  );
+};
 export const runProviderContractSuite = ({
   name,
   expectedProviderName,
@@ -28,27 +144,18 @@ export const runProviderContractSuite = ({
   test(`${name} exposes explicit capabilities`, async () => {
     const provider = await loadProvider();
     expect(provider.name).toBe(expectedProviderName);
-    expect(provider.capabilities).toMatchObject({
-      ...caps,
-      query: {
-        limit: caps.query.limit,
-        skip: caps.query.skip,
-        count: caps.query.count
-      }
-    });
-    expect(provider.capabilities.query.operators).toEqual(
-      expect.arrayContaining(caps.query.operators)
-    );
+    expectProviderCapabilities(provider, caps);
   });
   test(`${name} returns complete localized page and route metadata`, async () => {
     const provider = await loadProvider();
     const event = createEvent();
     if (!caps.routeBackedCollections) {
-      await expectUnsupportedOperation(() => provider.page?.(event, "docs", "/de/dokumentation/einstieg"), "route-backed pages");
-      await expectUnsupportedOperation(() => provider.routeMeta?.(event, "docs", "/de/dokumentation/einstieg", { locale: "de" }), "route metadata");
+      await expectUnsupportedProviderOperation(() => provider.page?.(event, "docs", "/de/dokumentation/einstieg"), "route-backed pages");
+      await expectUnsupportedProviderOperation(() => provider.routeMeta?.(event, "docs", "/de/dokumentation/einstieg", { locale: "de" }), "route metadata");
       return;
     }
-    const page = unwrapProviderResult(await provider.page?.(event, "docs", "/de/dokumentation/einstieg"));
+    const page = unwrapProviderContractResult(await provider.page?.(event, "docs", "/de/dokumentation/einstieg"));
+    expectNoLegacyProviderEnvelopeFields(page);
     expect(page).toMatchObject({
       title: "Einstieg",
       locale: "de",
@@ -62,7 +169,7 @@ export const runProviderContractSuite = ({
     });
     expect(page?.variants).toEqual(expect.any(Array));
     expect(page?.localePaths).toEqual(expect.any(Object));
-    const routeMeta = unwrapProviderResult(await provider.routeMeta?.(event, "docs", "/de/dokumentation/einstieg", { locale: "de" }));
+    const routeMeta = unwrapProviderContractResult(await provider.routeMeta?.(event, "docs", "/de/dokumentation/einstieg", { locale: "de" }));
     expect(routeMeta).toMatchObject({
       locale: "de",
       path: expect.stringMatching(/\/dokumentation\/einstieg$/),
@@ -72,19 +179,19 @@ export const runProviderContractSuite = ({
         locale: "de"
       })
     });
-    const miss = unwrapProviderResult(await provider.page?.(createEvent(), "docs", "/de/dokumentation/not-found"));
+    const miss = unwrapProviderContractResult(await provider.page?.(createEvent(), "docs", "/de/dokumentation/not-found"));
     expect(miss).toBeNull();
   });
   test(`${name} supports list queries with locale, ordering, limit, count, and projection`, async () => {
     const provider = await loadProvider();
     if (!caps.query.limit) {
-      await expectUnsupportedQueryShape(() => provider.query(createEvent(), toContentProviderQuery({
+      await expectUnsupportedProviderQueryShape(() => provider.query(createEvent(), toContentProviderQuery({
         collection: "posts",
         resolveLocale: { locale: "de", fallback: false },
         limit: 1
       })), "limit");
     } else {
-      const response = unwrapProviderResult(await provider.query(createEvent(), toContentProviderQuery({
+      const response = unwrapProviderContractResult(await provider.query(createEvent(), toContentProviderQuery({
         collection: "posts",
         resolveLocale: { locale: "de", fallback: false },
         sort: [{ date: -1 }],
@@ -101,13 +208,13 @@ export const runProviderContractSuite = ({
       expect(typeof response.total).toBe("number");
     }
     if (!caps.query.count) {
-      await expectUnsupportedQueryShape(() => provider.query(createEvent(), toContentProviderQuery({
+      await expectUnsupportedProviderQueryShape(() => provider.query(createEvent(), toContentProviderQuery({
         collection: "posts",
         resolveLocale: { locale: "de", fallback: false },
         count: true
       })), "count");
     } else {
-      const countResponse = unwrapProviderResult(await provider.query(createEvent(), toContentProviderQuery({
+      const countResponse = unwrapProviderContractResult(await provider.query(createEvent(), toContentProviderQuery({
         collection: "posts",
         resolveLocale: { locale: "de", fallback: false },
         count: true
@@ -119,12 +226,12 @@ export const runProviderContractSuite = ({
     const provider = await loadProvider();
     const event = createEvent();
     if (!caps.navigation) {
-      await expectUnsupportedOperation(() => provider.navigation?.(event, "docs", { locale: "de" }), "navigation");
+      await expectUnsupportedProviderOperation(() => provider.navigation?.(event, "docs", { locale: "de" }), "navigation");
       const wire = toContentProviderNavigationQuery({ where: { locale: "de" } });
-      await expectUnsupportedOperation(() => provider.navigationQuery?.(event, wire.query, wire.options), "navigation");
+      await expectUnsupportedProviderOperation(() => provider.navigationQuery?.(event, wire.query, wire.options), "navigation");
       return;
     }
-    const nav = unwrapProviderResult(await provider.navigation?.(event, "docs", { locale: "de" }));
+    const nav = unwrapProviderContractResult(await provider.navigation?.(event, "docs", { locale: "de" }));
     expect(collectNavPaths(nav || [])).toContain("/dokumentation/einstieg");
     expect(nav?.[0]).toEqual(expect.objectContaining({
       locale: "de",
@@ -137,13 +244,13 @@ export const runProviderContractSuite = ({
     expect(navPaths.indexOf("/dokumentation/einstieg")).toBeLessThan(
       navPaths.indexOf("/dokumentation/einstieg/installation")
     );
-    const fieldNav = unwrapProviderResult(await provider.navigation?.(event, "docs", ["description"]));
+    const fieldNav = unwrapProviderContractResult(await provider.navigation?.(event, "docs", ["description"]));
     expect(fieldNav?.[0]).toEqual(expect.objectContaining({
       title: expect.any(String),
       description: expect.any(String)
     }));
     const globalNavWire = toContentProviderNavigationQuery({ where: { locale: "de" } });
-    const globalNav = unwrapProviderResult(await provider.navigationQuery?.(event, globalNavWire.query, globalNavWire.options));
+    const globalNav = unwrapProviderContractResult(await provider.navigationQuery?.(event, globalNavWire.query, globalNavWire.options));
     const globalNavPaths = collectNavPaths(globalNav || []);
     expect(globalNavPaths).toContain("/dokumentation/einstieg");
     expect(globalNavPaths.length).toBeGreaterThan(0);
@@ -151,7 +258,7 @@ export const runProviderContractSuite = ({
       collection: "docs",
       resolveLocale: { locale: "de", fallback: false, exact: true }
     });
-    const resolvedLocaleNav = unwrapProviderResult(await provider.navigationQuery?.(event, resolvedLocaleNavWire.query, resolvedLocaleNavWire.options));
+    const resolvedLocaleNav = unwrapProviderContractResult(await provider.navigationQuery?.(event, resolvedLocaleNavWire.query, resolvedLocaleNavWire.options));
     expect(collectNavPaths(resolvedLocaleNav || [])).toContain("/dokumentation/einstieg");
     expect(JSON.stringify(nav)).not.toContain("Draft Roadmap");
   });
@@ -159,10 +266,10 @@ export const runProviderContractSuite = ({
     const provider = await loadProvider();
     const event = createEvent();
     if (!caps.surroundings) {
-      await expectUnsupportedOperation(() => provider.surroundings?.(event, "docs", "/de/dokumentation/einstieg/installation", { locale: "de" }), "surroundings");
+      await expectUnsupportedProviderOperation(() => provider.surroundings?.(event, "docs", "/de/dokumentation/einstieg/installation", { locale: "de" }), "surroundings");
       return;
     }
-    const surround = unwrapProviderResult(await provider.surroundings?.(event, "docs", "/de/dokumentation/einstieg/installation", { locale: "de" }));
+    const surround = unwrapProviderContractResult(await provider.surroundings?.(event, "docs", "/de/dokumentation/einstieg/installation", { locale: "de" }));
     expect(surround).toHaveLength(2);
     expect(surround?.map((item) => item?.unprefixedPath)).toContain("/dokumentation/einstieg/alltag");
   });
@@ -170,10 +277,10 @@ export const runProviderContractSuite = ({
     const provider = await loadProvider();
     const event = createEvent();
     if (!caps.searchSections) {
-      await expectUnsupportedOperation(() => provider.searchSections?.(event, "docs", { locale: "de" }), "search sections");
+      await expectUnsupportedProviderOperation(() => provider.searchSections?.(event, "docs", { locale: "de" }), "search sections");
       return;
     }
-    const sections = unwrapProviderResult(await provider.searchSections?.(event, "docs", { locale: "de" }));
+    const sections = unwrapProviderContractResult(await provider.searchSections?.(event, "docs", { locale: "de" }));
     expect(sections?.some((section) => section.id.startsWith("/de/dokumentation/einstieg") || section.id.startsWith("/dokumentation/einstieg"))).toBe(true);
     expect(JSON.stringify(sections)).not.toContain("Draft Roadmap");
   });
@@ -181,10 +288,10 @@ export const runProviderContractSuite = ({
     const provider = await loadProvider();
     const event = createEvent();
     if (!caps.sitemap) {
-      await expectUnsupportedOperation(() => provider.sitemapEntries?.(event, { include: ["docs"] }), "sitemap entries");
+      await expectUnsupportedProviderOperation(() => provider.sitemapEntries?.(event, { include: ["docs"] }), "sitemap entries");
       return;
     }
-    const sitemap = unwrapProviderResult(await provider.sitemapEntries?.(event, { include: ["docs"] }));
+    const sitemap = unwrapProviderContractResult(await provider.sitemapEntries?.(event, { include: ["docs"] }));
     expect(sitemap?.some((entry) => entry.loc.endsWith("/de/dokumentation/einstieg"))).toBe(true);
     expect(JSON.stringify(sitemap)).not.toContain("/docs/draft-roadmap");
   });
@@ -213,7 +320,7 @@ export const runProviderContractSuite = ({
   test(`${name} supports data-only collection reads and rejects data-only sitemap access`, async () => {
     if (!caps.dataCollections) return;
     const provider = await loadProvider();
-    const response = unwrapProviderResult(await provider.query(createEvent(), toContentProviderQuery({
+    const response = unwrapProviderContractResult(await provider.query(createEvent(), toContentProviderQuery({
       collection: "versions",
       resolveLocale: { locale: "en", fallback: false },
       sort: [{ date: -1 }]

package/dist/web-types.json

@@ -1,7 +1,7 @@
 {
   "framework": "vue",
   "name": "@lupinum/ginko-content",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "contributions": {
     "html": {
       "description-markup": "markdown",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lupinum/ginko-content",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Collection-first content engine for Nuxt",
   "homepage": "https://ginko-content.nuxt.dev",
   "bugs": {