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

package/dist/utils/redirectMap.js.map

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

package/dist/utils/retry.d.ts

@@ -0,0 +1,103 @@
+import type { RetryConfig } from '../types';
+/**
+ * Calculates the delay for the next retry attempt using exponential backoff
+ *
+ * @param attempt - Current retry attempt (0-based)
+ * @param config - Retry configuration
+ * @param retryAfter - Optional retry-after value from rate limit response
+ * @returns Delay in milliseconds
+ */
+export declare function calculateBackoffDelay(attempt: number, config: Required<RetryConfig>, retryAfter?: number): number;
+/**
+ * Executes a function with retry logic
+ *
+ * @param fn - Async function to execute
+ * @param config - Retry configuration
+ * @returns Promise resolving to the function result
+ *
+ * @example
+ * ```ts
+ * const result = await withRetry(
+ *   async () => await client.getEntry('id'),
+ *   { maxRetries: 3, initialDelay: 1000 }
+ * );
+ * ```
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, config?: RetryConfig): Promise<T>;
+/**
+ * Interval-based rate limiter that enforces minimum time between requests.
+ * Unlike token bucket, this prevents bursts entirely by spacing requests evenly.
+ * Requests are processed in FIFO order with guaranteed minimum intervals.
+ *
+ * @example
+ * ```ts
+ * const limiter = new RateLimiter(14); // 14 req/s = ~71ms between requests
+ * await limiter.acquire(); // Wait for permission to make request
+ * await fetch(...);
+ * ```
+ */
+export declare class RateLimiter {
+    /** Minimum interval between requests in milliseconds */
+    private readonly intervalMs;
+    /** Timestamp when the next request can be made */
+    private nextAvailableTime;
+    /** Queue of pending requests */
+    private readonly queue;
+    /** Whether the queue processor is running */
+    private processing;
+    /** Additional pause time from 429 responses (ms) */
+    private pauseUntil;
+    constructor(requestsPerSecond: number, 
+    /** @deprecated Use single parameter - kept for backward compatibility */
+    _refillRate?: number);
+    /**
+     * Calculates how long to wait before the next request can be made
+     */
+    private getWaitTime;
+    /**
+     * Processes the queue, releasing requests one at a time with proper spacing
+     */
+    private processQueue;
+    /**
+     * Acquires permission to make a request.
+     * Returns a promise that resolves when the request can proceed.
+     * Requests are processed in FIFO order with minimum interval spacing.
+     *
+     * @returns Promise that resolves when rate limit allows the request
+     */
+    acquire(): Promise<void>;
+    /**
+     * Gets the number of requests currently waiting in the queue
+     */
+    getQueueLength(): number;
+    /**
+     * Pauses the rate limiter for a specified duration.
+     * All requests (current and queued) will wait until pause expires.
+     * Does NOT block - just sets the pause time and returns.
+     *
+     * @param seconds - Duration to pause in seconds
+     */
+    pause(seconds: number): void;
+    /**
+     * Gets the current interval between requests in milliseconds
+     */
+    getIntervalMs(): number;
+}
+/**
+ * Retry configuration for Contentful 429 handling.
+ * Preview/draft uses longer backoff than published delivery.
+ */
+export declare function getRetryConfig(preview: boolean): Required<RetryConfig>;
+/**
+ * Minimum pause applied to the shared rate limiter after a 429.
+ * Preview uses a longer floor so short retryAfter values do not re-burst.
+ */
+export declare function getRateLimitPauseSeconds(retryAfter: number | undefined, preview: boolean): number;
+/**
+ * Gets the appropriate rate limiter based on preview mode
+ *
+ * @param preview - Whether using preview API
+ * @returns The appropriate rate limiter instance
+ */
+export declare function getRateLimiter(preview: boolean): RateLimiter;
+//# sourceMappingURL=retry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/utils/retry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAoB5C;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,QAAQ,CAAC,WAAW,CAAC,EAC7B,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,CAaR;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAyCzF;AASD;;;;;;;;;;;GAWG;AACH,qBAAa,WAAW;IACtB,wDAAwD;IACxD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,kDAAkD;IAClD,OAAO,CAAC,iBAAiB,CAAa;IACtC,gCAAgC;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;IAC1C,6CAA6C;IAC7C,OAAO,CAAC,UAAU,CAAS;IAC3B,oDAAoD;IACpD,OAAO,CAAC,UAAU,CAAa;gBAG7B,iBAAiB,EAAE,MAAM;IACzB,yEAAyE;IACzE,WAAW,CAAC,EAAE,MAAM;IAOtB;;OAEG;IACH,OAAO,CAAC,WAAW;IAOnB;;OAEG;YACW,YAAY;IAyB1B;;;;;;OAMG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAgB9B;;OAEG;IACH,cAAc,IAAI,MAAM;IAIxB;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAQ5B;;OAEG;IACH,aAAa,IAAI,MAAM;CAGxB;AA8BD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,QAAQ,CAAC,WAAW,CAAC,CAEtE;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAGjG;AAcD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,WAAW,CAE5D"}

