@ai-growth/nextjs/dist/utils/content-fetching.d.ts

Seamlessly integrate Sanity CMS with Next.js applications for automated blog routing and rendering

/**
 * @fileoverview Content fetching utilities for Sanity CMS
 *
 * This module provides type-safe functions for fetching content from Sanity
 * using GROQ queries. All functions leverage the Sanity client factory and
 * TypeScript interfaces for maximum type safety and developer experience.
 *
 * @example
 * ```typescript
 * import { getDocumentBySlug, getDocumentsByType } from '@ai-growth/nextjs/utils';
 *
 * // Fetch a single post by slug
 * const post = await getDocumentBySlug<SanityPost>('post', 'my-blog-post');
 *
 * // Fetch all published posts
 * const posts = await getDocumentsByType<SanityPost>('post', {
 *   filter: { status: 'published' },
 *   orderBy: 'publishedAt desc'
 * });
 * ```
 */
import { type RetryConfig } from './retry';
import type { SanityDocument, SanityQueryResult, SanityQueryParams } from '../types/sanity';
/**
 * Options for fetching single documents
 */
export interface ContentFetchOptions {
    /** GROQ projection to limit returned fields */
    projection?: string;
    /** Whether to include draft documents */
    includeDrafts?: boolean;
    /** Additional GROQ filter conditions */
    additionalFilter?: string;
    /** Query parameters for GROQ variables */
    params?: SanityQueryParams;
    /** Retry configuration for this request */
    retry?: Partial<RetryConfig>;
}
/**
 * Options for fetching collections of documents
 */
export interface ContentListOptions extends ContentFetchOptions {
    /** Number of documents to return (default: 10) */
    limit?: number;
    /** Number of documents to skip */
    offset?: number;
    /** GROQ order expression (e.g., 'publishedAt desc', '_createdAt asc') */
    orderBy?: string;
    /** Filter conditions for common fields */
    filter?: Partial<{
        /** Filter by document status */
        status: string;
        /** Filter by featured flag */
        featured: boolean;
        /** Filter by publication date range */
        publishedAfter: string;
        publishedBefore: string;
        /** Custom filter object */
        [key: string]: unknown;
    }>;
    /** Whether to include total count in response */
    includeTotal?: boolean;
}
/**
 * Options for custom GROQ queries
 */
export interface CustomQueryOptions {
    /** Whether to include total count for list queries */
    includeTotal?: boolean;
}
/**
 * Fetch a single document by its slug
 *
 * @template T The expected document type
 * @param type Document type (e.g., 'post', 'page')
 * @param slug Document slug
 * @param options Fetch options including projection and filters
 * @returns Promise resolving to the document or null if not found
 *
 * @example
 * ```typescript
 * const post = await getDocumentBySlug<SanityPost>('post', 'my-blog-post', {
 *   projection: '_id, title, slug, publishedAt, author->{name, image}'
 * });
 * ```
 */
export declare function getDocumentBySlug<T extends SanityDocument = SanityDocument>(type: string, slug: string, options?: ContentFetchOptions): Promise<T | null>;
/**
 * Fetch a single document by its ID
 *
 * @template T The expected document type
 * @param id Document ID
 * @param options Fetch options including projection
 * @returns Promise resolving to the document or null if not found
 *
 * @example
 * ```typescript
 * const post = await getDocumentById<SanityPost>('post-123', {
 *   projection: '_id, title, body, author->{name}'
 * });
 * ```
 */
export declare function getDocumentById<T extends SanityDocument = SanityDocument>(id: string, options?: ContentFetchOptions): Promise<T | null>;
/**
 * Fetch multiple documents by type
 *
 * @template T The expected document type
 * @param type Document type (e.g., 'post', 'page')
 * @param options List options including pagination, sorting, and filtering
 * @returns Promise resolving to query result with documents and metadata
 *
 * @example
 * ```typescript
 * const result = await getDocumentsByType<SanityPost>('post', {
 *   filter: { status: 'published', featured: true },
 *   orderBy: 'publishedAt desc',
 *   limit: 10,
 *   projection: '_id, title, slug, publishedAt, mainImage',
 *   includeTotal: true
 * });
 * ```
 */
