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

package/dist/baseTypes/baseShared.d.ts

@@ -0,0 +1,30 @@
+export type { BaseArticleSkeleton } from './baseArticle';
+export type { BaseArticleTypeSkeleton } from './baseArticleType';
+export type { BaseCollectionSkeleton } from './baseCollection';
+export type { BaseComponentSkeleton } from './baseComponent';
+export type { BaseExternalComponentSkeleton } from './baseExternalComponent';
+export type { BaseExternalVideoSkeleton } from './baseExternalVideo';
+export type { BaseLinkSkeleton } from './baseLink';
+export type { BaseMediaSkeleton } from './baseMedia';
+export type { BasePageSkeleton } from './basePage';
+export type { BasePageVariantSkeleton } from './basePageVariant';
+export type { BasePersonSkeleton } from './basePerson';
+export type { BaseTagSkeleton } from './baseTag';
+import type { BaseArticleSkeleton } from './baseArticle';
+import type { BaseArticleTypeSkeleton } from './baseArticleType';
+import type { BaseCollectionSkeleton } from './baseCollection';
+import type { BaseComponentSkeleton } from './baseComponent';
+import type { BaseCustomTypeSkeleton } from './baseCustomType';
+import type { BaseExternalComponentSkeleton } from './baseExternalComponent';
+import type { BaseExternalVideoSkeleton } from './baseExternalVideo';
+import type { BaseLinkSkeleton } from './baseLink';
+import type { BaseMediaSkeleton } from './baseMedia';
+import type { BasePageSkeleton } from './basePage';
+import type { BasePageVariantSkeleton } from './basePageVariant';
+import type { BasePersonSkeleton } from './basePerson';
+import type { BaseTagSkeleton } from './baseTag';
+export type BaseContent = BaseCollectionSkeleton | BaseComponentSkeleton | BaseExternalComponentSkeleton | BaseExternalVideoSkeleton | BaseMediaSkeleton | BasePersonSkeleton;
+export type BaseLink = BaseArticleSkeleton | BaseArticleTypeSkeleton | BaseLinkSkeleton | BasePageSkeleton | BasePageVariantSkeleton | BasePersonSkeleton | BaseTagSkeleton | BaseCustomTypeSkeleton;
+export type BaseContentTypes = BaseContent['contentTypeId'];
+export type BaseLinkTypes = BaseLink['contentTypeId'];
+//# sourceMappingURL=baseShared.d.ts.map

package/dist/baseTypes/baseShared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseShared.d.ts","sourceRoot":"","sources":["../../src/baseTypes/baseShared.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACzD,YAAY,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AACjE,YAAY,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC/D,YAAY,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAC7D,YAAY,EAAE,6BAA6B,EAAE,MAAM,yBAAyB,CAAC;AAC7E,YAAY,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AACrE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACrD,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,YAAY,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AACjE,YAAY,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACvD,YAAY,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAEjD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,yBAAyB,CAAC;AAC7E,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AACrE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAEjD,MAAM,MAAM,WAAW,GACnB,sBAAsB,GACtB,qBAAqB,GACrB,6BAA6B,GAC7B,yBAAyB,GACzB,iBAAiB,GACjB,kBAAkB,CAAC;AAEvB,MAAM,MAAM,QAAQ,GAChB,mBAAmB,GACnB,uBAAuB,GACvB,gBAAgB,GAChB,gBAAgB,GAChB,uBAAuB,GACvB,kBAAkB,GAClB,eAAe,GACf,sBAAsB,CAAC;AAE3B,MAAM,MAAM,gBAAgB,GAAG,WAAW,CAAC,eAAe,CAAC,CAAC;AAC5D,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC,eAAe,CAAC,CAAC"}

package/dist/baseTypes/baseShared.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=baseShared.js.map

package/dist/baseTypes/baseShared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseShared.js","sourceRoot":"","sources":["../../src/baseTypes/baseShared.ts"],"names":[],"mappings":""}

