@storyblok/management-api-client 0.2.1 → 0.2.3

package/dist/types.d.cts

@@ -0,0 +1,130 @@
+import { AssetFolder, AssetFolderCreate, AssetFolderUpdate } from "./generated/asset_folders/types.gen.cjs";
+import { Asset, AssetSignRequest, AssetUpdate, AssetUpdateRequest, ListData, SignedResponseObject } from "./generated/assets/types.gen.cjs";
+import { AssetField, ListData as ListData$1, MultilinkField, PluginField, RichtextField, StoryAlternate, StoryContent, StoryCreate, StoryLocalizedPath, StoryMapi, StoryTranslatedSlug, StoryUpdate, TableField } from "./generated/stories/types.gen.cjs";
+import { Client, RetryOptions } from "./generated/shared/client/types.gen.cjs";
+import { ClientError } from "./error.cjs";
+import { RateLimitConfig } from "./utils/rate-limit.cjs";
+import { ComponentFolder } from "./generated/component_folders/types.gen.cjs";
+import { Component, ComponentCreate, ComponentSchemaField, ComponentUpdate } from "./generated/components/types.gen.cjs";
+import { DatasourceEntry, DatasourceEntryCreate, DatasourceEntryUpdate } from "./generated/datasource_entries/types.gen.cjs";
+import { Datasource, DatasourceCreate, DatasourceUpdate } from "./generated/datasources/types.gen.cjs";
+import { InternalTag } from "./generated/internal_tags/types.gen.cjs";
+import { Preset } from "./generated/presets/types.gen.cjs";
+import { Space, SpaceCreate, SpaceUpdate } from "./generated/spaces/types.gen.cjs";
+import { User } from "./generated/users/types.gen.cjs";
+import { AssetCreate, AssetUploadRequest } from "./resources/assets.cjs";
+import { Region } from "@storyblok/region-helper";
+
+//#region src/types.d.ts
+type Prettify<T> = { [K in keyof T]: T[K] } & {};
+type ApiResponse<T, ThrowOnError extends boolean = false> = ThrowOnError extends true ? {
+  data: T;
+  response: Response;
+  request: Request;
+} : {
+  data: T;
+  error: undefined;
+  response: Response;
+  request: Request;
+} | {
+  data: undefined;
+  error: ClientError;
+  response: Response;
+  request: Request;
+};
+interface RequestConfigOverrides {
+  throwOnError?: boolean;
+}
+/**
+ * Arbitrary options forwarded to the underlying `fetch()` call.
+ *
+ * Standard `RequestInit` properties (`cache`, `credentials`, `mode`, …) and
+ * non-standard, vendor-specific properties (Next.js `next`, Cloudflare `cf`, …)
+ * are both supported.
+ *
+ * @example
+ * ```ts
+ * client.stories.get(123, {
+ *   fetchOptions: {
+ *     cache: 'no-store',
+ *     next: { revalidate: 60 },
+ *   },
+ * })
+ * ```
+ */
+type FetchOptions = Record<string, unknown>;
+interface HttpRequestOptions {
+  query?: Record<string, unknown>;
+  body?: unknown;
+  headers?: Record<string, string>;
+  signal?: AbortSignal;
+  throwOnError?: RequestConfigOverrides['throwOnError'];
+  fetchOptions?: FetchOptions;
+}
+/**
+ * Dependencies injected into every resource factory.
+ */
+interface MapiResourceDeps {
+  client: Client;
+  spaceId?: number;
+  wrapRequest: <TData, ThrowOnError extends boolean = false>(fn: () => Promise<unknown>, throwOnError?: ThrowOnError) => Promise<ApiResponse<TData, ThrowOnError>>;
+}
+interface ManagementApiClientConfig {
+  /**
+   * Personal access token for authentication.
+   * Provide either `personalAccessToken` or `oauthToken`.
+   */
+  personalAccessToken?: string;
+  /**
+   * OAuth bearer token for authentication.
+   * Provide either `personalAccessToken` or `oauthToken`.
+   */
+  oauthToken?: string;
+  /**
+   * The Storyblok space ID. Used as the default for space-scoped endpoints.
+   * You can also override it per request via `path.space_id`.
+   */
+  spaceId?: number;
+  /**
+   * Storyblok region. Determines the base URL.
+   * @default 'eu'
+   */
+  region?: Region;
+  /**
+   * Override the base URL entirely (e.g. for testing).
+   */
+  baseUrl?: string;
+  /**
+   * Additional request headers.
+   */
+  headers?: Record<string, string>;
+  /**
+   * Throw on HTTP errors instead of returning them.
+   * @default false
+   */
+  throwOnError?: boolean;
+  /**
+   * Retry configuration for failed requests.
+   */
+  retry?: RetryOptions;
+  /**
+   * Request timeout in milliseconds.
+   * @default 30_000
+   */
+  timeout?: number;
+  /**
+   * Preventive rate limiting to avoid hitting the Storyblok Management API rate limits.
+   *
+   * - `undefined` (default): single bucket at maxConcurrency: 6.
+   * - `number`: fixed max concurrent requests per second.
+   * - `{ maxConcurrency?: number; adaptToServerHeaders?: boolean }`: full config.
+   * - `false`: disable rate limiting entirely.
+   */
+  rateLimit?: RateLimitConfig | number | false;
+}
+type AssetListQuery = NonNullable<ListData['query']>;
+type Story = Prettify<StoryMapi>;
+type StoryListQuery = NonNullable<ListData$1['query']>;
+//#endregion
+export { ApiResponse, AssetListQuery, FetchOptions, HttpRequestOptions, ManagementApiClientConfig, MapiResourceDeps, RequestConfigOverrides, Story, StoryListQuery };
+//# sourceMappingURL=types.d.cts.map

