@storyblok/api-client 0.2.4 → 1.0.0-alpha.1

package/dist/client.cjs

@@ -0,0 +1,176 @@
+const require_runtime = require('./_virtual/_rolldown/runtime.cjs');
+const require_utils_gen = require('./generated/shared/client/utils.gen.cjs');
+const require_client_gen = require('./generated/shared/client/client.gen.cjs');
+require('./generated/shared/client/index.cjs');
+const require_cache = require('./utils/cache.cjs');
+const require_error = require('./error.cjs');
+const require_rate_limit = require('./utils/rate-limit.cjs');
+const require_request = require('./utils/request.cjs');
+const require_cv = require('./utils/cv.cjs');
+const require_stories = require('./resources/stories.cjs');
+const require_links = require('./resources/links.cjs');
+const require_tags = require('./resources/tags.cjs');
+const require_datasources = require('./resources/datasources.cjs');
+const require_datasource_entries = require('./resources/datasource-entries.cjs');
+const require_spaces = require('./resources/spaces.cjs');
+let _storyblok_region_helper = require("@storyblok/region-helper");
+
+//#region src/client.ts
+const createApiClientBase = (config) => {
+	const { accessToken, region = "eu", baseUrl, headers = {}, throwOnError = false, cache = {}, inlineRelations = false, retry, timeout = 3e4, rateLimit, fetch: customFetch } = config;
+	const retryOptions = {
+		limit: 3,
+		backoffLimit: 2e4,
+		jitter: true,
+		...retry
+	};
+	const throttleManager = require_rate_limit.createThrottleManager(rateLimit ?? {});
+	const cacheProvider = cache.provider ?? require_cache.createMemoryCacheProvider();
+	const swrOptions = cache.onRevalidationError ? { onRevalidationError: cache.onRevalidationError } : void 0;
+	const strategy = cache.strategy ? typeof cache.strategy === "string" ? require_cache.createStrategy(cache.strategy, swrOptions) : cache.strategy : require_cache.createStrategy("cache-first");
+	const cacheTtlMs = cache.ttlMs ?? 6e4;
+	const cacheFlush = cache.flush ?? "auto";
+	let currentCv;
+	const client = require_client_gen.createClient(require_utils_gen.createConfig({
+		auth: accessToken,
+		baseUrl: baseUrl || (0, _storyblok_region_helper.getRegionBaseUrl)(region),
+		headers,
+		throwOnError,
+		kyOptions: {
+			throwHttpErrors: true,
+			timeout,
+			retry: retryOptions,
+			...customFetch && { fetch: customFetch }
+		}
+	}));
+	client.interceptors.error.use((error, response) => new require_error.ClientError(response?.statusText || "API request failed", {
+		status: response?.status ?? 0,
+		statusText: response?.statusText ?? "",
+		data: error
+	}));
+	const security = [{
+		in: "query",
+		name: "token",
+		type: "apiKey"
+	}];
+	const updateCv = async (result) => {
+		const nextCv = require_cv.extractCv(result.data);
+		if (nextCv === void 0) return true;
+		if (currentCv !== void 0 && nextCv < currentCv) return false;
+		if (cacheFlush === "auto" && currentCv !== void 0 && currentCv !== nextCv) await cacheProvider.flush();
+		currentCv = nextCv;
+		return true;
+	};
+	const cacheSuccessResult = async (key, result) => {
+		const shouldCacheResult = await updateCv(result);
+		if (result.error === void 0 && shouldCacheResult) await cacheProvider.set(key, {
+			value: result,
+			ttlMs: cacheTtlMs
+		});
+		return result;
+	};
+	const requestNetwork = async (method, path, query, options) => {
+		return client.request({
+			...options,
+			method,
+			query,
+			security,
+			url: path
+		});
+	};
+	/**
+	* Wraps a raw SDK call to cast the `error: unknown` type returned by
+	* generated code to `ClientError` — the error interceptor ensures the
+	* runtime value IS a ClientError.
+	*/
+	const asApiResponse = (p) => p;
+	const requestWithCache = async (method, path, rawQuery, fetchFn, cacheOptions) => {
+		const query = currentCv !== void 0 ? require_cv.applyCvToQuery(rawQuery, currentCv) : rawQuery;
+		if (!require_request.shouldUseCache(method, path, rawQuery)) {
+			const networkResult = await fetchFn(query);
+			throttleManager.adaptToResponse(networkResult.response);
+			await updateCv(networkResult);
+			return networkResult;
+		}
+		const baseKey = require_request.createCacheKey(method, path, rawQuery);
+		const key = cacheOptions?.cacheKeyPrefix ? `${cacheOptions.cacheKeyPrefix}:${baseKey}` : baseKey;
+		const cachedResult = (await cacheProvider.get(key))?.value;
+		const loadNetwork = async () => {
+			const result = await fetchFn(query);
+			throttleManager.adaptToResponse(result.response);
+			return cacheSuccessResult(key, result);
+		};
+		return strategy({
+			key,
+			cachedResult,
+			loadNetwork
+		});
+	};
+	const request = async (method, path, options = {}) => {
+		const rawQuery = options.query || {};
+		return requestWithCache(method, path, rawQuery, (query) => {
+			return throttleManager.execute(path, rawQuery, () => requestNetwork(method, path, query, options));
+		});
+	};
+	const getRequest = (path, options = {}) => {
+		return request("GET", path, options);
+	};
+	const resourceDeps = {
+		client,
+		requestWithCache,
+		asApiResponse,
+		throttleManager
+	};
+	const stories = require_stories.createStoriesResource({
+		...resourceDeps,
+		inlineRelations
+	});
+	/**
+	* Flush the in-memory cache and reset the tracked cv.
+	*
+	* Call this explicitly when `cache.flush` is set to `'manual'`, e.g. after
+	* receiving a Storyblok webhook event that signals content has changed.
+	*/
+	const flushCache = async () => {
+		await cacheProvider.flush();
+		currentCv = void 0;
+	};
+	return {
+		datasourceEntries: require_datasource_entries.createDatasourceEntriesResource(resourceDeps),
+		datasources: require_datasources.createDatasourcesResource(resourceDeps),
+		flushCache,
+		get: getRequest,
+		interceptors: client.interceptors,
+		links: require_links.createLinksResource(resourceDeps),
+		spaces: require_spaces.createSpacesResource(resourceDeps),
+		stories,
+		tags: require_tags.createTagsResource(resourceDeps)
+	};
+};
+/**
+* Creates a Storyblok Content Delivery API client.
+*
+* Use `.withTypes<YourTypes>()` on the returned client to enable discriminated
+* union typing on `story.content` without including any schema values in your bundle.
+*
+* @example
+* ```ts
+* import type { pageBlock, heroBlock } from './blocks';
+*
+* const client = createApiClient({ accessToken: 'your-token' })
+*   .withTypes<StoryblokTypes>();
+* ```
+*/
+const createApiClient = (config) => {
+	const self = {
+		...createApiClientBase(config),
+		withTypes() {
+			return self;
+		}
+	};
+	return self;
+};
+
+//#endregion
+exports.createApiClient = createApiClient;
+//# sourceMappingURL=client.cjs.map