package/dist/baseTypes/baseTag.d.ts

@@ -0,0 +1,108 @@
+import type { EntryFieldTypes, EntrySkeletonType } from 'contentful';
+import type { BaseExternalVideoSkeleton } from './baseExternalVideo';
+import type { BaseMediaSkeleton } from './baseMedia';
+import type { BaseNavigationSkeleton } from './baseNavigation';
+import type { BaseSchemaSkeleton } from './baseSchema';
+import type { BaseContent } from './baseShared';
+import type { BaseTagTypeSkeleton } from './baseTagType';
+import type { BaseTemplateSkeleton } from './baseTemplate';
+export interface BaseTagFields {
+    /**
+     * Field type definition for field 'cmsLabel' (Cms label)
+     * @name Cms label
+     * @localized false
+     */
+    cmsLabel: EntryFieldTypes.Symbol;
+    /**
+     * Field type definition for field 'name' (Name)
+     * @name Name
+     * @localized false
+     */
+    name: EntryFieldTypes.Symbol;
+    /**
+     * Field type definition for field 'tagType' (Tag type)
+     * @name Tag type
+     * @localized false
+     */
+    tagType: EntryFieldTypes.EntryLink<BaseTagTypeSkeleton>;
+    /**
+     * Field type definition for field 'slug' (Slug)
+     * @name Slug
+     * @localized false
+     */
+    slug: EntryFieldTypes.Symbol;
+    /**
+     * Field type definition for field 'description' (Description)
+     * @name Description
+     * @localized false
+     */
+    description: EntryFieldTypes.Symbol;
+    /**
+     * Field type definition for field 'featuredImage' (Featured Image)
+     * @name Featured Image
+     * @localized false
+     */
+    featuredImage: EntryFieldTypes.AssetLink;
+    /**
+     * Field type definition for field 'visuals' (Visuals)
+     * @name Visuals
+     * @localized false
+     */
+    visuals?: EntryFieldTypes.Array<EntryFieldTypes.EntryLink<BaseExternalVideoSkeleton | BaseMediaSkeleton>>;
+    /**
+     * Field type definition for field 'menu' (Menu)
+     * @name Menu
+     * @localized false
+     */
+    menu?: EntryFieldTypes.EntryLink<BaseNavigationSkeleton>;
+    /**
+     * Field type definition for field 'footer' (Footer)
+     * @name Footer
+     * @localized false
+     */
+    footer?: EntryFieldTypes.EntryLink<BaseNavigationSkeleton>;
+    /**
+     * Field type definition for field 'template' (Template)
+     * @name Template
+     * @localized false
+     */
+    template?: EntryFieldTypes.EntryLink<BaseTemplateSkeleton>;
+    /**
+     * Field type definition for field 'topContent' (Top content)
+     * @name Top content
+     * @localized false
+     */
+    topContent?: EntryFieldTypes.Array<EntryFieldTypes.EntryLink<BaseContent>>;
+    /**
+     * Field type definition for field 'structuredData' (Structured data)
+     * @name Structured data
+     * @localized false
+     */
+    structuredData?: EntryFieldTypes.Array<EntryFieldTypes.EntryLink<BaseSchemaSkeleton>>;
+    /**
+     * Field type definition for field 'backgroundColour' (Background colour)
+     * @name Background colour
+     * @localized false
+     */
+    backgroundColour?: EntryFieldTypes.Symbol<string>;
+    /**
+     * Field type definition for field 'textColour' (Text colour)
+     * @name Text colour
+     * @localized false
+     */
+    textColour?: EntryFieldTypes.Symbol<string>;
+    /**
+     * Field type definition for field 'indexed' (Indexed)
+     * @name Indexed
+     * @localized false
+     */
+    indexed: EntryFieldTypes.Boolean;
+    /**
+     * Field type definition for field 'hidden' (Hidden)
+     * @name Hidden
+     * @localized false
+     */
+    hidden: EntryFieldTypes.Boolean;
+}
+export type BaseTagSkeleton = EntrySkeletonType<BaseTagFields, 'tag'>;
+//# sourceMappingURL=baseTag.d.ts.map

