@stoneforge/quarry 1.13.0 → 1.14.0

package/dist/external-sync/providers/notion/notion-api.js

@@ -0,0 +1,492 @@
+/**
+ * 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
+ */
+// ============================================================================
+// Error Types
+// ============================================================================
+/**
+ * Typed error for Notion API failures.
+ * Wraps fetch errors with status code, Notion error code, and message.
+ */
+export class NotionApiError extends Error {
+    /** HTTP status code from Notion's response */
+    status;
+    /** Notion-specific error code (e.g., "validation_error", "object_not_found") */
+    code;
+    /** Parsed error body from Notion (if available) */
+    responseBody;
+    constructor(message, status, code = 'unknown', responseBody = null, cause) {
+        super(message);
+        this.name = 'NotionApiError';
+        this.status = status;
+        this.code = code;
+        this.responseBody = responseBody;
+        this.cause = cause;
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, NotionApiError);
+        }
+    }
+    /**
+     * Whether this error is due to rate limiting (429 Too Many Requests).
+     */
+    get isRateLimited() {
+        return this.status === 429;
+    }
+    /**
+     * Whether this error is transient and can be retried.
+     * Includes rate limiting (429) and server errors (502, 503, 504).
+     */
+    get isRetryable() {
+        return this.status === 429 || this.status === 502 || this.status === 503 || this.status === 504;
+    }
+    /**
+     * Whether this error is due to authentication failure.
+     */
+    get isAuthError() {
+        return this.status === 401;
+    }
+    /**
+     * Whether this error is a not-found response.
+     */
+    get isNotFound() {
+        return this.status === 404 || this.code === 'object_not_found';
+    }
+    /**
+     * Whether this is a validation error.
+     */
+    get isValidationError() {
+        return this.status === 400 || this.code === 'validation_error';
+    }
+    /**
+     * Returns a JSON-serializable representation of the error.
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            status: this.status,
+            code: this.code,
+            responseBody: this.responseBody,
+        };
+    }
+}
+/**
+ * Type guard for NotionApiError.
+ */
+export function isNotionApiError(error) {
+    return error instanceof NotionApiError;
+}
+// ============================================================================
+// Constants
+// ============================================================================
+/** Notion API base URL */
+const NOTION_API_BASE = 'https://api.notion.com/v1';
+/** Default Notion API version */
+const DEFAULT_NOTION_VERSION = '2022-06-28';
+/** Default maximum retry count for retryable responses (429, 502, 503, 504) */
+const DEFAULT_MAX_RETRIES = 3;
+/** Default Retry-After fallback if the header is missing (in seconds) */
+const DEFAULT_RETRY_AFTER_SECONDS = 1;
+/** Maximum number of blocks per Notion API request (POST /pages or PATCH /blocks/{id}/children) */
+const NOTION_BLOCK_BATCH_SIZE = 100;
+/** Number of concurrent block delete requests (kept under Notion's 3 req/s rate limit with headroom) */
+const CONCURRENT_BLOCK_DELETES = 8;
+// ============================================================================
+// Client Implementation
+// ============================================================================
+/**
+ * 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 class NotionApiClient {
+    token;
+    notionVersion;
+    maxRetries;
+    warnOnRateLimit;
+    /** Rate limit state tracked from 429 responses */
+    rateLimitState = {
+        wasRateLimited: false,
+        lastRetryAfterSeconds: null,
+        totalRateLimitHits: 0,
+    };
+    constructor(options) {
+        if (!options.token) {
+            throw new Error('Notion API token is required');
+        }
+        this.token = options.token;
+        this.notionVersion = options.notionVersion ?? DEFAULT_NOTION_VERSION;
+        this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+        this.warnOnRateLimit = options.warnOnRateLimit ?? true;
+    }
+    /**
+     * Returns the current rate limit state.
+     */
+    getRateLimitState() {
+        return { ...this.rateLimitState };
+    }
+    // --------------------------------------------------------------------------
+    // Public API Methods
+    // --------------------------------------------------------------------------
+    /**
+     * Retrieve a page by ID.
+     *
+     * GET /pages/{page_id}
+     *
+     * @see https://developers.notion.com/reference/retrieve-a-page
+     */
+    async getPage(pageId) {
+        return this.request('GET', `/pages/${pageId}`);
+    }
+    /**
+     * 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
+     */
+    async getDatabase(databaseId) {
+        return this.request('GET', `/databases/${databaseId}`);
+    }
+    /**
+     * 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
+     */
+    async updateDatabase(databaseId, updates) {
+        return this.request('PATCH', `/databases/${databaseId}`, updates);
+    }
+    /**
+     * 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
+     */
+    async getBlocks(blockId) {
+        const allBlocks = [];
+        let cursor;
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            const params = new URLSearchParams({ page_size: '100' });
+            if (cursor) {
+                params.set('start_cursor', cursor);
+            }
+            const response = await this.request('GET', `/blocks/${blockId}/children?${params.toString()}`);
+            allBlocks.push(...response.results);
+            if (!response.has_more || !response.next_cursor) {
+                break;
+            }
+            cursor = response.next_cursor;
+        }
+        return allBlocks;
+    }
+    /**
+     * Create a new page in a database or as a child of another page.
+     *
+     * POST /pages
+     *
+     * @see https://developers.notion.com/reference/post-page
+     */
+    async createPage(databaseId, properties, children) {
+        const body = {
+            parent: { database_id: databaseId },
+            properties,
+            ...(children && children.length > 0 ? { children } : {}),
+        };
+        return this.request('POST', '/pages', body);
+    }
+    /**
+     * Update page properties.
+     *
+     * PATCH /pages/{page_id}
+     *
+     * @see https://developers.notion.com/reference/patch-page
+     */
+    async updatePage(pageId, properties) {
+        const body = { properties };
+        return this.request('PATCH', `/pages/${pageId}`, body);
+    }
+    /**
+     * 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
+     */
+    async updatePageContent(pageId, blocks) {
+        // Step 1: Get existing blocks and delete them concurrently in batches
+        // Filter out archived blocks — Notion rejects DELETE on archived blocks with:
+        // "Can't edit block that is archived. You must unarchive the block before editing."
+        const existingBlocks = await this.getBlocks(pageId);
+        const deletableBlocks = existingBlocks.filter(block => !block.archived);
+        for (let i = 0; i < deletableBlocks.length; i += CONCURRENT_BLOCK_DELETES) {
+            const batch = deletableBlocks.slice(i, i + CONCURRENT_BLOCK_DELETES);
+            await Promise.all(batch.map(block => this.request('DELETE', `/blocks/${block.id}`)));
+        }
+        // Step 2: Append new blocks in batches of 100
+        if (blocks.length === 0) {
+            return [];
+        }
+        const allResults = [];
+        for (let i = 0; i < blocks.length; i += NOTION_BLOCK_BATCH_SIZE) {
+            const batch = blocks.slice(i, i + NOTION_BLOCK_BATCH_SIZE);
+            const response = await this.request('PATCH', `/blocks/${pageId}/children`, { children: batch });
+            allResults.push(...response.results);
+        }
+        return allResults;
+    }
+    /**
+     * 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
+     */
+    async appendBlocks(blockId, blocks) {
+        if (blocks.length === 0) {
+            return [];
+        }
+        const allResults = [];
+        for (let i = 0; i < blocks.length; i += NOTION_BLOCK_BATCH_SIZE) {
+            const batch = blocks.slice(i, i + NOTION_BLOCK_BATCH_SIZE);
+            const response = await this.request('PATCH', `/blocks/${blockId}/children`, { children: batch });
+            allResults.push(...response.results);
+        }
+        return allResults;
+    }
+    /**
+     * 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
+     */
+    async queryDatabase(databaseId, filter, cursor) {
+        const body = {
+            page_size: 100,
+        };
+        if (filter) {
+            body.filter = filter;
+        }
+        if (cursor) {
+            body.start_cursor = cursor;
+        }
+        return this.request('POST', `/databases/${databaseId}/query`, body);
+    }
+    /**
+     * 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.
+     */
+    async queryDatabaseAll(databaseId, filter) {
+        const allPages = [];
+        let cursor;
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            const response = await this.queryDatabase(databaseId, filter, cursor);
+            allPages.push(...response.results);
+            if (!response.has_more || !response.next_cursor) {
+                break;
+            }
+            cursor = response.next_cursor;
+        }
+        return allPages;
+    }
+    // --------------------------------------------------------------------------
+    // Internal: HTTP Request Handling
+    // --------------------------------------------------------------------------
+    /**
+     * 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, ...)
+     */
+    async request(method, path, body) {
+        let lastError;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            try {
+                return await this.executeRequest(method, path, body);
+            }
+            catch (err) {
+                if (err instanceof NotionApiError && err.isRetryable && attempt < this.maxRetries) {
+                    let retryDelay;
+                    if (err.isRateLimited) {
+                        // 429: Use Retry-After header (existing behavior)
+                        retryDelay = (this.rateLimitState.lastRetryAfterSeconds ?? DEFAULT_RETRY_AFTER_SECONDS) * 1000;
+                    }
+                    else {
+                        // 502/503/504: Use exponential backoff starting at 1s
+                        retryDelay = DEFAULT_RETRY_AFTER_SECONDS * 1000 * Math.pow(2, attempt);
+                    }
+                    if (this.warnOnRateLimit) {
+                        const reason = err.isRateLimited
+                            ? 'Rate limited'
+                            : `Server error (${err.status})`;
+                        console.warn(`[NotionApiClient] ${reason} on ${method} ${path}. ` +
+                            `Retrying in ${retryDelay / 1000}s (attempt ${attempt + 1}/${this.maxRetries}).`);
+                    }
+                    await sleep(retryDelay);
+                    lastError = err;
+                    continue;
+                }
+                throw err;
+            }
+        }
+        // Should not reach here, but just in case
+        throw lastError ?? new NotionApiError('Max retries exceeded', 429, 'rate_limited');
+    }
+    /**
+     * Executes a single HTTP request to the Notion API (no retry logic).
+     */
+    async executeRequest(method, path, body) {
+        const url = `${NOTION_API_BASE}${path}`;
+        const headers = {
+            Authorization: `Bearer ${this.token}`,
+            'Notion-Version': this.notionVersion,
+        };
+        if (body !== undefined) {
+            headers['Content-Type'] = 'application/json';
+        }
+        let response;
+        try {
+            response = await fetch(url, {
+                method,
+                headers,
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+            });
+        }
+        catch (err) {
+            throw new NotionApiError(`Network error requesting ${method} ${path}: ${err instanceof Error ? err.message : String(err)}`, 0, 'network_error', null, err instanceof Error ? err : undefined);
+        }
+        if (!response.ok) {
+            await this.handleErrorResponse(response, method, path);
+        }
+        // DELETE responses may have no body (204 No Content)
+        if (response.status === 204 || response.headers.get('content-length') === '0') {
+            return undefined;
+        }
+        return (await response.json());
+    }
+    // --------------------------------------------------------------------------
+    // Internal: Error Handling
+    // --------------------------------------------------------------------------
+    /**
+     * Handles non-OK responses by throwing a NotionApiError.
+     */
+    async handleErrorResponse(response, method, path) {
+        let responseBody = null;
+        let errorMessage;
+        let errorCode = 'unknown';
+        try {
+            responseBody = (await response.json());
+            errorMessage = responseBody.message ?? `Notion API error: ${response.status}`;
+            errorCode = responseBody.code ?? 'unknown';
+        }
+        catch {
+            errorMessage = `Notion API error: ${response.status} ${response.statusText}`;
+        }
+        // Enrich rate limit error with Retry-After info
+        if (response.status === 429) {
+            const retryAfter = response.headers.get('Retry-After');
+            if (retryAfter) {
+                errorMessage = `Rate limited. Retry after ${retryAfter}s. ${errorMessage}`;
+            }
+            // Track the rate limit hit
+            const retryAfterSeconds = retryAfter
+                ? parseInt(retryAfter, 10)
+                : DEFAULT_RETRY_AFTER_SECONDS;
+            this.rateLimitState = {
+                wasRateLimited: true,
+                lastRetryAfterSeconds: isNaN(retryAfterSeconds)
+                    ? DEFAULT_RETRY_AFTER_SECONDS
+                    : retryAfterSeconds,
+                totalRateLimitHits: this.rateLimitState.totalRateLimitHits + 1,
+            };
+        }
+        throw new NotionApiError(`${method} ${path} failed: ${errorMessage}`, response.status, errorCode, responseBody);
+    }
+}
+// ============================================================================
+// Utility Functions
+// ============================================================================
+/**
+ * Parses the Retry-After value from a NotionApiError's response body or falls back to default.
+ */
+function parseRetryAfterFromError(err) {
+    // The Retry-After header is already parsed into the error message;
+    // try to extract it. This is a best-effort parse.
+    const match = err.message.match(/Retry after (\d+)s/);
+    if (match) {
+        const seconds = parseInt(match[1], 10);
+        if (!isNaN(seconds) && seconds > 0) {
+            return seconds;
+        }
+    }
+    return err.responseBody?.status === 429
+        ? DEFAULT_RETRY_AFTER_SECONDS
+        : DEFAULT_RETRY_AFTER_SECONDS;
+}
+/**
+ * Promise-based sleep utility.
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// Export utility functions and constants for testing
+export { sleep, parseRetryAfterFromError, NOTION_BLOCK_BATCH_SIZE, CONCURRENT_BLOCK_DELETES };
+//# sourceMappingURL=notion-api.js.map

package/dist/external-sync/providers/notion/notion-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notion-api.js","sourceRoot":"","sources":["../../../../src/external-sync/providers/notion/notion-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA6CH,+EAA+E;AAC/E,cAAc;AACd,+EAA+E;AAE/E;;;GAGG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IACvC,8CAA8C;IACrC,MAAM,CAAS;IACxB,gFAAgF;IACvE,IAAI,CAAS;IACtB,mDAAmD;IAC1C,YAAY,CAA6B;IAElD,YACE,OAAe,EACf,MAAc,EACd,OAAe,SAAS,EACxB,eAA2C,IAAI,EAC/C,KAAa;QAEb,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QAEnB,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC5B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;IAED;;OAEG;IACH,IAAI,aAAa;QACf,OAAO,IAAI,CAAC,MAAM,KAAK,GAAG,CAAC;IAC7B,CAAC;IAED;;;OAGG;IACH,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,MAAM,KAAK,GAAG,IAAI,IAAI,CAAC,MAAM,KAAK,GAAG,IAAI,IAAI,CAAC,MAAM,KAAK,GAAG,IAAI,IAAI,CAAC,MAAM,KAAK,GAAG,CAAC;IAClG,CAAC;IAED;;OAEG;IACH,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,MAAM,KAAK,GAAG,CAAC;IAC7B,CAAC;IAED;;OAEG;IACH,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,MAAM,KAAK,GAAG,IAAI,IAAI,CAAC,IAAI,KAAK,kBAAkB,CAAC;IACjE,CAAC;IAED;;OAEG;IACH,IAAI,iBAAiB;QACnB,OAAO,IAAI,CAAC,MAAM,KAAK,GAAG,IAAI,IAAI,CAAC,IAAI,KAAK,kBAAkB,CAAC;IACjE,CAAC;IAED;;OAEG;IACH,MAAM;QAOJ,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,YAAY,EAAE,IAAI,CAAC,YAAY;SAChC,CAAC;IACJ,CAAC;CACF;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,OAAO,KAAK,YAAY,cAAc,CAAC;AACzC,CAAC;AAED,+EAA+E;AAC/E,YAAY;AACZ,+EAA+E;AAE/E,0BAA0B;AAC1B,MAAM,eAAe,GAAG,2BAA2B,CAAC;AAEpD,iCAAiC;AACjC,MAAM,sBAAsB,GAAG,YAAY,CAAC;AAE5C,+EAA+E;AAC/E,MAAM,mBAAmB,GAAG,CAAC,CAAC;AAE9B,yEAAyE;AACzE,MAAM,2BAA2B,GAAG,CAAC,CAAC;AAEtC,mGAAmG;AACnG,MAAM,uBAAuB,GAAG,GAAG,CAAC;AAEpC,wGAAwG;AACxG,MAAM,wBAAwB,GAAG,CAAC,CAAC;AAEnC,+EAA+E;AAC/E,wBAAwB;AACxB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,OAAO,eAAe;IACT,KAAK,CAAS;IACd,aAAa,CAAS;IACtB,UAAU,CAAS;IACnB,eAAe,CAAU;IAE1C,kDAAkD;IAC1C,cAAc,GAAmB;QACvC,cAAc,EAAE,KAAK;QACrB,qBAAqB,EAAE,IAAI;QAC3B,kBAAkB,EAAE,CAAC;KACtB,CAAC;IAEF,YAAY,OAA+B;QACzC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;QAClD,CAAC;QAED,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC3B,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,sBAAsB,CAAC;QACrE,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,mBAAmB,CAAC;QAC5D,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC,eAAe,IAAI,IAAI,CAAC;IACzD,CAAC;IAED;;OAEG;IACH,iBAAiB;QACf,OAAO,EAAE,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;IACpC,CAAC;IAED,6EAA6E;IAC7E,qBAAqB;IACrB,6EAA6E;IAE7E;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,CAAC,MAAc;QAC1B,OAAO,IAAI,CAAC,OAAO,CAAa,KAAK,EAAE,UAAU,MAAM,EAAE,CAAC,CAAC;IAC7D,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,WAAW,CAAC,UAAkB;QAClC,OAAO,IAAI,CAAC,OAAO,CAAiB,KAAK,EAAE,cAAc,UAAU,EAAE,CAAC,CAAC;IACzE,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,cAAc,CAClB,UAAkB,EAClB,OAAkC;QAElC,OAAO,IAAI,CAAC,OAAO,CAAiB,OAAO,EAAE,cAAc,UAAU,EAAE,EAAE,OAAO,CAAC,CAAC;IACpF,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,SAAS,CAAC,OAAe;QAC7B,MAAM,SAAS,GAAkB,EAAE,CAAC;QACpC,IAAI,MAA0B,CAAC;QAE/B,iDAAiD;QACjD,OAAO,IAAI,EAAE,CAAC;YACZ,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;YACzD,IAAI,MAAM,EAAE,CAAC;gBACX,MAAM,CAAC,GAAG,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;YACrC,CAAC;YAED,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CACjC,KAAK,EACL,WAAW,OAAO,aAAa,MAAM,CAAC,QAAQ,EAAE,EAAE,CACnD,CAAC;YAEF,SAAS,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;YAEpC,IAAI,CAAC,QAAQ,CAAC,QAAQ,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;gBAChD,MAAM;YACR,CAAC;YAED,MAAM,GAAG,QAAQ,CAAC,WAAW,CAAC;QAChC,CAAC;QAED,OAAO,SAAS,CAAC;IACnB,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,UAAU,CACd,UAAkB,EAClB,UAAmC,EACnC,QAAsC;QAEtC,MAAM,IAAI,GAA0B;YAClC,MAAM,EAAE,EAAE,WAAW,EAAE,UAAU,EAAE;YACnC,UAAU;YACV,GAAG,CAAC,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACzD,CAAC;QAEF,OAAO,IAAI,CAAC,OAAO,CAAa,MAAM,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC;IAC1D,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,UAAU,CACd,MAAc,EACd,UAAmC;QAEnC,MAAM,IAAI,GAA0B,EAAE,UAAU,EAAE,CAAC;QACnD,OAAO,IAAI,CAAC,OAAO,CAAa,OAAO,EAAE,UAAU,MAAM,EAAE,EAAE,IAAI,CAAC,CAAC;IACrE,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,iBAAiB,CACrB,MAAc,EACd,MAAmC;QAEnC,sEAAsE;QACtE,8EAA8E;QAC9E,oFAAoF;QACpF,MAAM,cAAc,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QACpD,MAAM,eAAe,GAAG,cAAc,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAExE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,eAAe,CAAC,MAAM,EAAE,CAAC,IAAI,wBAAwB,EAAE,CAAC;YAC1E,MAAM,KAAK,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,wBAAwB,CAAC,CAAC;YACrE,MAAM,OAAO,CAAC,GAAG,CACf,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAO,QAAQ,EAAE,WAAW,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,CACxE,CAAC;QACJ,CAAC;QAED,8CAA8C;QAC9C,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,MAAM,UAAU,GAAkB,EAAE,CAAC;QAErC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,uBAAuB,EAAE,CAAC;YAChE,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,uBAAuB,CAAC,CAAC;YAC3D,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CACjC,OAAO,EACP,WAAW,MAAM,WAAW,EAC5B,EAAE,QAAQ,EAAE,KAAK,EAAE,CACpB,CAAC;YACF,UAAU,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;QACvC,CAAC;QAED,OAAO,UAAU,CAAC;IACpB,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,YAAY,CAChB,OAAe,EACf,MAAmC;QAEnC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,MAAM,UAAU,GAAkB,EAAE,CAAC;QAErC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,uBAAuB,EAAE,CAAC;YAChE,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,uBAAuB,CAAC,CAAC;YAC3D,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CACjC,OAAO,EACP,WAAW,OAAO,WAAW,EAC7B,EAAE,QAAQ,EAAE,KAAK,EAAE,CACpB,CAAC;YACF,UAAU,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;QACvC,CAAC;QAED,OAAO,UAAU,CAAC;IACpB,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,aAAa,CACjB,UAAkB,EAClB,MAAgC,EAChC,MAAe;QAEf,MAAM,IAAI,GAA4B;YACpC,SAAS,EAAE,GAAG;SACf,CAAC;QAEF,IAAI,MAAM,EAAE,CAAC;YACX,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACvB,CAAC;QAED,IAAI,MAAM,EAAE,CAAC;YACX,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC;QAC7B,CAAC;QAED,OAAO,IAAI,CAAC,OAAO,CACjB,MAAM,EACN,cAAc,UAAU,QAAQ,EAChC,IAAI,CACL,CAAC;IACJ,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,gBAAgB,CACpB,UAAkB,EAClB,MAAgC;QAEhC,MAAM,QAAQ,GAAiB,EAAE,CAAC;QAClC,IAAI,MAA0B,CAAC;QAE/B,iDAAiD;QACjD,OAAO,IAAI,EAAE,CAAC;YACZ,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;YACtE,QAAQ,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;YAEnC,IAAI,CAAC,QAAQ,CAAC,QAAQ,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;gBAChD,MAAM;YACR,CAAC;YAED,MAAM,GAAG,QAAQ,CAAC,WAAW,CAAC;QAChC,CAAC;QAED,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,6EAA6E;IAC7E,kCAAkC;IAClC,6EAA6E;IAE7E;;;;;;OAMG;IACK,KAAK,CAAC,OAAO,CAAI,MAAc,EAAE,IAAY,EAAE,IAAc;QACnE,IAAI,SAAqC,CAAC;QAE1C,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,IAAI,CAAC,UAAU,EAAE,OAAO,EAAE,EAAE,CAAC;YAC5D,IAAI,CAAC;gBACH,OAAO,MAAM,IAAI,CAAC,cAAc,CAAI,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;YAC1D,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,GAAG,YAAY,cAAc,IAAI,GAAG,CAAC,WAAW,IAAI,OAAO,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;oBAClF,IAAI,UAAkB,CAAC;oBAEvB,IAAI,GAAG,CAAC,aAAa,EAAE,CAAC;wBACtB,kDAAkD;wBAClD,UAAU,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,qBAAqB,IAAI,2BAA2B,CAAC,GAAG,IAAI,CAAC;oBACjG,CAAC;yBAAM,CAAC;wBACN,sDAAsD;wBACtD,UAAU,GAAG,2BAA2B,GAAG,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;oBACzE,CAAC;oBAED,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;wBACzB,MAAM,MAAM,GAAG,GAAG,CAAC,aAAa;4BAC9B,CAAC,CAAC,cAAc;4BAChB,CAAC,CAAC,iBAAiB,GAAG,CAAC,MAAM,GAAG,CAAC;wBACnC,OAAO,CAAC,IAAI,CACV,qBAAqB,MAAM,OAAO,MAAM,IAAI,IAAI,IAAI;4BAClD,eAAe,UAAU,GAAG,IAAI,cAAc,OAAO,GAAG,CAAC,IAAI,IAAI,CAAC,UAAU,IAAI,CACnF,CAAC;oBACJ,CAAC;oBAED,MAAM,KAAK,CAAC,UAAU,CAAC,CAAC;oBACxB,SAAS,GAAG,GAAG,CAAC;oBAChB,SAAS;gBACX,CAAC;gBAED,MAAM,GAAG,CAAC;YACZ,CAAC;QACH,CAAC;QAED,0CAA0C;QAC1C,MAAM,SAAS,IAAI,IAAI,cAAc,CAAC,sBAAsB,EAAE,GAAG,EAAE,cAAc,CAAC,CAAC;IACrF,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,cAAc,CAAI,MAAc,EAAE,IAAY,EAAE,IAAc;QAC1E,MAAM,GAAG,GAAG,GAAG,eAAe,GAAG,IAAI,EAAE,CAAC;QAExC,MAAM,OAAO,GAA2B;YACtC,aAAa,EAAE,UAAU,IAAI,CAAC,KAAK,EAAE;YACrC,gBAAgB,EAAE,IAAI,CAAC,aAAa;SACrC,CAAC;QAEF,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,OAAO,CAAC,cAAc,CAAC,GAAG,kBAAkB,CAAC;QAC/C,CAAC;QAED,IAAI,QAAkB,CAAC;QACvB,IAAI,CAAC;YACH,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;gBAC1B,MAAM;gBACN,OAAO;gBACP,IAAI,EAAE,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;aAC5D,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,cAAc,CACtB,4BAA4B,MAAM,IAAI,IAAI,KAAK,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EACjG,CAAC,EACD,eAAe,EACf,IAAI,EACJ,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CACvC,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,CAAC,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;QACzD,CAAC;QAED,qDAAqD;QACrD,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,IAAI,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,KAAK,GAAG,EAAE,CAAC;YAC9E,OAAO,SAAc,CAAC;QACxB,CAAC;QAED,OAAO,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAM,CAAC;IACtC,CAAC;IAED,6EAA6E;IAC7E,2BAA2B;IAC3B,6EAA6E;IAE7E;;OAEG;IACK,KAAK,CAAC,mBAAmB,CAC/B,QAAkB,EAClB,MAAc,EACd,IAAY;QAEZ,IAAI,YAAY,GAA+B,IAAI,CAAC;QACpD,IAAI,YAAoB,CAAC;QACzB,IAAI,SAAS,GAAG,SAAS,CAAC;QAE1B,IAAI,CAAC;YACH,YAAY,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAwB,CAAC;YAC9D,YAAY,GAAG,YAAY,CAAC,OAAO,IAAI,qBAAqB,QAAQ,CAAC,MAAM,EAAE,CAAC;YAC9E,SAAS,GAAG,YAAY,CAAC,IAAI,IAAI,SAAS,CAAC;QAC7C,CAAC;QAAC,MAAM,CAAC;YACP,YAAY,GAAG,qBAAqB,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC;QAC/E,CAAC;QAED,gDAAgD;QAChD,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YAC5B,MAAM,UAAU,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;YACvD,IAAI,UAAU,EAAE,CAAC;gBACf,YAAY,GAAG,6BAA6B,UAAU,MAAM,YAAY,EAAE,CAAC;YAC7E,CAAC;YAED,2BAA2B;YAC3B,MAAM,iBAAiB,GAAG,UAAU;gBAClC,CAAC,CAAC,QAAQ,CAAC,UAAU,EAAE,EAAE,CAAC;gBAC1B,CAAC,CAAC,2BAA2B,CAAC;YAEhC,IAAI,CAAC,cAAc,GAAG;gBACpB,cAAc,EAAE,IAAI;gBACpB,qBAAqB,EAAE,KAAK,CAAC,iBAAiB,CAAC;oBAC7C,CAAC,CAAC,2BAA2B;oBAC7B,CAAC,CAAC,iBAAiB;gBACrB,kBAAkB,EAAE,IAAI,CAAC,cAAc,CAAC,kBAAkB,GAAG,CAAC;aAC/D,CAAC;QACJ,CAAC;QAED,MAAM,IAAI,cAAc,CACtB,GAAG,MAAM,IAAI,IAAI,YAAY,YAAY,EAAE,EAC3C,QAAQ,CAAC,MAAM,EACf,SAAS,EACT,YAAY,CACb,CAAC;IACJ,CAAC;CACF;AAED,+EAA+E;AAC/E,oBAAoB;AACpB,+EAA+E;AAE/E;;GAEG;AACH,SAAS,wBAAwB,CAAC,GAAmB;IACnD,mEAAmE;IACnE,kDAAkD;IAClD,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC;IACtD,IAAI,KAAK,EAAE,CAAC;QACV,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACvC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;YACnC,OAAO,OAAO,CAAC;QACjB,CAAC;IACH,CAAC;IAED,OAAO,GAAG,CAAC,YAAY,EAAE,MAAM,KAAK,GAAG;QACrC,CAAC,CAAC,2BAA2B;QAC7B,CAAC,CAAC,2BAA2B,CAAC;AAClC,CAAC;AAED;;GAEG;AACH,SAAS,KAAK,CAAC,EAAU;IACvB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED,qDAAqD;AACrD,OAAO,EAAE,KAAK,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,CAAC"}

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

@@ -0,0 +1,93 @@
+/**
+ * Notion Blocks ↔ Markdown Converter
+ *
+ * Bidirectional converter between markdown text and Notion block format.
+ * Internal module with no external dependencies.
+ *
+ * Supported conversions:
+ * - Paragraphs ↔ paragraph blocks
+ * - Headings (# ## ###) ↔ heading_1, heading_2, heading_3 blocks
+ * - Bulleted lists (- or *) ↔ bulleted_list_item blocks
+ * - Numbered lists (1. 2. 3.) ↔ numbered_list_item blocks
+ * - Code blocks (```) ↔ code blocks (with language annotation)
+ * - Blockquotes (>) ↔ quote blocks
+ * - Checkboxes (- [ ] / - [x]) ↔ to_do blocks
+ * - Rich text: **bold**, *italic*, `inline code`, [links](url)
+ */
+import type { NotionBlock, NotionRichText } from './notion-types.js';
+/**
+ * Maximum length for a single rich_text element's text.content in the Notion API.
+ * @see https://developers.notion.com/reference/block
+ */
+export declare const NOTION_MAX_TEXT_LENGTH = 2000;
+/**
+ * Maximum number of elements in a single rich_text array in the Notion API.
+ * When a block's rich_text array exceeds this limit, the block must be split
+ * into multiple blocks of the same type.
+ * @see https://developers.notion.com/reference/block
+ */
+export declare const NOTION_MAX_RICH_TEXT_ARRAY_LENGTH = 100;
+/**
+ * Split a plain text string into multiple NotionRichText elements,
+ * each with text.content at most `maxLength` characters.
+ * Splits at word boundaries when possible.
+ */
+export declare function chunkRichText(text: string, maxLength?: number): NotionRichText[];
+/**
+ * Convert markdown text to an array of Notion blocks.
+ *
+ * Parses markdown line-by-line, recognizing headings, lists, code blocks,
+ * blockquotes, checkboxes, and paragraphs. Rich text formatting (bold,
+ * italic, inline code, links) is preserved within each block.
+ */
+export declare function markdownToNotionBlocks(markdown: string): NotionBlock[];
+/**
+ * Convert Notion blocks back to a markdown string.
+ *
+ * Handles all supported block types. Unsupported block types produce
+ * a fallback `[Unsupported: {type}]` text.
+ */
+export declare function notionBlocksToMarkdown(blocks: readonly NotionBlock[]): string;
+/**
+ * Check whether a URL string is valid for use in a Notion link block.
+ * Notion only accepts absolute http: or https: URLs. Relative paths,
+ * fragment-only references (#section), workspace element IDs (el-xxxx),
+ * empty strings, and malformed URLs are all rejected.
+ */
+export declare function isValidNotionUrl(url: string): boolean;
+/**
+ * Parse inline markdown formatting into an array of NotionRichText objects.
+ *
+ * Supports:
+ * - **bold** or __bold__
+ * - *italic* or _italic_
+ * - `inline code`
+ * - [link text](url)
+ * - Combinations thereof
+ */
+export declare function parseInlineMarkdown(text: string): NotionRichText[];
+/**
+ * Convert an array of Notion rich text objects back to inline markdown.
+ */
+export declare function richTextToMarkdown(richTexts: readonly NotionRichText[]): string;
+/**
+ * The complete set of language identifiers accepted by the Notion API
+ * for code blocks. Any language not in this set will be rejected.
+ * @see https://developers.notion.com/reference/block#code
+ */
+export declare const NOTION_LANGUAGES: Set<string>;
+/**
+ * Map common code fence language aliases to their Notion-accepted equivalents.
+ * These cover short names, file extensions, and alternate spellings that
+ * markdown authors commonly use but Notion does not recognize.
+ */
+export declare const LANGUAGE_ALIASES: Record<string, string>;
+/**
+ * Map a code fence language identifier to a Notion-accepted language value.
+ *
+ * 1. If the lowercased input is already in NOTION_LANGUAGES, return it.
+ * 2. If it matches a known alias, return the mapped value.
+ * 3. Otherwise, fall back to 'plain text' (always accepted by Notion).
+ */
+export declare function mapLanguageToNotion(lang: string): string;
+//# sourceMappingURL=notion-blocks.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"notion-blocks.d.ts","sourceRoot":"","sources":["../../../../src/external-sync/providers/notion/notion-blocks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,cAAc,EAEf,MAAM,mBAAmB,CAAC;AAO3B;;;GAGG;AACH,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAE3C;;;;;GAKG;AACH,eAAO,MAAM,iCAAiC,MAAM,CAAC;AAiCrD;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,SAAS,SAAyB,GACjC,cAAc,EAAE,CAQlB;AA8GD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,EAAE,CAuHtE;AAMD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,GAAG,MAAM,CA2B7E;AAoPD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAOrD;AAMD;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,EAAE,CA2DlE;AAMD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,SAAS,cAAc,EAAE,GAAG,MAAM,CAM/E;AA4GD;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,aAa3B,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CA6BnD,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKxD"}