@stoneforge/quarry 1.12.0 → 1.14.0

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

@@ -0,0 +1,57 @@
+/**
+ * Notion External Provider
+ *
+ * Implements the ExternalProvider interface for Notion.
+ * Handles connection testing via the Notion API and provides a
+ * DocumentSyncAdapter for bidirectional page synchronization.
+ *
+ * The provider uses a NotionApiClient for all API interactions.
+ * Connection testing calls GET /users/me to verify the token.
+ *
+ * Configuration:
+ * - Token: set via `sf external-sync config set-token notion ntn_xxxxx`
+ * - Project (database ID): set via `sf external-sync config set-project notion <database-id>`
+ *
+ * @example
+ * ```typescript
+ * const provider = createNotionProvider({ token: 'ntn_...' });
+ * const registry = createProviderRegistry();
+ * registry.register(provider);
+ *
+ * // Test connection
+ * const connected = await provider.testConnection({ provider: 'notion', token: 'ntn_...' });
+ *
+ * // Get document adapter
+ * const adapter = provider.getDocumentAdapter();
+ * const page = await adapter.getPage('database-id', 'page-id');
+ * ```
+ */
+import type { ExternalProvider } from '@stoneforge/core';
+/**
+ * Options for creating a Notion provider.
+ */
+export interface CreateNotionProviderOptions {
+    /** Notion integration token */
+    token: string;
+}
+/**
+ * Create a configured Notion provider.
+ *
+ * The provider is fully configured with the given token and ready
+ * for registration in the provider registry.
+ *
+ * @param options - Configuration including the integration token
+ * @returns A configured Notion ExternalProvider
+ */
+export declare function createNotionProvider(options: CreateNotionProviderOptions): ExternalProvider;
+/**
+ * Create a placeholder Notion provider for registry registration.
+ *
+ * Similar to the GitHub and Linear placeholders — registers the provider
+ * shape so the registry knows Notion is available. Connection testing
+ * always returns false. All adapter methods throw descriptive errors.
+ *
+ * @returns A placeholder Notion ExternalProvider
+ */
+export declare function createNotionPlaceholderProvider(): ExternalProvider;
+//# sourceMappingURL=notion-provider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"notion-provider.d.ts","sourceRoot":"","sources":["../../../../src/external-sync/providers/notion/notion-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAMjB,MAAM,kBAAkB,CAAC;AA4I1B;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,2BAA2B,GACnC,gBAAgB,CAGlB;AAED;;;;;;;;GAQG;AACH,wBAAgB,+BAA+B,IAAI,gBAAgB,CAElE"}

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

