@lifestreamdynamics/vault-sdk 1.0.0

package/dist/resources/documents.js

@@ -0,0 +1,377 @@
+import { handleError } from '../handle-error.js';
+import { encrypt, decrypt } from '../lib/encryption.js';
+/**
+ * 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 class DocumentsResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * 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/');
+     * ```
+     */
+    async list(vaultId, dirPath) {
+        try {
+            const searchParams = {};
+            if (dirPath)
+                searchParams.dir = dirPath;
+            const data = await this.http.get(`vaults/${vaultId}/documents`, { searchParams }).json();
+            return data.documents;
+        }
+        catch (error) {
+            throw await handleError(error, 'Documents', vaultId);
+        }
+    }
+    /**
+     * 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);
+     * ```
+     */
+    async get(vaultId, docPath) {
+        try {
+            return await this.http.get(`vaults/${vaultId}/documents/${docPath}`).json();
+        }
+        catch (error) {
+            throw await handleError(error, 'Document', docPath);
+        }
+    }
+    /**
+     * 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.'
+     * );
+     * ```
+     */
+    async put(vaultId, docPath, content) {
+        try {
+            return await this.http.put(`vaults/${vaultId}/documents/${docPath}`, {
+                json: { content },
+            }).json();
+        }
+        catch (error) {
+            throw await handleError(error, 'Document', docPath);
+        }
+    }
+    /**
+     * 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');
+     * ```
+     */
+    async delete(vaultId, docPath) {
+        try {
+            await this.http.delete(`vaults/${vaultId}/documents/${docPath}`);
+        }
+        catch (error) {
+            throw await handleError(error, 'Document', docPath);
+        }
+    }
+    /**
+     * 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
+     */
+    async move(vaultId, sourcePath, destination, overwrite) {
+        try {
+            return await this.http.post(`vaults/${vaultId}/documents/${sourcePath}/move`, {
+                json: { destination, overwrite },
+            }).json();
+        }
+        catch (error) {
+            throw await handleError(error, 'Document', sourcePath);
+        }
+    }
+    /**
+     * 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
+     */
+    async copy(vaultId, sourcePath, destination, overwrite) {
+        try {
+            return await this.http.post(`vaults/${vaultId}/documents/${sourcePath}/copy`, {
+                json: { destination, overwrite },
+            }).json();
+        }
+        catch (error) {
+            throw await handleError(error, 'Document', sourcePath);
+        }
+    }
+    /**
+     * 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
+     */
+    async putEncrypted(vaultId, docPath, content, keyHex) {
+        try {
+            const encryptedContent = encrypt(content, keyHex);
+            return await this.http.put(`vaults/${vaultId}/documents/${docPath}`, {
+                json: { content: encryptedContent, encrypted: true, encryptionAlgorithm: 'aes-256-gcm' },
+            }).json();
+        }
+        catch (error) {
+            throw await handleError(error, 'Document', docPath);
+        }
+    }
+    /**
+     * 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
+     */
+    async getEncrypted(vaultId, docPath, keyHex) {
+        try {
+            const result = await this.http.get(`vaults/${vaultId}/documents/${docPath}`).json();
+            if (result.document.encrypted) {
+                result.content = decrypt(result.content, keyHex);
+            }
+            return result;
+        }
+        catch (error) {
+            throw await handleError(error, 'Document', docPath);
+        }
+    }
+    /**
+     * 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)
+     */
+    async listVersions(vaultId, docPath) {
+        try {
+            const data = await this.http.get(`vaults/${vaultId}/documents/${docPath}/versions`).json();
+            return data.versions;
+        }
+        catch (error) {
+            throw await handleError(error, 'Document', docPath);
+        }
+    }
+    /**
+     * 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
+     */
+    async getVersion(vaultId, docPath, versionNum) {
+        try {
+            const data = await this.http.get(`vaults/${vaultId}/documents/${docPath}/versions/${versionNum}`).json();
+            return data.version;
+        }
+        catch (error) {
+            throw await handleError(error, 'Document', docPath);
+        }
+    }
+    /**
+     * 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
+     */
+    async diffVersions(vaultId, docPath, from, to) {
+        try {
+            return await this.http.post(`vaults/${vaultId}/documents/${docPath}/versions/diff`, {
+                json: { from, to },
+            }).json();
+        }
+        catch (error) {
+            throw await handleError(error, 'Document', docPath);
+        }
+    }
+    /**
+     * 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
+     */
+    async restoreVersion(vaultId, docPath, versionNum) {
+        try {
+            const data = await this.http.post(`vaults/${vaultId}/documents/${docPath}/versions/${versionNum}/restore`).json();
+            return data.document;
+        }
+        catch (error) {
+            throw await handleError(error, 'Document', docPath);
+        }
+    }
+    /**
+     * 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
+     */
+    async pinVersion(vaultId, docPath, versionNum) {
+        try {
+            const data = await this.http.post(`vaults/${vaultId}/documents/${docPath}/versions/${versionNum}/pin`).json();
+            return data.version;
+        }
+        catch (error) {
+            throw await handleError(error, 'Document', docPath);
+        }
+    }
+    /**
+     * 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
+     */
+    async unpinVersion(vaultId, docPath, versionNum) {
+        try {
+            const data = await this.http.post(`vaults/${vaultId}/documents/${docPath}/versions/${versionNum}/unpin`).json();
+            return data.version;
+        }
+        catch (error) {
+            throw await handleError(error, 'Document', docPath);
+        }
+    }
+}
+//# sourceMappingURL=documents.js.map

