/**
 * Notion REST API Client
 *
 * Pure fetch-based client for Notion page and block operations.
 * Supports Bearer token authentication, rate limit handling with Retry-After,
 * automatic retry on transient server errors (502/503/504) with exponential backoff,
 * cursor-based pagination, and typed error responses.
 *
 * No external dependencies — uses only the standard fetch API.
 *
 * @see https://developers.notion.com/reference
 */
import type { NotionPage, NotionBlock, NotionBlockInput, NotionDatabaseQueryResponse, NotionErrorResponse, NotionDatabase, NotionUpdateDatabaseInput } from './notion-types.js';
/**
 * Configuration for creating a NotionApiClient.
 */
export interface NotionApiClientOptions {
    /** Notion integration token (internal integration or OAuth token) */
    token: string;
    /** Notion API version header (default: "2022-06-28") */
    notionVersion?: string;
    /** Maximum number of automatic retries on retryable responses: 429, 502, 503, 504 (default: 3) */
    maxRetries?: number;
    /** Rate limit warning threshold — log a warning after a 429 (default: true) */
    warnOnRateLimit?: boolean;
}
/**
 * Rate limit state tracked from 429 responses.
 */
export interface RateLimitState {
    /** Whether the client has been rate limited at least once */
    readonly wasRateLimited: boolean;
    /** The most recent Retry-After value in seconds (from last 429 response) */
    readonly lastRetryAfterSeconds: number | null;
    /** Total number of 429 responses received */
    readonly totalRateLimitHits: number;
}
/**
 * Typed error for Notion API failures.
 * Wraps fetch errors with status code, Notion error code, and message.
 */
export declare class NotionApiError extends Error {
    /** HTTP status code from Notion's response */
    readonly status: number;
    /** Notion-specific error code (e.g., "validation_error", "object_not_found") */
    readonly code: string;
    /** Parsed error body from Notion (if available) */
    readonly responseBody: NotionErrorResponse | null;
    constructor(message: string, status: number, code?: string, responseBody?: NotionErrorResponse | null, cause?: Error);
    /**
     * Whether this error is due to rate limiting (429 Too Many Requests).
     */
    get isRateLimited(): boolean;
    /**
     * Whether this error is transient and can be retried.
     * Includes rate limiting (429) and server errors (502, 503, 504).
     */
    get isRetryable(): boolean;
    /**
     * Whether this error is due to authentication failure.
     */
    get isAuthError(): boolean;
    /**
     * Whether this error is a not-found response.
     */
    get isNotFound(): boolean;
    /**
     * Whether this is a validation error.
     */
    get isValidationError(): boolean;
    /**
     * Returns a JSON-serializable representation of the error.
     */
    toJSON(): {
        name: string;
        message: string;
        status: number;
        code: string;
        responseBody: NotionErrorResponse | null;
    };
}
/**
 * Type guard for NotionApiError.
 */
export declare function isNotionApiError(error: unknown): error is NotionApiError;
/** Maximum number of blocks per Notion API request (POST /pages or PATCH /blocks/{id}/children) */
declare const NOTION_BLOCK_BATCH_SIZE = 100;
/** Number of concurrent block delete requests (kept under Notion's 3 req/s rate limit with headroom) */
declare const CONCURRENT_BLOCK_DELETES = 8;
/**
 * Fetch-based Notion REST API client for page and block operations.
 *
 * Features:
 * - Bearer token authentication (internal integrations or OAuth)
 * - Notion-Version header for API versioning
 * - Automatic retry on 429 (Too Many Requests) with Retry-After
 * - Automatic retry on 502/503/504 (server errors) with exponential backoff
 * - Cursor-based pagination for list endpoints
 * - Typed errors with Notion error codes
 *
 * @example
 * ```typescript
 * const client = new NotionApiClient({ token: 'ntn_...' });
 * const page = await client.getPage('page-uuid');
 * const blocks = await client.getBlocks('page-uuid');
 * ```
 */