package/dist/baseTypes/baseTag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseTag.d.ts","sourceRoot":"","sources":["../../src/baseTypes/baseTag.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACrE,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AACrE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAE3D,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,QAAQ,EAAE,eAAe,CAAC,MAAM,CAAC;IACjC;;;;OAIG;IACH,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC;IAC7B;;;;OAIG;IACH,OAAO,EAAE,eAAe,CAAC,SAAS,CAAC,mBAAmB,CAAC,CAAC;IACxD;;;;OAIG;IACH,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC;IAC7B;;;;OAIG;IACH,WAAW,EAAE,eAAe,CAAC,MAAM,CAAC;IACpC;;;;OAIG;IACH,aAAa,EAAE,eAAe,CAAC,SAAS,CAAC;IACzC;;;;OAIG;IACH,OAAO,CAAC,EAAE,eAAe,CAAC,KAAK,CAC7B,eAAe,CAAC,SAAS,CAAC,yBAAyB,GAAG,iBAAiB,CAAC,CACzE,CAAC;IACF;;;;OAIG;IACH,IAAI,CAAC,EAAE,eAAe,CAAC,SAAS,CAAC,sBAAsB,CAAC,CAAC;IACzD;;;;OAIG;IACH,MAAM,CAAC,EAAE,eAAe,CAAC,SAAS,CAAC,sBAAsB,CAAC,CAAC;IAC3D;;;;OAIG;IACH,QAAQ,CAAC,EAAE,eAAe,CAAC,SAAS,CAAC,oBAAoB,CAAC,CAAC;IAC3D;;;;OAIG;IACH,UAAU,CAAC,EAAE,eAAe,CAAC,KAAK,CAAC,eAAe,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC;IAC3E;;;;OAIG;IACH,cAAc,CAAC,EAAE,eAAe,CAAC,KAAK,CAAC,eAAe,CAAC,SAAS,CAAC,kBAAkB,CAAC,CAAC,CAAC;IACtF;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,eAAe,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAClD;;;;OAIG;IACH,UAAU,CAAC,EAAE,eAAe,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC5C;;;;OAIG;IACH,OAAO,EAAE,eAAe,CAAC,OAAO,CAAC;IACjC;;;;OAIG;IACH,MAAM,EAAE,eAAe,CAAC,OAAO,CAAC;CACjC;AAED,MAAM,MAAM,eAAe,GAAG,iBAAiB,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC"}

package/dist/baseTypes/baseTag.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=baseTag.js.map

package/dist/baseTypes/baseTag.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseTag.js","sourceRoot":"","sources":["../../src/baseTypes/baseTag.ts"],"names":[],"mappings":""}

package/dist/baseTypes/baseTagType.d.ts

@@ -0,0 +1,11 @@
+import type { EntryFieldTypes, EntrySkeletonType } from 'contentful';
+export interface BaseTagTypeFields {
+    /**
+     * Field type definition for field 'name' (Name)
+     * @name Name
+     * @localized false
+     */
+    name: EntryFieldTypes.Symbol;
+}
+export type BaseTagTypeSkeleton = EntrySkeletonType<BaseTagTypeFields, 'tagType'>;
+//# sourceMappingURL=baseTagType.d.ts.map

package/dist/baseTypes/baseTagType.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseTagType.d.ts","sourceRoot":"","sources":["../../src/baseTypes/baseTagType.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAErE,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC;CAC9B;AAED,MAAM,MAAM,mBAAmB,GAAG,iBAAiB,CAAC,iBAAiB,EAAE,SAAS,CAAC,CAAC"}

