@se-studio/contentful-rest-api 1.0.46 → 1.0.47

package/dist/api/asset.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Contentful Asset API Module
+ *
+ * Provides functions for fetching and serving Contentful assets
+ * with proper caching and Content-Disposition handling.
+ */
+import { type ContentfulAssetResponse } from '../client';
+import type { ContentfulConfig, FetchOptions } from '../types';
+export type { ContentfulAssetFields, ContentfulAssetResponse } from '../client';
+/**
+ * Check if a content type can be displayed inline in the browser.
+ * Returns true for PDFs, images, videos, and common text formats.
+ *
+ * @param contentType - MIME type to check
+ * @returns true if the browser can display this content type inline
+ */
+export declare function isBrowserViewable(contentType: string): boolean;
+/**
+ * Fetch asset metadata from Contentful by asset ID.
+ * Uses the shared Contentful client with rate limiting and retry logic.
+ *
+ * @param config - Contentful configuration
+ * @param assetId - The Contentful asset ID
+ * @param options - Optional fetch options (preview, cache settings)
+ * @returns The asset response or null if not found
+ */
+export declare function contentfulAssetRest(config: ContentfulConfig, assetId: string, options: FetchOptions): Promise<ContentfulAssetResponse | null>;
+//# sourceMappingURL=asset.d.ts.map

package/dist/api/asset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset.d.ts","sourceRoot":"","sources":["../../src/api/asset.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,uBAAuB,EAAuB,MAAM,WAAW,CAAC;AAE9E,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAG/D,YAAY,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AAchF;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAO9D;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC,CAazC"}

package/dist/api/asset.js

@@ -0,0 +1,55 @@
+/**
+ * Contentful Asset API Module
+ *
+ * Provides functions for fetching and serving Contentful assets
+ * with proper caching and Content-Disposition handling.
+ */
+import { getContentfulClient } from '../client';
+import { getCacheTags } from '../revalidation/utils';
+/**
+ * Content types that browsers can display inline
+ */
+const BROWSER_VIEWABLE_TYPES = [
+    'application/pdf',
+    'text/plain',
+    'text/html',
+    'text/css',
+    'text/javascript',
+    'application/json',
+];
+/**
+ * Check if a content type can be displayed inline in the browser.
+ * Returns true for PDFs, images, videos, and common text formats.
+ *
+ * @param contentType - MIME type to check
+ * @returns true if the browser can display this content type inline
+ */
+export function isBrowserViewable(contentType) {
+    // All images and videos are viewable
+    if (contentType.startsWith('image/') || contentType.startsWith('video/')) {
+        return true;
+    }
+    return BROWSER_VIEWABLE_TYPES.includes(contentType);
+}
+/**
+ * Fetch asset metadata from Contentful by asset ID.
+ * Uses the shared Contentful client with rate limiting and retry logic.
+ *
+ * @param config - Contentful configuration
+ * @param assetId - The Contentful asset ID
+ * @param options - Optional fetch options (preview, cache settings)
+ * @returns The asset response or null if not found
+ */
+export async function contentfulAssetRest(config, assetId, options) {
+    const client = getContentfulClient(config, options.preview);
+    // Get cache tags for this asset
+    const cacheTags = getCacheTags('asset', assetId, options?.preview);
+    return client.getAsset(assetId, {
+        ...options,
+        next: {
+            revalidate: options?.next?.revalidate ?? 86400, // Default 24 hours
+            tags: [...cacheTags, ...(options?.next?.tags ?? [])],
+        },
+    });
+}
+//# sourceMappingURL=asset.js.map

package/dist/api/asset.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset.js","sourceRoot":"","sources":["../../src/api/asset.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAgC,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAC9E,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAMrD;;GAEG;AACH,MAAM,sBAAsB,GAAG;IAC7B,iBAAiB;IACjB,YAAY;IACZ,WAAW;IACX,UAAU;IACV,iBAAiB;IACjB,kBAAkB;CACnB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,WAAmB;IACnD,qCAAqC;IACrC,IAAI,WAAW,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,WAAW,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QACzE,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,sBAAsB,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AACtD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,MAAwB,EACxB,OAAe,EACf,OAAqB;IAErB,MAAM,MAAM,GAAG,mBAAmB,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAE5D,gCAAgC;IAChC,MAAM,SAAS,GAAG,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAEnE,OAAO,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE;QAC9B,GAAG,OAAO;QACV,IAAI,EAAE;YACJ,UAAU,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,IAAI,KAAK,EAAE,mBAAmB;YACnE,IAAI,EAAE,CAAC,GAAG,SAAS,EAAE,GAAG,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC;SACrD;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/api/context.d.ts