export declare class NotionApiClient {
    private readonly token;
    private readonly notionVersion;
    private readonly maxRetries;
    private readonly warnOnRateLimit;
    /** Rate limit state tracked from 429 responses */
    private rateLimitState;
    constructor(options: NotionApiClientOptions);
    /**
     * Returns the current rate limit state.
     */
    getRateLimitState(): RateLimitState;
    /**
     * Retrieve a page by ID.
     *
     * GET /pages/{page_id}
     *
     * @see https://developers.notion.com/reference/retrieve-a-page
     */
    getPage(pageId: string): Promise<NotionPage>;
    /**
     * Retrieve a database by ID.
     *
     * GET /databases/{database_id}
     *
     * Returns the database schema including all property definitions.
     * Used for discovering the title property name and checking which
     * properties (Category, Tags) exist before creating pages.
     *
     * @see https://developers.notion.com/reference/retrieve-a-database
     */
    getDatabase(databaseId: string): Promise<NotionDatabase>;
    /**
     * Update a database schema (add or modify properties).
     *
     * PATCH /databases/{database_id}
     *
     * Used to auto-create missing properties (e.g., Category as select,
     * Tags as multi_select) when they don't exist in the database schema.
     *
     * @see https://developers.notion.com/reference/update-a-database
     */
    updateDatabase(databaseId: string, updates: NotionUpdateDatabaseInput): Promise<NotionDatabase>;
    /**
     * Retrieve all block children for a given block (or page).
     * Automatically paginates through all results.
     *
     * GET /blocks/{block_id}/children
     *
     * @see https://developers.notion.com/reference/get-block-children
     */
    getBlocks(blockId: string): Promise<NotionBlock[]>;
    /**
     * Create a new page in a database or as a child of another page.
     *
     * POST /pages
     *
     * @see https://developers.notion.com/reference/post-page
     */
    createPage(databaseId: string, properties: Record<string, unknown>, children?: readonly NotionBlockInput[]): Promise<NotionPage>;
    /**
     * Update page properties.
     *
     * PATCH /pages/{page_id}
     *
     * @see https://developers.notion.com/reference/patch-page
     */
    updatePage(pageId: string, properties: Record<string, unknown>): Promise<NotionPage>;
    /**
     * Replace all content blocks of a page.
     *
     * This is a two-step operation:
     * 1. Delete all existing top-level block children
     * 2. Append new block children in batches of 100 (Notion's per-request limit)
     *
     * CAUTION: This is not atomic. If step 2 fails, the page may have partial content.
     *
     * @see https://developers.notion.com/reference/delete-a-block
     * @see https://developers.notion.com/reference/patch-block-children
     */
    updatePageContent(pageId: string, blocks: readonly NotionBlockInput[]): Promise<NotionBlock[]>;
    /**
     * Append block children to a page or block.
     *
     * Respects Notion's 100-block-per-request limit by batching automatically.
     * Block order is preserved across batches.
     *
     * PATCH /blocks/{block_id}/children
     *
     * @param blockId - The page or block ID to append children to
     * @param blocks - The blocks to append
     * @returns All appended blocks
     *
     * @see https://developers.notion.com/reference/patch-block-children
     */
    appendBlocks(blockId: string, blocks: readonly NotionBlockInput[]): Promise<NotionBlock[]>;
    /**
     * Query a database with optional filter and cursor-based pagination.
     *
     * POST /databases/{database_id}/query
     *
     * When no cursor is provided and the result has more pages, this method
     * returns only the first page. Callers can use `next_cursor` to fetch
     * additional pages, or use `queryDatabaseAll()` to auto-paginate.
     *
     * @see https://developers.notion.com/reference/post-database-query
     */
    queryDatabase(databaseId: string, filter?: Record<string, unknown>, cursor?: string): Promise<NotionDatabaseQueryResponse>;
    /**
     * Query a database and automatically paginate through all results.
     *
     * This is a convenience wrapper around `queryDatabase()` that follows
     * `next_cursor` until all pages have been fetched.
     *
     * @param databaseId - The database to query.
     * @param filter - Optional Notion filter object.
     * @returns All pages matching the query.
     */
    queryDatabaseAll(databaseId: string, filter?: Record<string, unknown>): Promise<NotionPage[]>;
    /**
     * Performs an HTTP request to the Notion API with automatic retry on retryable errors.
     *
     * Retry strategy:
     * - 429 (rate limited): Uses Retry-After header value (existing behavior)
     * - 502/503/504 (server errors): Uses exponential backoff starting at 1s (1s, 2s, 4s, ...)
     */
    private request;
    /**
     * Executes a single HTTP request to the Notion API (no retry logic).
     */
    private executeRequest;
    /**
     * Handles non-OK responses by throwing a NotionApiError.
     */
    private handleErrorResponse;
}
/**
 * Parses the Retry-After value from a NotionApiError's response body or falls back to default.
 */
declare function parseRetryAfterFromError(err: NotionApiError): number;
/**
 * Promise-based sleep utility.
 */
declare function sleep(ms: number): Promise<void>;
export { sleep, parseRetryAfterFromError, NOTION_BLOCK_BATCH_SIZE, CONCURRENT_BLOCK_DELETES };
//# sourceMappingURL=notion-api.d.ts.map