package/dist/types.d.mts

@@ -0,0 +1,130 @@
+import { AssetFolder, AssetFolderCreate, AssetFolderUpdate } from "./generated/asset_folders/types.gen.mjs";
+import { Asset, AssetSignRequest, AssetUpdate, AssetUpdateRequest, ListData, SignedResponseObject } from "./generated/assets/types.gen.mjs";
+import { AssetField, ListData as ListData$1, MultilinkField, PluginField, RichtextField, StoryAlternate, StoryContent, StoryCreate, StoryLocalizedPath, StoryMapi, StoryTranslatedSlug, StoryUpdate, TableField } from "./generated/stories/types.gen.mjs";
+import { Client, RetryOptions } from "./generated/shared/client/types.gen.mjs";
+import { ClientError } from "./error.mjs";
+import { RateLimitConfig } from "./utils/rate-limit.mjs";
+import { ComponentFolder } from "./generated/component_folders/types.gen.mjs";
+import { Component, ComponentCreate, ComponentSchemaField, ComponentUpdate } from "./generated/components/types.gen.mjs";
+import { DatasourceEntry, DatasourceEntryCreate, DatasourceEntryUpdate } from "./generated/datasource_entries/types.gen.mjs";
+import { Datasource, DatasourceCreate, DatasourceUpdate } from "./generated/datasources/types.gen.mjs";
+import { InternalTag } from "./generated/internal_tags/types.gen.mjs";
+import { Preset } from "./generated/presets/types.gen.mjs";
+import { Space, SpaceCreate, SpaceUpdate } from "./generated/spaces/types.gen.mjs";
+import { User } from "./generated/users/types.gen.mjs";
+import { AssetCreate, AssetUploadRequest } from "./resources/assets.mjs";
+import { Region } from "@storyblok/region-helper";
+
+//#region src/types.d.ts
+type Prettify<T> = { [K in keyof T]: T[K] } & {};
+type ApiResponse<T, ThrowOnError extends boolean = false> = ThrowOnError extends true ? {
+  data: T;
+  response: Response;
+  request: Request;
+} : {
+  data: T;
+  error: undefined;
+  response: Response;
+  request: Request;
+} | {
+  data: undefined;
+  error: ClientError;
+  response: Response;
+  request: Request;
+};
+interface RequestConfigOverrides {
+  throwOnError?: boolean;
+}
+/**
+ * Arbitrary options forwarded to the underlying `fetch()` call.
+ *
+ * Standard `RequestInit` properties (`cache`, `credentials`, `mode`, …) and
+ * non-standard, vendor-specific properties (Next.js `next`, Cloudflare `cf`, …)
+ * are both supported.
+ *
+ * @example
+ * ```ts
+ * client.stories.get(123, {
+ *   fetchOptions: {
+ *     cache: 'no-store',
+ *     next: { revalidate: 60 },
+ *   },
+ * })
+ * ```
+ */
+type FetchOptions = Record<string, unknown>;
+interface HttpRequestOptions {
+  query?: Record<string, unknown>;
+  body?: unknown;
+  headers?: Record<string, string>;
+  signal?: AbortSignal;
+  throwOnError?: RequestConfigOverrides['throwOnError'];
+  fetchOptions?: FetchOptions;
+}
+/**
+ * Dependencies injected into every resource factory.
+ */
+interface MapiResourceDeps {
+  client: Client;
+  spaceId?: number;
+  wrapRequest: <TData, ThrowOnError extends boolean = false>(fn: () => Promise<unknown>, throwOnError?: ThrowOnError) => Promise<ApiResponse<TData, ThrowOnError>>;
+}
+interface ManagementApiClientConfig {
+  /**
+   * Personal access token for authentication.
+   * Provide either `personalAccessToken` or `oauthToken`.
+   */
+  personalAccessToken?: string;
+  /**
+   * OAuth bearer token for authentication.
+   * Provide either `personalAccessToken` or `oauthToken`.
+   */
+  oauthToken?: string;
+  /**
+   * The Storyblok space ID. Used as the default for space-scoped endpoints.
+   * You can also override it per request via `path.space_id`.
+   */
+  spaceId?: number;
+  /**
+   * Storyblok region. Determines the base URL.
+   * @default 'eu'
+   */
+  region?: Region;
+  /**
+   * Override the base URL entirely (e.g. for testing).
+   */
+  baseUrl?: string;
+  /**
+   * Additional request headers.
+   */
+  headers?: Record<string, string>;
+  /**
+   * Throw on HTTP errors instead of returning them.
+   * @default false
+   */
+  throwOnError?: boolean;
+  /**
+   * Retry configuration for failed requests.
+   */
+  retry?: RetryOptions;
+  /**
+   * Request timeout in milliseconds.
+   * @default 30_000
+   */
+  timeout?: number;
+  /**
+   * Preventive rate limiting to avoid hitting the Storyblok Management API rate limits.
+   *
+   * - `undefined` (default): single bucket at maxConcurrency: 6.
+   * - `number`: fixed max concurrent requests per second.
+   * - `{ maxConcurrency?: number; adaptToServerHeaders?: boolean }`: full config.
+   * - `false`: disable rate limiting entirely.
+   */
+  rateLimit?: RateLimitConfig | number | false;
+}
+type AssetListQuery = NonNullable<ListData['query']>;
+type Story = Prettify<StoryMapi>;
+type StoryListQuery = NonNullable<ListData$1['query']>;
+//#endregion
+export { ApiResponse, AssetListQuery, FetchOptions, HttpRequestOptions, ManagementApiClientConfig, MapiResourceDeps, RequestConfigOverrides, Story, StoryListQuery };
+//# sourceMappingURL=types.d.mts.map