@@ -0,0 +1,24 @@
+import type { BaseConverterContext, UrlCalculators } from '../converters/helpers';
+/**
+ * Creates a base converter context with default resolvers for all content types.
+ *
+ * Sets up default converters for:
+ * - Pages, Articles, Article Types
+ * - Components, Collections, External Components
+ * - Links (pages, articles, tags, people, etc.)
+ * - Navigation items
+ *
+ * Projects can extend this context with custom resolvers for specific content types.
+ *
+ * @returns Base converter context with all default resolvers configured
+ *
+ * @example
+ * ```ts
+ * const context = createBaseConverterContext();
+ *
+ * // Use with API functions
+ * const page = await contentfulPageRest(context, config, 'home');
+ * ```
+ */
+export declare function createBaseConverterContext(urlCalculators: UrlCalculators): BaseConverterContext;
+//# sourceMappingURL=context.d.ts.map

package/dist/api/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/api/context.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EACV,oBAAoB,EAKpB,cAAc,EACf,MAAM,uBAAuB,CAAC;AAW/B;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,0BAA0B,CAAC,cAAc,EAAE,cAAc,GAAG,oBAAoB,CAqC/F"}

package/dist/api/context.js

@@ -0,0 +1,62 @@
+import { baseArticleConverter, baseArticleLinkConverter, baseArticleTypeConverter, baseArticleTypeLinkConverter, } from '../converters/article';
+import { baseCollectionConverter } from '../converters/collection';
+import { baseComponentConverter } from '../converters/component';
+import { baseCustomTypeConverter, baseCustomTypeLinkConverter } from '../converters/customType';
+import { baseExternalComponentConverter } from '../converters/externalComponent';
+import { baseLinkConverter } from '../converters/link';
+import { baseNavigationItemConverter } from '../converters/navigationItem';
+import { basePageConverter, basePageLinkConverter, basePageVariantLinkConverter, } from '../converters/page';
+import { basePersonConverter, basePersonLinkConverter } from '../converters/person';
+import { baseTagConverter, baseTagLinkConverter } from '../converters/tag';
+/**
+ * Creates a base converter context with default resolvers for all content types.
+ *
+ * Sets up default converters for:
+ * - Pages, Articles, Article Types
+ * - Components, Collections, External Components
+ * - Links (pages, articles, tags, people, etc.)
+ * - Navigation items
+ *
+ * Projects can extend this context with custom resolvers for specific content types.
+ *
+ * @returns Base converter context with all default resolvers configured
+ *
+ * @example
+ * ```ts
+ * const context = createBaseConverterContext();
+ *
+ * // Use with API functions
+ * const page = await contentfulPageRest(context, config, 'home');
+ * ```
+ */
+export function createBaseConverterContext(urlCalculators) {
+    const linkResolver = new Map();
+    linkResolver.set('page', basePageLinkConverter);
+    linkResolver.set('article', baseArticleLinkConverter);
+    linkResolver.set('articleType', baseArticleTypeLinkConverter);
+    linkResolver.set('tag', baseTagLinkConverter);
+    linkResolver.set('person', basePersonLinkConverter);
+    linkResolver.set('pageVariant', basePageVariantLinkConverter);
+    linkResolver.set('link', baseLinkConverter);
+    linkResolver.set('customType', baseCustomTypeLinkConverter);
+    const contentResolver = new Map();
+    contentResolver.set('collection', baseCollectionConverter);
+    contentResolver.set('component', baseComponentConverter);
+    contentResolver.set('externalComponent', baseExternalComponentConverter);
+    return {
+        pageResolver: basePageConverter,
+        navigationItemResolver: baseNavigationItemConverter,
+        articleResolver: baseArticleConverter,
+        articleTypeResolver: baseArticleTypeConverter,
+        tagResolver: baseTagConverter,
+        personResolver: basePersonConverter,
+        customTypeResolver: baseCustomTypeConverter,
+        componentResolver: baseComponentConverter,
+        collectionResolver: baseCollectionConverter,
+        linkResolver,
+        contentResolver,
+        urlCalculators,
+        videoPrefix: '',
+    };
+}
+//# sourceMappingURL=context.js.map