package/dist/client.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.cjs","names":["createThrottleManager","createMemoryCacheProvider","createStrategy","createClient","createConfig","ClientError","extractCv","applyCvToQuery","shouldUseCache","createCacheKey","createStoriesResource","createDatasourceEntriesResource","createDatasourcesResource","createLinksResource","createSpacesResource","createTagsResource"],"sources":["../src/client.ts"],"sourcesContent":["import { createClient, createConfig } from './generated/shared/client';\nimport type { CacheProvider, CacheStrategy, CacheStrategyHandler } from './utils/cache';\nimport { createMemoryCacheProvider, createStrategy } from './utils/cache';\nimport { ClientError } from './error';\nimport type { RateLimitConfig, ThrottleManager } from './utils/rate-limit';\nimport { createThrottleManager } from './utils/rate-limit';\nimport { applyCvToQuery, extractCv } from './utils/cv';\nimport { createCacheKey, shouldUseCache } from './utils/request';\nimport { getRegionBaseUrl, type Region } from '@storyblok/region-helper';\nimport type { Block as Component } from '@storyblok/schema';\nimport type { RetryOptions } from 'ky';\nimport type { Client, RequestOptions } from './generated/shared/client';\nimport { createStoriesResource } from './resources/stories';\nimport { createLinksResource } from './resources/links';\nimport { createTagsResource } from './resources/tags';\nimport { createDatasourcesResource } from './resources/datasources';\nimport { createDatasourceEntriesResource } from './resources/datasource-entries';\nimport { createSpacesResource } from './resources/spaces';\n\n// ---------------------------------------------------------------------------\n// Client types (co-located with runtime)\n// ---------------------------------------------------------------------------\n\nexport type ApiResponse<Data = unknown, ThrowOnError extends boolean = false> =\n  ThrowOnError extends true\n    ? { data: Data; error?: never; response: Response; request: Request }\n    : { data?: Data; error?: ClientError; response: Response; request: Request };\n\nexport type HttpRequestOptions = Omit<\n  RequestOptions,\n  'method' | 'security' | 'url'\n>;\n\nexport type HttpRequestMethod = <TData = unknown>(\n  path: string,\n  options?: HttpRequestOptions,\n) => Promise<ApiResponse<TData>>;\n\n/**\n * Arbitrary options forwarded to the underlying `fetch()` call.\n *\n * Standard `RequestInit` properties (`cache`, `credentials`, `mode`, …) and\n * non-standard, vendor-specific properties (Next.js `next`, Cloudflare `cf`, …)\n * are both supported.\n *\n * @example\n * ```ts\n * client.stories.get('home', {\n *   fetchOptions: {\n *     cache: 'no-store',\n *     next: { revalidate: 60, tags: ['home'] },\n *   },\n * })\n * ```\n */\nexport type FetchOptions = Record<string, unknown>;\n\nexport interface RequestWithCacheOptions {\n  /** Prefix added to the cache key to namespace entries (e.g. `'inline'`). */\n  cacheKeyPrefix?: string;\n}\n\nexport interface ResourceDeps<DefaultThrowOnError extends boolean = false> {\n  client: Client;\n  requestWithCache: <TData, ThrowOnError extends boolean = DefaultThrowOnError>(\n    method: 'GET',\n    path: string,\n    rawQuery: Record<string, unknown>,\n    fetchFn: (query: Record<string, unknown>) => Promise<ApiResponse<TData, ThrowOnError>>,\n    options?: RequestWithCacheOptions,\n  ) => Promise<ApiResponse<TData, ThrowOnError>>;\n  asApiResponse: <TData, ThrowOnError extends boolean = DefaultThrowOnError>(p: Promise<unknown>) => Promise<ApiResponse<TData, ThrowOnError>>;\n  throttleManager: ThrottleManager;\n}\n\n// ---------------------------------------------------------------------------\n// Config types\n// ---------------------------------------------------------------------------\n\n/**\n * Cache configuration.\n *\n * **Note:** Requests with `version: 'draft'` always bypass the cache regardless\n * of the configured strategy. Only published content is cached.\n */\nexport interface CacheConfig {\n  /** Custom cache provider. Defaults to an in-memory LRU cache (1 000 entries). */\n  provider?: CacheProvider;\n  /** Cache strategy for published requests. @default 'cache-first' */\n  strategy?: CacheStrategy | CacheStrategyHandler;\n  /** Time-to-live in milliseconds for cached entries. @default 60_000 */\n  ttlMs?: number;\n  /**\n   * Controls when the cache is flushed on cv change.\n   *\n   * - `'auto'` (default): automatically flush the cache whenever the API returns a new cv value.\n   * - `'manual'`: never auto-flush; call `client.flushCache()` explicitly (e.g. on webhook trigger).\n   */\n  flush?: 'auto' | 'manual';\n  /**\n   * Called when SWR background revalidation fails.\n   * Only relevant when `strategy` is `'swr'`.\n   * @default console.warn\n   */\n  onRevalidationError?: (error: unknown) => void;\n}\n\nexport interface ContentApiClientConfig<\n  ThrowOnError extends boolean = false,\n  InlineRelations extends boolean = false,\n> {\n  accessToken: string;\n  region?: Region;\n  baseUrl?: string;\n  headers?: Record<string, string>;\n  throwOnError?: ThrowOnError;\n  cache?: CacheConfig;\n  inlineRelations?: InlineRelations;\n  retry?: RetryOptions;\n  /**\n   * Request timeout in milliseconds.\n   * @default 30_000\n   */\n  timeout?: number;\n  /**\n   * Preventive rate limiting to avoid hitting the Storyblok CDN rate limits.\n   *\n   * - `undefined` (default): auto-detect tier from path + `per_page` query param.\n   * - `number`: fixed max concurrent requests per second (single queue).\n   * - `{ maxConcurrency?: number; adaptToServerHeaders?: boolean }`: full config.\n   * - `false`: disable rate limiting entirely.\n   */\n  rateLimit?: RateLimitConfig | number | false;\n  /**\n   * Custom `fetch` function to use for all requests.\n   * Must be fully compatible with the Fetch API standard.\n   *\n   * Use cases:\n   * - SSR framework fetch wrappers (e.g., Next.js `fetch` with caching)\n   * - Custom instrumentation or logging around requests\n   *\n   * @default globalThis.fetch\n   */\n  fetch?: typeof globalThis.fetch;\n}\n\ntype StoryblokTypesConfig = { components: Component } | { blocks: Component };\n\ntype ResolveComponents<T extends StoryblokTypesConfig> =\n  T extends { components: infer C extends Component } ? C\n    : T extends { blocks: infer B extends Component } ? B\n      : never;\n\n/**\n * The return type of `createApiClient`, parameterised by `TComponents` and `InlineRelations`\n * so that `.withTypes<T>()` can change the story response types without touching the\n * runtime object.\n */\nexport type ContentApiClient<\n  TComponents extends Component = Component,\n  InlineRelations extends boolean = false,\n  ThrowOnError extends boolean = false,\n> = Omit<ReturnType<typeof createApiClientBase>, 'stories' | 'withTypes'> & {\n  stories: ReturnType<typeof createStoriesResource<TComponents, InlineRelations, ThrowOnError>>;\n  /**\n   * Returns the same client instance cast to a version that narrows story content\n   * to the provided component types. No runtime cost — the type parameter is erased.\n   *\n   * Accepts either `{ components: ... }` or `{ blocks: ... }` — the latter matches the\n   * `Schema` type produced by `@storyblok/schema`'s `InferSchema`.\n   *\n   * @example\n   * ```ts\n   * import type { Schema } from './schema';\n   *\n   * const client = createApiClient({ accessToken: 'your-token' })\n   *   .withTypes<Schema>();\n   * // story.content is now typed as a discriminated union\n   * ```\n   */\n  withTypes: <T extends StoryblokTypesConfig>() => ContentApiClient<ResolveComponents<T>, InlineRelations, ThrowOnError>;\n};\n\n// ---------------------------------------------------------------------------\n// Client factory\n// ---------------------------------------------------------------------------\n\nexport const createApiClientBase = <\n  ThrowOnError extends boolean = false,\n  InlineRelations extends boolean = false,\n>(\n  config: ContentApiClientConfig<ThrowOnError, InlineRelations>,\n) => {\n  const {\n    accessToken,\n    region = 'eu',\n    baseUrl,\n    headers = {},\n    throwOnError = false,\n    cache = {},\n    inlineRelations = false,\n    retry,\n    timeout = 30_000,\n    rateLimit,\n    fetch: customFetch,\n  } = config;\n  const retryOptions: RetryOptions = { limit: 3, backoffLimit: 20_000, jitter: true, ...retry };\n  // `rateLimit` defaults to `{}` (auto-detect mode) when not supplied.\n  const throttleManager = createThrottleManager(rateLimit ?? {});\n  const cacheProvider = cache.provider ?? createMemoryCacheProvider();\n  const swrOptions = cache.onRevalidationError ? { onRevalidationError: cache.onRevalidationError } : undefined;\n  const strategy = cache.strategy\n    ? typeof cache.strategy === 'string'\n      ? createStrategy(cache.strategy, swrOptions)\n      : cache.strategy\n    : createStrategy('cache-first');\n  const cacheTtlMs = cache.ttlMs ?? 60_000;\n  const cacheFlush = cache.flush ?? 'auto';\n  let currentCv: number | undefined;\n\n  const client: Client = createClient(\n    createConfig({\n      auth: accessToken,\n      baseUrl: baseUrl || getRegionBaseUrl(region),\n      headers,\n      throwOnError,\n      kyOptions: {\n        // Enable `throwHttpErrors` to make retry work, even if `throwOnError`\n        // is `false`. The client's error handling will still work because it\n        // catches `HTTPError`.\n        throwHttpErrors: true,\n        timeout,\n        retry: retryOptions,\n        ...(customFetch && { fetch: customFetch }),\n      },\n    }),\n  );\n\n  client.interceptors.error.use(\n    (error: unknown, response: Response) =>\n      new ClientError(response?.statusText || 'API request failed', {\n        status: response?.status ?? 0,\n        statusText: response?.statusText ?? '',\n        data: error,\n      }),\n  );\n\n  const security = [\n    {\n      in: 'query' as const,\n      name: 'token',\n      type: 'apiKey' as const,\n    },\n  ];\n\n  const updateCv = async (result: ApiResponse): Promise<boolean> => {\n    const nextCv = extractCv(result.data);\n    if (nextCv === undefined) {\n      return true;\n    }\n\n    // Guard against cv regression: SWR background revalidation may carry a\n    // stale cv from a prior request; never move cv backward.\n    if (currentCv !== undefined && nextCv < currentCv) {\n      return false;\n    }\n\n    if (cacheFlush === 'auto' && currentCv !== undefined && currentCv !== nextCv) {\n      await cacheProvider.flush();\n    }\n\n    currentCv = nextCv;\n    return true;\n  };\n\n  const cacheSuccessResult = async <TResponse extends ApiResponse>(key: string, result: TResponse) => {\n    const shouldCacheResult = await updateCv(result);\n    if (result.error === undefined && shouldCacheResult) {\n      await cacheProvider.set(key, {\n        value: result,\n        ttlMs: cacheTtlMs,\n      });\n    }\n    return result;\n  };\n\n  const requestNetwork = async (\n    method: 'GET',\n    path: string,\n    query: Record<string, unknown>,\n    options: HttpRequestOptions,\n  ): Promise<ApiResponse> => {\n    return client.request<unknown, ClientError, boolean>({\n      ...options,\n      method,\n      query,\n      security,\n      url: path,\n    });\n  };\n\n  /**\n   * Wraps a raw SDK call to cast the `error: unknown` type returned by\n   * generated code to `ClientError` — the error interceptor ensures the\n   * runtime value IS a ClientError.\n   */\n  const asApiResponse = <TData, ThrowOnError extends boolean = false>(\n    p: Promise<unknown>,\n  ): Promise<ApiResponse<TData, ThrowOnError>> => p as unknown as Promise<ApiResponse<TData, ThrowOnError>>;\n\n  const requestWithCache = async <TData = unknown, ThrowOnError extends boolean = false>(\n    method: 'GET',\n    path: string,\n    rawQuery: Record<string, unknown>,\n    fetchFn: (query: Record<string, unknown>) => Promise<ApiResponse<TData, ThrowOnError>>,\n    cacheOptions?: RequestWithCacheOptions,\n  ): Promise<ApiResponse<TData, ThrowOnError>> => {\n    const query = currentCv !== undefined ? applyCvToQuery(rawQuery, currentCv) : rawQuery;\n    const cacheEnabled = shouldUseCache(method, path, rawQuery);\n\n    if (!cacheEnabled) {\n      const networkResult = await fetchFn(query);\n      throttleManager.adaptToResponse(networkResult.response);\n      await updateCv(networkResult);\n      return networkResult;\n    }\n\n    const baseKey = createCacheKey(method, path, rawQuery);\n    const key = cacheOptions?.cacheKeyPrefix ? `${cacheOptions.cacheKeyPrefix}:${baseKey}` : baseKey;\n    const cachedEntry = await cacheProvider.get<ApiResponse<TData, ThrowOnError>>(key);\n    const cachedResult = cachedEntry?.value;\n\n    const loadNetwork = async () => {\n      const result = await fetchFn(query);\n      throttleManager.adaptToResponse(result.response);\n      return cacheSuccessResult(key, result);\n    };\n\n    return strategy({\n      key,\n      cachedResult,\n      loadNetwork,\n    });\n  };\n\n  const request = async (\n    method: 'GET',\n    path: string,\n    options: HttpRequestOptions = {},\n  ): Promise<ApiResponse> => {\n    const rawQuery = options.query || {};\n\n    return requestWithCache(method, path, rawQuery, (query) => {\n      return throttleManager.execute(path, rawQuery, () => requestNetwork(method, path, query, options));\n    });\n  };\n\n  const getRequest = (\n    path: string,\n    options: HttpRequestOptions = {},\n  ) => {\n    return request('GET', path, options);\n  };\n\n  const resourceDeps: ResourceDeps<ThrowOnError> = {\n    client,\n    requestWithCache,\n    asApiResponse,\n    throttleManager,\n  };\n\n  const stories = createStoriesResource<Component, InlineRelations, ThrowOnError>({\n    ...resourceDeps,\n    inlineRelations,\n  });\n\n  /**\n   * Flush the in-memory cache and reset the tracked cv.\n   *\n   * Call this explicitly when `cache.flush` is set to `'manual'`, e.g. after\n   * receiving a Storyblok webhook event that signals content has changed.\n   */\n  const flushCache = async (): Promise<void> => {\n    await cacheProvider.flush();\n    currentCv = undefined;\n  };\n\n  return {\n    datasourceEntries: createDatasourceEntriesResource(resourceDeps),\n    datasources: createDatasourcesResource(resourceDeps),\n    flushCache,\n    get: getRequest,\n    interceptors: client.interceptors,\n    links: createLinksResource(resourceDeps),\n    spaces: createSpacesResource(resourceDeps),\n    stories,\n    tags: createTagsResource(resourceDeps),\n  };\n};\n\n/**\n * Creates a Storyblok Content Delivery API client.\n *\n * Use `.withTypes<YourTypes>()` on the returned client to enable discriminated\n * union typing on `story.content` without including any schema values in your bundle.\n *\n * @example\n * ```ts\n * import type { pageBlock, heroBlock } from './blocks';\n *\n * const client = createApiClient({ accessToken: 'your-token' })\n *   .withTypes<StoryblokTypes>();\n * ```\n */\nexport const createApiClient = <\n  ThrowOnError extends boolean = false,\n  InlineRelations extends boolean = false,\n>(\n  config: ContentApiClientConfig<ThrowOnError, InlineRelations>,\n): ContentApiClient<Component, InlineRelations, ThrowOnError> => {\n  const base = createApiClientBase(config);\n  const self: ContentApiClient<Component, InlineRelations, ThrowOnError> = {\n    ...base,\n    withTypes<T extends StoryblokTypesConfig>(): ContentApiClient<ResolveComponents<T>, InlineRelations, ThrowOnError> {\n      return self as unknown as ContentApiClient<ResolveComponents<T>, InlineRelations, ThrowOnError>;\n    },\n  };\n  return self;\n};\n"],"mappings":"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"}