@@ -0,0 +1,159 @@
+/**
+ * Notion External Provider
+ *
+ * Implements the ExternalProvider interface for Notion.
+ * Handles connection testing via the Notion API and provides a
+ * DocumentSyncAdapter for bidirectional page synchronization.
+ *
+ * The provider uses a NotionApiClient for all API interactions.
+ * Connection testing calls GET /users/me to verify the token.
+ *
+ * Configuration:
+ * - Token: set via `sf external-sync config set-token notion ntn_xxxxx`
+ * - Project (database ID): set via `sf external-sync config set-project notion <database-id>`
+ *
+ * @example
+ * ```typescript
+ * const provider = createNotionProvider({ token: 'ntn_...' });
+ * const registry = createProviderRegistry();
+ * registry.register(provider);
+ *
+ * // Test connection
+ * const connected = await provider.testConnection({ provider: 'notion', token: 'ntn_...' });
+ *
+ * // Get document adapter
+ * const adapter = provider.getDocumentAdapter();
+ * const page = await adapter.getPage('database-id', 'page-id');
+ * ```
+ */
+import { NotionApiClient } from './notion-api.js';
+import { NotionDocumentAdapter } from './notion-document-adapter.js';
+// ============================================================================
+// Constants
+// ============================================================================
+/** Notion API base URL for connection testing */
+const NOTION_API_BASE = 'https://api.notion.com/v1';
+/** Default Notion API version header */
+const DEFAULT_NOTION_VERSION = '2022-06-28';
+// ============================================================================
+// NotionProvider
+// ============================================================================
+/**
+ * ExternalProvider implementation for Notion.
+ *
+ * Supports document sync only. Connection testing calls GET /users/me
+ * to verify the integration token is valid.
+ */
+class NotionProvider {
+    name = 'notion';
+    displayName = 'Notion';
+    supportedAdapters = ['document'];
+    documentAdapter;
+    constructor(api) {
+        this.documentAdapter = new NotionDocumentAdapter(api);
+    }
+    /**
+     * Test whether the Notion connection is valid.
+     *
+     * Calls GET /users/me to verify the integration token has valid
+     * permissions. Uses a raw fetch call (like the GitHub provider)
+     * since the API client doesn't expose a user endpoint.
+     *
+     * @param config - Provider configuration with token to test
+     * @returns true if the connection is valid, false otherwise
+     */
+    async testConnection(config) {
+        if (!config.token) {
+            return false;
+        }
+        try {
+            const response = await fetch(`${NOTION_API_BASE}/users/me`, {
+                method: 'GET',
+                headers: {
+                    Authorization: `Bearer ${config.token}`,
+                    'Notion-Version': DEFAULT_NOTION_VERSION,
+                },
+            });
+            return response.ok;
+        }
+        catch {
+            // Network errors, DNS failures, etc.
+            return false;
+        }
+    }
+    /**
+     * Returns the Notion document sync adapter.
+     *
+     * @returns NotionDocumentAdapter for Notion page sync
+     */
+    getDocumentAdapter() {
+        return this.documentAdapter;
+    }
+}
+// ============================================================================
+// Placeholder Provider
+// ============================================================================
+const PLACEHOLDER_MESSAGE = 'Notion document sync adapter is not configured. Set a token via `sf external-sync config set-token notion <token>` to enable sync.';
+/**
+ * Placeholder DocumentSyncAdapter for Notion.
+ * All methods throw to indicate they are not yet configured.
+ */
+class NotionPlaceholderDocumentAdapter {
+    async getPage(_project, _externalId) {
+        throw new Error(PLACEHOLDER_MESSAGE);
+    }
+    async listPagesSince(_project, _since) {
+        throw new Error(PLACEHOLDER_MESSAGE);
+    }
+    async createPage(_project, _page) {
+        throw new Error(PLACEHOLDER_MESSAGE);
+    }
+    async updatePage(_project, _externalId, _updates) {
+        throw new Error(PLACEHOLDER_MESSAGE);
+    }
+}
+/**
+ * Placeholder Notion ExternalProvider.
+ *
+ * Declares Notion as a known provider that supports document sync.
+ * Connection testing always returns false (not configured).
+ * The actual provider is created with createNotionProvider() when configured.
+ */
+class NotionPlaceholderProvider {
+    name = 'notion';
+    displayName = 'Notion';
+    supportedAdapters = ['document'];
+    documentAdapter = new NotionPlaceholderDocumentAdapter();
+    async testConnection(_config) {
+        return false;
+    }
+    getDocumentAdapter() {
+        return this.documentAdapter;
+    }
+}
+/**
+ * Create a configured Notion provider.
+ *
+ * The provider is fully configured with the given token and ready
+ * for registration in the provider registry.
+ *
+ * @param options - Configuration including the integration token
+ * @returns A configured Notion ExternalProvider
+ */
+export function createNotionProvider(options) {
+    const api = new NotionApiClient({ token: options.token });
+    return new NotionProvider(api);
+}
+/**
+ * Create a placeholder Notion provider for registry registration.
+ *
+ * Similar to the GitHub and Linear placeholders — registers the provider
+ * shape so the registry knows Notion is available. Connection testing
+ * always returns false. All adapter methods throw descriptive errors.
+ *
+ * @returns A placeholder Notion ExternalProvider
+ */
+export function createNotionPlaceholderProvider() {
+    return new NotionPlaceholderProvider();
+}
+//# sourceMappingURL=notion-provider.js.map

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

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

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