package/dist/utils/normalize-asset-url.cjs

@@ -0,0 +1,21 @@
+
+//#region src/utils/normalize-asset-url.ts
+/**
+* Normalizes an S3 asset URL to a Storyblok CDN URL.
+*
+* The MAPI returns asset filenames pointing to the raw S3 origin
+* (e.g. `https://s3.amazonaws.com/a.storyblok.com/f/...`) instead of the
+* CloudFront CDN (e.g. `https://a.storyblok.com/f/...`). The S3 URL does not
+* support the Storyblok Image Service (`/m/...`), which breaks image
+* optimization in frontends.
+*
+* Works for all regions because the regional CDN domain
+* (`a.storyblok.com`, `a-us.storyblok.com`, `a-ap.storyblok.com`,
+* `a-ca.storyblok.com`, `a.storyblokchina.cn`) is embedded as the S3 bucket
+* name in the path.
+*/
+const normalizeAssetUrl = (url) => url.replace(/^https?:\/\/s3\.amazonaws\.com\//, "https://");
+
+//#endregion
+exports.normalizeAssetUrl = normalizeAssetUrl;
+//# sourceMappingURL=normalize-asset-url.cjs.map

package/dist/utils/normalize-asset-url.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize-asset-url.cjs","names":[],"sources":["../../src/utils/normalize-asset-url.ts"],"sourcesContent":["/**\n * Normalizes an S3 asset URL to a Storyblok CDN URL.\n *\n * The MAPI returns asset filenames pointing to the raw S3 origin\n * (e.g. `https://s3.amazonaws.com/a.storyblok.com/f/...`) instead of the\n * CloudFront CDN (e.g. `https://a.storyblok.com/f/...`). The S3 URL does not\n * support the Storyblok Image Service (`/m/...`), which breaks image\n * optimization in frontends.\n *\n * Works for all regions because the regional CDN domain\n * (`a.storyblok.com`, `a-us.storyblok.com`, `a-ap.storyblok.com`,\n * `a-ca.storyblok.com`, `a.storyblokchina.cn`) is embedded as the S3 bucket\n * name in the path.\n */\nexport const normalizeAssetUrl = (url: string): string =>\n  url.replace(/^https?:\\/\\/s3\\.amazonaws\\.com\\//, 'https://');\n"],"mappings":";;;;;;;;;;;;;;;;AAcA,MAAa,qBAAqB,QAChC,IAAI,QAAQ,oCAAoC,WAAW"}

package/dist/utils/normalize-asset-url.d.cts

@@ -0,0 +1,19 @@
+//#region src/utils/normalize-asset-url.d.ts
+/**
+ * Normalizes an S3 asset URL to a Storyblok CDN URL.
+ *
+ * The MAPI returns asset filenames pointing to the raw S3 origin
+ * (e.g. `https://s3.amazonaws.com/a.storyblok.com/f/...`) instead of the
+ * CloudFront CDN (e.g. `https://a.storyblok.com/f/...`). The S3 URL does not
+ * support the Storyblok Image Service (`/m/...`), which breaks image
+ * optimization in frontends.
+ *
+ * Works for all regions because the regional CDN domain
+ * (`a.storyblok.com`, `a-us.storyblok.com`, `a-ap.storyblok.com`,
+ * `a-ca.storyblok.com`, `a.storyblokchina.cn`) is embedded as the S3 bucket
+ * name in the path.
+ */
+declare const normalizeAssetUrl: (url: string) => string;
+//#endregion
+export { normalizeAssetUrl };
+//# sourceMappingURL=normalize-asset-url.d.cts.map

package/dist/utils/normalize-asset-url.d.mts

@@ -0,0 +1,19 @@
+//#region src/utils/normalize-asset-url.d.ts
+/**
+ * Normalizes an S3 asset URL to a Storyblok CDN URL.
+ *
+ * The MAPI returns asset filenames pointing to the raw S3 origin
+ * (e.g. `https://s3.amazonaws.com/a.storyblok.com/f/...`) instead of the
+ * CloudFront CDN (e.g. `https://a.storyblok.com/f/...`). The S3 URL does not
+ * support the Storyblok Image Service (`/m/...`), which breaks image
+ * optimization in frontends.
+ *
+ * Works for all regions because the regional CDN domain
+ * (`a.storyblok.com`, `a-us.storyblok.com`, `a-ap.storyblok.com`,
+ * `a-ca.storyblok.com`, `a.storyblokchina.cn`) is embedded as the S3 bucket
+ * name in the path.
+ */
+declare const normalizeAssetUrl: (url: string) => string;
+//#endregion
+export { normalizeAssetUrl };
+//# sourceMappingURL=normalize-asset-url.d.mts.map

package/dist/utils/normalize-asset-url.mjs

@@ -0,0 +1,20 @@
+//#region src/utils/normalize-asset-url.ts
+/**
+* Normalizes an S3 asset URL to a Storyblok CDN URL.
+*
+* The MAPI returns asset filenames pointing to the raw S3 origin
+* (e.g. `https://s3.amazonaws.com/a.storyblok.com/f/...`) instead of the
+* CloudFront CDN (e.g. `https://a.storyblok.com/f/...`). The S3 URL does not
+* support the Storyblok Image Service (`/m/...`), which breaks image
+* optimization in frontends.
+*
+* Works for all regions because the regional CDN domain
+* (`a.storyblok.com`, `a-us.storyblok.com`, `a-ap.storyblok.com`,
+* `a-ca.storyblok.com`, `a.storyblokchina.cn`) is embedded as the S3 bucket
+* name in the path.
+*/
+const normalizeAssetUrl = (url) => url.replace(/^https?:\/\/s3\.amazonaws\.com\//, "https://");
+
+//#endregion
+export { normalizeAssetUrl };
+//# sourceMappingURL=normalize-asset-url.mjs.map

package/dist/utils/normalize-asset-url.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize-asset-url.mjs","names":[],"sources":["../../src/utils/normalize-asset-url.ts"],"sourcesContent":["/**\n * Normalizes an S3 asset URL to a Storyblok CDN URL.\n *\n * The MAPI returns asset filenames pointing to the raw S3 origin\n * (e.g. `https://s3.amazonaws.com/a.storyblok.com/f/...`) instead of the\n * CloudFront CDN (e.g. `https://a.storyblok.com/f/...`). The S3 URL does not\n * support the Storyblok Image Service (`/m/...`), which breaks image\n * optimization in frontends.\n *\n * Works for all regions because the regional CDN domain\n * (`a.storyblok.com`, `a-us.storyblok.com`, `a-ap.storyblok.com`,\n * `a-ca.storyblok.com`, `a.storyblokchina.cn`) is embedded as the S3 bucket\n * name in the path.\n */\nexport const normalizeAssetUrl = (url: string): string =>\n  url.replace(/^https?:\\/\\/s3\\.amazonaws\\.com\\//, 'https://');\n"],"mappings":";;;;;;;;;;;;;;;AAcA,MAAa,qBAAqB,QAChC,IAAI,QAAQ,oCAAoC,WAAW"}

package/dist/utils/rate-limit.cjs

@@ -0,0 +1,87 @@
+
+//#region src/utils/rate-limit.ts
+const DEFAULT_MAX_CONCURRENT = 6;
+const MAX_RATE_LIMIT = 1e3;
+/**
+* Concurrency limiter: allows up to `initialLimit` requests to be in-flight
+* at the same time. A slot is freed as soon as the request's promise settles
+* (resolves or rejects), so throughput scales with how quickly requests
+* complete rather than being artificially capped at N per second.
+*/
+function createThrottle(initialLimit) {
+	let limit = initialLimit;
+	let activeCount = 0;
+	const queue = [];
+	const tryNext = () => {
+		while (queue.length > 0 && activeCount < limit) {
+			activeCount++;
+			queue.shift()();
+		}
+	};
+	const execute = (fn) => {
+		return new Promise((resolve, reject) => {
+			queue.push(() => {
+				fn().then((value) => {
+					activeCount--;
+					tryNext();
+					resolve(value);
+				}, (error) => {
+					activeCount--;
+					tryNext();
+					reject(error);
+				});
+			});
+			tryNext();
+		});
+	};
+	const setLimit = (n) => {
+		limit = n;
+		tryNext();
+	};
+	return {
+		execute,
+		setLimit
+	};
+}
+/**
+* Extracts the quota (`q=`) value from the `X-RateLimit-Policy` response header.
+* Returns `undefined` if the header is absent or unparseable.
+*
+* Example header: `"concurrent-requests";q=30`
+*/
+function parseRateLimitPolicyHeader(response) {
+	const policy = response.headers.get("x-ratelimit-policy");
+	if (!policy) return;
+	const match = policy.match(/q=(\d+)/);
+	if (!match) return;
+	return Math.min(Number.parseInt(match[1], 10), MAX_RATE_LIMIT);
+}
+/**
+* Creates a `ThrottleManager` from the user-supplied `rateLimit` config.
+*
+* - `false`                     -> no throttling (passthrough)
+* - `number`                    -> fixed single queue at that concurrency
+* - `{ maxConcurrency: n }`      -> fixed single queue at n concurrent requests
+* - `{}` / `undefined` (default)-> single queue at DEFAULT_MAX_CONCURRENT
+*/
+function createThrottleManager(config) {
+	if (config === false) return {
+		execute: (fn) => fn(),
+		adaptToResponse: () => {}
+	};
+	const { maxConcurrency = DEFAULT_MAX_CONCURRENT, adaptToServerHeaders = true } = typeof config === "number" ? { maxConcurrency: config } : config;
+	const cappedLimit = Math.min(maxConcurrency, MAX_RATE_LIMIT);
+	const throttle = createThrottle(cappedLimit);
+	return {
+		execute: (fn) => throttle.execute(fn),
+		adaptToResponse: (response) => {
+			if (!adaptToServerHeaders || response === void 0) return;
+			const serverLimit = parseRateLimitPolicyHeader(response);
+			if (serverLimit !== void 0) throttle.setLimit(Math.min(cappedLimit, serverLimit));
+		}
+	};
+}
+
+//#endregion
+exports.createThrottleManager = createThrottleManager;
+//# sourceMappingURL=rate-limit.cjs.map

package/dist/utils/rate-limit.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.cjs","names":[],"sources":["../../src/utils/rate-limit.ts"],"sourcesContent":["const DEFAULT_MAX_CONCURRENT = 6;\nconst MAX_RATE_LIMIT = 1_000;\n\nexport interface RateLimitConfig {\n  /**\n   * Maximum number of concurrent in-flight requests.\n   * Defaults to 6. Capped at 1000.\n   */\n  maxConcurrency?: number;\n  /**\n   * Dynamically adjust the rate limit based on the `X-RateLimit-Policy`\n   * response header returned by the Storyblok API.\n   * @default true\n   */\n  adaptToServerHeaders?: boolean;\n}\n\nexport interface ThrottleManager {\n  execute: <T>(fn: () => Promise<T>) => Promise<T>;\n  adaptToResponse: (response: Response | undefined) => void;\n}\n\ninterface Throttle {\n  execute: <T>(fn: () => Promise<T>) => Promise<T>;\n  setLimit: (n: number) => void;\n}\n\n/**\n * Concurrency limiter: allows up to `initialLimit` requests to be in-flight\n * at the same time. A slot is freed as soon as the request's promise settles\n * (resolves or rejects), so throughput scales with how quickly requests\n * complete rather than being artificially capped at N per second.\n */\nexport function createThrottle(initialLimit: number): Throttle {\n  let limit = initialLimit;\n  let activeCount = 0;\n  const queue: Array<() => void> = [];\n\n  const tryNext = () => {\n    while (queue.length > 0 && activeCount < limit) {\n      activeCount++;\n      const run = queue.shift()!;\n      run();\n    }\n  };\n\n  const execute = <T>(fn: () => Promise<T>): Promise<T> => {\n    return new Promise<T>((resolve, reject) => {\n      queue.push(() => {\n        fn().then(\n          (value) => {\n            activeCount--;\n            tryNext();\n            resolve(value);\n          },\n          (error) => {\n            activeCount--;\n            tryNext();\n            reject(error);\n          },\n        );\n      });\n      tryNext();\n    });\n  };\n\n  const setLimit = (n: number) => {\n    limit = n;\n    // If the limit increased, unblock any waiting requests.\n    tryNext();\n  };\n\n  return { execute, setLimit };\n}\n\n/**\n * Extracts the quota (`q=`) value from the `X-RateLimit-Policy` response header.\n * Returns `undefined` if the header is absent or unparseable.\n *\n * Example header: `\"concurrent-requests\";q=30`\n */\nexport function parseRateLimitPolicyHeader(response: Response): number | undefined {\n  const policy = response.headers.get('x-ratelimit-policy');\n  if (!policy) {\n    return undefined;\n  }\n  const match = policy.match(/q=(\\d+)/);\n  if (!match) {\n    return undefined;\n  }\n  return Math.min(Number.parseInt(match[1], 10), MAX_RATE_LIMIT);\n}\n\n/**\n * Creates a `ThrottleManager` from the user-supplied `rateLimit` config.\n *\n * - `false`                     -> no throttling (passthrough)\n * - `number`                    -> fixed single queue at that concurrency\n * - `{ maxConcurrency: n }`      -> fixed single queue at n concurrent requests\n * - `{}` / `undefined` (default)-> single queue at DEFAULT_MAX_CONCURRENT\n */\nexport function createThrottleManager(config: RateLimitConfig | number | false): ThrottleManager {\n  // Disabled - every request goes straight through.\n  if (config === false) {\n    return {\n      execute: fn => fn(),\n      adaptToResponse: () => {},\n    };\n  }\n\n  const resolvedConfig: RateLimitConfig = typeof config === 'number' ? { maxConcurrency: config } : config;\n  const { maxConcurrency = DEFAULT_MAX_CONCURRENT, adaptToServerHeaders = true } = resolvedConfig;\n\n  const cappedLimit = Math.min(maxConcurrency, MAX_RATE_LIMIT);\n  const throttle = createThrottle(cappedLimit);\n\n  return {\n    execute: fn => throttle.execute(fn),\n    adaptToResponse: (response) => {\n      if (!adaptToServerHeaders || response === undefined) {\n        return;\n      }\n      const serverLimit = parseRateLimitPolicyHeader(response);\n      if (serverLimit !== undefined) {\n        // Never exceed the user-configured ceiling.\n        throttle.setLimit(Math.min(cappedLimit, serverLimit));\n      }\n    },\n  };\n}\n"],"mappings":";;AAAA,MAAM,yBAAyB;AAC/B,MAAM,iBAAiB;;;;;;;AAgCvB,SAAgB,eAAe,cAAgC;CAC7D,IAAI,QAAQ;CACZ,IAAI,cAAc;CAClB,MAAM,QAA2B,EAAE;CAEnC,MAAM,gBAAgB;AACpB,SAAO,MAAM,SAAS,KAAK,cAAc,OAAO;AAC9C;AAEA,GADY,MAAM,OAAO,EACpB;;;CAIT,MAAM,WAAc,OAAqC;AACvD,SAAO,IAAI,SAAY,SAAS,WAAW;AACzC,SAAM,WAAW;AACf,QAAI,CAAC,MACF,UAAU;AACT;AACA,cAAS;AACT,aAAQ,MAAM;QAEf,UAAU;AACT;AACA,cAAS;AACT,YAAO,MAAM;MAEhB;KACD;AACF,YAAS;IACT;;CAGJ,MAAM,YAAY,MAAc;AAC9B,UAAQ;AAER,WAAS;;AAGX,QAAO;EAAE;EAAS;EAAU;;;;;;;;AAS9B,SAAgB,2BAA2B,UAAwC;CACjF,MAAM,SAAS,SAAS,QAAQ,IAAI,qBAAqB;AACzD,KAAI,CAAC,OACH;CAEF,MAAM,QAAQ,OAAO,MAAM,UAAU;AACrC,KAAI,CAAC,MACH;AAEF,QAAO,KAAK,IAAI,OAAO,SAAS,MAAM,IAAI,GAAG,EAAE,eAAe;;;;;;;;;;AAWhE,SAAgB,sBAAsB,QAA2D;AAE/F,KAAI,WAAW,MACb,QAAO;EACL,UAAS,OAAM,IAAI;EACnB,uBAAuB;EACxB;CAIH,MAAM,EAAE,iBAAiB,wBAAwB,uBAAuB,SADhC,OAAO,WAAW,WAAW,EAAE,gBAAgB,QAAQ,GAAG;CAGlG,MAAM,cAAc,KAAK,IAAI,gBAAgB,eAAe;CAC5D,MAAM,WAAW,eAAe,YAAY;AAE5C,QAAO;EACL,UAAS,OAAM,SAAS,QAAQ,GAAG;EACnC,kBAAkB,aAAa;AAC7B,OAAI,CAAC,wBAAwB,aAAa,OACxC;GAEF,MAAM,cAAc,2BAA2B,SAAS;AACxD,OAAI,gBAAgB,OAElB,UAAS,SAAS,KAAK,IAAI,aAAa,YAAY,CAAC;;EAG1D"}

package/dist/utils/rate-limit.d.cts

@@ -0,0 +1,17 @@
+//#region src/utils/rate-limit.d.ts
+interface RateLimitConfig {
+  /**
+   * Maximum number of concurrent in-flight requests.
+   * Defaults to 6. Capped at 1000.
+   */
+  maxConcurrency?: number;
+  /**
+   * Dynamically adjust the rate limit based on the `X-RateLimit-Policy`
+   * response header returned by the Storyblok API.
+   * @default true
+   */
+  adaptToServerHeaders?: boolean;
+}
+//#endregion
+export { RateLimitConfig };
+//# sourceMappingURL=rate-limit.d.cts.map

package/dist/utils/rate-limit.d.mts

@@ -0,0 +1,17 @@
+//#region src/utils/rate-limit.d.ts
+interface RateLimitConfig {
+  /**
+   * Maximum number of concurrent in-flight requests.
+   * Defaults to 6. Capped at 1000.
+   */
+  maxConcurrency?: number;
+  /**
+   * Dynamically adjust the rate limit based on the `X-RateLimit-Policy`
+   * response header returned by the Storyblok API.
+   * @default true
+   */
+  adaptToServerHeaders?: boolean;
+}
+//#endregion
+export { RateLimitConfig };
+//# sourceMappingURL=rate-limit.d.mts.map

package/dist/utils/rate-limit.mjs

@@ -0,0 +1,86 @@
+//#region src/utils/rate-limit.ts
+const DEFAULT_MAX_CONCURRENT = 6;
+const MAX_RATE_LIMIT = 1e3;
+/**
+* Concurrency limiter: allows up to `initialLimit` requests to be in-flight
+* at the same time. A slot is freed as soon as the request's promise settles
+* (resolves or rejects), so throughput scales with how quickly requests
+* complete rather than being artificially capped at N per second.
+*/
+function createThrottle(initialLimit) {
+	let limit = initialLimit;
+	let activeCount = 0;
+	const queue = [];
+	const tryNext = () => {
+		while (queue.length > 0 && activeCount < limit) {
+			activeCount++;
+			queue.shift()();
+		}
+	};
+	const execute = (fn) => {
+		return new Promise((resolve, reject) => {
+			queue.push(() => {
+				fn().then((value) => {
+					activeCount--;
+					tryNext();
+					resolve(value);
+				}, (error) => {
+					activeCount--;
+					tryNext();
+					reject(error);
+				});
+			});
+			tryNext();
+		});
+	};
+	const setLimit = (n) => {
+		limit = n;
+		tryNext();
+	};
+	return {
+		execute,
+		setLimit
+	};
+}
+/**
+* Extracts the quota (`q=`) value from the `X-RateLimit-Policy` response header.
+* Returns `undefined` if the header is absent or unparseable.
+*
+* Example header: `"concurrent-requests";q=30`
+*/
+function parseRateLimitPolicyHeader(response) {
+	const policy = response.headers.get("x-ratelimit-policy");
+	if (!policy) return;
+	const match = policy.match(/q=(\d+)/);
+	if (!match) return;
+	return Math.min(Number.parseInt(match[1], 10), MAX_RATE_LIMIT);
+}
+/**
+* Creates a `ThrottleManager` from the user-supplied `rateLimit` config.
+*
+* - `false`                     -> no throttling (passthrough)
+* - `number`                    -> fixed single queue at that concurrency
+* - `{ maxConcurrency: n }`      -> fixed single queue at n concurrent requests
+* - `{}` / `undefined` (default)-> single queue at DEFAULT_MAX_CONCURRENT
+*/
+function createThrottleManager(config) {
+	if (config === false) return {
+		execute: (fn) => fn(),
+		adaptToResponse: () => {}
+	};
+	const { maxConcurrency = DEFAULT_MAX_CONCURRENT, adaptToServerHeaders = true } = typeof config === "number" ? { maxConcurrency: config } : config;
+	const cappedLimit = Math.min(maxConcurrency, MAX_RATE_LIMIT);
+	const throttle = createThrottle(cappedLimit);
+	return {
+		execute: (fn) => throttle.execute(fn),
+		adaptToResponse: (response) => {
+			if (!adaptToServerHeaders || response === void 0) return;
+			const serverLimit = parseRateLimitPolicyHeader(response);
+			if (serverLimit !== void 0) throttle.setLimit(Math.min(cappedLimit, serverLimit));
+		}
+	};
+}
+
+//#endregion
+export { createThrottleManager };
+//# sourceMappingURL=rate-limit.mjs.map

package/dist/utils/rate-limit.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.mjs","names":[],"sources":["../../src/utils/rate-limit.ts"],"sourcesContent":["const DEFAULT_MAX_CONCURRENT = 6;\nconst MAX_RATE_LIMIT = 1_000;\n\nexport interface RateLimitConfig {\n  /**\n   * Maximum number of concurrent in-flight requests.\n   * Defaults to 6. Capped at 1000.\n   */\n  maxConcurrency?: number;\n  /**\n   * Dynamically adjust the rate limit based on the `X-RateLimit-Policy`\n   * response header returned by the Storyblok API.\n   * @default true\n   */\n  adaptToServerHeaders?: boolean;\n}\n\nexport interface ThrottleManager {\n  execute: <T>(fn: () => Promise<T>) => Promise<T>;\n  adaptToResponse: (response: Response | undefined) => void;\n}\n\ninterface Throttle {\n  execute: <T>(fn: () => Promise<T>) => Promise<T>;\n  setLimit: (n: number) => void;\n}\n\n/**\n * Concurrency limiter: allows up to `initialLimit` requests to be in-flight\n * at the same time. A slot is freed as soon as the request's promise settles\n * (resolves or rejects), so throughput scales with how quickly requests\n * complete rather than being artificially capped at N per second.\n */\nexport function createThrottle(initialLimit: number): Throttle {\n  let limit = initialLimit;\n  let activeCount = 0;\n  const queue: Array<() => void> = [];\n\n  const tryNext = () => {\n    while (queue.length > 0 && activeCount < limit) {\n      activeCount++;\n      const run = queue.shift()!;\n      run();\n    }\n  };\n\n  const execute = <T>(fn: () => Promise<T>): Promise<T> => {\n    return new Promise<T>((resolve, reject) => {\n      queue.push(() => {\n        fn().then(\n          (value) => {\n            activeCount--;\n            tryNext();\n            resolve(value);\n          },\n          (error) => {\n            activeCount--;\n            tryNext();\n            reject(error);\n          },\n        );\n      });\n      tryNext();\n    });\n  };\n\n  const setLimit = (n: number) => {\n    limit = n;\n    // If the limit increased, unblock any waiting requests.\n    tryNext();\n  };\n\n  return { execute, setLimit };\n}\n\n/**\n * Extracts the quota (`q=`) value from the `X-RateLimit-Policy` response header.\n * Returns `undefined` if the header is absent or unparseable.\n *\n * Example header: `\"concurrent-requests\";q=30`\n */\nexport function parseRateLimitPolicyHeader(response: Response): number | undefined {\n  const policy = response.headers.get('x-ratelimit-policy');\n  if (!policy) {\n    return undefined;\n  }\n  const match = policy.match(/q=(\\d+)/);\n  if (!match) {\n    return undefined;\n  }\n  return Math.min(Number.parseInt(match[1], 10), MAX_RATE_LIMIT);\n}\n\n/**\n * Creates a `ThrottleManager` from the user-supplied `rateLimit` config.\n *\n * - `false`                     -> no throttling (passthrough)\n * - `number`                    -> fixed single queue at that concurrency\n * - `{ maxConcurrency: n }`      -> fixed single queue at n concurrent requests\n * - `{}` / `undefined` (default)-> single queue at DEFAULT_MAX_CONCURRENT\n */\nexport function createThrottleManager(config: RateLimitConfig | number | false): ThrottleManager {\n  // Disabled - every request goes straight through.\n  if (config === false) {\n    return {\n      execute: fn => fn(),\n      adaptToResponse: () => {},\n    };\n  }\n\n  const resolvedConfig: RateLimitConfig = typeof config === 'number' ? { maxConcurrency: config } : config;\n  const { maxConcurrency = DEFAULT_MAX_CONCURRENT, adaptToServerHeaders = true } = resolvedConfig;\n\n  const cappedLimit = Math.min(maxConcurrency, MAX_RATE_LIMIT);\n  const throttle = createThrottle(cappedLimit);\n\n  return {\n    execute: fn => throttle.execute(fn),\n    adaptToResponse: (response) => {\n      if (!adaptToServerHeaders || response === undefined) {\n        return;\n      }\n      const serverLimit = parseRateLimitPolicyHeader(response);\n      if (serverLimit !== undefined) {\n        // Never exceed the user-configured ceiling.\n        throttle.setLimit(Math.min(cappedLimit, serverLimit));\n      }\n    },\n  };\n}\n"],"mappings":";AAAA,MAAM,yBAAyB;AAC/B,MAAM,iBAAiB;;;;;;;AAgCvB,SAAgB,eAAe,cAAgC;CAC7D,IAAI,QAAQ;CACZ,IAAI,cAAc;CAClB,MAAM,QAA2B,EAAE;CAEnC,MAAM,gBAAgB;AACpB,SAAO,MAAM,SAAS,KAAK,cAAc,OAAO;AAC9C;AAEA,GADY,MAAM,OAAO,EACpB;;;CAIT,MAAM,WAAc,OAAqC;AACvD,SAAO,IAAI,SAAY,SAAS,WAAW;AACzC,SAAM,WAAW;AACf,QAAI,CAAC,MACF,UAAU;AACT;AACA,cAAS;AACT,aAAQ,MAAM;QAEf,UAAU;AACT;AACA,cAAS;AACT,YAAO,MAAM;MAEhB;KACD;AACF,YAAS;IACT;;CAGJ,MAAM,YAAY,MAAc;AAC9B,UAAQ;AAER,WAAS;;AAGX,QAAO;EAAE;EAAS;EAAU;;;;;;;;AAS9B,SAAgB,2BAA2B,UAAwC;CACjF,MAAM,SAAS,SAAS,QAAQ,IAAI,qBAAqB;AACzD,KAAI,CAAC,OACH;CAEF,MAAM,QAAQ,OAAO,MAAM,UAAU;AACrC,KAAI,CAAC,MACH;AAEF,QAAO,KAAK,IAAI,OAAO,SAAS,MAAM,IAAI,GAAG,EAAE,eAAe;;;;;;;;;;AAWhE,SAAgB,sBAAsB,QAA2D;AAE/F,KAAI,WAAW,MACb,QAAO;EACL,UAAS,OAAM,IAAI;EACnB,uBAAuB;EACxB;CAIH,MAAM,EAAE,iBAAiB,wBAAwB,uBAAuB,SADhC,OAAO,WAAW,WAAW,EAAE,gBAAgB,QAAQ,GAAG;CAGlG,MAAM,cAAc,KAAK,IAAI,gBAAgB,eAAe;CAC5D,MAAM,WAAW,eAAe,YAAY;AAE5C,QAAO;EACL,UAAS,OAAM,SAAS,QAAQ,GAAG;EACnC,kBAAkB,aAAa;AAC7B,OAAI,CAAC,wBAAwB,aAAa,OACxC;GAEF,MAAM,cAAc,2BAA2B,SAAS;AACxD,OAAI,gBAAgB,OAElB,UAAS,SAAS,KAAK,IAAI,aAAa,YAAY,CAAC;;EAG1D"}

package/eslint.config.js

@@ -0,0 +1,5 @@
+import { storyblokLintConfig } from '@storyblok/eslint-config';
+
+export default storyblokLintConfig({}, {
+  ignores: ['dist/', 'src/generated/', '**/*.md'],
+});