package/dist/api/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/api/context.ts"],"names":[],"mappings":"AACA,OAAO,EACL,oBAAoB,EACpB,wBAAwB,EACxB,wBAAwB,EACxB,4BAA4B,GAC7B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,EAAE,uBAAuB,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AAChG,OAAO,EAAE,8BAA8B,EAAE,MAAM,iCAAiC,CAAC;AASjF,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,2BAA2B,EAAE,MAAM,8BAA8B,CAAC;AAC3E,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,4BAA4B,GAC7B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AACpF,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,0BAA0B,CAAC,cAA8B;IACvE,MAAM,YAAY,GAAoB,IAAI,GAAG,EAAE,CAAC;IAChD,YAAY,CAAC,GAAG,CAAC,MAAM,EAAE,qBAA6C,CAAC,CAAC;IACxE,YAAY,CAAC,GAAG,CAAC,SAAS,EAAE,wBAA8D,CAAC,CAAC;IAC5F,YAAY,CAAC,GAAG,CACd,aAAa,EACb,4BAAsE,CACvE,CAAC;IACF,YAAY,CAAC,GAAG,CAAC,KAAK,EAAE,oBAA4C,CAAC,CAAC;IACtE,YAAY,CAAC,GAAG,CAAC,QAAQ,EAAE,uBAA+C,CAAC,CAAC;IAC5E,YAAY,CAAC,GAAG,CAAC,aAAa,EAAE,4BAAoD,CAAC,CAAC;IACtF,YAAY,CAAC,GAAG,CAAC,MAAM,EAAE,iBAAyC,CAAC,CAAC;IACpE,YAAY,CAAC,GAAG,CAAC,YAAY,EAAE,2BAAmD,CAAC,CAAC;IAEpF,MAAM,eAAe,GAAuB,IAAI,GAAG,EAAE,CAAC;IACtD,eAAe,CAAC,GAAG,CAAC,YAAY,EAAE,uBAAkD,CAAC,CAAC;IACtF,eAAe,CAAC,GAAG,CAAC,WAAW,EAAE,sBAAiD,CAAC,CAAC;IACpF,eAAe,CAAC,GAAG,CACjB,mBAAmB,EACnB,8BAAyD,CAC1D,CAAC;IAEF,OAAO;QACL,YAAY,EAAE,iBAAiB;QAC/B,sBAAsB,EAAE,2BAA2B;QACnD,eAAe,EAAE,oBAAoB;QACrC,mBAAmB,EAAE,wBAAwB;QAC7C,WAAW,EAAE,gBAAgB;QAC7B,cAAc,EAAE,mBAAmB;QACnC,kBAAkB,EAAE,uBAAuB;QAC3C,iBAAiB,EAAE,sBAAsB;QACzC,kBAAkB,EAAE,uBAAuB;QAC3C,YAAY;QACZ,eAAe;QACf,cAAc;QACd,WAAW,EAAE,EAAE;KAChB,CAAC;AACJ,CAAC"}

package/dist/api/custom-type.d.ts

