/**
 * Document Sync Adapter Utilities
 *
 * Shared field mapping logic for converting between Stoneforge documents and
 * external document representations (e.g., Notion pages, Obsidian notes).
 *
 * These utilities are provider-agnostic — they handle the common conversion
 * logic that all document sync providers need.
 *
 * Key functions:
 * - documentToExternalDocumentInput: Convert a Stoneforge Document → ExternalDocumentInput for push
 * - externalDocumentToDocumentUpdates: Convert an ExternalDocument → Partial<Document> for pull
 * - diffDocumentUpdates: Return only changed fields between existing and updated document
 * - computeExternalDocumentHash: Deterministic hash for change detection
 */
import type { Document, ContentType, DocumentCategory, Element, ElementId, Dependency, DependencyType } from '@stoneforge/core';
import type { ExternalDocument, ExternalDocumentInput } from '@stoneforge/core';
/**
 * Document categories that are system-managed and should be excluded from
 * external sync. These documents are structural (task descriptions, message
 * content) and are synced through their parent element's sync adapter.
 */
export declare const SYSTEM_CATEGORIES: ReadonlySet<DocumentCategory>;
/**
 * Checks whether a document category is a system category that should
 * be excluded from document sync.
 */
export declare function isSystemCategory(category: DocumentCategory): boolean;
/**
 * Checks whether a document should be included in external sync operations
 * (link-all, push, pull). A document is syncable if:
 * - It does not have a system category (task-description, message-content)
 * - It has a non-empty title (null, undefined, or whitespace-only titles are excluded)
 *
 * Documents without titles are typically system-generated (messages, task descriptions)
 * that happen to not have the system category set, or scratch documents. They all
 * slugify to "untitled.md" and overwrite each other, so they must be excluded.
 */
export declare function isSyncableDocument(doc: Document): boolean;
/**
 * Maps Stoneforge ContentType to external document content type.
 *
 * Stoneforge uses 'markdown', 'text', and 'json'.
 * External systems use 'markdown', 'text', and 'html'.
 * JSON content is mapped to 'text' for external systems since most
 * document providers don't have a native JSON content type.
 */
export declare function mapContentTypeToExternal(contentType: ContentType): 'markdown' | 'html' | 'text';
/**
 * Maps external document content type to Stoneforge ContentType.
 *
 * External systems use 'markdown', 'text', and 'html'.
 * HTML content is mapped to 'text' since Stoneforge doesn't have an HTML
 * content type — the content is stored as-is, just categorized as text.
 */
export declare function mapContentTypeFromExternal(contentType: 'markdown' | 'html' | 'text'): ContentType;
/**
 * Minimal API interface for resolving library paths.
 * This avoids coupling to the full QuarryAPI type while providing
 * the dependency and element lookup methods needed for path resolution.
 */
export interface LibraryPathAPI {
    /** Get all dependencies for an element, optionally filtered by type */
    getDependencies(id: ElementId, types?: DependencyType[]): Promise<Dependency[]>;
    /** Get a single element by ID */
    get<T extends Element>(id: ElementId): Promise<T | null>;
}
/**
 * Resolves the library path for a document by querying its parent-child
 * dependencies. Builds a hierarchical path from the root library down
 * to the document's immediate parent library.
 *
 * For example, if a document belongs to library "API Reference" which
 * is a child of library "Documentation", the returned path would be
 * "documentation/api-reference".
 *
 * Design decisions:
 * - If a document belongs to multiple libraries, the first one found is used
 * - Library names are slugified for directory names
 * - If the document has no library parent, returns undefined
 *
 * @param api - API for querying dependencies and elements
 * @param documentId - The document's element ID
 * @returns The slugified library path (e.g., 'documentation/api-reference'), or undefined if not in a library
 */
export declare function resolveDocumentLibraryPath(api: LibraryPathAPI, documentId: ElementId): Promise<string | undefined>;
/**
 * Batch-resolves library paths for multiple documents.
 * More efficient than calling resolveDocumentLibraryPath individually
 * since it can reuse cached library lookups.
 *
 * @param api - API for querying dependencies and elements
 * @param documentIds - Array of document element IDs
 * @returns Map from document ID to library path (undefined entries omitted)
 */
export declare function resolveDocumentLibraryPaths(api: LibraryPathAPI, documentIds: ElementId[]): Promise<Map<string, string>>;
/**
 * Converts a Stoneforge Document into an ExternalDocumentInput for
 * creating/updating a page in an external system.
 *
 * Handles:
 * - Title mapping (1:1, falls back to empty string if undefined)
 * - Content mapping (1:1)
 * - ContentType mapping (markdown/text → markdown/text, json → text)
 * - Optional library path for directory-based organization
 *
 * @param doc - The Stoneforge document to convert
 * @param libraryPath - Optional pre-computed library path for the document
 * @returns ExternalDocumentInput ready for the provider adapter
 */
export declare function documentToExternalDocumentInput(doc: Document, libraryPath?: string): ExternalDocumentInput;
/**
 * Converts an ExternalDocument into a partial Document update object for
 * applying external changes to a local Stoneforge document.
 *
 * Handles:
 * - Title mapping (1:1)
 * - Content mapping (1:1)
 * - ContentType mapping (markdown/text/html → markdown/text/text)
 *
 * If existingDoc is provided, only changed fields are returned (diff mode).
 * If existingDoc is undefined, all mappable fields are returned (create mode).
 *
 * @param externalDoc - The external document to convert
 * @param existingDoc - The existing local document (undefined for new documents)
 * @returns Partial<Document> with only the changed fields (or all fields if no existingDoc)
 */
export declare function externalDocumentToDocumentUpdates(externalDoc: ExternalDocument, existingDoc?: Document): Partial<Document>;
/**
 * Compares a full update against an existing document and returns only
 * the fields that actually changed.
 *
 * This prevents unnecessary updates when pulling changes from external
 * systems where the data hasn't actually changed.
 *
 * Compared fields: title, content, contentType, category, tags
 */
export declare function diffDocumentUpdates(existing: Document, updates: Partial<Document>): Partial<Document>;
/**
 * Computes a deterministic hash of an ExternalDocument for change detection.
 *
 * The hash is based on the document's title, content, and contentType.
 * Used by the sync engine to detect whether an external document has
 * changed since the last sync, avoiding unnecessary pull operations.
 *
 * @param doc - The external document to hash
 * @returns A hex-encoded SHA-256 hash string
 */
export declare function computeExternalDocumentHash(doc: ExternalDocument): string;
//# sourceMappingURL=document-sync-adapter.d.ts.map