package/dist/client.d.cts

@@ -0,0 +1,333 @@
+import { DatasourceEntryCapi, ListData } from "./generated/datasource_entries/types.gen.cjs";
+import { DatasourceCapi, GetData, ListData as ListData$1 } from "./generated/datasources/types.gen.cjs";
+import { Middleware } from "./generated/shared/client/utils.gen.cjs";
+import { Client, RequestOptions, ResolvedRequestOptions } from "./generated/shared/client/types.gen.cjs";
+import { LinkCapi, ListData as ListData$2 } from "./generated/links/types.gen.cjs";
+import { SpaceCapi } from "./generated/spaces/types.gen.cjs";
+import { StoryCapi } from "./generated/stories/types.gen.cjs";
+import { ListData as ListData$3, TagCapi } from "./generated/tags/types.gen.cjs";
+import { CacheProvider, CacheStrategy, CacheStrategyHandler } from "./utils/cache.cjs";
+import { ClientError } from "./error.cjs";
+import { RateLimitConfig, ThrottleManager } from "./utils/rate-limit.cjs";
+import { StoryWithInlinedRelations, createStoriesResource } from "./resources/stories.cjs";
+import { RetryOptions } from "ky";
+import { Region } from "@storyblok/region-helper";
+import { Block } from "@storyblok/schema";
+
+//#region src/client.d.ts
+type ApiResponse<Data = unknown, ThrowOnError extends boolean = false> = ThrowOnError extends true ? {
+  data: Data;
+  error?: never;
+  response: Response;
+  request: Request;
+} : {
+  data?: Data;
+  error?: ClientError;
+  response: Response;
+  request: Request;
+};
+type HttpRequestOptions = Omit<RequestOptions, 'method' | 'security' | 'url'>;
+type HttpRequestMethod = <TData = unknown>(path: string, options?: HttpRequestOptions) => Promise<ApiResponse<TData>>;
+/**
+ * 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('home', {
+ *   fetchOptions: {
+ *     cache: 'no-store',
+ *     next: { revalidate: 60, tags: ['home'] },
+ *   },
+ * })
+ * ```
+ */
+type FetchOptions = Record<string, unknown>;
+interface RequestWithCacheOptions {
+  /** Prefix added to the cache key to namespace entries (e.g. `'inline'`). */
+  cacheKeyPrefix?: string;
+}
+interface ResourceDeps<DefaultThrowOnError extends boolean = false> {
+  client: Client;
+  requestWithCache: <TData, ThrowOnError extends boolean = DefaultThrowOnError>(method: 'GET', path: string, rawQuery: Record<string, unknown>, fetchFn: (query: Record<string, unknown>) => Promise<ApiResponse<TData, ThrowOnError>>, options?: RequestWithCacheOptions) => Promise<ApiResponse<TData, ThrowOnError>>;
+  asApiResponse: <TData, ThrowOnError extends boolean = DefaultThrowOnError>(p: Promise<unknown>) => Promise<ApiResponse<TData, ThrowOnError>>;
+  throttleManager: ThrottleManager;
+}
+/**
+ * Cache configuration.
+ *
+ * **Note:** Requests with `version: 'draft'` always bypass the cache regardless
+ * of the configured strategy. Only published content is cached.
+ */
+interface CacheConfig {
+  /** Custom cache provider. Defaults to an in-memory LRU cache (1 000 entries). */
+  provider?: CacheProvider;
+  /** Cache strategy for published requests. @default 'cache-first' */
+  strategy?: CacheStrategy | CacheStrategyHandler;
+  /** Time-to-live in milliseconds for cached entries. @default 60_000 */
+  ttlMs?: number;
+  /**
+   * Controls when the cache is flushed on cv change.
+   *
+   * - `'auto'` (default): automatically flush the cache whenever the API returns a new cv value.
+   * - `'manual'`: never auto-flush; call `client.flushCache()` explicitly (e.g. on webhook trigger).
+   */
+  flush?: 'auto' | 'manual';
+  /**
+   * Called when SWR background revalidation fails.
+   * Only relevant when `strategy` is `'swr'`.
+   * @default console.warn
+   */
+  onRevalidationError?: (error: unknown) => void;
+}
+interface ContentApiClientConfig<ThrowOnError extends boolean = false, InlineRelations extends boolean = false> {
+  accessToken: string;
+  region?: Region;
+  baseUrl?: string;
+  headers?: Record<string, string>;
+  throwOnError?: ThrowOnError;
+  cache?: CacheConfig;
+  inlineRelations?: InlineRelations;
+  retry?: RetryOptions;
+  /**
+   * Request timeout in milliseconds.
+   * @default 30_000
+   */
+  timeout?: number;
+  /**
+   * Preventive rate limiting to avoid hitting the Storyblok CDN rate limits.
+   *
+   * - `undefined` (default): auto-detect tier from path + `per_page` query param.
+   * - `number`: fixed max concurrent requests per second (single queue).
+   * - `{ maxConcurrency?: number; adaptToServerHeaders?: boolean }`: full config.
+   * - `false`: disable rate limiting entirely.
+   */
+  rateLimit?: RateLimitConfig | number | false;
+  /**
+   * Custom `fetch` function to use for all requests.
+   * Must be fully compatible with the Fetch API standard.
+   *
+   * Use cases:
+   * - SSR framework fetch wrappers (e.g., Next.js `fetch` with caching)
+   * - Custom instrumentation or logging around requests
+   *
+   * @default globalThis.fetch
+   */
+  fetch?: typeof globalThis.fetch;
+}
+type StoryblokTypesConfig = {
+  components: Block;
+} | {
+  blocks: Block;
+};
+type ResolveComponents<T extends StoryblokTypesConfig> = T extends {
+  components: infer C extends Block;
+} ? C : T extends {
+  blocks: infer B extends Block;
+} ? B : never;
+/**
+ * The return type of `createApiClient`, parameterised by `TComponents` and `InlineRelations`
+ * so that `.withTypes<T>()` can change the story response types without touching the
+ * runtime object.
+ */
+type ContentApiClient<TComponents extends Block = Block, InlineRelations extends boolean = false, ThrowOnError extends boolean = false> = Omit<ReturnType<typeof createApiClientBase>, 'stories' | 'withTypes'> & {
+  stories: ReturnType<typeof createStoriesResource<TComponents, InlineRelations, ThrowOnError>>;
+  /**
+   * Returns the same client instance cast to a version that narrows story content
+   * to the provided component types. No runtime cost — the type parameter is erased.
+   *
+   * Accepts either `{ components: ... }` or `{ blocks: ... }` — the latter matches the
+   * `Schema` type produced by `@storyblok/schema`'s `InferSchema`.
+   *
+   * @example
+   * ```ts
+   * import type { Schema } from './schema';
+   *
+   * const client = createApiClient({ accessToken: 'your-token' })
+   *   .withTypes<Schema>();
+   * // story.content is now typed as a discriminated union
+   * ```
+   */
+  withTypes: <T extends StoryblokTypesConfig>() => ContentApiClient<ResolveComponents<T>, InlineRelations, ThrowOnError>;
+};
+declare const createApiClientBase: <ThrowOnError extends boolean = false, InlineRelations extends boolean = false>(config: ContentApiClientConfig<ThrowOnError, InlineRelations>) => {
+  datasourceEntries: {
+    list: <ThrowOnError_1 extends boolean = ThrowOnError>(options?: {
+      query?: ListData["query"];
+      signal?: AbortSignal;
+      throwOnError?: ThrowOnError_1 | undefined;
+      fetchOptions?: FetchOptions;
+    }) => Promise<ApiResponse<{
+      datasource_entries: Array<DatasourceEntryCapi>;
+      cv?: number | null;
+    }, ThrowOnError_1>>;
+  };
+  datasources: {
+    get: <ThrowOnError_1 extends boolean = ThrowOnError>(id: GetData["path"]["id"], options?: {
+      query?: GetData["query"];
+      signal?: AbortSignal;
+      throwOnError?: ThrowOnError_1 | undefined;
+      fetchOptions?: FetchOptions;
+    }) => Promise<ApiResponse<{
+      datasource: DatasourceCapi;
+      cv?: number;
+    }, ThrowOnError_1>>;
+    list: <ThrowOnError_1 extends boolean = ThrowOnError>(options?: {
+      query?: ListData$1["query"];
+      signal?: AbortSignal;
+      throwOnError?: ThrowOnError_1 | undefined;
+      fetchOptions?: FetchOptions;
+    }) => Promise<ApiResponse<{
+      datasources: Array<DatasourceCapi>;
+      cv?: number;
+    }, ThrowOnError_1>>;
+  };
+  flushCache: () => Promise<void>;
+  get: (path: string, options?: HttpRequestOptions) => Promise<{
+    data?: unknown;
+    error?: ClientError;
+    response: Response;
+    request: Request;
+  }>;
+  interceptors: Middleware<Request, Response, unknown, ResolvedRequestOptions<"fields", boolean, string>>;
+  links: {
+    list: <ThrowOnError_1 extends boolean = ThrowOnError>(options?: {
+      query?: ListData$2["query"];
+      signal?: AbortSignal;
+      throwOnError?: ThrowOnError_1 | undefined;
+      fetchOptions?: FetchOptions;
+    }) => Promise<ApiResponse<{
+      links: {
+        [key: string]: LinkCapi;
+      };
+      cv?: number;
+    }, ThrowOnError_1>>;
+  };
+  spaces: {
+    get: <ThrowOnError_1 extends boolean = ThrowOnError>(options?: {
+      signal?: AbortSignal;
+      throwOnError?: ThrowOnError_1 | undefined;
+      fetchOptions?: FetchOptions;
+    }) => Promise<ApiResponse<{
+      space: SpaceCapi;
+    }, ThrowOnError_1>>;
+  };
+  stories: {
+    get: <ThrowOnError_1 extends boolean = ThrowOnError, const ResolveRelationsStr extends string | undefined = undefined>(identifier: string | number, options?: {
+      query?: (Omit<{
+        find_by?: "uuid";
+        version?: "published" | "draft";
+        cv?: number;
+        from_release?: string;
+        resolve_links?: "story" | "url" | "link";
+        resolve_links_level?: 1 | 2;
+        resolve_relations?: string;
+        resolve_level?: 2;
+        resolve_assets?: 0 | 1;
+        fallback_lang?: string;
+        language?: string;
+      }, "resolve_relations"> & {
+        resolve_relations?: ResolveRelationsStr | undefined;
+      }) | undefined;
+      signal?: AbortSignal;
+      throwOnError?: ThrowOnError_1 | undefined;
+      fetchOptions?: FetchOptions;
+    }) => Promise<ApiResponse<Omit<{
+      story: StoryCapi;
+      cv?: number;
+      rels?: Array<StoryCapi>;
+      links?: Array<{
+        [key: string]: unknown;
+      }>;
+      rel_uuids?: Array<string>;
+      link_uuids?: Array<string>;
+    }, "story"> & {
+      story: InlineRelations extends true ? StoryWithInlinedRelations : StoryCapi;
+    }, ThrowOnError_1>>;
+    list: <ThrowOnError_1 extends boolean = ThrowOnError, const ResolveRelationsStr_1 extends string | undefined = undefined>(options?: {
+      query?: (Omit<{
+        version?: "published" | "draft";
+        cv?: number;
+        starts_with?: string;
+        from_release?: string;
+        search_term?: string;
+        per_page?: number;
+        page?: number;
+        resolve_links?: "story" | "url" | "link";
+        resolve_links_level?: 1 | 2;
+        resolve_relations?: string;
+        resolve_level?: 2;
+        resolve_assets?: 0 | 1;
+        fallback_lang?: string;
+        language?: string;
+        content_type?: string;
+        by_slugs?: string;
+        excluding_slugs?: string;
+        by_uuids?: string;
+        by_uuids_ordered?: string;
+        excluding_ids?: string;
+        with_tag?: string;
+        sort_by?: string;
+        in_workflow_stages?: string;
+        filter_query?: string;
+        level?: number;
+        is_startpage?: 0 | 1;
+        first_published_at_gt?: string;
+        first_published_at_lt?: string;
+        published_at_gt?: string;
+        published_at_lt?: string;
+        updated_at_gt?: string;
+        updated_at_lt?: string;
+        excluding_fields?: string;
+      }, "resolve_relations"> & {
+        resolve_relations?: ResolveRelationsStr_1 | undefined;
+      }) | undefined;
+      signal?: AbortSignal;
+      throwOnError?: ThrowOnError_1 | undefined;
+      fetchOptions?: FetchOptions;
+    }) => Promise<ApiResponse<Omit<{
+      stories: Array<StoryCapi>;
+      cv?: number;
+      rels?: Array<StoryCapi>;
+      links?: Array<{
+        [key: string]: unknown;
+      }>;
+      rel_uuids?: Array<string>;
+      link_uuids?: Array<string>;
+    }, "stories"> & {
+      stories: (InlineRelations extends true ? StoryWithInlinedRelations : StoryCapi)[];
+    }, ThrowOnError_1>>;
+  };
+  tags: {
+    list: <ThrowOnError_1 extends boolean = ThrowOnError>(options?: {
+      query?: ListData$3["query"];
+      signal?: AbortSignal;
+      throwOnError?: ThrowOnError_1 | undefined;
+      fetchOptions?: FetchOptions;
+    }) => Promise<ApiResponse<{
+      tags: Array<TagCapi>;
+      cv?: number;
+    }, ThrowOnError_1>>;
+  };
+};
+/**
+ * Creates a Storyblok Content Delivery API client.
+ *
+ * Use `.withTypes<YourTypes>()` on the returned client to enable discriminated
+ * union typing on `story.content` without including any schema values in your bundle.
+ *
+ * @example
+ * ```ts
+ * import type { pageBlock, heroBlock } from './blocks';
+ *
+ * const client = createApiClient({ accessToken: 'your-token' })
+ *   .withTypes<StoryblokTypes>();
+ * ```
+ */
+declare const createApiClient: <ThrowOnError extends boolean = false, InlineRelations extends boolean = false>(config: ContentApiClientConfig<ThrowOnError, InlineRelations>) => ContentApiClient<Block, InlineRelations, ThrowOnError>;
+//#endregion
+export { ApiResponse, CacheConfig, ContentApiClient, ContentApiClientConfig, FetchOptions, HttpRequestMethod, HttpRequestOptions, RequestWithCacheOptions, ResourceDeps, createApiClient };
+//# sourceMappingURL=client.d.cts.map