package/dist/utils/retry.js

@@ -0,0 +1,248 @@
+import { getRetryAfter, isRetryableError } from './errors.js';
+/**
+ * Default retry configuration
+ */
+const DEFAULT_RETRY_CONFIG = {
+    maxRetries: 3,
+    initialDelay: 1000, // 1 second
+    maxDelay: 30000, // 30 seconds
+    backoffMultiplier: 2,
+};
+/**
+ * Sleep utility for async delays
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Calculates the delay for the next retry attempt using exponential backoff
+ *
+ * @param attempt - Current retry attempt (0-based)
+ * @param config - Retry configuration
+ * @param retryAfter - Optional retry-after value from rate limit response
+ * @returns Delay in milliseconds
+ */
+export function calculateBackoffDelay(attempt, config, retryAfter) {
+    // If server specified retry-after, use that
+    if (retryAfter !== undefined) {
+        return Math.min(retryAfter * 1000, config.maxDelay);
+    }
+    // Calculate exponential backoff
+    const exponentialDelay = config.initialDelay * config.backoffMultiplier ** attempt;
+    // Add jitter (random value between 0 and delay) to prevent thundering herd
+    const jitter = Math.random() * exponentialDelay;
+    return Math.min(exponentialDelay + jitter, config.maxDelay);
+}
+/**
+ * Executes a function with retry logic
+ *
+ * @param fn - Async function to execute
+ * @param config - Retry configuration
+ * @returns Promise resolving to the function result
+ *
+ * @example
+ * ```ts
+ * const result = await withRetry(
+ *   async () => await client.getEntry('id'),
+ *   { maxRetries: 3, initialDelay: 1000 }
+ * );
+ * ```
+ */
+export async function withRetry(fn, config) {
+    const retryConfig = {
+        ...DEFAULT_RETRY_CONFIG,
+        ...config,
+    };
+    let lastError;
+    for (let attempt = 0; attempt <= retryConfig.maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            // Don't retry if it's the last attempt
+            if (attempt === retryConfig.maxRetries) {
+                break;
+            }
+            // Only retry if the error is retryable
+            if (!isRetryableError(error)) {
+                throw error;
+            }
+            const retryAfter = getRetryAfter(error);
+            const delay = calculateBackoffDelay(attempt, retryConfig, retryAfter);
+            // Only log in development mode
+            if (typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production') {
+                console.warn(`Retry attempt ${attempt + 1}/${retryConfig.maxRetries} after ${delay}ms`, error);
+            }
+            await sleep(delay);
+        }
+    }
+    // If we get here, all retries failed
+    throw lastError;
+}
+/**
+ * Interval-based rate limiter that enforces minimum time between requests.
+ * Unlike token bucket, this prevents bursts entirely by spacing requests evenly.
+ * Requests are processed in FIFO order with guaranteed minimum intervals.
+ *
+ * @example
+ * ```ts
+ * const limiter = new RateLimiter(14); // 14 req/s = ~71ms between requests
+ * await limiter.acquire(); // Wait for permission to make request
+ * await fetch(...);
+ * ```
+ */
+export class RateLimiter {
+    /** Minimum interval between requests in milliseconds */
+    intervalMs;
+    /** Timestamp when the next request can be made */
+    nextAvailableTime = 0;
+    /** Queue of pending requests */
+    queue = [];
+    /** Whether the queue processor is running */
+    processing = false;
+    /** Additional pause time from 429 responses (ms) */
+    pauseUntil = 0;
+    constructor(requestsPerSecond, 
+    /** @deprecated Use single parameter - kept for backward compatibility */
+    _refillRate) {
+        // Calculate minimum interval between requests
+        // Use 80% of theoretical max to leave headroom
+        this.intervalMs = Math.ceil(1000 / (requestsPerSecond * 0.8));
+    }
+    /**
+     * Calculates how long to wait before the next request can be made
+     */
+    getWaitTime() {
+        const now = Date.now();
+        const waitForInterval = Math.max(0, this.nextAvailableTime - now);
+        const waitForPause = Math.max(0, this.pauseUntil - now);
+        return Math.max(waitForInterval, waitForPause);
+    }
+    /**
+     * Processes the queue, releasing requests one at a time with proper spacing
+     */
+    async processQueue() {
+        if (this.processing) {
+            return;
+        }
+        this.processing = true;
+        while (this.queue.length > 0) {
+            const waitTime = this.getWaitTime();
+            if (waitTime > 0) {
+                await sleep(waitTime);
+            }
+            // Update next available time BEFORE releasing the request
+            this.nextAvailableTime = Date.now() + this.intervalMs;
+            // Release the next queued request
+            const entry = this.queue.shift();
+            entry?.resolve();
+        }
+        this.processing = false;
+    }
+    /**
+     * Acquires permission to make a request.
+     * Returns a promise that resolves when the request can proceed.
+     * Requests are processed in FIFO order with minimum interval spacing.
+     *
+     * @returns Promise that resolves when rate limit allows the request
+     */
+    async acquire() {
+        const waitTime = this.getWaitTime();
+        // If no wait needed and no queue, proceed immediately
+        if (waitTime === 0 && this.queue.length === 0) {
+            this.nextAvailableTime = Date.now() + this.intervalMs;
+            return;
+        }
+        // Otherwise, queue the request
+        return new Promise((resolve) => {
+            this.queue.push({ resolve });
+            this.processQueue();
+        });
+    }
+    /**
+     * Gets the number of requests currently waiting in the queue
+     */
+    getQueueLength() {
+        return this.queue.length;
+    }
+    /**
+     * Pauses the rate limiter for a specified duration.
+     * All requests (current and queued) will wait until pause expires.
+     * Does NOT block - just sets the pause time and returns.
+     *
+     * @param seconds - Duration to pause in seconds
+     */
+    pause(seconds) {
+        const pauseUntil = Date.now() + seconds * 1000;
+        // Only extend pause, never shorten it
+        if (pauseUntil > this.pauseUntil) {
+            this.pauseUntil = pauseUntil;
+        }
+    }
+    /**
+     * Gets the current interval between requests in milliseconds
+     */
+    getIntervalMs() {
+        return this.intervalMs;
+    }
+}
+// ============================================================================
+// Shared Rate Limiter Instances
+// ============================================================================
+/**
+ * Rate limits for Contentful APIs (requests per second)
+ */
+const CONTENTFUL_RATE_LIMITS = {
+    /** Content Delivery API: 55 requests/second */
+    delivery: 55,
+    /** Content Preview API: 14 requests/second (use 10 for proactive headroom) */
+    preview: 10,
+};
+const DELIVERY_RETRY_CONFIG = {
+    maxRetries: 20,
+    initialDelay: 2000,
+    maxDelay: 30000,
+    backoffMultiplier: 2,
+};
+const PREVIEW_RETRY_CONFIG = {
+    maxRetries: 25,
+    initialDelay: 3000,
+    maxDelay: 60000,
+    backoffMultiplier: 2,
+};
+/**
+ * Retry configuration for Contentful 429 handling.
+ * Preview/draft uses longer backoff than published delivery.
+ */
+export function getRetryConfig(preview) {
+    return preview ? PREVIEW_RETRY_CONFIG : DELIVERY_RETRY_CONFIG;
+}
+/**
+ * Minimum pause applied to the shared rate limiter after a 429.
+ * Preview uses a longer floor so short retryAfter values do not re-burst.
+ */
+export function getRateLimitPauseSeconds(retryAfter, preview) {
+    const minPause = preview ? 4 : 2;
+    return Math.max(retryAfter ?? minPause, minPause);
+}
+/**
+ * Shared rate limiter for Contentful Delivery API (55 req/s)
+ * Module-level singleton shared across all client instances
+ */
+const deliveryRateLimiter = new RateLimiter(CONTENTFUL_RATE_LIMITS.delivery);
+/**
+ * Shared rate limiter for Contentful Preview API (14 req/s)
+ * Module-level singleton shared across all client instances
+ */
+const previewRateLimiter = new RateLimiter(CONTENTFUL_RATE_LIMITS.preview);
+/**
+ * Gets the appropriate rate limiter based on preview mode
+ *
+ * @param preview - Whether using preview API
+ * @returns The appropriate rate limiter instance
+ */
+export function getRateLimiter(preview) {
+    return preview ? previewRateLimiter : deliveryRateLimiter;
+}
+//# sourceMappingURL=retry.js.map

