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

package/dist/telemetry/queryContext.js

@@ -0,0 +1,9 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+const storage = new AsyncLocalStorage();
+export function withCmsQueryContext(context, fn) {
+    return storage.run(context, fn);
+}
+export function getCmsQueryContext() {
+    return storage.getStore();
+}
+//# sourceMappingURL=queryContext.js.map

package/dist/telemetry/queryContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queryContext.js","sourceRoot":"","sources":["../../src/telemetry/queryContext.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAOrD,MAAM,OAAO,GAAG,IAAI,iBAAiB,EAAmB,CAAC;AAEzD,MAAM,UAAU,mBAAmB,CAAI,OAAwB,EAAE,EAAW;IAC1E,OAAO,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AAClC,CAAC;AAED,MAAM,UAAU,kBAAkB;IAChC,OAAO,OAAO,CAAC,QAAQ,EAAE,CAAC;AAC5B,CAAC"}

package/dist/telemetry/queryLog.d.ts

@@ -0,0 +1,17 @@
+export interface CmsQueryLogEntry {
+    url: string;
+    operation: string;
+    identifier?: string;
+    bytes: number;
+    ms: number;
+}
+export declare function isCmsQueryLoggingEnabled(): boolean;
+/** Format byte count as a compact human-readable size (e.g. 23.5k, 1.2M). */
+export declare function formatPayloadSize(bytes: number): string;
+export declare function logCmsQuery(entry: Omit<CmsQueryLogEntry, 'operation' | 'identifier'> & Partial<Pick<CmsQueryLogEntry, 'operation' | 'identifier'>>): void;
+/** Read response body bytes and return text for JSON parsing. */
+export declare function readResponseBodyWithSize(response: Response): Promise<{
+    bytes: number;
+    text: string;
+}>;
+//# sourceMappingURL=queryLog.d.ts.map

package/dist/telemetry/queryLog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queryLog.d.ts","sourceRoot":"","sources":["../../src/telemetry/queryLog.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,wBAAgB,wBAAwB,IAAI,OAAO,CAElD;AAED,6EAA6E;AAC7E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQvD;AAED,wBAAgB,WAAW,CACzB,KAAK,EAAE,IAAI,CAAC,gBAAgB,EAAE,WAAW,GAAG,YAAY,CAAC,GACvD,OAAO,CAAC,IAAI,CAAC,gBAAgB,EAAE,WAAW,GAAG,YAAY,CAAC,CAAC,GAC5D,IAAI,CAuBN;AAED,iEAAiE;AACjE,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAc1C"}

package/dist/telemetry/queryLog.js