package/dist/baseTypes/baseTagType.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=baseTagType.js.map

package/dist/baseTypes/baseTagType.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseTagType.js","sourceRoot":"","sources":["../../src/baseTypes/baseTagType.ts"],"names":[],"mappings":""}

package/dist/baseTypes/baseTemplate.d.ts

@@ -0,0 +1,55 @@
+import type { EntryFieldTypes, EntrySkeletonType } from 'contentful';
+import type { BaseNavigationSkeleton } from './baseNavigation';
+import type { BaseContent } from './baseShared';
+export interface BaseTemplateFields {
+    /**
+     * Field type definition for field 'cmsLabel' (CMS Label)
+     * @name CMS Label
+     * @localized false
+     */
+    cmsLabel: EntryFieldTypes.Symbol;
+    /**
+     * Field type definition for field 'preContent' (Pre content)
+     * @name Pre content
+     * @localized false
+     */
+    preContent?: EntryFieldTypes.Array<EntryFieldTypes.EntryLink<BaseContent>>;
+    /**
+     * Field type definition for field 'postContent' (Post content)
+     * @name Post content
+     * @localized false
+     */
+    postContent?: EntryFieldTypes.Array<EntryFieldTypes.EntryLink<BaseContent>>;
+    /**
+     * Field type definition for field 'menu' (Menu)
+     * @name Menu
+     * @localized false
+     */
+    menu?: EntryFieldTypes.EntryLink<BaseNavigationSkeleton>;
+    /**
+     * Field type definition for field 'footer' (Footer)
+     * @name Footer
+     * @localized false
+     */
+    footer?: EntryFieldTypes.EntryLink<BaseNavigationSkeleton>;
+    /**
+     * Field type definition for field 'backgroundColour' (Background colour)
+     * @name Background colour
+     * @localized false
+     */
+    backgroundColour?: EntryFieldTypes.Symbol<string>;
+    /**
+     * Field type definition for field 'textColour' (Text colour)
+     * @name Text colour
+     * @localized false
+     */
+    textColour?: EntryFieldTypes.Symbol<string>;
+    /**
+     * Field type definition for field 'flags' (Flags)
+     * @name Flags
+     * @localized false
+     */
+    flags?: EntryFieldTypes.Array<EntryFieldTypes.Symbol<'Sticky nav'>>;
+}
+export type BaseTemplateSkeleton = EntrySkeletonType<BaseTemplateFields, 'template'>;
+//# sourceMappingURL=baseTemplate.d.ts.map

package/dist/baseTypes/baseTemplate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseTemplate.d.ts","sourceRoot":"","sources":["../../src/baseTypes/baseTemplate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACrE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,QAAQ,EAAE,eAAe,CAAC,MAAM,CAAC;IACjC;;;;OAIG;IACH,UAAU,CAAC,EAAE,eAAe,CAAC,KAAK,CAAC,eAAe,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC;IAC3E;;;;OAIG;IACH,WAAW,CAAC,EAAE,eAAe,CAAC,KAAK,CAAC,eAAe,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC;IAC5E;;;;OAIG;IACH,IAAI,CAAC,EAAE,eAAe,CAAC,SAAS,CAAC,sBAAsB,CAAC,CAAC;IACzD;;;;OAIG;IACH,MAAM,CAAC,EAAE,eAAe,CAAC,SAAS,CAAC,sBAAsB,CAAC,CAAC;IAC3D;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,eAAe,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAClD;;;;OAIG;IACH,UAAU,CAAC,EAAE,eAAe,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC5C;;;;OAIG;IACH,KAAK,CAAC,EAAE,eAAe,CAAC,KAAK,CAAC,eAAe,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC;CACrE;AAED,MAAM,MAAM,oBAAoB,GAAG,iBAAiB,CAAC,kBAAkB,EAAE,UAAU,CAAC,CAAC"}

package/dist/baseTypes/baseTemplate.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=baseTemplate.js.map

