/**
 * Code-based data loader types for SDK custom blocks.
 *
 * These types enable SDK sites to define loader functions that fetch
 * data from external APIs (not just CMS endpoints).
 */
import type { BlockKind } from '../types';
/**
 * Context provided to code-based data loaders.
 *
 * Contains block metadata and page context for making informed
 * data fetching decisions.
 */
export interface DataLoaderContext {
    /** Site ID from page context */
    siteId: string;
    /** Page ID from page context */
    pageId: string;
    /** Unique block instance ID */
    blockId: string;
    /** Block kind (e.g., 'custom.featured-products') */
    blockKind: BlockKind;
    /**
     * The block's CMS content.
     * Use this to access field values for parameterizing API calls.
     */
    content: Record<string, unknown>;
    /** Whether fetching preview/draft content */
    previewStage: 'published' | 'preview';
    /**
     * URL search parameters from the page request.
     * Use for pagination, filtering, or sorting based on URL params.
     *
     * Always defined (defaults to empty object if not provided to loadPage).
     * This allows loaders to safely access properties without null checks.
     *
     * @example
     * ```typescript
     * const page = parseInt(searchParams?.page as string || '1', 10);
     * const limit = parseInt(content.postsPerPage as string || '12', 10);
     * const offset = (page - 1) * limit;
     * ```
     */
    searchParams: Record<string, string | string[] | undefined>;
}
/**
 * A code-based data loader function.
 *
 * Receives context about the block and returns fetched data.
 * Runs server-side during `loadPage()`.
 *
 * @example
 * ```typescript
 * const productsLoader: DataLoaderFn = async (ctx) => {
 *   const categoryId = ctx.content.categoryId;
 *   const response = await fetch(`https://api.shop.com/products?category=${categoryId}`);
 *   return response.json();
 * };
 * ```
 */
export type DataLoaderFn = (context: DataLoaderContext) => Promise<unknown>;
/**
 * Map of loader key to loader function for a block kind.
 *
 * Keys become the property names in the `data` prop passed to the component.
 */
export type BlockLoaderMap = Record<string, DataLoaderFn>;
/**
 * Registry of code-based data loaders.
 *
 * Keys are block kinds (e.g., 'custom.featured-products').
 * Values are maps of loader keys to loader functions.
 *
 * @example
 * ```typescript
 * const dataLoaderOverrides: DataLoaderOverrides = {
 *   'custom.featured-products': {
 *     products: async (ctx) => {
 *       return fetchProducts(ctx.content.categoryId);
 *     },
 *   },
 *   'custom.instagram-feed': {
 *     posts: async (ctx) => {
 *       return fetchInstagramPosts(ctx.content.accessToken);
 *     },
 *   },
 * };
 * ```
 */
export type DataLoaderOverrides = Record<string, BlockLoaderMap>;