@@ -0,0 +1,54 @@
+import { deriveOperationFromUrl } from './deriveOperation.js';
+import { getCmsQueryContext } from './queryContext.js';
+export function isCmsQueryLoggingEnabled() {
+    return process.env.LOG_CMS_QUERIES === '1';
+}
+/** Format byte count as a compact human-readable size (e.g. 23.5k, 1.2M). */
+export function formatPayloadSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes}`;
+    if (bytes < 1024 * 1024) {
+        const kb = bytes / 1024;
+        return kb >= 100 ? `${Math.round(kb)}k` : `${kb.toFixed(1)}k`;
+    }
+    const mb = bytes / (1024 * 1024);
+    return mb >= 100 ? `${Math.round(mb)}M` : `${mb.toFixed(1)}M`;
+}
+export function logCmsQuery(entry) {
+    if (!isCmsQueryLoggingEnabled())
+        return;
+    const context = getCmsQueryContext();
+    const derived = deriveOperationFromUrl(entry.url);
+    const payload = {
+        url: entry.url,
+        operation: entry.operation ?? context?.operation ?? derived.operation,
+        ...(entry.identifier !== undefined
+            ? entry.identifier
+                ? { identifier: entry.identifier }
+                : {}
+            : context?.identifier
+                ? { identifier: context.identifier }
+                : derived.identifier
+                    ? { identifier: derived.identifier }
+                    : {}),
+        bytes: entry.bytes,
+        ms: entry.ms,
+    };
+    console.log(`[CMS query] ${JSON.stringify(payload)}`);
+}
+/** Read response body bytes and return text for JSON parsing. */
+export async function readResponseBodyWithSize(response) {
+    const contentLength = response.headers.get('content-length');
+    if (contentLength) {
+        const parsed = Number.parseInt(contentLength, 10);
+        const text = await response.text();
+        return {
+            bytes: Number.isNaN(parsed) ? Buffer.byteLength(text, 'utf8') : parsed,
+            text,
+        };
+    }
+    const buffer = await response.arrayBuffer();
+    const text = new TextDecoder().decode(buffer);
+    return { bytes: buffer.byteLength, text };
+}
+//# sourceMappingURL=queryLog.js.map

package/dist/telemetry/queryLog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queryLog.js","sourceRoot":"","sources":["../../src/telemetry/queryLog.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAUpD,MAAM,UAAU,wBAAwB;IACtC,OAAO,OAAO,CAAC,GAAG,CAAC,eAAe,KAAK,GAAG,CAAC;AAC7C,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,iBAAiB,CAAC,KAAa;IAC7C,IAAI,KAAK,GAAG,IAAI;QAAE,OAAO,GAAG,KAAK,EAAE,CAAC;IACpC,IAAI,KAAK,GAAG,IAAI,GAAG,IAAI,EAAE,CAAC;QACxB,MAAM,EAAE,GAAG,KAAK,GAAG,IAAI,CAAC;QACxB,OAAO,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;IAChE,CAAC;IACD,MAAM,EAAE,GAAG,KAAK,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;IACjC,OAAO,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;AAChE,CAAC;AAED,MAAM,UAAU,WAAW,CACzB,KAC6D;IAE7D,IAAI,CAAC,wBAAwB,EAAE;QAAE,OAAO;IAExC,MAAM,OAAO,GAAG,kBAAkB,EAAE,CAAC;IACrC,MAAM,OAAO,GAAG,sBAAsB,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAElD,MAAM,OAAO,GAAqB;QAChC,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,OAAO,EAAE,SAAS,IAAI,OAAO,CAAC,SAAS;QACrE,GAAG,CAAC,KAAK,CAAC,UAAU,KAAK,SAAS;YAChC,CAAC,CAAC,KAAK,CAAC,UAAU;gBAChB,CAAC,CAAC,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE;gBAClC,CAAC,CAAC,EAAE;YACN,CAAC,CAAC,OAAO,EAAE,UAAU;gBACnB,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE;gBACpC,CAAC,CAAC,OAAO,CAAC,UAAU;oBAClB,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE;oBACpC,CAAC,CAAC,EAAE,CAAC;QACX,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,EAAE,EAAE,KAAK,CAAC,EAAE;KACb,CAAC;IAEF,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;AACxD,CAAC;AAED,iEAAiE;AACjE,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,QAAkB;IAElB,MAAM,aAAa,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAC7D,IAAI,aAAa,EAAE,CAAC;QAClB,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC;QAClD,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;QACnC,OAAO;YACL,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM;YACtE,IAAI;SACL,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,WAAW,EAAE,CAAC;IAC5C,MAAM,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC9C,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC;AAC5C,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Configuration options for creating a Contentful client
+ */
+export interface ContentfulConfig {
+    /** Contentful space ID */
+    spaceId: string;
+    /** Access token for the Contentful API (CDA or CPA token) */
+    accessToken: string;
+    /** Environment name (defaults to 'master') */
+    environment?: string;
+    /** Host override (useful for proxies or custom endpoints) */
+    host?: string;
+}
+/**
+ * Retry configuration for failed requests
+ */
+export interface RetryConfig {
+    /** Maximum number of retry attempts */
+    maxRetries?: number;
+    /** Initial delay in milliseconds */
+    initialDelay?: number;
+    /** Maximum delay in milliseconds */
+    maxDelay?: number;
+    /** Backoff multiplier */
+    backoffMultiplier?: number;
+}
+/**
+ * Options for fetching content from Contentful
+ */
+export interface FetchOptions {
+    /** Locale to fetch content in */
+    locale?: string;
+    /** Use preview API instead of delivery API */
+    preview: boolean;
+    /** Include depth for linked entries */
+    include?: number;
+    cache?: 'force-cache' | 'no-store';
+    next?: {
+        revalidate?: number | false;
+        tags?: string[];
+    };
+    /** Retry configuration */
+    retry?: RetryConfig;
+    /**
+     * When true, `enrichAllAssets` fetches a tiny Contentful CDN variant per included raster picture
+     * and sets `IPicture.blurDataURL` for Next.js blur placeholders. One HTTP request per distinct
+     * picture asset; SVG assets and pictures that already have `blurDataURL` are skipped. Default off.
+     */
+    enrichPictureBlurPlaceholders?: boolean;
+    /**
+     * `page` — full layout model (nav, template, contents). Default for single-entity REST.
+     * `listing` — metadata/links only (no nav or content trees). Default for bulk link fetches.
+     */
+    fetchProfile?: CmsFetchProfile;
+    /**
+     * `bundled` (default) — resolve menu/footer via Contentful includes during conversion.
+     * `flat` — stub nav root ids during conversion; assemble full trees post-convert via registry.
+     */
+    navigationResolution?: NavigationResolution;
+    /** Pagination page size for `contentfulAllArticleLinks`. Default 100. */
+    pageSize?: number;
+    /**
+     * When true, skip video/blur asset enrichment (for Node smoke integrity checks outside Next.js).
+     */
+    skipAssetEnrichment?: boolean;
+}
+/** CMS fetch profile: full page render vs lightweight listing/metadata. */
+export type CmsFetchProfile = 'page' | 'listing';
+/** How menu/footer are resolved on page-profile entity fetches. */
+export type NavigationResolution = 'flat' | 'bundled';
+/**
+ * Error information for failed content conversion
+ */
+export interface CmsError {
+    /** ID of the entry that failed to convert */
+    entryId: string;
+    /** Content type of the entry that failed */
+    entryType?: string;
+    /** Human-readable error message */
+    message: string;
+    /** Original error object for debugging */
+    error?: unknown;
+}
+/**
+ * Response wrapper for CMS operations that may include partial errors
+ */
+export interface CmsResponse<T> {
+    /** The successful data */
+    data: T;
+    /** Any errors that occurred during processing */
+    errors: CmsError[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,0BAA0B;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,uCAAuC;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oCAAoC;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yBAAyB;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,iCAAiC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,OAAO,EAAE,OAAO,CAAC;IACjB,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,aAAa,GAAG,UAAU,CAAC;IACnC,IAAI,CAAC,EAAE;QACL,UAAU,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;QAC5B,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;KACjB,CAAC;IACF,0BAA0B;IAC1B,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB;;;;OAIG;IACH,6BAA6B,CAAC,EAAE,OAAO,CAAC;IACxC;;;OAGG;IACH,YAAY,CAAC,EAAE,eAAe,CAAC;IAC/B;;;OAGG;IACH,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;IAC5C,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,2EAA2E;AAC3E,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,SAAS,CAAC;AAEjD,mEAAmE;AACnE,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,SAAS,CAAC;AAEtD;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,0BAA0B;IAC1B,IAAI,EAAE,CAAC,CAAC;IACR,iDAAiD;IACjD,MAAM,EAAE,QAAQ,EAAE,CAAC;CACpB"}

package/dist/types.js

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

package/dist/types.js.map

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

package/dist/utils/arrayUtils.d.ts

@@ -0,0 +1,3 @@
+export declare function notEmpty<TValue>(value: TValue | null | undefined): value is TValue;
+export declare function arrayOrUndefined<T>(array?: ReadonlyArray<T>): readonly T[] | undefined;
+//# sourceMappingURL=arrayUtils.d.ts.map

package/dist/utils/arrayUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arrayUtils.d.ts","sourceRoot":"","sources":["../../src/utils/arrayUtils.ts"],"names":[],"mappings":"AAAA,wBAAgB,QAAQ,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,KAAK,IAAI,MAAM,CAGlF;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,4BAK3D"}

package/dist/utils/arrayUtils.js

@@ -0,0 +1,12 @@
+export function notEmpty(value) {
+    if (value === null || value === undefined)
+        return false;
+    return true;
+}
+export function arrayOrUndefined(array) {
+    if (array && array.length > 0) {
+        return array;
+    }
+    return undefined;
+}
+//# sourceMappingURL=arrayUtils.js.map

package/dist/utils/arrayUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"arrayUtils.js","sourceRoot":"","sources":["../../src/utils/arrayUtils.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,QAAQ,CAAS,KAAgC;IAC/D,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACxD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAI,KAAwB;IAC1D,IAAI,KAAK,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/utils/dateUtils.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Validates if a value can be converted to a valid Date object
+ */
+export declare function isValidDate(date: unknown): boolean;
+/**
+ * Safely creates a Date object, returning null if invalid
+ */
+export declare function safeDate(date: unknown): Date | null;
+//# sourceMappingURL=dateUtils.d.ts.map

package/dist/utils/dateUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dateUtils.d.ts","sourceRoot":"","sources":["../../src/utils/dateUtils.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAWlD;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,GAAG,IAAI,CAUnD"}

package/dist/utils/dateUtils.js

@@ -0,0 +1,26 @@
+/**
+ * Validates if a value can be converted to a valid Date object
+ */
+export function isValidDate(date) {
+    if (date instanceof Date) {
+        return !Number.isNaN(date.getTime());
+    }
+    if (typeof date === 'string' || typeof date === 'number') {
+        const parsed = new Date(date);
+        return !Number.isNaN(parsed.getTime()) && parsed.getTime() > 0;
+    }
+    return false;
+}
+/**
+ * Safely creates a Date object, returning null if invalid
+ */
+export function safeDate(date) {
+    if (!isValidDate(date)) {
+        return null;
+    }
+    if (date instanceof Date) {
+        return date;
+    }
+    return new Date(date);
+}
+//# sourceMappingURL=dateUtils.js.map

package/dist/utils/dateUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dateUtils.js","sourceRoot":"","sources":["../../src/utils/dateUtils.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,IAAa;IACvC,IAAI,IAAI,YAAY,IAAI,EAAE,CAAC;QACzB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;IACvC,CAAC;IAED,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QACzD,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC;QAC9B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,IAAI,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IACjE,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAa;IACpC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,IAAI,YAAY,IAAI,EAAE,CAAC;QACzB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,IAAI,IAAI,CAAC,IAAuB,CAAC,CAAC;AAC3C,CAAC"}

package/dist/utils/errors.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Custom error classes for Contentful API errors
+ */
+/**
+ * Base error class for all Contentful-related errors
+ */
+export declare class ContentfulError extends Error {
+    readonly statusCode?: number | undefined;
+    readonly details?: unknown | undefined;
+    constructor(message: string, statusCode?: number | undefined, details?: unknown | undefined);
+}
+/**
+ * Error thrown when rate limit is exceeded
+ */
+export declare class RateLimitError extends ContentfulError {
+    readonly retryAfter?: number | undefined;
+    constructor(message: string, retryAfter?: number | undefined, details?: unknown);
+}
+/**
+ * Error thrown when entry is not found
+ */
+export declare class EntryNotFoundError extends ContentfulError {
+    readonly entryId: string;
+    readonly contentType?: string | undefined;
+    constructor(entryId: string, contentType?: string | undefined);
+}
+/**
+ * Error thrown when authentication fails
+ */
+export declare class AuthenticationError extends ContentfulError {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when validation fails
+ */
+export declare class ValidationError extends ContentfulError {
+    readonly validationErrors?: unknown | undefined;
+    constructor(message: string, validationErrors?: unknown | undefined);
+}
+/**
+ * Checks if an error is a Contentful error
+ */
+export declare function isContentfulError(error: unknown): error is ContentfulError;
+/**
+ * Checks if an error is a rate limit error
+ */
+export declare function isRateLimitError(error: unknown): error is RateLimitError;
+/**
+ * Checks if an error is retryable
+ */
+export declare function isRetryableError(error: unknown): boolean;
+/**
+ * Extracts retry-after header value from error
+ */
+export declare function getRetryAfter(error: unknown): number | undefined;
+//# sourceMappingURL=errors.d.ts.map

package/dist/utils/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,qBAAa,eAAgB,SAAQ,KAAK;aAGtB,UAAU,CAAC,EAAE,MAAM;aACnB,OAAO,CAAC,EAAE,OAAO;gBAFjC,OAAO,EAAE,MAAM,EACC,UAAU,CAAC,EAAE,MAAM,YAAA,EACnB,OAAO,CAAC,EAAE,OAAO,YAAA;CAMpC;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,eAAe;aAG/B,UAAU,CAAC,EAAE,MAAM;gBADnC,OAAO,EAAE,MAAM,EACC,UAAU,CAAC,EAAE,MAAM,YAAA,EACnC,OAAO,CAAC,EAAE,OAAO;CAMpB;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,eAAe;aAEnC,OAAO,EAAE,MAAM;aACf,WAAW,CAAC,EAAE,MAAM;gBADpB,OAAO,EAAE,MAAM,EACf,WAAW,CAAC,EAAE,MAAM,YAAA;CAMvC;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,eAAe;gBAC1C,OAAO,SAA0B;CAK9C;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,eAAe;aAGhC,gBAAgB,CAAC,EAAE,OAAO;gBAD1C,OAAO,EAAE,MAAM,EACC,gBAAgB,CAAC,EAAE,OAAO,YAAA;CAM7C;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAE1E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAExE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAWxD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAKhE"}

package/dist/utils/errors.js

@@ -0,0 +1,100 @@
+/**
+ * Custom error classes for Contentful API errors
+ */
+/**
+ * Base error class for all Contentful-related errors
+ */
+export class ContentfulError extends Error {
+    statusCode;
+    details;
+    constructor(message, statusCode, details) {
+        super(message);
+        this.statusCode = statusCode;
+        this.details = details;
+        this.name = 'ContentfulError';
+        Object.setPrototypeOf(this, ContentfulError.prototype);
+    }
+}
+/**
+ * Error thrown when rate limit is exceeded
+ */
+export class RateLimitError extends ContentfulError {
+    retryAfter;
+    constructor(message, retryAfter, details) {
+        super(message, 429, details);
+        this.retryAfter = retryAfter;
+        this.name = 'RateLimitError';
+        Object.setPrototypeOf(this, RateLimitError.prototype);
+    }
+}
+/**
+ * Error thrown when entry is not found
+ */
+export class EntryNotFoundError extends ContentfulError {
+    entryId;
+    contentType;
+    constructor(entryId, contentType) {
+        super(`Entry not found: ${entryId}${contentType ? ` (${contentType})` : ''}`, 404);
+        this.entryId = entryId;
+        this.contentType = contentType;
+        this.name = 'EntryNotFoundError';
+        Object.setPrototypeOf(this, EntryNotFoundError.prototype);
+    }
+}
+/**
+ * Error thrown when authentication fails
+ */
+export class AuthenticationError extends ContentfulError {
+    constructor(message = 'Authentication failed') {
+        super(message, 401);
+        this.name = 'AuthenticationError';
+        Object.setPrototypeOf(this, AuthenticationError.prototype);
+    }
+}
+/**
+ * Error thrown when validation fails
+ */
+export class ValidationError extends ContentfulError {
+    validationErrors;
+    constructor(message, validationErrors) {
+        super(message, 400, validationErrors);
+        this.validationErrors = validationErrors;
+        this.name = 'ValidationError';
+        Object.setPrototypeOf(this, ValidationError.prototype);
+    }
+}
+/**
+ * Checks if an error is a Contentful error
+ */
+export function isContentfulError(error) {
+    return error instanceof ContentfulError;
+}
+/**
+ * Checks if an error is a rate limit error
+ */
+export function isRateLimitError(error) {
+    return error instanceof RateLimitError;
+}
+/**
+ * Checks if an error is retryable
+ */
+export function isRetryableError(error) {
+    if (isRateLimitError(error)) {
+        return true;
+    }
+    if (isContentfulError(error)) {
+        // Retry on 5xx errors and rate limits
+        return error.statusCode !== undefined && (error.statusCode >= 500 || error.statusCode === 429);
+    }
+    return false;
+}
+/**
+ * Extracts retry-after header value from error
+ */
+export function getRetryAfter(error) {
+    if (isRateLimitError(error)) {
+        return error.retryAfter;
+    }
+    return undefined;
+}
+//# sourceMappingURL=errors.js.map

package/dist/utils/errors.js.map

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

package/dist/utils/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Utility functions for error handling, retry logic, and rate limiting
+ */
+export { arrayOrUndefined, notEmpty } from './arrayUtils';
+export { isValidDate, safeDate } from './dateUtils';
+export { AuthenticationError, ContentfulError, EntryNotFoundError, getRetryAfter, isContentfulError, isRateLimitError, isRetryableError, RateLimitError, ValidationError, } from './errors';
+export { calculateBackoffDelay, getRateLimiter, getRateLimitPauseSeconds, getRetryConfig, RateLimiter, withRetry, } from './retry';
+export { type ArticleForTagSelection, filterVisibleTags, getPrimaryTag, isTagShowEnabled, isTagVisible, type PrimaryTagSelector, type TagVisibilityFields, } from './tags';
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,eAAe,GAChB,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,qBAAqB,EACrB,cAAc,EACd,wBAAwB,EACxB,cAAc,EACd,WAAW,EACX,SAAS,GACV,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,KAAK,sBAAsB,EAC3B,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EAChB,YAAY,EACZ,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,GACzB,MAAM,QAAQ,CAAC"}

package/dist/utils/index.js

@@ -0,0 +1,9 @@
+/**
+ * Utility functions for error handling, retry logic, and rate limiting
+ */
+export { arrayOrUndefined, notEmpty } from './arrayUtils.js';
+export { isValidDate, safeDate } from './dateUtils.js';
+export { AuthenticationError, ContentfulError, EntryNotFoundError, getRetryAfter, isContentfulError, isRateLimitError, isRetryableError, RateLimitError, ValidationError, } from './errors.js';
+export { calculateBackoffDelay, getRateLimiter, getRateLimitPauseSeconds, getRetryConfig, RateLimiter, withRetry, } from './retry.js';
+export { filterVisibleTags, getPrimaryTag, isTagShowEnabled, isTagVisible, } from './tags.js';
+//# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,eAAe,GAChB,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,qBAAqB,EACrB,cAAc,EACd,wBAAwB,EACxB,cAAc,EACd,WAAW,EACX,SAAS,GACV,MAAM,SAAS,CAAC;AACjB,OAAO,EAEL,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EAChB,YAAY,GAGb,MAAM,QAAQ,CAAC"}

package/dist/utils/redirectMap.d.ts

@@ -0,0 +1,40 @@
+import type { IRedirect } from '@se-studio/core-data-types';
+/**
+ * Shape of the baked redirect map consumed by middleware (and generated at build time).
+ * Keyed by normalized fromPath.
+ */
+export interface RedirectMapEntry {
+    to: string;
+    status: 301 | 302 | 307 | 308;
+}
+export type RedirectMap = Record<string, RedirectMapEntry>;
+/**
+ * Pure helper that turns a list of IRedirect (from Contentful) into the simple
+ * map used by middleware at runtime or baked into a static module at build.
+ *
+ * - Filters out inactive redirects.
+ * - Prefers explicit statusCode; defaults to 301.
+ * - Normalizes paths: ensures leading `/` (unless external) and trailing `/`
+ *   for internal paths (aligns with the project's trailingSlash: true convention
+ *   used by UrlCalculators and sitemap hrefs).
+ * - Drops self-redirects (A → A) after normalization.
+ * - Detects and drops rules that participate in redirect cycles (A → B → A, etc.).
+ *   A console warning is emitted for cycles (visible during build/generate scripts).
+ *
+ * This is intentionally side-effect free (except build-visible warnings) and safe
+ * to run in a Next.js build script or edge middleware context.
+ */
+export declare function buildRedirectMap(redirects: IRedirect[] | null | undefined): RedirectMap;
+/**
+ * Filter a list of sitemap-like entries, removing any whose `url` (after light
+ * normalization for trailing slash) is the source ("from") of an active redirect.
+ *
+ * Use this (or pass `redirectMap` to `getSitemapEntries`) so that URLs which
+ * redirect away do not appear in your sitemap.
+ *
+ * Works for any `{ url: string }` shape (SitemapEntry, ISitemapEntry, etc.).
+ */
+export declare function filterSitemapEntriesExcludingRedirects<T extends {
+    url: string;
+}>(entries: T[], redirectMap: RedirectMap): T[];
+//# sourceMappingURL=redirectMap.d.ts.map

package/dist/utils/redirectMap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redirectMap.d.ts","sourceRoot":"","sources":["../../src/utils/redirectMap.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAE5D;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;CAC/B;AAED,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;AAW3D;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,SAAS,EAAE,GAAG,IAAI,GAAG,SAAS,GAAG,WAAW,CA8EvF;AAED;;;;;;;;GAQG;AACH,wBAAgB,sCAAsC,CAAC,CAAC,SAAS;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,EAC9E,OAAO,EAAE,CAAC,EAAE,EACZ,WAAW,EAAE,WAAW,GACvB,CAAC,EAAE,CAoBL"}

package/dist/utils/redirectMap.js

@@ -0,0 +1,129 @@
+function normalizeRedirectPath(p) {
+    if (!p)
+        return '';
+    let s = p.trim();
+    const isExternal = /^https?:\/\//i.test(s);
+    if (!isExternal && !s.startsWith('/'))
+        s = `/${s}`;
+    if (!isExternal && !s.endsWith('/'))
+        s = `${s}/`;
+    return s;
+}
+/**
+ * Pure helper that turns a list of IRedirect (from Contentful) into the simple
+ * map used by middleware at runtime or baked into a static module at build.
+ *
+ * - Filters out inactive redirects.
+ * - Prefers explicit statusCode; defaults to 301.
+ * - Normalizes paths: ensures leading `/` (unless external) and trailing `/`
+ *   for internal paths (aligns with the project's trailingSlash: true convention
+ *   used by UrlCalculators and sitemap hrefs).
+ * - Drops self-redirects (A → A) after normalization.
+ * - Detects and drops rules that participate in redirect cycles (A → B → A, etc.).
+ *   A console warning is emitted for cycles (visible during build/generate scripts).
+ *
+ * This is intentionally side-effect free (except build-visible warnings) and safe
+ * to run in a Next.js build script or edge middleware context.
+ */
+export function buildRedirectMap(redirects) {
+    const map = {};
+    if (!redirects || redirects.length === 0) {
+        return map;
+    }
+    for (const r of redirects) {
+        if (r.active === false)
+            continue;
+        const from = normalizeRedirectPath(r.fromPath || '');
+        if (!from)
+            continue;
+        const to = normalizeRedirectPath(r.to || '');
+        if (!to)
+            continue;
+        // Self-loop guard (after normalization)
+        if (from === to)
+            continue;
+        const status = (r.statusCode ?? 301);
+        // Last one wins if duplicates (editors should avoid); keeps it simple.
+        map[from] = { to, status };
+    }
+    // Cycle detection: walk the graph of internal redirects and drop any 'from' that
+    // participates in a cycle. We do this after the initial map so we have a clean
+    // from->to graph of only the candidates.
+    const fromTo = {};
+    for (const [f, e] of Object.entries(map)) {
+        // Only follow if the target is itself a redirect source (internal hop)
+        if (map[e.to]) {
+            fromTo[f] = e.to;
+        }
+    }
+    function findCycle(start) {
+        const path = [];
+        const seen = new Set();
+        let cur = start;
+        while (cur) {
+            if (seen.has(cur)) {
+                // cycle detected; return the cycle portion
+                const idx = path.indexOf(cur);
+                return idx >= 0 ? path.slice(idx).concat(cur) : path.concat(cur);
+            }
+            seen.add(cur);
+            path.push(cur);
+            cur = fromTo[cur];
+        }
+        return null;
+    }
+    const cyclicFroms = new Set();
+    for (const f of Object.keys(fromTo)) {
+        if (!cyclicFroms.has(f)) {
+            const cycle = findCycle(f);
+            if (cycle) {
+                for (const node of cycle) {
+                    if (fromTo[node] !== undefined)
+                        cyclicFroms.add(node);
+                }
+            }
+        }
+    }
+    if (cyclicFroms.size > 0) {
+        if (typeof console !== 'undefined' && console.warn) {
+            console.warn(`[redirects] Dropping ${cyclicFroms.size} redirect rule(s) that participate in cycle(s):`, Array.from(cyclicFroms));
+        }
+        for (const bad of cyclicFroms) {
+            delete map[bad];
+        }
+    }
+    return map;
+}
+/**
+ * Filter a list of sitemap-like entries, removing any whose `url` (after light
+ * normalization for trailing slash) is the source ("from") of an active redirect.
+ *
+ * Use this (or pass `redirectMap` to `getSitemapEntries`) so that URLs which
+ * redirect away do not appear in your sitemap.
+ *
+ * Works for any `{ url: string }` shape (SitemapEntry, ISitemapEntry, etc.).
+ */
+export function filterSitemapEntriesExcludingRedirects(entries, redirectMap) {
+    if (!redirectMap || Object.keys(redirectMap).length === 0) {
+        return entries;
+    }
+    const froms = new Set(Object.keys(redirectMap));
+    return entries.filter((entry) => {
+        const u = entry.url || '';
+        if (!u)
+            return true;
+        if (froms.has(u))
+            return false;
+        // Robustness for trailing slash differences (map keys are normalized with trailing / for internals)
+        if (u.endsWith('/')) {
+            if (froms.has(u.slice(0, -1)))
+                return false;
+        }
+        else {
+            if (froms.has(`${u}/`))
+                return false;
+        }
+        return true;
+    });
+}
+//# sourceMappingURL=redirectMap.js.map