package/dist/utils/retry.js.map

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

package/dist/utils/tags.d.ts

@@ -0,0 +1,35 @@
+import type { IArticleTypeLink, ITagLink } from '@se-studio/core-data-types';
+/** Treat undefined/null as visible; only explicit `false` hides from UI. */
+export declare function isTagShowEnabled(show?: boolean | null): boolean;
+export type TagVisibilityFields = Pick<ITagLink, 'show' | 'tagType'>;
+/** Whether a tag should render visually (card/detail). Does not affect search. */
+export declare function isTagVisible(tag: TagVisibilityFields): boolean;
+/**
+ * Tags to display on cards/detail pages.
+ * Related-articles ambient fallback (article.tags on detail pages) also uses {@link isTagVisible};
+ * explicit CMS tag filters and search may still include non-visible tags.
+ */
+export declare function filterVisibleTags<T extends TagVisibilityFields>(tags: ReadonlyArray<T> | undefined): T[];
+export type ArticleForTagSelection = {
+    slug: string;
+    tags: ReadonlyArray<ITagLink>;
+    articleType: IArticleTypeLink | undefined;
+};
+export type PrimaryTagSelector = (article: ArticleForTagSelection) => ITagLink | undefined;
+type ArticleLike = {
+    slug?: string;
+    tags?: ReadonlyArray<ITagLink>;
+    articleType?: IArticleTypeLink | null;
+};
+/**
+ * Returns the primary tag for an article.
+ * Without a selector, returns tags[0] (default behaviour).
+ * With a selector, calls the selector with the full article context; falls back to tags[0] if it returns undefined.
+ *
+ * The returned value (if any) is passed as the 3rd arg to urlCalculators.article(...)
+ * by the article link converter. This is how projects with different article URL structures
+ * (see docs/routing.md) control whether/which tag appears in the path.
+ */
+export declare function getPrimaryTag(article: ArticleLike | undefined, selector?: PrimaryTagSelector): ITagLink | undefined;
+export {};
+//# sourceMappingURL=tags.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tags.d.ts","sourceRoot":"","sources":["../../src/utils/tags.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAE7E,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAAC,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,GAAG,OAAO,CAE/D;AAED,MAAM,MAAM,mBAAmB,GAAG,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAErE,kFAAkF;AAClF,wBAAgB,YAAY,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAE9D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,mBAAmB,EAC7D,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,SAAS,GACjC,CAAC,EAAE,CAKL;AAED,MAAM,MAAM,sBAAsB,GAAG;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;IAC9B,WAAW,EAAE,gBAAgB,GAAG,SAAS,CAAC;CAC3C,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,EAAE,sBAAsB,KAAK,QAAQ,GAAG,SAAS,CAAC;AAE3F,KAAK,WAAW,GAAG;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;IAC/B,WAAW,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;CACvC,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,WAAW,GAAG,SAAS,EAChC,QAAQ,CAAC,EAAE,kBAAkB,GAC5B,QAAQ,GAAG,SAAS,CAKtB"}