@@ -0,0 +1,388 @@
+/**
+ * Notion API Type Definitions
+ *
+ * Type definitions for Notion's REST API responses and block/rich-text objects.
+ * These types represent the subset of Notion's schema used by the document sync
+ * provider and the blocks ↔ markdown converter.
+ *
+ * Only fields needed for document synchronization are included — this is not a
+ * comprehensive representation of the full Notion API.
+ *
+ * @see https://developers.notion.com/reference
+ */
+/**
+ * Rich text annotations (formatting) applied to a text span.
+ */
+export interface NotionAnnotations {
+    readonly bold: boolean;
+    readonly italic: boolean;
+    readonly strikethrough: boolean;
+    readonly underline: boolean;
+    readonly code: boolean;
+    readonly color: string;
+}
+/**
+ * Default annotations — no formatting applied.
+ */
+export declare const DEFAULT_ANNOTATIONS: NotionAnnotations;
+/**
+ * Notion rich text object — the atomic unit of formatted text.
+ *
+ * Rich text can be of type "text", "mention", or "equation".
+ * We only model "text" in detail since that's what we produce during sync.
+ */
+export interface NotionRichText {
+    /** The type of rich text object */
+    readonly type: 'text' | 'mention' | 'equation';
+    /** Plain text content without formatting */
+    readonly plain_text: string;
+    /** Text-specific content (present when type === 'text') */
+    readonly text?: {
+        /** The text content */
+        readonly content: string;
+        /** Optional link */
+        readonly link: {
+            readonly url: string;
+        } | null;
+    };
+    /** Inline formatting annotations */
+    readonly annotations: NotionAnnotations;
+    /** Optional URL for the rich text (e.g. links) */
+    readonly href: string | null;
+}
+/**
+ * Notion page property value.
+ *
+ * Properties are typed fields on a page. Each property has a type discriminator
+ * and corresponding value field. We model the subset needed for document sync.
+ */
+export interface NotionProperty {
+    /** Unique property ID */
+    readonly id: string;
+    /** Property type discriminator */
+    readonly type: string;
+    /** Title property value (array of rich text) */
+    readonly title?: readonly NotionRichText[];
+    /** Rich text property value */
+    readonly rich_text?: readonly NotionRichText[];
+    /** Select property value */
+    readonly select?: {
+        readonly id: string;
+        readonly name: string;
+        readonly color: string;
+    } | null;
+    /** Multi-select property value */
+    readonly multi_select?: readonly {
+        readonly id: string;
+        readonly name: string;
+        readonly color: string;
+    }[];
+    /** Checkbox property value */
+    readonly checkbox?: boolean;
+    /** URL property value */
+    readonly url?: string | null;
+    /** Date property value */
+    readonly date?: {
+        readonly start: string;
+        readonly end: string | null;
+    } | null;
+    /** Number property value */
+    readonly number?: number | null;
+    /** Last edited time property value (ISO 8601) */
+    readonly last_edited_time?: string;
+    /** Created time property value (ISO 8601) */
+    readonly created_time?: string;
+}
+/**
+ * Notion block object — the content building block of a page.
+ *
+ * Every block has a type discriminator and a corresponding type-specific object.
+ * We model the most common block types used in document content.
+ *
+ * Metadata fields (id, has_children, etc.) are optional because they are present
+ * on blocks read from the API but absent on blocks created locally (e.g. by the
+ * markdown → Notion converter).
+ */
+export interface NotionBlock {
+    /** Unique block ID (UUID) — present on API responses */
+    readonly id?: string;
+    /** Block type discriminator */
+    readonly type: string;
+    /** Whether this block has nested children — present on API responses */
+    readonly has_children?: boolean;
+    /** Creation timestamp (ISO 8601) — present on API responses */
+    readonly created_time?: string;
+    /** Last edit timestamp (ISO 8601) — present on API responses */
+    readonly last_edited_time?: string;
+    /** Whether this block has been archived (deleted) — present on API responses */
+    readonly archived?: boolean;
+    readonly paragraph?: {
+        readonly rich_text: readonly NotionRichText[];
+        readonly color?: string;
+    };
+    readonly heading_1?: {
+        readonly rich_text: readonly NotionRichText[];
+        readonly color?: string;
+        readonly is_toggleable?: boolean;
+    };
+    readonly heading_2?: {
+        readonly rich_text: readonly NotionRichText[];
+        readonly color?: string;
+        readonly is_toggleable?: boolean;
+    };
+    readonly heading_3?: {
+        readonly rich_text: readonly NotionRichText[];
+        readonly color?: string;
+        readonly is_toggleable?: boolean;
+    };
+    readonly bulleted_list_item?: {
+        readonly rich_text: readonly NotionRichText[];
+        readonly color?: string;
+    };
+    readonly numbered_list_item?: {
+        readonly rich_text: readonly NotionRichText[];
+        readonly color?: string;
+    };
+    readonly to_do?: {
+        readonly rich_text: readonly NotionRichText[];
+        readonly checked: boolean;
+        readonly color?: string;
+    };
+    readonly toggle?: {
+        readonly rich_text: readonly NotionRichText[];
+    };
+    readonly code?: {
+        readonly rich_text: readonly NotionRichText[];
+        readonly caption?: readonly NotionRichText[];
+        readonly language: string;
+    };
+    readonly quote?: {
+        readonly rich_text: readonly NotionRichText[];
+        readonly color?: string;
+    };
+    readonly callout?: {
+        readonly rich_text: readonly NotionRichText[];
+        readonly icon?: unknown;
+    };
+    readonly divider?: Record<string, never>;
+    readonly table_of_contents?: Record<string, never>;
+    readonly child_page?: {
+        readonly title: string;
+    };
+    readonly child_database?: {
+        readonly title: string;
+    };
+}
+/**
+ * Block types that we support for markdown ↔ Notion conversion.
+ */
+export declare const SUPPORTED_BLOCK_TYPES: readonly ["paragraph", "heading_1", "heading_2", "heading_3", "bulleted_list_item", "numbered_list_item", "code", "quote", "to_do"];
+export type SupportedBlockType = (typeof SUPPORTED_BLOCK_TYPES)[number];
+/**
+ * Check if a block type is supported for conversion.
+ */
+export declare function isSupportedBlockType(type: string): type is SupportedBlockType;
+/**
+ * Notion page object.
+ *
+ * Pages are the primary content container in Notion. Each page has properties
+ * (metadata fields) and block children (the page content).
+ */
+export interface NotionPage {
+    /** Unique page ID (UUID) */
+    readonly id: string;
+    /** Object type (always "page") */
+    readonly object: 'page';
+    /** Creation timestamp (ISO 8601) */
+    readonly created_time: string;
+    /** Last edit timestamp (ISO 8601) */
+    readonly last_edited_time: string;
+    /** Whether the page has been archived (moved to trash) */
+    readonly archived: boolean;
+    /** URL to view the page in Notion */
+    readonly url: string;
+    /** Public URL if the page is published (null otherwise) */
+    readonly public_url: string | null;
+    /** Page properties keyed by property name */
+    readonly properties: Record<string, NotionProperty>;
+    /** Parent reference */
+    readonly parent: {
+        readonly type: 'database_id';
+        readonly database_id: string;
+    } | {
+        readonly type: 'page_id';
+        readonly page_id: string;
+    } | {
+        readonly type: 'workspace';
+        readonly workspace: true;
+    };
+}
+/**
+ * Response from querying a Notion database (POST /databases/{id}/query).
+ *
+ * Uses cursor-based pagination with `has_more` / `next_cursor`.
+ */
+export interface NotionDatabaseQueryResponse {
+    /** Object type (always "list") */
+    readonly object: 'list';
+    /** Array of page objects matching the query */
+    readonly results: readonly NotionPage[];
+    /** Whether there are more results beyond this page */
+    readonly has_more: boolean;
+    /** Cursor for the next page of results (null if no more) */
+    readonly next_cursor: string | null;
+    /** Type of items in the results */
+    readonly type: 'page_or_database';
+}
+/**
+ * Paginated response for block children (GET /blocks/{id}/children).
+ */
+export interface NotionBlockChildrenResponse {
+    /** Object type (always "list") */
+    readonly object: 'list';
+    /** Array of block objects */
+    readonly results: readonly NotionBlock[];
+    /** Whether there are more results beyond this page */
+    readonly has_more: boolean;
+    /** Cursor for the next page of results (null if no more) */
+    readonly next_cursor: string | null;
+    /** Type of items in the results */
+    readonly type: 'block';
+}
+/**
+ * Input for creating a new block.
+ *
+ * When creating blocks, we provide the type and corresponding content object.
+ * This is a simplified version — only the block types we produce are included.
+ */
+export interface NotionBlockInput {
+    /** Block type */
+    readonly type: string;
+    /** Object key matching the type (e.g., 'paragraph', 'heading_1', etc.) */
+    readonly [key: string]: unknown;
+}
+/**
+ * Input for creating a page in a database.
+ */
+export interface NotionCreatePageInput {
+    /** Parent database or page reference */
+    readonly parent: {
+        readonly database_id: string;
+    } | {
+        readonly page_id: string;
+    };
+    /** Page properties */
+    readonly properties: Record<string, unknown>;
+    /** Optional block children (page content) */
+    readonly children?: readonly NotionBlockInput[];
+}
+/**
+ * Input for updating page properties.
+ */
+export interface NotionUpdatePageInput {
+    /** Properties to update */
+    readonly properties?: Record<string, unknown>;
+    /** Whether to archive (trash) the page */
+    readonly archived?: boolean;
+}
+/**
+ * Schema definition for a database property.
+ *
+ * This represents the database-level schema (from GET /databases/{id}),
+ * not the page-level property values. Each property has a type and
+ * type-specific configuration (e.g., select options, formula expression).
+ */
+export interface NotionDatabaseProperty {
+    /** Unique property ID */
+    readonly id: string;
+    /** Property type (e.g., 'title', 'select', 'multi_select', 'rich_text') */
+    readonly type: string;
+    /** Property name */
+    readonly name: string;
+    /** Select options (present when type === 'select') */
+    readonly select?: {
+        readonly options: readonly {
+            readonly id: string;
+            readonly name: string;
+            readonly color: string;
+        }[];
+    };
+    /** Multi-select options (present when type === 'multi_select') */
+    readonly multi_select?: {
+        readonly options: readonly {
+            readonly id: string;
+            readonly name: string;
+            readonly color: string;
+        }[];
+    };
+}
+/**
+ * Notion database object.
+ *
+ * Represents a database schema retrieved via GET /databases/{id}.
+ * Contains the database properties (schema definitions) which describe
+ * the structure of pages within the database.
+ *
+ * @see https://developers.notion.com/reference/retrieve-a-database
+ */
+export interface NotionDatabase {
+    /** Unique database ID (UUID) */
+    readonly id: string;
+    /** Object type (always "database") */
+    readonly object: 'database';
+    /** Creation timestamp (ISO 8601) */
+    readonly created_time: string;
+    /** Last edit timestamp (ISO 8601) */
+    readonly last_edited_time: string;
+    /** Database title */
+    readonly title: readonly NotionRichText[];
+    /** Database properties schema, keyed by property name */
+    readonly properties: Record<string, NotionDatabaseProperty>;
+    /** Whether the database has been archived */
+    readonly archived: boolean;
+    /** URL to view the database in Notion */
+    readonly url: string;
+}
+/**
+ * Input for updating a database schema.
+ *
+ * Used with PATCH /databases/{id} to add or modify properties.
+ *
+ * @see https://developers.notion.com/reference/update-a-database
+ */
+export interface NotionUpdateDatabaseInput {
+    /** Properties to add or update in the database schema */
+    readonly properties?: Record<string, unknown>;
+}
+/**
+ * Cached database schema information used by the document adapter.
+ *
+ * Contains the discovered property names for title, category, and tags,
+ * so the adapter doesn't need to query the database schema on every operation.
+ */
+export interface NotionDatabaseSchema {
+    /** The name of the title property (every database has exactly one) */
+    readonly titlePropertyName: string;
+    /** Whether a 'Category' select property exists in the database */
+    readonly hasCategoryProperty: boolean;
+    /** Whether a 'Tags' multi_select property exists in the database */
+    readonly hasTagsProperty: boolean;
+    /** Whether a 'Library' select property exists in the database */
+    readonly hasLibraryProperty: boolean;
+}
+/**
+ * Notion API error response body.
+ *
+ * @see https://developers.notion.com/reference/errors
+ */
+export interface NotionErrorResponse {
+    /** Object type (always "error") */
+    readonly object: 'error';
+    /** HTTP status code */
+    readonly status: number;
+    /** Notion-specific error code (e.g., "validation_error", "object_not_found") */
+    readonly code: string;
+    /** Human-readable error message */
+    readonly message: string;
+}
+//# sourceMappingURL=notion-types.d.ts.map

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

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

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