package/dist/baseTypes/baseTemplate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseTemplate.js","sourceRoot":"","sources":["../../src/baseTypes/baseTemplate.ts"],"names":[],"mappings":""}

package/dist/client.d.ts

@@ -0,0 +1,143 @@
+/** biome-ignore-all lint/suspicious/noExplicitAny: Any ok for now! */
+import type { ContentfulConfig, FetchOptions } from './types';
+/**
+ * Contentful REST API response structure
+ * The items array contains Entry objects when T is an EntrySkeletonType
+ */
+export interface ContentfulResponse<T = any> {
+    sys: {
+        type: 'Array';
+    };
+    total: number;
+    skip: number;
+    limit: number;
+    items: T extends import('contentful').EntrySkeletonType ? Array<import('contentful').Entry<T, 'WITHOUT_LINK_RESOLUTION', string>> : T[];
+    includes?: {
+        Entry?: any[];
+        Asset?: any[];
+    };
+}
+/**
+ * Contentful Asset fields structure
+ */
+export interface ContentfulAssetFields {
+    title?: string;
+    description?: string;
+    file?: {
+        url: string;
+        fileName: string;
+        contentType: string;
+        details?: {
+            size?: number;
+            image?: {
+                width: number;
+                height: number;
+            };
+        };
+    };
+}
+/**
+ * Contentful Asset API response structure
+ */
+export interface ContentfulAssetResponse {
+    sys: {
+        id: string;
+        type: 'Asset';
+        createdAt: string;
+        updatedAt: string;
+    };
+    fields: ContentfulAssetFields;
+}
+/**
+ * Query parameters for Contentful API
+ */
+export interface ContentfulQuery {
+    content_type?: string;
+    locale?: string;
+    include?: number;
+    limit?: number;
+    skip?: number;
+    [key: string]: any;
+}
+/**
+ * Fetch-based Contentful client that participates in Next.js caching.
+ * Includes proactive rate limiting and automatic retry on 429 errors.
+ */
+export declare class ContentfulFetchClient {
+    private readonly baseUrl;
+    private readonly accessToken;
+    private readonly rateLimiter;
+    private readonly isPreview;
+    constructor(config: ContentfulConfig, preview?: boolean);
+    /**
+     * Fetches entries from Contentful with proactive rate limiting
+     * and automatic retry on rate limit errors.
+     *
+     * Rate limits are applied proactively:
+     * - Preview API: 14 requests/second
+     * - Delivery API: 55 requests/second
+     *
+     * If a 429 is still received (e.g., due to other processes), retries with backoff.
+     */
+    getEntries<T = any>(query: ContentfulQuery, options?: FetchOptions): Promise<ContentfulResponse<T>>;
+    /**
+     * Fetches a single asset from Contentful by ID with proactive rate limiting
+     * and automatic retry on rate limit errors.
+     *
+     * @param assetId - The Contentful asset ID
+     * @param options - Optional fetch options (locale, preview, caching, retry)
+     * @returns The asset response or null if not found
+     */
+    getAsset(assetId: string, options?: FetchOptions): Promise<ContentfulAssetResponse | null>;
+}
+/**
+ * Creates a Contentful Content Delivery API (CDA) client
+ *
+ * @param config - Configuration object for the Contentful client
+ * @returns Contentful CDA client instance
+ *
+ * @example
+ * ```ts
+ * const client = createContentfulClient({
+ *   spaceId: process.env.CONTENTFUL_SPACE_ID!,
+ *   accessToken: process.env.CONTENTFUL_ACCESS_TOKEN!,
+ *   environment: 'master'
+ * });
+ * ```
+ */
+export declare function createContentfulClient(config: ContentfulConfig): ContentfulFetchClient;
+/**
+ * Creates a Contentful Content Preview API (CPA) client
+ *
+ * @param config - Configuration object for the Contentful preview client
+ * @returns Contentful CPA client instance
+ *
+ * @example
+ * ```ts
+ * const previewClient = createContentfulPreviewClient({
+ *   spaceId: process.env.CONTENTFUL_SPACE_ID!,
+ *   accessToken: process.env.CONTENTFUL_PREVIEW_ACCESS_TOKEN!,
+ *   environment: 'master'
+ * });
+ * ```
+ */
+export declare function createContentfulPreviewClient(config: ContentfulConfig): ContentfulFetchClient;
+/**
+ * Gets the appropriate Contentful client based on preview mode
+ *
+ * @param config - Configuration for the Contentful client
+ * @param preview - Whether to use the preview API
+ * @returns Contentful client instance (CDA or CPA)
+ *
+ * @example
+ * ```ts
+ * const client = getContentfulClient({
+ *   spaceId: process.env.CONTENTFUL_SPACE_ID!,
+ *   accessToken: preview
+ *     ? process.env.CONTENTFUL_PREVIEW_ACCESS_TOKEN!
+ *     : process.env.CONTENTFUL_ACCESS_TOKEN!,
+ * }, preview);
+ * ```
+ */
+export declare function getContentfulClient(config: ContentfulConfig, preview: boolean): ContentfulFetchClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

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