package/dist/resources/documents.js.map

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

package/dist/resources/hooks.d.ts

@@ -0,0 +1,195 @@
+import type { KyInstance } from 'ky';
+/** A hook object returned by the API. */
+export interface Hook {
+    /** Unique hook identifier. */
+    id: string;
+    /** Vault this hook belongs to. */
+    vaultId: string;
+    /** Human-readable name for the hook. */
+    name: string;
+    /** Event that triggers the hook (e.g., `'document.create'`, `'document.update'`, `'document.delete'`). */
+    triggerEvent: string;
+    /** Optional filter for narrowing which events trigger the hook. */
+    triggerFilter: Record<string, unknown> | null;
+    /** The type of action to perform (e.g., `'auto-tag'`, `'template'`). */
+    actionType: string;
+    /** Configuration object for the action. */
+    actionConfig: Record<string, unknown>;
+    /** Whether the hook is currently active. */
+    isActive: boolean;
+    /** ISO 8601 creation timestamp. */
+    createdAt: string;
+    /** ISO 8601 last-updated timestamp. */
+    updatedAt: string;
+}
+/** A hook execution log entry. */
+export interface HookExecution {
+    /** Unique execution identifier. */
+    id: string;
+    /** Hook that was executed. */
+    hookId: string;
+    /** Vault event that triggered the execution. */
+    eventId: string;
+    /** Execution status (e.g., `'success'`, `'error'`). */
+    status: string;
+    /** Duration of execution in milliseconds, or `null` if not recorded. */
+    durationMs: number | null;
+    /** Result data from the execution, or `null`. */
+    result: unknown;
+    /** Error message if the execution failed, or `null`. */
+    error: string | null;
+    /** ISO 8601 timestamp of when the execution occurred. */
+    createdAt: string;
+}
+/** Parameters for creating a new hook. */
+export interface CreateHookParams {
+    /** Human-readable name for the hook. */
+    name: string;
+    /** Event that triggers the hook. */
+    triggerEvent: string;
+    /** Optional filter for narrowing trigger events. */
+    triggerFilter?: Record<string, unknown> | null;
+    /** The type of action to perform. */
+    actionType: string;
+    /** Configuration for the action. */
+    actionConfig: Record<string, unknown>;
+}
+/** Parameters for updating an existing hook. */
+export interface UpdateHookParams {
+    /** New name for the hook. */
+    name?: string;
+    /** Whether the hook should be active. */
+    isActive?: boolean;
+    /** New trigger event. */
+    triggerEvent?: string;
+    /** New trigger filter. */
+    triggerFilter?: Record<string, unknown> | null;
+    /** New action type. */
+    actionType?: string;
+    /** New action configuration. */
+    actionConfig?: Record<string, unknown>;
+}
+/**
+ * Resource for managing vault hooks.
+ *
+ * Hooks are internal event handlers that run automatically when document
+ * events occur within a vault. They can perform actions such as auto-tagging,
+ * template application, and other automated workflows.
+ *
+ * Requires a **pro** or higher subscription tier.
+ *
+ * @example
+ * ```typescript
+ * const hooks = await client.hooks.list('vault-123');
+ * const hook = await client.hooks.create('vault-123', {
+ *   name: 'Auto-tag on create',
+ *   triggerEvent: 'document.create',
+ *   actionType: 'auto-tag',
+ *   actionConfig: { tags: ['new'] },
+ * });
+ * ```
+ */
+export declare class HooksResource {
+    private http;
+    constructor(http: KyInstance);
+    /**
+     * Lists all hooks for a vault.
+     *
+     * @param vaultId - The vault to list hooks for
+     * @returns Array of hook objects
+     * @throws {AuthenticationError} If not authenticated
+     * @throws {AuthorizationError} If the user lacks access to the vault
+     * @throws {NetworkError} If the request fails due to network issues
+     *
+     * @example
+     * ```typescript
+     * const hooks = await client.hooks.list('vault-123');
+     * for (const hook of hooks) {
+     *   console.log(hook.name, hook.triggerEvent, hook.isActive);
+     * }
+     * ```
+     */
+    list(vaultId: string): Promise<Hook[]>;
+    /**
+     * Creates a new hook in a vault.
+     *
+     * @param vaultId - The vault to create the hook in
+     * @param params - Hook creation parameters
+     * @returns The created hook object
+     * @throws {ValidationError} If parameters are invalid
+     * @throws {AuthenticationError} If not authenticated
+     * @throws {AuthorizationError} If the user lacks access to the vault
+     * @throws {NetworkError} If the request fails due to network issues
+     *
+     * @example
+     * ```typescript
+     * const hook = await client.hooks.create('vault-123', {
+     *   name: 'Auto-tag new docs',
+     *   triggerEvent: 'document.create',
+     *   actionType: 'auto-tag',
+     *   actionConfig: { tags: ['new'] },
+     * });
+     * ```
+     */
+    create(vaultId: string, params: CreateHookParams): Promise<Hook>;
+    /**
+     * Updates an existing hook.
+     *
+     * Only the provided fields are modified; omitted fields remain unchanged.
+     *
+     * @param vaultId - The vault the hook belongs to
+     * @param hookId - The hook to update
+     * @param params - Fields to update
+     * @returns The updated hook object
+     * @throws {ValidationError} If parameters are invalid
+     * @throws {NotFoundError} If the hook does not exist in the vault
+     * @throws {AuthenticationError} If not authenticated
+     * @throws {NetworkError} If the request fails due to network issues
+     *
+     * @example
+     * ```typescript
+     * const updated = await client.hooks.update('vault-123', 'hook-456', {
+     *   name: 'Renamed Hook',
+     *   isActive: false,
+     * });
+     * ```
+     */
+    update(vaultId: string, hookId: string, params: UpdateHookParams): Promise<Hook>;
+    /**
+     * Deletes a hook permanently.
+     *
+     * @param vaultId - The vault the hook belongs to
+     * @param hookId - The hook to delete
+     * @throws {NotFoundError} If the hook does not exist in the vault
+     * @throws {AuthenticationError} If not authenticated
+     * @throws {NetworkError} If the request fails due to network issues
+     *
+     * @example
+     * ```typescript
+     * await client.hooks.delete('vault-123', 'hook-456');
+     * ```
+     */
+    delete(vaultId: string, hookId: string): Promise<void>;
+    /**
+     * Lists recent executions for a hook.
+     *
+     * Returns up to 50 most recent execution log entries, ordered by most recent first.
+     *
+     * @param vaultId - The vault the hook belongs to
+     * @param hookId - The hook to get executions for
+     * @returns Array of hook execution log entries
+     * @throws {NotFoundError} If the hook does not exist in the vault
+     * @throws {AuthenticationError} If not authenticated
+     * @throws {NetworkError} If the request fails due to network issues
+     *
+     * @example
+     * ```typescript
+     * const executions = await client.hooks.listExecutions('vault-123', 'hook-456');
+     * for (const exec of executions) {
+     *   console.log(exec.status, exec.durationMs, exec.createdAt);
+     * }
+     * ```
+     */
+    listExecutions(vaultId: string, hookId: string): Promise<HookExecution[]>;
+}
+//# sourceMappingURL=hooks.d.ts.map

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

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