@se-studio/contentful-rest-api 0.0.0-next16-20260822103555

package/docs/llms.md

@@ -0,0 +1,430 @@
+# @se-studio/contentful-rest-api — LLM Reference
+
+Type-safe Contentful REST API client for Next.js App Router applications. Handles fetching, caching, rate limiting, and content conversion.
+
+## Setup
+
+```ts
+import { coreGetContentfulConfig } from '@se-studio/contentful-rest-api';
+
+// Reads CONTENTFUL_SPACE_ID, CONTENTFUL_ACCESS_TOKEN, CONTENTFUL_ENVIRONMENT from env
+const config = coreGetContentfulConfig();
+```
+
+Or build manually:
+```ts
+import type { ContentfulConfig } from '@se-studio/contentful-rest-api';
+
+const config: ContentfulConfig = {
+  spaceId: process.env.CONTENTFUL_SPACE_ID!,
+  accessToken: process.env.CONTENTFUL_ACCESS_TOKEN!,    // delivery token
+  previewAccessToken: process.env.CONTENTFUL_PREVIEW_ACCESS_TOKEN, // optional
+  environment: process.env.CONTENTFUL_ENVIRONMENT ?? 'master',
+};
+```
+
+## Primary Fetch Functions
+
+All functions share the signature `fn(config, identifier, options?)`.
+
+```ts
+import {
+  contentfulPageRest,
+  contentfulArticleRest,
+  contentfulArticleTypeRest,
+  contentfulNavigationRest,   // via contentfulAnyEntryRest
+  contentfulTagRest,
+  contentfulTagTypeRest,
+  contentfulPersonRest,
+  contentfulBannerRest,
+  contentfulTemplateRest, // IFetchedTemplate includes structuredData (Schema.org Mustache list)
+  contentfulComponentRest,
+  contentfulCustomTypeRest,
+  contentfulAssetRest,
+  listMediaLibraryPage,       // cms-dev media inventory (images/videos/animations/external-videos)
+  mediaLibraryPageToMarkdown,
+  contentfulAnyEntryRest,     // generic fallback by entry ID
+} from '@se-studio/contentful-rest-api';
+
+// Media library page (Preview API by default) — thumbnails via buildAssetThumbUrl
+// const media = await listMediaLibraryPage(config, 'images', { page: 1, limit: 50, preview: true });
+
+// Fetch a page by slug
+const page = await contentfulPageRest(config, 'home', {
+  preview: false,
+  cache: { tags: ['page#home'], revalidate: 3600 },
+});
+
+// Fetch an article by slug
+const article = await contentfulArticleRest(config, 'my-article-slug', {
+  cache: { tags: ['article#my-article-slug'], revalidate: 3600 },
+});
+
+// Fetch all links (for sitemaps / related content)
+const allPageLinks    = await contentfulAllPageLinks(config);
+const allArticleLinks = await contentfulAllArticleLinks(config);
+const allTagLinks     = await contentfulAllTagLinks(config);
+const allPersonLinks  = await contentfulAllPersonLinks(config);
+// CmsResponse<IPersonLink[]> — each link includes resolved bio (IResolvedRichText) when set in CMS
+```
+
+## Page variants
+
+`contentfulPageRest` resolves a `pageVariant` slug when no `page` matches. The variant merges onto `originalPage` and applies `alternativeContents` swaps.
+
+Each `alternatePageContent` entry:
+
+- **`sourceContent`** — component/collection to replace (by entry id in the merged tree)
+- **`replacementContents`** — array of replacements (primary; supports 1→N swaps)
+- **`replacementContent`** — singular fallback when `replacementContents` is empty
+
+Exported helpers: `mergeAlternatePageContentsInTree`, `resolveAlternateReplacements`.
+
+## 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);
+```
+
+**Custom layout assembly:** when menu/footer are resolved outside the flat post-convert step, rebuild the sprite from final trees:
+
+```ts
+import { rebuildIconSpriteFromLayout } from '@se-studio/contentful-rest-api';
+
+model.icons = await rebuildIconSpriteFromLayout(model.contents, model.menu, model.footer);
+```
+
+Lower-level helpers (`collectIconsFromContent`, `collectIconsFromNavigation`, `deduplicateIcons`, `processIconsForSprite`) are also exported from the package root.
+
+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
+import { filterRelatedArticles } from '@se-studio/contentful-rest-api';
+
+const related = filterRelatedArticles(allArticleLinks, {
+  tagIds: ['tag-entry-id-1', 'tag-entry-id-2'], // OR filter — must match at least one
+  tagSlugs: ['topic-a'],                        // slugs also supported (combined with OR)
+  articleTypeSlugs: ['resources/news'],         // or articleTypeIds
+  authorSlugs: ['alice'],                       // or authorIds
+  strictAuthorMatch: true,                      // hard filter (exclude non-matches) instead of boost
+  tagTypeSlugs: ['condition'],                  // hard filter on any tag's tagType
+  excludeArticleIds: [currentArticle.id],
+  before: new Date('2025-01-01'),
+  count: 3,                                     // undefined = all matches after sort
+  allowUnindexed: true,
+});
+```
+
+When tag criteria are set, articles must match at least one (OR). More distinct matching tags → higher rank (then newest date). `strictAuthorMatch` turns author criteria into an exclude filter (key for person-scoped full lists). Use via `getAllArticleLinks({ articleTypeSlugs, strictAuthorMatch, ... })` in core-ui helpers for News Grids / Publications Lists without duplicating filter logic. Direct import is server-only (main barrel of the package pulls server-only transitive deps via enrichers).
+
+## Sitemap Helpers
+
+(The actual URLs in the entries are produced by your project's `UrlCalculators` + link converters. See `docs/routing.md` for the multi-project guidance and sync checklist.)
+
+```ts
+import {
+  contentfulPageSitemapEntries,
+  contentfulArticleSitemapEntries,
+  contentfulArticleTypeSitemapEntries,
+  contentfulTagSitemapEntries,
+  contentfulPersonSitemapEntries,
+  getAllSitemapEntries,
+  createSitemapProvider,
+} from '@se-studio/contentful-rest-api';
+```
+
+## FetchOptions
+
+```ts
+interface FetchOptions {
+  preview?: boolean;         // use preview API (default: false)
+  locale?: string;           // Contentful locale (default: 'en-US')
+  cache?: {
+    tags?: string[];         // Next.js cache tags for revalidation
+    revalidate?: number;     // seconds; 0 = no cache
+  };
+}
+```
+
+## Cache Tags (for revalidation)
+
+**Publish cascades:** `template` → `page` + `article`; `articleType` → `article`; `customType` → `tag` + `person` (coarse; Next 15 workaround until per-entity `cacheTag` on Next 16).
+
+Use these tag helpers to generate consistent cache tag strings:
+
+```ts
+import {
+  pageTag,          // pageTag('home')        → 'page#home'
+  articleTag,       // articleTag('slug')      → 'article#slug'
+  articleTypeTag,   // articleTypeTag('news')  → 'article-type#news'
+  tagTag,           // tagTag('slug')          → 'tag#slug'
+  personTag,
+  pageVariantTag,
+  locationTag,
+  templateTag,
+  customTypeTag,
+  assetTag,
+  // Constants
+  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`.
+
+```ts
+import {
+  createBaseConverterContext,
+  buildFetchOptions,
+  basePageConverter,
+  baseComponentConverter,
+  baseCollectionConverter,
+} from '@se-studio/contentful-rest-api';
+
+const context = createBaseConverterContext();
+// extend context.resolvers if you need custom content types
+```
+
+Base converters available:
+- `basePageConverter` — converts page entries
+- `baseComponentConverter` — converts component entries
+- `baseCollectionConverter` — converts collection entries
+- `baseExternalComponentConverter`
+- `baseArticleConverter`, `baseArticleTypeConverter` — full article converter resolves `download` (same as `baseArticleLinkConverter`); article type **index** `structuredData` comes from `indexPageStructuredData` + template schemas only (entry-level `structuredData` applies on individual articles via `baseArticleConverter`)
+- `baseCustomTypeConverter` — custom type **index** `structuredData` comes from `indexPageStructuredData` only (entry-level `structuredData` applies to child entries)
+- `baseArticleLinkConverter` — `href` is internal when the article has article-level body content (`topContent`, `content`, or `bottomContent` on the article entry; article-type `articlePageTopContent` does not count); external-only articles use `externalLink` as `href`; `externalLink` always on the link object
+- `basePersonConverter`
+- `baseTagConverter`, `baseTagTypeConverter`
+- `baseBannerConverter`
+
+### Context extension points
+
+`BaseConverterContext` has optional resolver hooks for project-specific behaviour:
+
+- `maskResolver?: (maskName: string) => string | undefined` — maps a CMS mask dropdown value to a CSS mask URL or Tailwind class string, stored as `IVisual.mask`
+- `gradientResolver?: (gradientName: string) => string | undefined` — maps a CMS gradient dropdown value to a CSS gradient string (e.g. `linear-gradient(...)`), stored as `IVisual.gradient` and rendered as an overlay div on top of the visual
+- `previewEntryResolvers?: Readonly<Record<string, PreviewEntryResolver>>` — maps Contentful content type ids to Live Preview URL resolvers for **customer page-like types** not built into core (e.g. HSD `location` → `/drive/{slug}/`). Built-in types always win; extensions only run on unknown content types.
+
+```ts
+const context = createBaseConverterContext(urlCalculators);
+context.maskResolver = (name) => maskMap[name];
+context.gradientResolver = (name) => gradientMap[name];
+context.previewEntryResolvers = {
+  location: slugPreviewResolver('location', (slug) => `/drive/${slug}/`),
+};
+```
+
+## Preview
+
+```ts
+import {
+  createBaseConverterContext,
+  getPreviewEntryInfo,
+  slugPreviewResolver,
+  type PreviewEntryResolver,
+} from '@se-studio/contentful-rest-api';
+
+const context = createBaseConverterContext(urlCalculators);
+
+// Built-in: page, pageVariant, pageTest, article, articleType, tag, person, customType
+const info = await getPreviewEntryInfo(context, config, entryId);
+// info: { contentType, entryId, slug, href, articleTypeSlug? } | null
+
+// Custom page-like types (do not hardcode customer types in core):
+context.previewEntryResolvers = {
+  location: slugPreviewResolver('location', (slug) => `/drive/${slug}/`),
+  // Or full control — receives fields, includes (include: 1), urlCalculators:
+  locationShell: ({ entryId, fields, includes, urlCalculators }) => {
+    /* resolve linked entry, return PreviewEntryInfo | null */
+    return null;
+  },
+};
+
+const locationInfo = await getPreviewEntryInfo(context, config, locationEntryId);
+```
+
+**Built-in content types:** `page`, `pageVariant`, `pageTest` (redirects to linked control `page` or `pageVariant`), `article`, `articleType`, `tag`, `person`, `customType`.
+
+**Custom types:** register via `context.previewEntryResolvers[contentTypeId]`. Prefer `slugPreviewResolver(contentType, toHref)` when only `fields.slug` is needed. Return type is always `PreviewEntryInfo | null`.
+
+## Error Handling
+
+```ts
+import {
+  isContentfulError,
+  isRateLimitError,
+  EntryNotFoundError,
+  AuthenticationError,
+  RateLimitError,
+  withRetry,
+} from '@se-studio/contentful-rest-api';
+```
+
+## Rich Text
+
+```ts
+import type { IContentfulRichText } from '@se-studio/contentful-rest-api';
+// Use with core-ui's RTF component
+```
+
+## Primary Tag Selection
+
+`getPrimaryTag(article, selector?)` returns the primary tag from an article. Without a selector it returns `tags[0]`. Supply a predicate to apply custom logic — the library does not prescribe which tag is "primary".
+
+```ts
+import { getPrimaryTag, type PrimaryTagSelector } from '@se-studio/contentful-rest-api';
+
+// Default: returns tags[0]
+const primaryTag = getPrimaryTag(article);
+
+// Custom selection — client supplies the predicate
+const mySelector: PrimaryTagSelector = (tag, articleType) =>
+  articleType?.slug === 'news'
+    ? tag.tagType?.slug === 'disease-area'
+    : tag.tagType?.slug === 'presentation-type';
+
+const primaryTag = getPrimaryTag(article, mySelector);
+// Falls back to tags[0] if no tag matches the predicate
+```
+
+To also drive the generated `article.href` URL, pass `primaryTagSelector` when building the converter context:
+
+See also the full routing + UrlCalculators contract + examples from other consumers in the monorepo at `docs/routing.md` (critical when you have a non-default primary tag selection or custom article URL shape).
+
+```ts
+const context = createBaseConverterContext({
+  ...config,
+  primaryTagSelector: mySelector,
+});
+```
+
+`ITagLink` carries `tagType?: { id, name, slug, show? }` so selectors can match on tag type without an extra fetch.
+
+## Tag visual visibility
+
+`show` on Tag and TagType controls **UI rendering only** (cards, detail pages). It does not affect search indexing (`indexed`), live pages (`hidden`), or related-articles matching.
+
+```ts
+import {
+  filterVisibleTags,
+  isTagShowEnabled,
+  isTagVisible,
+} from '@se-studio/contentful-rest-api';
+
+// Visible when tag.show and tag.tagType.show are not explicitly false
+const displayTags = filterVisibleTags(article.tags);
+```
+
+## Utility Functions
+
+```ts
+import {
+  filterVisibleTags,   // tags to show on cards/detail (show !== false on tag and tagType)
+  getPrimaryTag,       // select primary tag from an article; accepts optional predicate
+  isTagShowEnabled,    // undefined/null/true => visible; false => hidden from UI
+  isTagVisible,        // tag.show && tag.tagType.show (visual only)
+  type PrimaryTagSelector, // (tag, articleType) => boolean
+  type TagVisibilityFields,
+  notEmpty,            // array filter: arr.filter(notEmpty)
+  arrayOrUndefined,    // returns array or undefined if empty
+  safeDate,            // parse date string safely
+  isValidDate,
+} from '@se-studio/contentful-rest-api';
+```
+
+## Query logging (dev)
+
+Set `LOG_CMS_QUERIES=1` to emit structured per-fetch lines:
+
+```
+[CMS query] {"url":"...","operation":"Reading article","identifier":"my-slug","bytes":24064,"ms":45}
+```
+
+Merge with Next.js dev fetch cache lines (`(cache hit|miss)`) after the fact:
+
+```bash
+pnpm dev 2>&1 | tee dev.log
+pnpm --filter @se-studio/contentful-rest-api consolidate-cms-logs -- dev.log
+# => Reading article my-slug - 23.5k (cached) in 12ms
+```
+
+For reliable URL matching, enable full fetch URLs in the app's `next.config.js`:
+
+```js
+logging: { fetches: { fullUrl: true } }
+```
+
+Related: `LOG_CMS=1` (conversion warnings), `LOG_CMS_FETCH=1` (raw URLs only).
+
+## Download proxy (hide CDN URLs)
+
+```ts
+// app/download/[assetId]/[filename]/route.ts
+import { createDownloadHandler } from '@se-studio/contentful-rest-api/server';
+
+export const GET = createDownloadHandler({
+  getConfig: () => getContentfulConfig(),
+  // Default revalidate = 86400 (1 day). Static fund/letter PDFs: pass a long TTL via config only.
+  revalidate: 60 * 60 * 24 * 30, // e.g. 30 days for immutable-ish document packages
+  baseUrl: 'https://www.example.com',
+});
+```
+
+- Public hrefs: `/download/{assetId}/{canonicalFilename}` via `urlCalculators.download`.
+- Never emit raw Contentful/Webflow CDN URLs in published HTML for PDFs.
+- On file replace: use a **new asset id and/or filename** so long `Cache-Control` does not pin stale bytes.
+- Successful responses set `max-age` and `s-maxage` from `revalidate`; identity 301s use a short max-age.
+
+## Document content type
+
+Fund/compliance files without full Article machinery.
+
+```ts
+import {
+  baseDocumentConverter,
+  contentfulDocumentsRest,
+} from '@se-studio/contentful-rest-api';
+import type { IBaseDocument } from '@se-studio/core-data-types';
+
+// Optional hop page (omit → document.href falls back to file download proxy)
+urlCalculators.document = (slug) => `/documents/${slug}/`;
+
+const { data } = await contentfulDocumentsRest(context, config, options);
+// data: IBaseDocument[] — file.href always /download/...
+```
+
+## Important Constraints
+
+- Always supply `spaceId`, `accessToken`, and `environment`.
+- For Next.js: pass `cache.tags` and `cache.revalidate` so pages can be revalidated via Contentful webhooks.
+- For preview mode, also supply `previewAccessToken` and pass `{ preview: true }` in options.
+- `contentfulNavigationRest` is not a direct export — navigation is fetched via `contentfulAnyEntryRest` or via the app's `cms-server`.

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@se-studio/contentful-rest-api",
+  "version": "0.0.0-next16-20260822103555",
+  "description": "Type-safe Contentful REST API client with caching and rate limiting for Next.js applications",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Something-Else-Studio/se-core-product",
+    "directory": "packages/contentful-rest-api"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "require": "./dist/server.js",
+      "default": "./dist/server.js"
+    },
+    "./cms-integrity": {
+      "types": "./dist/cms-integrity.d.ts",
+      "import": "./dist/cms-integrity.js",
+      "require": "./dist/cms-integrity.js",
+      "default": "./dist/cms-integrity.js"
+    }
+  },
+  "files": [
+    "dist",
+    "*.md",
+    "docs"
+  ],
+  "keywords": [
+    "contentful",
+    "cms",
+    "nextjs",
+    "next.js",
+    "typescript",
+    "rest-api",
+    "rest",
+    "api-client",
+    "caching",
+    "cache",
+    "rate-limiting",
+    "webhook",
+    "revalidation",
+    "isr",
+    "incremental-static-regeneration"
+  ],
+  "homepage": "https://github.com/Something-Else-Studio/se-core-product#readme",
+  "bugs": {
+    "url": "https://github.com/Something-Else-Studio/se-core-product/issues"
+  },
+  "dependencies": {
+    "@contentful/rich-text-types": "^17.2.7",
+    "contentful": "^11.12.7",
+    "fflate": "^0.8.3",
+    "server-only": "0.0.1",
+    "@se-studio/core-data-types": "1.12.0"
+  },
+  "peerDependencies": {
+    "next": ">=15.5.0 <17"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.5",
+    "@types/node": "^24.13.3",
+    "next": "^16.3.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json && node scripts/fix-esm-imports.mjs",
+    "dev": "tsc --project tsconfig.build.json --watch",
+    "type-check": "tsc --noEmit",
+    "lint": "biome lint .",
+    "test": "vitest run && node --test scripts/cms-query-log-consolidate.test.mjs",
+    "consolidate-cms-logs": "node scripts/consolidate-cms-query-logs.mjs",
+    "clean": "rm -rf dist .turbo *.tsbuildinfo"
+  }
+}