@@ -0,0 +1,37 @@
+import type { IBaseCustomType } from '@se-studio/core-data-types';
+import type { BaseConverterContext } from '../converters/helpers';
+import type { CmsResponse, ContentfulConfig, FetchOptions } from '../types';
+/**
+ * Fetches a custom type from Contentful by slug
+ *
+ * Custom types represent index pages for categories like Topics or Resources.
+ * They provide configuration for both the main index page and potentially
+ * individual entry pages.
+ *
+ * @param context - Converter context
+ * @param config - Contentful configuration
+ * @param slug - Custom type's slug to fetch (e.g., 'topics', 'resources')
+ * @param options - Fetch options (locale, preview, caching, etc.)
+ * @returns Promise resolving to IBaseCustomType or null if not found
+ *
+ * @example
+ * ```ts
+ * const customType = await contentfulCustomTypeRest(
+ *   context,
+ *   {
+ *     spaceId: process.env.CONTENTFUL_SPACE_ID!,
+ *     accessToken: process.env.CONTENTFUL_ACCESS_TOKEN!,
+ *   },
+ *   'topics',
+ *   {
+ *     locale: 'en-US',
+ *     cache: {
+ *       tags: ['topics-custom-type'],
+ *       revalidate: 3600
+ *     }
+ *   }
+ * );
+ * ```
+ */
+export declare function contentfulCustomTypeRest(context: BaseConverterContext, config: ContentfulConfig, slug: string, options: FetchOptions): Promise<CmsResponse<IBaseCustomType | null>>;
+//# sourceMappingURL=custom-type.d.ts.map

package/dist/api/custom-type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-type.d.ts","sourceRoot":"","sources":["../../src/api/custom-type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAElE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAG5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,oBAAoB,EAC7B,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,WAAW,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC,CAc9C"}

package/dist/api/custom-type.js

@@ -0,0 +1,44 @@
+import { fetchSingleEntity } from './helpers';
+/**
+ * Fetches a custom type from Contentful by slug
+ *
+ * Custom types represent index pages for categories like Topics or Resources.
+ * They provide configuration for both the main index page and potentially
+ * individual entry pages.
+ *
+ * @param context - Converter context
+ * @param config - Contentful configuration
+ * @param slug - Custom type's slug to fetch (e.g., 'topics', 'resources')
+ * @param options - Fetch options (locale, preview, caching, etc.)
+ * @returns Promise resolving to IBaseCustomType or null if not found
+ *
+ * @example
+ * ```ts
+ * const customType = await contentfulCustomTypeRest(
+ *   context,
+ *   {
+ *     spaceId: process.env.CONTENTFUL_SPACE_ID!,
+ *     accessToken: process.env.CONTENTFUL_ACCESS_TOKEN!,
+ *   },
+ *   'topics',
+ *   {
+ *     locale: 'en-US',
+ *     cache: {
+ *       tags: ['topics-custom-type'],
+ *       revalidate: 3600
+ *     }
+ *   }
+ * );
+ * ```
+ */
+export async function contentfulCustomTypeRest(context, config, slug, options) {
+    return fetchSingleEntity(context, config, {
+        contentType: 'customType',
+        cacheTagType: 'customType',
+        cacheTagIdentifier: slug,
+        query: { 'fields.slug': slug },
+        resolver: (ctx, entry) => ctx.customTypeResolver(ctx, entry),
+        errorLogContext: { slug },
+    }, options);
+}
+//# sourceMappingURL=custom-type.js.map

package/dist/api/custom-type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-type.js","sourceRoot":"","sources":["../../src/api/custom-type.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,OAA6B,EAC7B,MAAwB,EACxB,IAAY,EACZ,OAAqB;IAErB,OAAO,iBAAiB,CACtB,OAAO,EACP,MAAM,EACN;QACE,WAAW,EAAE,YAAY;QACzB,YAAY,EAAE,YAAY;QAC1B,kBAAkB,EAAE,IAAI;QACxB,KAAK,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE;QAC9B,QAAQ,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,CAAC,kBAAkB,CAAC,GAAG,EAAE,KAAK,CAAC;QAC5D,eAAe,EAAE,EAAE,IAAI,EAAE;KAC1B,EACD,OAAO,CACR,CAAC;AACJ,CAAC"}

package/dist/api/helpers.d.ts

