@lifestreamdynamics/vault-sdk 1.0.0

package/dist/resources/documents.d.ts

@@ -0,0 +1,334 @@
+import type { KyInstance } from 'ky';
+/** Metadata for a document stored in a vault. */
+export interface Document {
+    /** Unique document identifier. */
+    id: string;
+    /** ID of the vault containing this document. */
+    vaultId: string;
+    /** File path relative to the vault root (e.g., `'notes/todo.md'`). */
+    path: string;
+    /** Document title extracted from frontmatter or first heading, if available. */
+    title: string | null;
+    /** SHA-256 hash of the document content. */
+    contentHash: string;
+    /** Document size in bytes. */
+    sizeBytes: number;
+    /** Tags extracted from frontmatter and inline hashtags. */
+    tags: string[];
+    /** Whether the document content is encrypted client-side. */
+    encrypted: boolean;
+    /** The encryption algorithm used, if encrypted. */
+    encryptionAlgorithm: string | null;
+    /** ISO 8601 timestamp of the last file modification. */
+    fileModifiedAt: string;
+    /** ISO 8601 creation timestamp. */
+    createdAt: string;
+    /** ISO 8601 last-updated timestamp. */
+    updatedAt: string;
+}
+/** A document with its full Markdown content. */
+export interface DocumentWithContent {
+    /** Document metadata. */
+    document: Document;
+    /** Raw Markdown content of the document. */
+    content: string;
+}
+/** Version metadata for a document. */
+export interface DocumentVersion {
+    id: string;
+    documentId: string;
+    versionNum: number;
+    contentHash: string;
+    sizeBytes: number;
+    changeSource: 'web' | 'api' | 'webdav';
+    changedBy: string | null;
+    isPinned: boolean;
+    expiresAt: string | null;
+    createdAt: string;
+}
+/** Version with its content. */
+export interface DocumentVersionWithContent extends DocumentVersion {
+    content: string | null;
+}
+/** Diff response between two versions. */
+export interface VersionDiffResponse {
+    fromVersion: number;
+    toVersion: number;
+    changes: Array<{
+        added?: boolean;
+        removed?: boolean;
+        value: string;
+    }>;
+}
+/** Summary information for a document in a listing. */
+export interface DocumentListItem {
+    /** File path relative to the vault root. */
+    path: string;
+    /** Document title, if available. */
+    title: string | null;
+    /** Tags extracted from the document. */
+    tags: string[];
+    /** Document size in bytes. */
+    sizeBytes: number;
+    /** ISO 8601 timestamp of the last file modification. */
+    fileModifiedAt: string;
+}
+/**
+ * Resource for managing documents within vaults.
+ *
+ * Documents are Markdown files stored in vaults. Each document has a file
+ * path relative to the vault root and must end with `.md`. The API supports
+ * CRUD operations as well as move and copy.
+ *
+ * @example
+ * ```typescript
+ * const docs = await client.documents.list('vault-uuid');
+ * const doc = await client.documents.get('vault-uuid', 'notes/todo.md');
+ * console.log(doc.content);
+ * ```
+ */
+export declare class DocumentsResource {
+    private http;
+    constructor(http: KyInstance);
+    /**
+     * Lists documents in a vault, optionally filtered by directory.
+     *
+     * @param vaultId - The vault ID to list documents from
+     * @param dirPath - Optional directory path to filter results (e.g., `'notes/'`)
+     * @returns Array of document summary objects
+     * @throws {NotFoundError} If the vault does not exist
+     * @throws {AuthenticationError} If the request is not authenticated
+     * @throws {NetworkError} If the request fails due to network issues
+     *
+     * @example
+     * ```typescript
+     * // List all documents
+     * const docs = await client.documents.list('vault-uuid');
+     *
+     * // List documents in a subdirectory
+     * const notes = await client.documents.list('vault-uuid', 'notes/');
+     * ```
+     */
+    list(vaultId: string, dirPath?: string): Promise<DocumentListItem[]>;
+    /**
+     * Retrieves a document's metadata and full Markdown content.
+     *
+     * @param vaultId - The vault ID containing the document
+     * @param docPath - File path relative to vault root (e.g., `'notes/todo.md'`)
+     * @returns The document metadata and raw Markdown content
+     * @throws {NotFoundError} If the vault or document does not exist
+     * @throws {AuthenticationError} If the request is not authenticated
+     * @throws {NetworkError} If the request fails due to network issues
+     *
+     * @example
+     * ```typescript
+     * const { document, content } = await client.documents.get(
+     *   'vault-uuid',
+     *   'notes/todo.md'
+     * );
+     * console.log(document.title, content);
+     * ```
+     */
+    get(vaultId: string, docPath: string): Promise<DocumentWithContent>;
+    /**
+     * Creates or updates a document (upsert).
+     *
+     * If a document already exists at the given path, it is updated only when
+     * the content has changed (compared by SHA-256 hash). Intermediate folders
+     * are created automatically.
+     *
+     * @param vaultId - The vault ID to write the document into
+     * @param docPath - File path relative to vault root (must end with `.md`)
+     * @param content - Raw Markdown content to write
+     * @returns The created or updated document metadata
+     * @throws {NotFoundError} If the vault does not exist
+     * @throws {ValidationError} If the path is invalid or content exceeds size limits
+     * @throws {AuthenticationError} If the request is not authenticated
+     * @throws {NetworkError} If the request fails due to network issues
+     *
+     * @example
+     * ```typescript
+     * // Create a new document
+     * const doc = await client.documents.put(
+     *   'vault-uuid',
+     *   'notes/hello.md',
+     *   '# Hello World\n\nThis is my first note.'
+     * );
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Update an existing document
+     * const { content } = await client.documents.get('vault-uuid', 'notes/hello.md');
+     * await client.documents.put(
+     *   'vault-uuid',
+     *   'notes/hello.md',
+     *   content + '\n\nAppended text.'
+     * );
+     * ```
+     */
+    put(vaultId: string, docPath: string, content: string): Promise<Document>;
+    /**
+     * Permanently deletes a document from a vault.
+     *
+     * Removes the document from both the filesystem and the database.
+     * This action is irreversible.
+     *
+     * @param vaultId - The vault ID containing the document
+     * @param docPath - File path of the document to delete
+     * @throws {NotFoundError} If the vault or document does not exist
+     * @throws {AuthenticationError} If the request is not authenticated
+     * @throws {NetworkError} If the request fails due to network issues
+     *
+     * @example
+     * ```typescript
+     * await client.documents.delete('vault-uuid', 'notes/old-note.md');
+     * ```
+     */
+    delete(vaultId: string, docPath: string): Promise<void>;
+    /**
+     * Moves (renames) a document to a new path within the same vault.
+     *
+     * @param vaultId - The vault ID containing the document
+     * @param sourcePath - Current file path of the document
+     * @param destination - New file path for the document (must end with `.md`)
+     * @param overwrite - If `true`, overwrite any existing document at the destination. Defaults to `false`.
+     * @returns Object with a confirmation message and the source/destination paths
+     * @throws {NotFoundError} If the vault or source document does not exist
+     * @throws {ConflictError} If a document exists at the destination and `overwrite` is `false`
+     * @throws {ValidationError} If the destination path is invalid
+     * @throws {AuthenticationError} If the request is not authenticated
+     * @throws {NetworkError} If the request fails due to network issues
+     *
+     * @example
+     * ```typescript
+     * const result = await client.documents.move(
+     *   'vault-uuid',
+     *   'drafts/note.md',
+     *   'published/note.md'
+     * );
+     * console.log(result.destination); // 'published/note.md'
+     * ```
+     *
+     * @see {@link DocumentsResource.copy} to duplicate a document instead
+     */
+    move(vaultId: string, sourcePath: string, destination: string, overwrite?: boolean): Promise<{
+        message: string;
+        source: string;
+        destination: string;
+    }>;
+    /**
+     * Copies a document to a new path within the same vault.
+     *
+     * The original document is preserved. A new document is created at the
+     * destination path with the same content.
+     *
+     * @param vaultId - The vault ID containing the document
+     * @param sourcePath - File path of the document to copy
+     * @param destination - File path for the new copy (must end with `.md`)
+     * @param overwrite - If `true`, overwrite any existing document at the destination. Defaults to `false`.
+     * @returns Object with a confirmation message and the source/destination paths
+     * @throws {NotFoundError} If the vault or source document does not exist
+     * @throws {ConflictError} If a document exists at the destination and `overwrite` is `false`
+     * @throws {ValidationError} If the destination path is invalid
+     * @throws {AuthenticationError} If the request is not authenticated
+     * @throws {NetworkError} If the request fails due to network issues
+     *
+     * @example
+     * ```typescript
+     * const result = await client.documents.copy(
+     *   'vault-uuid',
+     *   'templates/meeting.md',
+     *   'notes/2024-01-15-meeting.md'
+     * );
+     * ```
+     *
+     * @see {@link DocumentsResource.move} to relocate a document instead
+     */
+    copy(vaultId: string, sourcePath: string, destination: string, overwrite?: boolean): Promise<{
+        message: string;
+        source: string;
+        destination: string;
+    }>;
+    /**
+     * Creates or updates a document with client-side encryption.
+     *
+     * The content is encrypted locally using AES-256-GCM before being sent to
+     * the server. The server stores only the ciphertext and cannot read the
+     * plaintext content. Search indexing, AI features, and hooks are disabled
+     * for encrypted documents.
+     *
+     * @param vaultId - The vault ID to write the document into
+     * @param docPath - File path relative to vault root (must end with `.md`)
+     * @param content - Raw Markdown content to encrypt and write
+     * @param keyHex - The 256-bit vault encryption key as a hex string
+     * @returns The created or updated document metadata
+     * @throws {Error} If the key is invalid
+     */
+    putEncrypted(vaultId: string, docPath: string, content: string, keyHex: string): Promise<Document>;
+    /**
+     * Retrieves an encrypted document and decrypts it client-side.
+     *
+     * @param vaultId - The vault ID containing the document
+     * @param docPath - File path relative to vault root
+     * @param keyHex - The 256-bit vault encryption key as a hex string
+     * @returns The document metadata and decrypted plaintext content
+     * @throws {Error} If the key is invalid or decryption fails
+     */
+    getEncrypted(vaultId: string, docPath: string, keyHex: string): Promise<DocumentWithContent>;
+    /**
+     * Lists version history for a document.
+     *
+     * @param vaultId - The vault ID containing the document
+     * @param docPath - File path relative to vault root
+     * @returns Array of version metadata objects (newest first)
+     */
+    listVersions(vaultId: string, docPath: string): Promise<DocumentVersion[]>;
+    /**
+     * Retrieves a specific version's content.
+     *
+     * @param vaultId - The vault ID containing the document
+     * @param docPath - File path relative to vault root
+     * @param versionNum - The version number to retrieve
+     * @returns The version metadata and content
+     */
+    getVersion(vaultId: string, docPath: string, versionNum: number): Promise<DocumentVersionWithContent>;
+    /**
+     * Computes a diff between two versions of a document.
+     *
+     * @param vaultId - The vault ID containing the document
+     * @param docPath - File path relative to vault root
+     * @param from - Source version number
+     * @param to - Target version number
+     * @returns The diff with line-level changes
+     */
+    diffVersions(vaultId: string, docPath: string, from: number, to: number): Promise<VersionDiffResponse>;
+    /**
+     * Restores a document to a previous version.
+     *
+     * @param vaultId - The vault ID containing the document
+     * @param docPath - File path relative to vault root
+     * @param versionNum - The version number to restore
+     * @returns The updated document metadata
+     */
+    restoreVersion(vaultId: string, docPath: string, versionNum: number): Promise<Document>;
+    /**
+     * Pins a version to prevent it from being pruned.
+     *
+     * @param vaultId - The vault ID containing the document
+     * @param docPath - File path relative to vault root
+     * @param versionNum - The version number to pin
+     * @returns The updated version metadata
+     */
+    pinVersion(vaultId: string, docPath: string, versionNum: number): Promise<DocumentVersion>;
+    /**
+     * Unpins a version, allowing it to be pruned.
+     *
+     * @param vaultId - The vault ID containing the document
+     * @param docPath - File path relative to vault root
+     * @param versionNum - The version number to unpin
+     * @returns The updated version metadata
+     */
+    unpinVersion(vaultId: string, docPath: string, versionNum: number): Promise<DocumentVersion>;
+}
+//# sourceMappingURL=documents.d.ts.map

package/dist/resources/documents.d.ts.map

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