@se-studio/contentful-rest-api 1.10.0 → 1.12.0

package/docs/llms.md

@@ -63,6 +63,36 @@ const allPersonLinks  = await contentfulAllPersonLinks(config);
 // CmsResponse<IPersonLink[]> — each link includes resolved bio (IResolvedRichText) when set in CMS
 ```
 
+## Flat navigation
+
+Assemble menus without Contentful include depth.
+
+**Page renders (preferred):** `navigationResolution: 'flat'` on `FetchOptions` — converters stub nav root ids; post-convert step calls registry + link index and rebuilds `model.menu` / `model.footer` / `model.icons`. Set in app `buildOptions`. Default is `'bundled'`.
+
+```ts
+buildFetchOptions({ navigationResolution: 'flat', ...options }, preview);
+```
+
+**Ad hoc:** `getNavigation` from `createAppHelpers` only — registry/link-index fetchers are not exported.
+
+```ts
+const { getNavigation } = createAppHelpers({ /* ... */ });
+const menu = await getNavigation(mainNavEntryId);
+```
+
+Caching (applied inside `getNavigation` via `buildFlatNavigationCacheOptions`):
+
+- **Tags (primary):** `FLAT_NAV_CACHE_TAGS` — collection tags for navigation, navigationItem, page, article, tag, **tagType**, **link**, person, etc.
+- **Revalidate (fallback):** `FLAT_NAV_TIME_REVALIDATE_SECONDS` (3600) when webhooks miss; override with `options.next.revalidate`.
+
+Unresolved internal targets → blank link; set `LOG_CMS=1` to warn.
+
+### Golden listing fields
+
+Defined in `listing-fetch-params.ts` (table in file header). Bulk link/index fetches use these `select` lists. Flat-nav **registry** fetches omit `select` (schema-tolerant per space).
+
+`tagType` links: `TAG_TYPE_LINK_FIELDS` includes `fields.slug`; spaces without slug fall back to `TAG_TYPE_MINIMAL_FIELDS` on 422.
+
 ## Related Articles Filtering
 
 ```ts
@@ -130,10 +160,14 @@ import {
   customTypeTag,
   assetTag,
   // Constants
-  PageTag, ArticleTag, NavigationTag, BannerTag, GlobalTag, AllTags,
+  PageTag, ArticleTag, TagTypeTag, LinkTag, NavigationTag, BannerTag, GlobalTag, AllTags,
+  FLAT_NAV_CACHE_TAGS, FLAT_NAV_TIME_REVALIDATE_SECONDS, buildFlatNavigationCacheOptions,
+  REVALIDATION_WEBHOOK_ENTRY_CONTENT_TYPES, REVALIDATION_WEBHOOK_ENTRY_CONTENT_TYPES_CSV,
 } from '@se-studio/contentful-rest-api';
 ```
 
+Production published-entry webhook filter: `REVALIDATION_WEBHOOK_ENTRY_CONTENT_TYPES_CSV` (includes `navigation`, `navigationItem`, `tagType`, `link` for flat nav). See `docs/CONTENTFUL_WEBHOOK_REVALIDATION.md`.
+
 ## Converter Pattern
 
 Used to extend how Contentful entries are transformed into typed models. You typically call `createBaseConverterContext()` and pass it via `buildFetchOptions`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@se-studio/contentful-rest-api",
-  "version": "1.10.0",
+  "version": "1.12.0",
   "description": "Type-safe Contentful REST API client with caching and rate limiting for Next.js applications",
   "repository": {
     "type": "git",