@@ -0,0 +1,47 @@
+/**
+ * Notion API Type Definitions
+ *
+ * Type definitions for Notion's REST API responses and block/rich-text objects.
+ * These types represent the subset of Notion's schema used by the document sync
+ * provider and the blocks ↔ markdown converter.
+ *
+ * Only fields needed for document synchronization are included — this is not a
+ * comprehensive representation of the full Notion API.
+ *
+ * @see https://developers.notion.com/reference
+ */
+/**
+ * Default annotations — no formatting applied.
+ */
+export const DEFAULT_ANNOTATIONS = {
+    bold: false,
+    italic: false,
+    strikethrough: false,
+    underline: false,
+    code: false,
+    color: 'default',
+};
+// ============================================================================
+// Supported Block Type Constants
+// ============================================================================
+/**
+ * Block types that we support for markdown ↔ Notion conversion.
+ */
+export const SUPPORTED_BLOCK_TYPES = [
+    'paragraph',
+    'heading_1',
+    'heading_2',
+    'heading_3',
+    'bulleted_list_item',
+    'numbered_list_item',
+    'code',
+    'quote',
+    'to_do',
+];
+/**
+ * Check if a block type is supported for conversion.
+ */
+export function isSupportedBlockType(type) {
+    return SUPPORTED_BLOCK_TYPES.includes(type);
+}
+//# sourceMappingURL=notion-types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"notion-types.js","sourceRoot":"","sources":["../../../../src/external-sync/providers/notion/notion-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAkBH;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAsB;IACpD,IAAI,EAAE,KAAK;IACX,MAAM,EAAE,KAAK;IACb,aAAa,EAAE,KAAK;IACpB,SAAS,EAAE,KAAK;IAChB,IAAI,EAAE,KAAK;IACX,KAAK,EAAE,SAAS;CACjB,CAAC;AA6GF,+EAA+E;AAC/E,iCAAiC;AACjC,+EAA+E;AAE/E;;GAEG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,WAAW;IACX,WAAW;IACX,WAAW;IACX,WAAW;IACX,oBAAoB;IACpB,oBAAoB;IACpB,MAAM;IACN,OAAO;IACP,OAAO;CACC,CAAC;AAIX;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAC/C,OAAQ,qBAA2C,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AACrE,CAAC"}