@storyblok/api-client 0.3.1 → 1.0.0-alpha.2

package/dist/client.d.mts

@@ -0,0 +1,567 @@
+import { CdnExperiment, Datasource, DatasourceEntry, GetDatasourceByIdData, GetSpaceData, Link, LinkWithFullSlug, ListCdnExperimentsV2Data, ListDatasourceEntriesData, ListDatasourcesData, ListLinksData, ListTagsData, PublicSpace, Story, Tag } from "./generated/capi/types.gen.mjs";
+import { Middleware } from "./generated/capi/client/utils.gen.mjs";
+import { Client, RequestOptions, ResolvedRequestOptions } from "./generated/capi/client/types.gen.mjs";
+import { StoryAlternate } from "./generated/capi/_internal.gen.mjs";
+import { AssetFieldValueRoot, BlockContentRoot } from "./generated/overlay/_internal.gen.mjs";
+import { CacheProvider, CacheStrategy, CacheStrategyHandler } from "./utils/cache.mjs";
+import { ClientError } from "./error.mjs";
+import { RateLimitConfig, ThrottleManager } from "./utils/rate-limit.mjs";
+import { Block } from "./generated/types/block.mjs";
+import { StoryWithInlinedRelations, createStoriesResource } from "./resources/stories.mjs";
+import { RetryOptions } from "ky";
+import { Region } from "@storyblok/region-helper";
+
+//#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 how the `cv` (content version) query parameter is managed.
+   *
+   * - `'auto'` (default): automatically attach the tracked `cv` to
+   *   subsequent published requests for cache busting.
+   * - `'manual'`: do not attach `cv` to outgoing requests. The client still
+   *   tracks cv internally for cache invalidation (flushing when cv changes),
+   *   but the query parameter is not sent. Useful for SSR with edge caching
+   *   where stable URLs are required.
+   */
+  cv?: 'auto' | 'manual';
+  /**
+   * 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?: ListDatasourceEntriesData["query"];
+      signal?: AbortSignal;
+      throwOnError?: ThrowOnError_1 | undefined;
+      fetchOptions?: FetchOptions;
+    }) => Promise<ApiResponse<{
+      datasource_entries: Array<DatasourceEntry>;
+      cv?: number | null;
+    }, ThrowOnError_1>>;
+  };
+  datasources: {
+    get: <ThrowOnError_1 extends boolean = ThrowOnError>(id: GetDatasourceByIdData["path"]["id"], options?: {
+      query?: GetDatasourceByIdData["query"];
+      signal?: AbortSignal;
+      throwOnError?: ThrowOnError_1 | undefined;
+      fetchOptions?: FetchOptions;
+    }) => Promise<ApiResponse<{
+      datasource: Datasource;
+      cv: number | null;
+    }, ThrowOnError_1>>;
+    list: <ThrowOnError_1 extends boolean = ThrowOnError>(options?: {
+      query?: ListDatasourcesData["query"];
+      signal?: AbortSignal;
+      throwOnError?: ThrowOnError_1 | undefined;
+      fetchOptions?: FetchOptions;
+    }) => Promise<ApiResponse<{
+      datasources: Array<Datasource>;
+      cv?: number | null;
+    }, ThrowOnError_1>>;
+  };
+  experiments: {
+    list: <ThrowOnError_1 extends boolean = ThrowOnError>(options?: {
+      query?: ListCdnExperimentsV2Data["query"];
+      signal?: AbortSignal;
+      throwOnError?: ThrowOnError_1 | undefined;
+      fetchOptions?: FetchOptions;
+    }) => Promise<ApiResponse<{
+      experiments: Array<CdnExperiment>;
+      cv?: number | null;
+    }, 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?: ListLinksData["query"];
+      signal?: AbortSignal;
+      throwOnError?: ThrowOnError_1 | undefined;
+      fetchOptions?: FetchOptions;
+    }) => Promise<ApiResponse<{
+      links: {
+        [key: string]: Link;
+      };
+    }, ThrowOnError_1>>;
+  };
+  spaces: {
+    get: <ThrowOnError_1 extends boolean = ThrowOnError>(options?: {
+      query?: GetSpaceData["query"];
+      signal?: AbortSignal;
+      throwOnError?: ThrowOnError_1 | undefined;
+      fetchOptions?: FetchOptions;
+    }) => Promise<ApiResponse<{
+      space: PublicSpace;
+    }, ThrowOnError_1>>;
+  };
+  stories: {
+    get: <ThrowOnError_1 extends boolean = ThrowOnError, const ResolveRelationsStr extends string | undefined = undefined>(identifier: string, options?: {
+      query?: (Omit<{
+        find_by?: string;
+        version?: "draft" | "published";
+        resolve_links?: "story" | "url" | "link";
+        resolve_links_level?: 1 | 2;
+        resolve_relations?: string;
+        from_release?: string;
+        content_type?: string;
+        cv?: number;
+        excluding_fields?: string;
+        language?: string;
+        fallback_lang?: string;
+        resolve_assets?: number;
+        resolve_level?: 2;
+        param_with_null_char?: string;
+      }, "resolve_relations"> & {
+        resolve_relations?: ResolveRelationsStr | undefined;
+      }) | undefined;
+      signal?: AbortSignal;
+      throwOnError?: ThrowOnError_1 | undefined;
+      fetchOptions?: FetchOptions;
+    }) => Promise<ApiResponse<Omit<{
+      story: Story;
+      cv: number;
+      rels?: Array<Story>;
+      links?: Array<LinkWithFullSlug | Link | Story>;
+      rel_uuids?: Array<string>;
+      link_uuids?: Array<string>;
+    }, "story"> & {
+      story: InlineRelations extends true ? StoryWithInlinedRelations : {
+        path: string | null;
+        id: number;
+        name: string;
+        created_at: string;
+        updated_at?: string | null | undefined;
+        version?: "draft" | "published" | undefined;
+        is_startpage: boolean;
+        published_at: string | null;
+        alternates: Array<StoryAlternate>;
+        uuid: string;
+        slug: string;
+        full_slug: string;
+        default_full_slug: string | null;
+        sort_by_date: string | null;
+        position: number;
+        tag_list: Array<string>;
+        parent_id: number;
+        meta_data: {
+          [key: string]: unknown;
+        } | {
+          [key: string]: unknown;
+        } | null;
+        group_id: string;
+        first_published_at: string | null;
+        release_id?: number | null | undefined;
+        lang: string;
+        translated_slugs: {
+          path: string;
+          name: string | null;
+          lang: string;
+          published: string | null;
+        }[] | {
+          path: string;
+          name: string | null;
+          lang: string;
+          published: string | null;
+        }[] | null;
+        content: {
+          [x: string]: string | number | boolean | string[] | AssetFieldValueRoot[] | {
+            type: "doc";
+            content?: Array<{
+              [key: string]: unknown;
+            }> | undefined;
+          } | {
+            fieldtype: "asset";
+            id: number | null;
+            alt: string | null;
+            name?: string | undefined;
+            focus?: string | null | undefined;
+            title?: string | null | undefined;
+            source?: string | null | undefined;
+            filename: string;
+            copyright?: string | null | undefined;
+            meta_data?: {
+              [key: string]: unknown;
+            } | undefined;
+            is_external_url?: boolean | undefined;
+          } | {
+            fieldtype: "multilink";
+            id: string;
+            url: string;
+            linktype: "story" | "url" | "email" | "asset";
+            cached_url: string;
+            anchor?: string | null | undefined;
+            target?: "_self" | "_blank" | null | undefined;
+          } | BlockContentRoot[] | {
+            thead: Array<{
+              _uid: string;
+              component: "_table_head";
+              value?: string;
+            }>;
+            tbody: Array<{
+              _uid: string;
+              component: "_table_row";
+              body?: Array<{
+                _uid: string;
+                component: "_table_col";
+                value?: string;
+              }>;
+            }>;
+          } | {
+            [x: string]: unknown;
+            plugin: string;
+            _uid?: string | undefined;
+          } | null | undefined;
+          _uid: string;
+          component: string;
+          _editable?: string | undefined;
+        };
+      };
+    }, ThrowOnError_1>>;
+    list: <ThrowOnError_1 extends boolean = ThrowOnError, const ResolveRelationsStr_1 extends string | undefined = undefined>(options?: {
+      query?: (Omit<{
+        version?: "draft" | "published";
+        cv?: number;
+        starts_with?: string;
+        search_term?: string;
+        sort_by?: string;
+        per_page?: number;
+        page?: number;
+        by_slugs?: string;
+        excluding_slugs?: string;
+        published_at_gt?: string;
+        published_at_gte?: string;
+        published_at_lt?: string;
+        published_at_lte?: string;
+        first_published_at_gt?: string;
+        first_published_at_gte?: string;
+        first_published_at_lt?: string;
+        first_published_at_lte?: string;
+        updated_at_gt?: string;
+        updated_at_gte?: string;
+        updated_at_lt?: string;
+        updated_at_lte?: string;
+        in_workflow_stages?: string;
+        content_type?: string;
+        level?: number;
+        resolve_relations?: string;
+        excluding_ids?: string;
+        by_uuids?: string;
+        by_uuids_ordered?: string;
+        by_ids?: string;
+        with_tag?: string;
+        is_startpage?: 0 | 1;
+        resolve_links?: "story" | "url" | "link";
+        resolve_links_level?: 1 | 2;
+        from_release?: string;
+        fallback_lang?: string;
+        language?: string;
+        filter_query?: {
+          __or?: Array<{
+            [key: string]: {
+              [key: string]: string;
+            };
+          }>;
+          [key: string]: {
+            in?: string;
+            not_in?: string;
+            like?: string;
+            not_like?: string;
+            exists?: string;
+            in_array?: Array<string> | string;
+            all_in_array?: Array<string> | string;
+            gt_date?: string;
+            lt_date?: string;
+            gt_int?: number;
+            lt_int?: number;
+            gt_float?: number;
+            lt_float?: number;
+            is?: "empty" | "not_empty" | "empty_array" | "not_empty_array" | "null" | "not_null" | "true" | "false";
+          } | Array<{
+            [key: string]: {
+              [key: string]: string;
+            };
+          }> | undefined;
+        };
+        excluding_fields?: string;
+        resolve_assets?: 1;
+        resolve_level?: 2;
+        only_variants?: "true";
+        non_existing_sort_by?: string;
+        non_existing_updated_at_gt?: string;
+        param_with_null_char?: string;
+      }, "resolve_relations"> & {
+        resolve_relations?: ResolveRelationsStr_1 | undefined;
+      }) | undefined;
+      signal?: AbortSignal;
+      throwOnError?: ThrowOnError_1 | undefined;
+      fetchOptions?: FetchOptions;
+    }) => Promise<ApiResponse<Omit<{
+      stories: Array<Story>;
+      cv: number;
+      rels?: Array<Story>;
+      links?: Array<LinkWithFullSlug | Link | Story>;
+      rel_uuids?: Array<string>;
+      link_uuids?: Array<string>;
+    }, "stories"> & {
+      stories: (InlineRelations extends true ? StoryWithInlinedRelations : {
+        path: string | null;
+        id: number;
+        name: string;
+        created_at: string;
+        updated_at?: string | null | undefined;
+        version?: "draft" | "published" | undefined;
+        is_startpage: boolean;
+        published_at: string | null;
+        alternates: Array<StoryAlternate>;
+        uuid: string;
+        slug: string;
+        full_slug: string;
+        default_full_slug: string | null;
+        sort_by_date: string | null;
+        position: number;
+        tag_list: Array<string>;
+        parent_id: number;
+        meta_data: {
+          [key: string]: unknown;
+        } | {
+          [key: string]: unknown;
+        } | null;
+        group_id: string;
+        first_published_at: string | null;
+        release_id?: number | null | undefined;
+        lang: string;
+        translated_slugs: {
+          path: string;
+          name: string | null;
+          lang: string;
+          published: string | null;
+        }[] | {
+          path: string;
+          name: string | null;
+          lang: string;
+          published: string | null;
+        }[] | null;
+        content: {
+          [x: string]: string | number | boolean | string[] | AssetFieldValueRoot[] | {
+            type: "doc";
+            content?: Array<{
+              [key: string]: unknown;
+            }> | undefined;
+          } | {
+            fieldtype: "asset";
+            id: number | null;
+            alt: string | null;
+            name?: string | undefined;
+            focus?: string | null | undefined;
+            title?: string | null | undefined;
+            source?: string | null | undefined;
+            filename: string;
+            copyright?: string | null | undefined;
+            meta_data?: {
+              [key: string]: unknown;
+            } | undefined;
+            is_external_url?: boolean | undefined;
+          } | {
+            fieldtype: "multilink";
+            id: string;
+            url: string;
+            linktype: "story" | "url" | "email" | "asset";
+            cached_url: string;
+            anchor?: string | null | undefined;
+            target?: "_self" | "_blank" | null | undefined;
+          } | BlockContentRoot[] | {
+            thead: Array<{
+              _uid: string;
+              component: "_table_head";
+              value?: string;
+            }>;
+            tbody: Array<{
+              _uid: string;
+              component: "_table_row";
+              body?: Array<{
+                _uid: string;
+                component: "_table_col";
+                value?: string;
+              }>;
+            }>;
+          } | {
+            [x: string]: unknown;
+            plugin: string;
+            _uid?: string | undefined;
+          } | null | undefined;
+          _uid: string;
+          component: string;
+          _editable?: string | undefined;
+        };
+      })[];
+    }, ThrowOnError_1>>;
+  };
+  tags: {
+    list: <ThrowOnError_1 extends boolean = ThrowOnError>(options?: {
+      query?: ListTagsData["query"];
+      signal?: AbortSignal;
+      throwOnError?: ThrowOnError_1 | undefined;
+      fetchOptions?: FetchOptions;
+    }) => Promise<ApiResponse<{
+      tags: Array<Tag>;
+    }, 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.mts.map