package/dist/client.js

@@ -0,0 +1,268 @@
+import { AuthenticationError, ContentfulError, EntryNotFoundError, RateLimitError, ValidationError, } from './utils/errors';
+import { calculateBackoffDelay, getRateLimiter } from './utils/retry';
+/**
+ * Builds query string from query parameters
+ */
+function buildQueryString(query) {
+    const params = new URLSearchParams();
+    Object.entries(query).forEach(([key, value]) => {
+        if (value !== undefined && value !== null) {
+            params.append(key, String(value));
+        }
+    });
+    return params.toString();
+}
+/**
+ * Sleep utility for async delays
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Retry configuration for 429 error handling in getEntries
+ */
+const RETRY_CONFIG = {
+    maxRetries: 10,
+    initialDelay: 1000,
+    maxDelay: 15000,
+    backoffMultiplier: 2,
+};
+/**
+ * Parses retry-after header from response
+ *
+ * @param response - Fetch response object
+ * @returns Retry-after value in seconds, or undefined if not present
+ */
+function parseRetryAfter(response) {
+    const retryAfterHeader = response.headers.get('X-Contentful-RateLimit-Reset') || response.headers.get('Retry-After');
+    if (retryAfterHeader) {
+        const parsed = Number.parseInt(retryAfterHeader, 10);
+        return Number.isNaN(parsed) ? undefined : parsed;
+    }
+    return undefined;
+}
+/**
+ * Parses error response from Contentful API
+ */
+async function parseErrorResponse(response) {
+    const statusCode = response.status;
+    let errorData;
+    try {
+        errorData = await response.json();
+    }
+    catch {
+        errorData = { message: response.statusText };
+    }
+    const message = errorData?.message || `Contentful API error: ${statusCode}`;
+    switch (statusCode) {
+        case 401:
+            return new AuthenticationError(message);
+        case 404:
+            return new EntryNotFoundError(errorData?.sys?.id || 'unknown', errorData?.sys?.contentType?.sys?.id);
+        case 429: {
+            // Parse retry-after header (in seconds)
+            const retryAfterHeader = response.headers.get('X-Contentful-RateLimit-Reset') || response.headers.get('Retry-After');
+            const retryAfter = retryAfterHeader ? Number.parseInt(retryAfterHeader, 10) : undefined;
+            return new RateLimitError(message, retryAfter, errorData);
+        }
+        case 400:
+            return new ValidationError(message, errorData);
+        default:
+            return new ContentfulError(message, statusCode, errorData);
+    }
+}
+/**
+ * Fetch-based Contentful client that participates in Next.js caching.
+ * Includes proactive rate limiting and automatic retry on 429 errors.
+ */
+export class ContentfulFetchClient {
+    baseUrl;
+    accessToken;
+    rateLimiter;
+    isPreview;
+    constructor(config, preview = false) {
+        const host = config.host || (preview ? 'preview.contentful.com' : 'cdn.contentful.com');
+        const environment = config.environment || 'master';
+        this.baseUrl = `https://${host}/spaces/${config.spaceId}/environments/${environment}`;
+        this.accessToken = config.accessToken;
+        this.isPreview = preview;
+        this.rateLimiter = getRateLimiter(preview);
+    }
+    /**
+     * Fetches entries from Contentful with proactive rate limiting
+     * and automatic retry on rate limit errors.
+     *
+     * Rate limits are applied proactively:
+     * - Preview API: 14 requests/second
+     * - Delivery API: 55 requests/second
+     *
+     * If a 429 is still received (e.g., due to other processes), retries with backoff.
+     */
+    async getEntries(query, options) {
+        const queryString = buildQueryString(query);
+        const url = `${this.baseUrl}/entries?${queryString}`;
+        const fetchOptions = {
+            headers: {
+                Authorization: `Bearer ${this.accessToken}`,
+                'Content-Type': 'application/json',
+            },
+        };
+        // Add Next.js cache configuration if provided
+        if (options?.next) {
+            fetchOptions.next = options.next;
+        }
+        for (let attempt = 0; attempt <= RETRY_CONFIG.maxRetries; attempt++) {
+            try {
+                // Wait for rate limiter before making request
+                await this.rateLimiter.acquire();
+                const response = await fetch(url, fetchOptions);
+                if (response.ok) {
+                    return response.json();
+                }
+                // Handle rate limiting (429) with automatic retry
+                if (response.status === 429 && attempt < RETRY_CONFIG.maxRetries) {
+                    const retryAfter = parseRetryAfter(response);
+                    const delay = calculateBackoffDelay(attempt, RETRY_CONFIG, retryAfter);
+                    console.warn(`[Contentful] Rate limited (429), retrying in ${delay}ms (attempt ${attempt + 1}/${RETRY_CONFIG.maxRetries}). ` +
+                        `Queue: ${this.rateLimiter.getQueueLength()} waiting. ` +
+                        `API: ${this.isPreview ? 'preview' : 'delivery'}`);
+                    // Pause the rate limiter - this affects all queued requests
+                    // Use the longer of retryAfter or 2 seconds as minimum pause
+                    const pauseSeconds = Math.max(retryAfter ?? 2, 2);
+                    this.rateLimiter.pause(pauseSeconds);
+                    // Wait before retrying this request
+                    await sleep(delay);
+                    continue;
+                }
+                // For non-429 errors or final retry attempt, throw the error
+                throw await parseErrorResponse(response);
+            }
+            catch (error) {
+                if (error instanceof ContentfulError) {
+                    throw error;
+                }
+                console.error('[Contentful] Unexpected error in request', error);
+                throw new ContentfulError('Unexpected error in request', 500);
+            }
+        }
+        // This should never be reached due to the throw in the loop,
+        // but TypeScript needs it for type safety
+        throw new ContentfulError('Max retries exceeded', 500);
+    }
+    /**
+     * Fetches a single asset from Contentful by ID with proactive rate limiting
+     * and automatic retry on rate limit errors.
+     *
+     * @param assetId - The Contentful asset ID
+     * @param options - Optional fetch options (locale, preview, caching, retry)
+     * @returns The asset response or null if not found
+     */
+    async getAsset(assetId, options) {
+        const url = `${this.baseUrl}/assets/${assetId}`;
+        const fetchOptions = {
+            headers: {
+                Authorization: `Bearer ${this.accessToken}`,
+                'Content-Type': 'application/json',
+            },
+        };
+        // Add Next.js cache configuration if provided
+        if (options?.next) {
+            fetchOptions.next = options.next;
+        }
+        for (let attempt = 0; attempt <= RETRY_CONFIG.maxRetries; attempt++) {
+            try {
+                // Wait for rate limiter before making request
+                await this.rateLimiter.acquire();
+                const response = await fetch(url, fetchOptions);
+                if (response.ok) {
+                    return response.json();
+                }
+                // Return null for 404 (asset not found)
+                if (response.status === 404) {
+                    return null;
+                }
+                // Handle rate limiting (429) with automatic retry
+                if (response.status === 429 && attempt < RETRY_CONFIG.maxRetries) {
+                    const retryAfter = parseRetryAfter(response);
+                    const delay = calculateBackoffDelay(attempt, RETRY_CONFIG, retryAfter);
+                    console.warn(`[Contentful] Rate limited (429), retrying in ${delay}ms (attempt ${attempt + 1}/${RETRY_CONFIG.maxRetries}). ` +
+                        `Queue: ${this.rateLimiter.getQueueLength()} waiting. ` +
+                        `API: ${this.isPreview ? 'preview' : 'delivery'}`);
+                    // Pause the rate limiter - this affects all queued requests
+                    const pauseSeconds = Math.max(retryAfter ?? 2, 2);
+                    this.rateLimiter.pause(pauseSeconds);
+                    // Wait before retrying this request
+                    await sleep(delay);
+                    continue;
+                }
+                // For non-429 errors or final retry attempt, throw the error
+                throw await parseErrorResponse(response);
+            }
+            catch (error) {
+                if (error instanceof ContentfulError) {
+                    throw error;
+                }
+                console.error('[Contentful] Unexpected error in asset request', error);
+                throw new ContentfulError('Unexpected error in asset request', 500);
+            }
+        }
+        throw new ContentfulError('Max retries exceeded', 500);
+    }
+}
+/**
+ * Creates a Contentful Content Delivery API (CDA) client
+ *
+ * @param config - Configuration object for the Contentful client
+ * @returns Contentful CDA client instance
+ *
+ * @example
+ * ```ts
+ * const client = createContentfulClient({
+ *   spaceId: process.env.CONTENTFUL_SPACE_ID!,
+ *   accessToken: process.env.CONTENTFUL_ACCESS_TOKEN!,
+ *   environment: 'master'
+ * });
+ * ```
+ */
+export function createContentfulClient(config) {
+    return new ContentfulFetchClient(config, false);
+}
+/**
+ * Creates a Contentful Content Preview API (CPA) client
+ *
+ * @param config - Configuration object for the Contentful preview client
+ * @returns Contentful CPA client instance
+ *
+ * @example
+ * ```ts
+ * const previewClient = createContentfulPreviewClient({
+ *   spaceId: process.env.CONTENTFUL_SPACE_ID!,
+ *   accessToken: process.env.CONTENTFUL_PREVIEW_ACCESS_TOKEN!,
+ *   environment: 'master'
+ * });
+ * ```
+ */
+export function createContentfulPreviewClient(config) {
+    return new ContentfulFetchClient(config, true);
+}
+/**
+ * Gets the appropriate Contentful client based on preview mode
+ *
+ * @param config - Configuration for the Contentful client
+ * @param preview - Whether to use the preview API
+ * @returns Contentful client instance (CDA or CPA)
+ *
+ * @example
+ * ```ts
+ * const client = getContentfulClient({
+ *   spaceId: process.env.CONTENTFUL_SPACE_ID!,
+ *   accessToken: preview
+ *     ? process.env.CONTENTFUL_PREVIEW_ACCESS_TOKEN!
+ *     : process.env.CONTENTFUL_ACCESS_TOKEN!,
+ * }, preview);
+ * ```
+ */
+export function getContentfulClient(config, preview) {
+    return preview ? createContentfulPreviewClient(config) : createContentfulClient(config);
+}
+//# sourceMappingURL=client.js.map