export declare function getDocumentsByType<T extends SanityDocument = SanityDocument>(type: string, options?: ContentListOptions): Promise<SanityQueryResult<T>>;
/**
 * Execute a custom GROQ query
 *
 * @template T The expected result type
 * @param query GROQ query string
 * @param params Query parameters
 * @param options Fetch options
 * @returns Promise resolving to the query result
 *
 * @example
 * ```typescript
 * const posts = await getDocuments<SanityPost[]>(
 *   `*[_type == "post" && references($authorId)]{
 *     _id, title, slug, publishedAt
 *   }`,
 *   { authorId: 'author-123' }
 * );
 * ```
 */
export declare function getDocuments<T = unknown>(query: string, params?: SanityQueryParams, _options?: CustomQueryOptions): Promise<T>;
/**
 * Fetch published documents of a specific type
 *
 * @template T The expected document type
 * @param type Document type
 * @param options List options (status filter will be overridden to 'published')
 * @returns Promise resolving to published documents
 */
export declare function getPublishedDocuments<T extends SanityDocument = SanityDocument>(type: string, options?: Omit<ContentListOptions<T>, 'filter'> & {
    filter?: Omit<ContentListOptions<T>['filter'], 'status'>;
}): Promise<SanityQueryResult<T>>;
/**
 * Fetch featured documents of a specific type
 *
 * @template T The expected document type
 * @param type Document type
 * @param options List options (featured filter will be overridden to true)
 * @returns Promise resolving to featured documents
 */
export declare function getFeaturedDocuments<T extends SanityDocument = SanityDocument>(type: string, options?: Omit<ContentListOptions<T>, 'filter'> & {
    filter?: Omit<ContentListOptions<T>['filter'], 'featured'>;
}): Promise<SanityQueryResult<T>>;
/**
 * Fetch recent documents of a specific type
 *
 * @template T The expected document type
 * @param type Document type
 * @param options List options (orderBy will be overridden to '_createdAt desc')
 * @returns Promise resolving to recent documents
 */
export declare function getRecentDocuments<T extends SanityDocument = SanityDocument>(type: string, options?: Omit<ContentListOptions<T>, 'orderBy'>): Promise<SanityQueryResult<T>>;
/**
 * Search documents by text content
 *
 * @template T The expected document type
 * @param type Document type
 * @param searchTerm Search term
 * @param searchFields Fields to search in (default: ['title'])
 * @param options Additional list options
 * @returns Promise resolving to matching documents
 *
 * @example
 * ```typescript
 * const posts = await searchDocuments<SanityPost>(
 *   'post',
 *   'javascript',
 *   ['title', 'excerpt'],
 *   { limit: 5 }
 * );
 * ```
 */
export declare function searchDocuments<T extends SanityDocument = SanityDocument>(type: string, searchTerm: string, searchFields?: string[], options?: ContentListOptions<T>): Promise<SanityQueryResult<T>>;
/**
 * Check if a document exists by slug
 *
 * @param type Document type
 * @param slug Document slug
 * @param options Fetch options
 * @returns Promise resolving to boolean indicating existence
 */
export declare function documentExistsBySlug(type: string, slug: string, options?: ContentFetchOptions): Promise<boolean>;
/**
 * Check if a document exists by ID
 *
 * @param id Document ID
 * @param options Fetch options
 * @returns Promise resolving to boolean indicating existence
 */
export declare function documentExistsById(id: string, options?: ContentFetchOptions): Promise<boolean>;
/**
 * Get document count by type
 *
 * @param type Document type
 * @param options Filter options
 * @returns Promise resolving to document count
 */
export declare function getDocumentCount(type: string, options?: Pick<ContentListOptions, 'filter' | 'includeDrafts' | 'additionalFilter'>): Promise<number>;
//# sourceMappingURL=content-fetching.d.ts.map