package/dist/utils/tags.js

@@ -0,0 +1,37 @@
+/** Treat undefined/null as visible; only explicit `false` hides from UI. */
+export function isTagShowEnabled(show) {
+    return show !== false;
+}
+/** Whether a tag should render visually (card/detail). Does not affect search. */
+export function isTagVisible(tag) {
+    return isTagShowEnabled(tag.show) && isTagShowEnabled(tag.tagType?.show);
+}
+/**
+ * Tags to display on cards/detail pages.
+ * Related-articles ambient fallback (article.tags on detail pages) also uses {@link isTagVisible};
+ * explicit CMS tag filters and search may still include non-visible tags.
+ */
+export function filterVisibleTags(tags) {
+    if (!tags?.length) {
+        return [];
+    }
+    return tags.filter(isTagVisible);
+}
+/**
+ * Returns the primary tag for an article.
+ * Without a selector, returns tags[0] (default behaviour).
+ * With a selector, calls the selector with the full article context; falls back to tags[0] if it returns undefined.
+ *
+ * The returned value (if any) is passed as the 3rd arg to urlCalculators.article(...)
+ * by the article link converter. This is how projects with different article URL structures
+ * (see docs/routing.md) control whether/which tag appears in the path.
+ */
+export function getPrimaryTag(article, selector) {
+    const { tags, articleType, slug } = article ?? {};
+    if (!tags?.length)
+        return undefined;
+    if (!selector)
+        return tags[0];
+    return selector({ slug: slug ?? '', tags, articleType: articleType ?? undefined }) ?? tags[0];
+}
+//# sourceMappingURL=tags.js.map

package/dist/utils/tags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tags.js","sourceRoot":"","sources":["../../src/utils/tags.ts"],"names":[],"mappings":"AAEA,4EAA4E;AAC5E,MAAM,UAAU,gBAAgB,CAAC,IAAqB;IACpD,OAAO,IAAI,KAAK,KAAK,CAAC;AACxB,CAAC;AAID,kFAAkF;AAClF,MAAM,UAAU,YAAY,CAAC,GAAwB;IACnD,OAAO,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,gBAAgB,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;AAC3E,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAkC;IAElC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC;QAClB,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;AACnC,CAAC;AAgBD;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAC3B,OAAgC,EAChC,QAA6B;IAE7B,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,GAAG,OAAO,IAAI,EAAE,CAAC;IAClD,IAAI,CAAC,IAAI,EAAE,MAAM;QAAE,OAAO,SAAS,CAAC;IACpC,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC;IAC9B,OAAO,QAAQ,CAAC,EAAE,IAAI,EAAE,IAAI,IAAI,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,IAAI,SAAS,EAAE,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC;AAChG,CAAC"}