Server API

Import server-safe helpers from @lupinum/ginko-content/server. Query operations take the active H3Event first and otherwise share the client query contract.

import {
  many,
  navigation,
  one,
  surround
} from '@lupinum/ginko-content/server'

Query operations

import { many } from '@lupinum/ginko-content/server'
import { posts } from '~~/content.config'

export default defineEventHandler(async (event) => {
  return await many(event, posts, {
    where: { draft: { $ne: true } },
    sort: { publishedAt: 'desc' },
    limit: 10
  })
})

Navigation and surroundings are first-class server operations:

const [tree, neighbors] = await Promise.all([
  navigation(event, docs, {
    locale: 'en',
    select: ['description', 'icon']
  }),
  surround(event, docs, {
    locale: 'en',
    by: { route: '/docs/installation' }
  })
])

An i18n handle requires a locale in operations that do not derive it from a route. Provider capability and input failures reject the promise; unsupported work is not emulated in server orchestration.

Sitemap entries

queryCollectionsSitemapEntries(event, options?): Promise<ContentSitemapEntry[]>

Build Nuxt Sitemap source entries from provider route facts:

import { queryCollectionsSitemapEntries } from '@lupinum/ginko-content/server'

const entries = await queryCollectionsSitemapEntries(event, {
  include: ['docs', 'posts'],
  exclude: ['internal'],
  includeDrafts: false,
  siteUrl: 'https://docs.example.com'
})

Data collections, collections with sitemap: false, draft routes excluded by policy, and provider routes with sitemap: false are omitted from the default enumeration. Explicitly naming a non-sitemap-backed collection in include throws. Production calls fail without an explicit or configured site URL. Providers must implement routes().

Route and navigation utilities

getCollectionPath(collection, options?): string
findFirstNavigationPage(items?): NavigationPageNode | null

getCollectionPath() projects a route from the collection handle's own mount and collection-local locale policy. Options are locale, slug, path, and localePrefix; path takes precedence over slug, and localePrefix: false returns the mounted provider coordinate without the application locale prefix. Because this is a pure helper, a collection declared with i18n: true must use the explicit i18n: { locales, defaultLocale } form before it can be passed here; the handle does not contain module-level inherited locale policy, and the helper never guesses it.

findFirstNavigationPage() walks a navigation tree depth-first and returns the first item with a usable path, skipping nodes with page: false.

Cache adapters

contentCacheHeaders(hint): Headers
headersContentCache(): ContentCacheAdapter

contentCacheHeaders() converts portable maxAge, swr, etag, and lastModified hints into Cache-Control, ETag, and Last-Modified headers. headersContentCache() returns an adapter that applies those headers. It does not advertise cache invalidation because response headers cannot purge an upstream cache.

import { headersContentCache } from '@lupinum/ginko-content/server'

export default headersContentCache()

Provider operations attach request hints with withContentCache() from @lupinum/ginko-content/provider; adapters remain application-owned.

Request cache hints

collectContentCacheHint(event, hint): void
getContentCacheHint(event): ContentCacheHint | false | undefined
clearContentCacheHint(event): void

collectContentCacheHint() merges a hint into the current request context. getContentCacheHint() returns the merged hint, undefined before collection, or false for preview requests. clearContentCacheHint() resets it. These low-level helpers are useful for custom server integrations; ordinary provider results should use withContentCache().