hacker-news-reel/dist/api.d.ts

A lightweight, typed client for the Hacker News API with validation using Zod

import type { ClientOptions, HackerNewsCommentTree, HackerNewsId, HackerNewsIdList, HackerNewsItem, HackerNewsUpdates, HackerNewsUser, HackerNewsUsername } from './types';
import type { ClientHooks } from './hooks';
/**
 * Creates a client with configurable fetch implementation
 * @param options Client options including optional fetch function, limiter configuration, and AbortSignal
 * @returns Object containing all HackerNews API methods
 *
 * Example with AbortSignal:
 * ```ts
 * // Create an AbortController to cancel requests when needed
 * const controller = new AbortController();
 * const client = createClient({ signal: controller.signal });
 *
 * // Later, to cancel all in-flight requests:
 * controller.abort();
 * ```
 *
 * Example with custom rate limiting:
 * ```ts
 * // Create a client with custom rate limiting
 * const client = createClient({
 *   limiter: {
 *     maxConcurrent: 10,       // Allow up to 10 concurrent requests
 *     minTime: 100,            // Minimum 100ms between requests
 *     reservoir: 50,           // Allow bursts up to 50 requests
 *     reservoirRefreshAmount: 10,  // Refill 10 tokens at a time
 *     reservoirRefreshInterval: 1000  // Refill every 1 second
 *   }
 * });
 * ```
 */
export declare const createClient: (options?: ClientOptions) => {
    getItem: (id: HackerNewsId) => Promise<HackerNewsItem>;
    getItems: (ids: HackerNewsIdList) => Promise<HackerNewsItem[]>;
    getUser: (username: HackerNewsUsername) => Promise<HackerNewsUser>;
    getMaxItemId: () => Promise<HackerNewsId>;
    getUpdates: () => Promise<HackerNewsUpdates>;
    getItemWithComments: (itemId: HackerNewsId, options?: {
        /** Maximum depth of comments to fetch (default: 25) */
        maxDepth?: number;
        /** Current depth in the recursion (used internally) */
        currentDepth?: number;
        /** Maximum number of concurrent requests per level (default: 5) */
        concurrency?: number;
    }) => Promise<HackerNewsCommentTree>;
    getTopStories: () => Promise<HackerNewsIdList>;
    getNewStories: () => Promise<HackerNewsIdList>;
    getBestStories: () => Promise<HackerNewsIdList>;
    getAskStories: () => Promise<HackerNewsIdList>;
    getShowStories: () => Promise<HackerNewsIdList>;
    getJobStories: () => Promise<HackerNewsIdList>;
    invalidateItemCache: (id: HackerNewsId) => void;
    invalidateUserCache: (username: HackerNewsUsername) => void;
    invalidateListCaches: () => void;
    clearAllCaches: () => void;
    /**
     * Register hooks with the client
     * @param hooks Object with beforeFetch, afterFetch, and/or onError functions
     * @returns The client instance for chaining
     *
     * Example:
     * ```ts
     * client.use({
     *   beforeFetch: (url, opts) => {
     *     console.log(`Fetching ${url}`);
     *     return { url, options: opts };
     *   },
     *   afterFetch: (response) => {
     *     console.log(`Received ${response.status} from ${response.url}`);
     *     return response;
     *   },
     *   onError: (err) => {
     *     console.error(`Error in fetch: ${err.message}`);
     *   }
     * });
     * ```
     */
    use: (hooks: ClientHooks) => /*elided*/ any;
    /**
     * Clear all registered hooks
     * @returns The client instance for chaining
     */
    clearHooks: () => /*elided*/ any;
};
export declare const getItem: (id: HackerNewsId) => Promise<HackerNewsItem>, getItems: (ids: HackerNewsIdList) => Promise<HackerNewsItem[]>, getUser: (username: HackerNewsUsername) => Promise<HackerNewsUser>, getMaxItemId: () => Promise<HackerNewsId>, getUpdates: () => Promise<HackerNewsUpdates>, getItemWithComments: (itemId: HackerNewsId, options?: {
    /** Maximum depth of comments to fetch (default: 25) */
    maxDepth?: number;
    /** Current depth in the recursion (used internally) */
    currentDepth?: number;
    /** Maximum number of concurrent requests per level (default: 5) */
    concurrency?: number;
}) => Promise<HackerNewsCommentTree>, getTopStories: () => Promise<HackerNewsIdList>, getNewStories: () => Promise<HackerNewsIdList>, getBestStories: () => Promise<HackerNewsIdList>, getAskStories: () => Promise<HackerNewsIdList>, getShowStories: () => Promise<HackerNewsIdList>, getJobStories: () => Promise<HackerNewsIdList>, invalidateItemCache: (id: HackerNewsId) => void, invalidateUserCache: (username: HackerNewsUsername) => void, invalidateListCaches: () => void, clearAllCaches: () => void;