@stoneforge/quarry 1.13.0 → 1.14.0

package/dist/external-sync/providers/notion/notion-api.d.ts

@@ -0,0 +1,253 @@
+/**
+ * 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

package/dist/external-sync/providers/notion/notion-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notion-api.d.ts","sourceRoot":"","sources":["../../../../src/external-sync/providers/notion/notion-api.ts"],"names":[],"mappings":"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"}