@@ -0,0 +1,73 @@
+import type { IArticleLink, IInternalLink, IVisual } from '@se-studio/core-data-types';
+import type { Asset, Entry, EntrySkeletonType } from 'contentful';
+import type { BaseArticleSkeleton } from '../baseTypes/baseArticle';
+import type { BaseArticleTypeSkeleton } from '../baseTypes/baseArticleType';
+import type { BasePageSkeleton } from '../baseTypes/basePage';
+import type { BasePersonSkeleton } from '../baseTypes/basePerson';
+import type { BaseTagSkeleton } from '../baseTypes/baseTag';
+import { type ContentfulResponse, getContentfulClient } from '../client';
+import type { BaseConverterContext, ConverterContext } from '../converters/helpers';
+import type { CmsResponse, ContentfulConfig, FetchOptions } from '../types';
+import type { DefaultChainModifier, PossibleResolvedEntry, SingleEntityFetchConfig } from './types';
+/**
+ * Build fetch options with defaults.
+ *
+ * @param options - Provided fetch options
+ * @param defaultDraftOnly - Default value for preview if not specified
+ * @returns Combined fetch options
+ */
+export declare function buildFetchOptions(options: FetchOptions | undefined, defaultDraftOnly?: boolean): FetchOptions;
+/**
+ * Get Contentful configuration from environment variables.
+ *
+ * Supports CONTENTFUL_SPACE_ID, CONTENTFUL_ENVIRONMENT (or CONTENTFUL_ENVIRONMENT_NAME),
+ * and access tokens for both delivery and preview.
+ *
+ * @param preview - Whether to get the preview access token
+ * @returns Contentful configuration object
+ * @throws Error if required environment variables are missing
+ */
+export declare function getContentfulConfig(preview: boolean): ContentfulConfig;
+/**
+ * Generic fetcher helper that simplifies CMS data fetching in projects.
+ *
+ * Combines a lower-level fetcher with project-specific context and configuration,
+ * handles common error logging pattern, and returns the data directly.
+ *
+ * @param fetcher - The API function to call
+ * @param context - The project's converter context
+ * @param config - Contentful configuration
+ * @param options - Fetch options
+ * @param errorLabel - Human-readable label for error logging (e.g., 'page links')
+ * @returns Promise resolving to the fetched data
+ */
+export declare function fetchWithErrors<T>(fetcher: (context: BaseConverterContext, config: ContentfulConfig, options: FetchOptions) => Promise<CmsResponse<T>>, context: BaseConverterContext, config: ContentfulConfig, options: FetchOptions, errorLabel: string): Promise<T>;
+/**
+ * Field selection constants for link-only fetching.
+ * These reduce payload size by excluding content arrays, navigation, templates, etc.
+ */
+export declare const PAGE_LINK_FIELDS = "sys,fields.cmsLabel,fields.title,fields.slug,fields.featuredImage,fields.backgroundColour,fields.textColour,fields.indexed,fields.hidden,fields.tags";
+export declare const ARTICLE_LINK_FIELDS = "sys,fields.cmsLabel,fields.title,fields.slug,fields.featuredImage,fields.backgroundColour,fields.textColour,fields.indexed,fields.hidden,fields.tags,fields.articleType,fields.date,fields.author,fields.externalLink,fields.download";
+export declare const ARTICLE_TYPE_LINK_FIELDS = "sys,fields.name,fields.slug,fields.featuredImage,fields.backgroundColour,fields.textColour,fields.indexed,fields.hidden";
+export declare const TAG_LINK_FIELDS = "sys,fields.cmsLabel,fields.name,fields.slug,fields.featuredImage,fields.backgroundColour,fields.textColour,fields.indexed,fields.hidden";
+export declare const PERSON_LINK_FIELDS = "sys,fields.name,fields.slug,fields.media,fields.backgroundColour,fields.textColour,fields.indexed,fields.hidden";
+export declare function convertAllAssets(response: ContentfulResponse<unknown>, context: BaseConverterContext): Map<string, IVisual>;
+export declare function convertAllRawAssets(response: ContentfulResponse<unknown>): Map<string, Asset>;
+export declare function convertAllIncludes(response: ContentfulResponse<unknown>): Map<string, PossibleResolvedEntry>;
+/**
+ * Generic helper for fetching a single entity from Contentful.
+ * Handles caching, error handling, retry logic, and conversion consistently.
+ *
+ * @param context - Base converter context for content transformation
+ * @param config - Contentful configuration (spaceId, accessToken, environment)
+ * @param fetchConfig - Configuration for this specific fetch
+ * @param options - Optional fetch options (locale, preview, caching, retry)
+ * @returns Promise resolving to the entity or null if not found, with any conversion errors
+ */
+export declare function fetchSingleEntity<TEntry extends EntrySkeletonType, TResult>(context: BaseConverterContext, config: ContentfulConfig, fetchConfig: SingleEntityFetchConfig<TEntry, TResult>, options: FetchOptions): Promise<CmsResponse<TResult | null>>;
+/**
+ * Shared helper function for paginated Contentful link fetching.
+ * Returns links with lastModified metadata from sys.updatedAt.
+ */
+export declare function fetchAllLinks<TEntry extends EntrySkeletonType = BasePageSkeleton | BaseArticleSkeleton | BaseArticleTypeSkeleton | BaseTagSkeleton | BasePersonSkeleton, TResult extends IInternalLink | IArticleLink = IInternalLink>(contentType: string, client: ReturnType<typeof getContentfulClient>, requestOptions: FetchOptions | undefined, converter: (context: ConverterContext, entry: Entry<TEntry, DefaultChainModifier, string>) => TResult, context: BaseConverterContext, pageSize?: number, select?: string): Promise<CmsResponse<TResult[]>>;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/api/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/api/helpers.ts"],"names":[],"mappings":"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"}

package/dist/api/helpers.js

@@ -0,0 +1,296 @@
+import { getContentfulClient } from '../client';
+import { convertAssetToVisual } from '../converters/asset';
+import { processIconsForSprite } from '../converters/iconCollector';
+import { getCacheTags } from '../revalidation/utils';
+import { withRetry } from '../utils';
+// ============================================================================
+// CMS Configuration and Options
+// ============================================================================
+/**
+ * Build fetch options with defaults.
+ *
+ * @param options - Provided fetch options
+ * @param defaultDraftOnly - Default value for preview if not specified
+ * @returns Combined fetch options
+ */
+export function buildFetchOptions(options, defaultDraftOnly = false) {
+    const preview = options?.preview === undefined ? defaultDraftOnly : options.preview;
+    return {
+        preview,
+        cache: 'force-cache',
+        ...options,
+    };
+}
+/**
+ * Get Contentful configuration from environment variables.
+ *
+ * Supports CONTENTFUL_SPACE_ID, CONTENTFUL_ENVIRONMENT (or CONTENTFUL_ENVIRONMENT_NAME),
+ * and access tokens for both delivery and preview.
+ *
+ * @param preview - Whether to get the preview access token
+ * @returns Contentful configuration object
+ * @throws Error if required environment variables are missing
+ */
+export function getContentfulConfig(preview) {
+    const spaceId = process.env.CONTENTFUL_SPACE_ID;
+    const environment = process.env.CONTENTFUL_ENVIRONMENT || process.env.CONTENTFUL_ENVIRONMENT_NAME;
+    const accessToken = preview
+        ? process.env.CONTENTFUL_PREVIEW_ACCESS_TOKEN
+        : process.env.CONTENTFUL_ACCESS_TOKEN;
+    if (!spaceId) {
+        throw new Error('CONTENTFUL_SPACE_ID environment variable is required');
+    }
+    if (!accessToken) {
+        if (preview) {
+            throw new Error('CONTENTFUL_PREVIEW_ACCESS_TOKEN environment variable is required');
+        }
+        throw new Error('CONTENTFUL_ACCESS_TOKEN environment variable is required');
+    }
+    if (!environment) {
+        throw new Error('CONTENTFUL_ENVIRONMENT or CONTENTFUL_ENVIRONMENT_NAME environment variable is required');
+    }
+    return {
+        spaceId,
+        accessToken,
+        environment,
+    };
+}
+/**
+ * Generic fetcher helper that simplifies CMS data fetching in projects.
+ *
+ * Combines a lower-level fetcher with project-specific context and configuration,
+ * handles common error logging pattern, and returns the data directly.
+ *
+ * @param fetcher - The API function to call
+ * @param context - The project's converter context
+ * @param config - Contentful configuration
+ * @param options - Fetch options
+ * @param errorLabel - Human-readable label for error logging (e.g., 'page links')
+ * @returns Promise resolving to the fetched data
+ */
+export async function fetchWithErrors(fetcher, context, config, options, errorLabel) {
+    const response = await fetcher(context, config, options);
+    if (response.errors.length > 0) {
+        console.warn(`Errors occurred while fetching ${errorLabel}:`, response.errors);
+    }
+    return response.data;
+}
+// ============================================================================
+// Field Selection Constants
+// ============================================================================
+/**
+ * Field selection constants for link-only fetching.
+ * These reduce payload size by excluding content arrays, navigation, templates, etc.
+ */
+export const PAGE_LINK_FIELDS = 'sys,fields.cmsLabel,fields.title,fields.slug,fields.featuredImage,fields.backgroundColour,fields.textColour,fields.indexed,fields.hidden,fields.tags';
+export const ARTICLE_LINK_FIELDS = 'sys,fields.cmsLabel,fields.title,fields.slug,fields.featuredImage,fields.backgroundColour,fields.textColour,fields.indexed,fields.hidden,fields.tags,fields.articleType,fields.date,fields.author,fields.externalLink,fields.download';
+export const ARTICLE_TYPE_LINK_FIELDS = 'sys,fields.name,fields.slug,fields.featuredImage,fields.backgroundColour,fields.textColour,fields.indexed,fields.hidden';
+export const TAG_LINK_FIELDS = 'sys,fields.cmsLabel,fields.name,fields.slug,fields.featuredImage,fields.backgroundColour,fields.textColour,fields.indexed,fields.hidden';
+export const PERSON_LINK_FIELDS = 'sys,fields.name,fields.slug,fields.media,fields.backgroundColour,fields.textColour,fields.indexed,fields.hidden';
+// ============================================================================
+// Asset and Include Conversion
+// ============================================================================
+export function convertAllAssets(response, context) {
+    const visuals = new Map();
+    const assets = response.includes?.Asset;
+    if (assets && assets.length > 0) {
+        for (const asset of assets) {
+            const visual = convertAssetToVisual(context, asset);
+            if (visual) {
+                visuals.set(visual.id, visual);
+            }
+        }
+    }
+    return visuals;
+}
+export function convertAllRawAssets(response) {
+    const rawAssets = new Map();
+    const assets = response.includes?.Asset;
+    if (assets && assets.length > 0) {
+        for (const asset of assets) {
+            rawAssets.set(asset.sys.id, asset);
+        }
+    }
+    return rawAssets;
+}
+export function convertAllIncludes(response) {
+    const includes = new Map();
+    const entries = [...response.items, ...(response.includes?.Entry || [])];
+    if (entries && entries.length > 0) {
+        for (const entry of entries) {
+            if (entry?.sys && entry.fields) {
+                includes.set(entry.sys.id, {
+                    id: entry.sys.id,
+                    type: entry.sys.contentType.sys.id,
+                    entry,
+                });
+            }
+        }
+    }
+    return includes;
+}
+// ============================================================================
+// Generic Single Entity Fetcher
+// ============================================================================
+/**
+ * Generic helper for fetching a single entity from Contentful.
+ * Handles caching, error handling, retry logic, and conversion consistently.
+ *
+ * @param context - Base converter context for content transformation
+ * @param config - Contentful configuration (spaceId, accessToken, environment)
+ * @param fetchConfig - Configuration for this specific fetch
+ * @param options - Optional fetch options (locale, preview, caching, retry)
+ * @returns Promise resolving to the entity or null if not found, with any conversion errors
+ */
+export async function fetchSingleEntity(context, config, fetchConfig, options) {
+    const client = getContentfulClient(config, options.preview);
+    // Set cache tags for this request
+    const cacheTags = getCacheTags(fetchConfig.cacheTagType, fetchConfig.cacheTagIdentifier, options?.preview);
+    const requestOptions = {
+        ...options,
+        next: {
+            ...options?.next,
+            tags: cacheTags,
+        },
+    };
+    const fetchFn = async () => {
+        const response = await client.getEntries({
+            content_type: fetchConfig.contentType,
+            ...fetchConfig.query,
+            include: 10,
+            locale: options?.locale,
+            limit: 1,
+        }, requestOptions);
+        const entry = response.items[0];
+        if (!entry || !entry.fields) {
+            return { data: null, errors: [] };
+        }
+        try {
+            const assets = convertAllAssets(response, context);
+            const rawAssets = convertAllRawAssets(response);
+            const includes = convertAllIncludes(response);
+            const fullContext = {
+                ...context,
+                includes,
+                assets,
+                rawAssets,
+                errors: [],
+            };
+            const converted = fetchConfig.resolver(fullContext, entry);
+            // Process icons if the result has an icons field (e.g., IBasePage)
+            if (converted && typeof converted === 'object' && 'icons' in converted) {
+                const icons = converted.icons;
+                if (icons && Array.isArray(icons) && icons.length > 0) {
+                    const processedIcons = await processIconsForSprite(icons);
+                    converted.icons =
+                        processedIcons.length > 0 ? processedIcons : undefined;
+                }
+            }
+            // Log errors in production
+            if (fullContext.errors.length > 0 &&
+                typeof process !== 'undefined' &&
+                process.env?.NODE_ENV === 'production') {
+                console.error(`CMS conversion errors for ${fetchConfig.contentType}:`, {
+                    entryId: entry.sys.id,
+                    ...fetchConfig.errorLogContext,
+                    errors: fullContext.errors,
+                });
+            }
+            return { data: converted, errors: fullContext.errors };
+        }
+        catch (error) {
+            const entryId = entry.sys.id;
+            const entryType = entry.sys.contentType?.sys?.id;
+            const errorMessage = error instanceof Error ? error.message : 'Unknown conversion error';
+            const cmsError = {
+                entryId,
+                entryType,
+                message: errorMessage,
+                error,
+            };
+            return { data: null, errors: [cmsError] };
+        }
+    };
+    // Apply retry logic if configured
+    if (options?.retry) {
+        return await withRetry(fetchFn, options.retry);
+    }
+    return await fetchFn();
+}
+// ============================================================================
+// Generic All Links Fetcher
+// ============================================================================
+/**
+ * Shared helper function for paginated Contentful link fetching.
+ * Returns links with lastModified metadata from sys.updatedAt.
+ */
+export async function fetchAllLinks(contentType, client, requestOptions, converter, context, pageSize = 100, select) {
+    const allLinks = [];
+    const errors = [];
+    let skip = 0;
+    let hasMore = true;
+    const fetchFn = async () => {
+        while (hasMore) {
+            try {
+                const response = await client.getEntries({
+                    content_type: contentType,
+                    include: 2, // Minimal include for link-only fetching
+                    locale: requestOptions?.locale,
+                    limit: pageSize,
+                    skip,
+                    ...(select && { select }),
+                }, requestOptions);
+                if (response.items.length === 0) {
+                    hasMore = false;
+                    break;
+                }
+                // Convert entries to links
+                const includes = convertAllIncludes(response);
+                const assets = convertAllAssets(response, context);
+                const rawAssets = convertAllRawAssets(response);
+                const fullContext = {
+                    ...context,
+                    includes,
+                    assets,
+                    rawAssets,
+                    errors: [],
+                };
+                for (const entry of response.items) {
+                    if (!entry.fields)
+                        continue;
+                    try {
+                        const converted = converter(fullContext, entry);
+                        // Add lastModified from sys.updatedAt
+                        converted.lastModified = entry.sys.updatedAt
+                            ? new Date(entry.sys.updatedAt)
+                            : undefined;
+                        allLinks.push(converted);
+                    }
+                    catch (error) {
+                        const entryId = entry.sys.id;
+                        const entryType = entry.sys.contentType?.sys?.id;
+                        const errorMessage = error instanceof Error ? error.message : 'Unknown conversion error';
+                        errors.push({
+                            entryId,
+                            entryType,
+                            message: errorMessage,
+                            error,
+                        });
+                    }
+                }
+                skip += pageSize;
+                // Check if we've fetched all items
+                if (skip >= response.total) {
+                    hasMore = false;
+                }
+            }
+            catch (error) {
+                console.error('Error fetching links', typeof error, error, JSON.stringify(error, null, 2));
+                throw error;
+            }
+        }
+        return { data: allLinks, errors };
+    };
+    return await fetchFn();
+}
+//# sourceMappingURL=helpers.js.map