@telvok/librarian-mcp 1.5.4 → 2.0.0

package/dist/tools/sync.js

@@ -0,0 +1,304 @@
+// ============================================================================
+// Sync Tool
+// Check for and receive updates to owned books from Telvok library
+// ============================================================================
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { loadApiKey } from './auth.js';
+import { getLibraryPath, getImportedPath } from '../library/storage.js';
+const TELVOK_API_URL = process.env.TELVOK_API_URL || 'https://telvok.com';
+// ============================================================================
+// Tool Definition
+// ============================================================================
+export const syncTool = {
+    name: 'sync',
+    title: 'Sync Purchased Books',
+    description: `Check for and receive updates to purchased books.
+
+USE THIS TOOL WHEN:
+- User asks to update/sync their purchased books
+- Starting a session and marketplace content might have changed
+- Checking if owned books have new entries
+
+Subscription books sync automatically. One-time purchases sync on request.
+
+TRIGGER PATTERNS:
+- "Update my books" → sync()
+- "Check for new content" → sync()
+- "Sync that book" → sync({ slug: "book-slug" })
+- Force sync manual books → sync({ options: { force: true } })
+
+Examples:
+- sync() - Check and sync all auto-sync books
+- sync({ slug: "premium-patterns" }) - Sync specific book
+- sync({ options: { force: true } }) - Include manual preference books`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            slug: {
+                type: 'string',
+                description: 'Specific book slug to sync (omit for all)',
+            },
+            options: {
+                type: 'object',
+                properties: {
+                    force: {
+                        type: 'boolean',
+                        description: 'Include manual preference books (default: false)',
+                    },
+                    download: {
+                        type: 'boolean',
+                        description: 'Download open book updates to local library (default: false)',
+                    },
+                },
+                description: 'Sync options',
+            },
+        },
+        required: [],
+    },
+    async handler(args) {
+        const { slug, options } = (args || {});
+        const force = options?.force || false;
+        const download = options?.download || false;
+        // Check authentication
+        const apiKey = await loadApiKey();
+        if (!apiKey) {
+            return {
+                success: false,
+                message: 'Not authenticated. Run auth({ action: "login" }) to connect your Telvok account first.',
+            };
+        }
+        try {
+            // Step 1: Check for available updates
+            const checkUrl = new URL(`${TELVOK_API_URL}/api/sync`);
+            if (slug) {
+                checkUrl.searchParams.set('slug', slug);
+            }
+            const checkResponse = await fetch(checkUrl.toString(), {
+                method: 'GET',
+                headers: {
+                    'Authorization': `Bearer ${apiKey}`,
+                },
+            });
+            const checkData = await checkResponse.json();
+            if (!checkResponse.ok) {
+                return {
+                    success: false,
+                    message: checkData.error || `Failed to check for updates: HTTP ${checkResponse.status}`,
+                };
+            }
+            // If no updates available
+            const updatesAvailable = checkData.updates_available || [];
+            const upToDate = checkData.up_to_date || [];
+            const pinned = checkData.pinned || [];
+            if (updatesAvailable.length === 0) {
+                const totalBooks = upToDate.length + pinned.length;
+                let message = '';
+                if (totalBooks === 0) {
+                    message = 'No books to sync. Purchase or claim books first.';
+                }
+                else if (pinned.length > 0) {
+                    message = `${upToDate.length} book${upToDate.length === 1 ? ' is' : 's are'} up to date. ${pinned.length} pinned (won't sync).`;
+                }
+                else {
+                    message = `All ${totalBooks} book${totalBooks === 1 ? ' is' : 's are'} up to date.`;
+                }
+                return {
+                    success: true,
+                    message,
+                    pinned: pinned.length > 0 ? pinned.map((p) => ({ slug: p.slug, name: p.name })) : undefined,
+                    up_to_date: upToDate.length,
+                };
+            }
+            // Step 2: Perform sync
+            const syncResponse = await fetch(`${TELVOK_API_URL}/api/sync`, {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${apiKey}`,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    slug,
+                    force,
+                    include_content: download,
+                }),
+            });
+            const syncData = await syncResponse.json();
+            if (!syncResponse.ok) {
+                return {
+                    success: false,
+                    message: syncData.error || `Failed to sync: HTTP ${syncResponse.status}`,
+                };
+            }
+            const synced = [];
+            const available = [];
+            const pinnedBooks = [];
+            // Process synced books
+            for (const book of syncData.synced || []) {
+                const newCount = typeof book.new_entries === 'number' ? book.new_entries : book.new_entries?.length || 0;
+                const modifiedCount = typeof book.modified_entries === 'number' ? book.modified_entries : book.modified_entries?.length || 0;
+                // If download requested and content provided, save to local
+                if (download && book.access_method === 'download' && Array.isArray(book.new_entries)) {
+                    await saveEntriesToLocal(book.slug, book.new_entries, book.modified_entries);
+                }
+                synced.push({
+                    slug: book.slug,
+                    name: book.name,
+                    new_entries: newCount,
+                    modified_entries: modifiedCount,
+                    access: download && book.pricing_type === 'open' ? 'downloaded' : 'cloud',
+                    version: formatVersion(book.new_version),
+                    synced_from: formatVersion(book.previous_version),
+                });
+            }
+            // Process skipped books
+            for (const book of syncData.skipped || []) {
+                if (book.reason === 'manual_no_force') {
+                    const update = updatesAvailable.find((u) => u.slug === book.slug);
+                    if (update) {
+                        available.push({
+                            slug: book.slug,
+                            name: book.name,
+                            new_entries: update.new_entries_count,
+                        });
+                    }
+                }
+                else if (book.reason === 'pinned') {
+                    pinnedBooks.push({
+                        slug: book.slug,
+                        name: book.name,
+                    });
+                }
+            }
+            // Build summary message
+            const messageParts = [];
+            const totalNewEntries = synced.reduce((sum, b) => sum + b.new_entries, 0);
+            const totalModified = synced.reduce((sum, b) => sum + b.modified_entries, 0);
+            if (synced.length > 0) {
+                let syncMsg = `Synced ${synced.length} book${synced.length === 1 ? '' : 's'}`;
+                if (totalNewEntries > 0 || totalModified > 0) {
+                    const parts = [];
+                    if (totalNewEntries > 0)
+                        parts.push(`${totalNewEntries} new`);
+                    if (totalModified > 0)
+                        parts.push(`${totalModified} modified`);
+                    syncMsg += `: ${parts.join(', ')} entries.`;
+                }
+                else {
+                    syncMsg += '.';
+                }
+                messageParts.push(syncMsg);
+            }
+            if (available.length > 0) {
+                messageParts.push(`${available.length} book${available.length === 1 ? ' has' : 's have'} updates available (set to manual).`);
+            }
+            if (pinnedBooks.length > 0) {
+                messageParts.push(`${pinnedBooks.length} book${pinnedBooks.length === 1 ? '' : 's'} pinned (won't sync).`);
+            }
+            if (messageParts.length === 0) {
+                if (upToDate.length > 0) {
+                    messageParts.push(`All ${upToDate.length} book${upToDate.length === 1 ? ' is' : 's are'} up to date.`);
+                }
+                else {
+                    messageParts.push('No books to sync. Purchase or claim books first.');
+                }
+            }
+            return {
+                success: true,
+                message: messageParts.join(' '),
+                synced: synced.length > 0 ? synced : undefined,
+                available: available.length > 0 ? available : undefined,
+                pinned: pinnedBooks.length > 0 ? pinnedBooks : undefined,
+                up_to_date: upToDate.length,
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Sync failed: ${message}`);
+        }
+    },
+};
+// ============================================================================
+// Helper: Save entries to local imported folder
+// ============================================================================
+async function saveEntriesToLocal(slug, newEntries, modifiedEntries) {
+    const libraryPath = getLibraryPath();
+    const importedPath = getImportedPath(libraryPath);
+    const bookPath = path.join(importedPath, slug);
+    // Ensure directory exists
+    await fs.mkdir(bookPath, { recursive: true });
+    // Save new entries
+    for (const entry of newEntries || []) {
+        const filename = slugify(entry.title) + '.md';
+        const content = formatEntryAsMarkdown(entry);
+        await fs.writeFile(path.join(bookPath, filename), content, 'utf-8');
+    }
+    // Save modified entries (overwrite)
+    for (const entry of modifiedEntries || []) {
+        const filename = slugify(entry.title) + '.md';
+        const content = formatEntryAsMarkdown(entry);
+        await fs.writeFile(path.join(bookPath, filename), content, 'utf-8');
+    }
+    // Update .meta.json
+    const metaPath = path.join(bookPath, '.meta.json');
+    let meta = {};
+    try {
+        const existing = await fs.readFile(metaPath, 'utf-8');
+        meta = JSON.parse(existing);
+    }
+    catch {
+        // No existing meta
+    }
+    meta.last_synced = new Date().toISOString();
+    await fs.writeFile(metaPath, JSON.stringify(meta, null, 2), 'utf-8');
+}
+function slugify(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '')
+        .substring(0, 50);
+}
+/**
+ * Format a timestamp as a human-readable version string
+ */
+function formatVersion(isoTimestamp) {
+    if (!isoTimestamp)
+        return 'never synced';
+    const date = new Date(isoTimestamp);
+    const now = new Date();
+    const diffMs = now.getTime() - date.getTime();
+    const diffDays = Math.floor(diffMs / (1000 * 60 * 60 * 24));
+    if (diffDays === 0) {
+        return `today at ${date.toLocaleTimeString('en-US', { hour: 'numeric', minute: '2-digit' })}`;
+    }
+    else if (diffDays === 1) {
+        return 'yesterday';
+    }
+    else if (diffDays < 7) {
+        return `${diffDays} days ago`;
+    }
+    else {
+        return date.toLocaleDateString('en-US', { month: 'short', day: 'numeric', year: 'numeric' });
+    }
+}
+function formatEntryAsMarkdown(entry) {
+    let md = '';
+    // Frontmatter
+    if (entry.intent || entry.context) {
+        md += '---\n';
+        if (entry.intent)
+            md += `intent: "${entry.intent}"\n`;
+        if (entry.context)
+            md += `context: "${entry.context}"\n`;
+        md += '---\n\n';
+    }
+    // Title and content
+    md += `# ${entry.title}\n\n`;
+    md += entry.content;
+    return md;
+}
+// ============================================================================
+// Export
+// ============================================================================
+export default syncTool;

package/dist/tools/unsubscribe.d.ts

@@ -0,0 +1,48 @@
+interface UnsubscribeResult {
+    success: boolean;
+    message: string;
+    book?: {
+        slug: string;
+        name: string;
+    };
+}
+export declare const unsubscribeTool: {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            slug: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    outputSchema: {
+        type: "object";
+        properties: {
+            success: {
+                type: string;
+            };
+            message: {
+                type: string;
+            };
+            book: {
+                type: string;
+                properties: {
+                    slug: {
+                        type: string;
+                    };
+                    name: {
+                        type: string;
+                    };
+                };
+            };
+        };
+        required: string[];
+    };
+    handler(args: unknown): Promise<UnsubscribeResult>;
+};
+export default unsubscribeTool;

package/dist/tools/unsubscribe.js

@@ -0,0 +1,120 @@
+// ============================================================================
+// Unsubscribe Tool
+// Cancel a subscription to a book from Telvok library
+// ============================================================================
+import { loadApiKey } from './auth.js';
+const TELVOK_API_URL = process.env.TELVOK_API_URL || 'https://telvok.com';
+// ============================================================================
+// Tool Definition
+// ============================================================================
+export const unsubscribeTool = {
+    name: 'unsubscribe',
+    title: 'Cancel Subscription',
+    description: `Cancel a subscription to a book.
+
+USE THIS TOOL WHEN:
+- User wants to stop a subscription
+- User says "unsubscribe", "cancel subscription", "stop paying for X"
+- User asks to cancel recurring payment for a book
+
+Only works for subscription purchases. One-time purchases grant permanent access.
+
+TRIGGER PATTERNS:
+- "Cancel my subscription to X" → unsubscribe({ slug: "book-slug" })
+- "Unsubscribe from that book" → unsubscribe({ slug: "..." })
+- "Stop my subscription" → First use my_books() to find subscription slugs
+
+Example:
+- unsubscribe({ slug: "premium-patterns" })`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            slug: {
+                type: 'string',
+                description: 'Book slug to unsubscribe from (from my_books() results)',
+            },
+        },
+        required: ['slug'],
+    },
+    outputSchema: {
+        type: 'object',
+        properties: {
+            success: { type: 'boolean' },
+            message: { type: 'string' },
+            book: {
+                type: 'object',
+                properties: {
+                    slug: { type: 'string' },
+                    name: { type: 'string' },
+                },
+            },
+        },
+        required: ['success', 'message'],
+    },
+    async handler(args) {
+        const { slug } = args;
+        if (!slug || typeof slug !== 'string') {
+            return {
+                success: false,
+                message: 'Book slug is required. Use my_books() to find your subscriptions.',
+            };
+        }
+        // Check authentication
+        const apiKey = await loadApiKey();
+        if (!apiKey) {
+            return {
+                success: false,
+                message: 'Not authenticated. Run auth({ action: "login" }) to connect your Telvok account first.',
+            };
+        }
+        try {
+            const response = await fetch(`${TELVOK_API_URL}/api/subscription/cancel`, {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${apiKey}`,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({ slug }),
+            });
+            const data = await response.json();
+            if (!response.ok) {
+                // Handle specific error cases
+                if (response.status === 404) {
+                    if (data.error?.includes('No active subscription')) {
+                        return {
+                            success: false,
+                            message: `No active subscription found for "${slug}". Use my_books() to see your current subscriptions.`,
+                        };
+                    }
+                    return {
+                        success: false,
+                        message: `Book "${slug}" not found.`,
+                    };
+                }
+                if (response.status === 400 && data.error?.includes('not a subscription')) {
+                    return {
+                        success: false,
+                        message: data.message || 'This is a one-time purchase. You retain permanent access - no subscription to cancel.',
+                    };
+                }
+                return {
+                    success: false,
+                    message: data.error || `Failed to unsubscribe: HTTP ${response.status}`,
+                };
+            }
+            return {
+                success: true,
+                message: data.message || `Subscription to "${data.book?.name || slug}" has been cancelled.`,
+                book: data.book,
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to unsubscribe: ${message}`);
+        }
+    },
+};
+// ============================================================================
+// Export
+// ============================================================================
+export default unsubscribeTool;

package/dist/tools 2/adopt.d.ts

@@ -0,0 +1,24 @@
+export interface AdoptResult {
+    success: boolean;
+    from: string;
+    to: string;
+}
+export declare const adoptTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            path: {
+                type: string;
+                description: string;
+            };
+            title: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handler(args: unknown): Promise<AdoptResult>;
+};

package/dist/tools 2/adopt.js

@@ -0,0 +1,154 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import matter from 'gray-matter';
+import { getLibraryPath, getImportedPath, getLocalPath, getPackagesPath } from '../library/storage.js';
+// ============================================================================
+// Tool Definition
+// ============================================================================
+export const adoptTool = {
+    name: 'adopt',
+    description: `Make imported knowledge ours.
+
+When an entry from an imported package proves useful, adopt it into our
+local library. It graduates from "their knowledge" to "our knowledge" -
+now we can edit and evolve it.
+
+Examples:
+- adopt({ path: "imported/stripe-patterns/webhook-idempotency" })
+- adopt({ path: "imported/auth-patterns/token-refresh", title: "Our token refresh" })`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            path: {
+                type: 'string',
+                description: "Path to entry to adopt (e.g., 'imported/package-name/entry-name')",
+            },
+            title: {
+                type: 'string',
+                description: 'New title for adopted entry. Keeps original if not provided.',
+            },
+        },
+        required: ['path'],
+    },
+    async handler(args) {
+        const { path: entryPath, title: newTitle } = args;
+        if (!entryPath) {
+            throw new Error('path is required');
+        }
+        const libraryPath = getLibraryPath();
+        const importedPath = getImportedPath(libraryPath);
+        const packagesPath = getPackagesPath(libraryPath);
+        const localPath = getLocalPath(libraryPath);
+        // Normalize path: strip "imported/" or "packages/" prefix if present, add .md if missing
+        let normalizedPath = entryPath;
+        if (normalizedPath.startsWith('imported/')) {
+            normalizedPath = normalizedPath.slice('imported/'.length);
+        }
+        else if (normalizedPath.startsWith('packages/')) {
+            normalizedPath = normalizedPath.slice('packages/'.length);
+        }
+        if (!normalizedPath.endsWith('.md')) {
+            normalizedPath += '.md';
+        }
+        // Try both imported/ and packages/ paths
+        let sourcePath = path.join(importedPath, normalizedPath);
+        try {
+            await fs.access(sourcePath);
+        }
+        catch {
+            // Try packages path (for marketplace downloads)
+            sourcePath = path.join(packagesPath, normalizedPath);
+            try {
+                await fs.access(sourcePath);
+            }
+            catch {
+                throw new Error(`Entry not found: ${entryPath}`);
+            }
+        }
+        // Read source file
+        const content = await fs.readFile(sourcePath, 'utf-8');
+        const { data, content: body } = matter(content);
+        // Extract package name from path
+        const pathParts = normalizedPath.split('/');
+        const packageName = pathParts[0];
+        // Determine title
+        let title = newTitle;
+        if (!title) {
+            // Try to extract from frontmatter or H1
+            title = data.title;
+            if (!title) {
+                const headingMatch = body.match(/^#\s+(.+)$/m);
+                if (headingMatch) {
+                    title = headingMatch[1].trim();
+                }
+                else {
+                    title = path.basename(sourcePath, '.md').replace(/-/g, ' ');
+                }
+            }
+        }
+        // Generate slug for new filename
+        const slug = slugify(title);
+        const now = new Date().toISOString();
+        // Ensure local directory exists
+        await fs.mkdir(localPath, { recursive: true });
+        // Handle filename collisions
+        let filename = `${slug}.md`;
+        let destPath = path.join(localPath, filename);
+        let counter = 1;
+        while (await fileExists(destPath)) {
+            filename = `${slug}-${counter}.md`;
+            destPath = path.join(localPath, filename);
+            counter++;
+        }
+        // Build new frontmatter
+        const newFrontmatter = {
+            ...data,
+            updated: now,
+            source: `adopted from ${packageName}`,
+        };
+        // Update title in frontmatter if changed
+        if (newTitle) {
+            newFrontmatter.title = newTitle;
+        }
+        // Update body if title changed
+        let newBody = body;
+        if (newTitle) {
+            // Replace first H1 if exists
+            const headingMatch = body.match(/^#\s+.+$/m);
+            if (headingMatch) {
+                newBody = body.replace(/^#\s+.+$/m, `# ${newTitle}`);
+            }
+            else {
+                // Prepend title
+                newBody = `# ${newTitle}\n\n${body}`;
+            }
+        }
+        // Write adopted file
+        const fileContent = matter.stringify(newBody, newFrontmatter);
+        await fs.writeFile(destPath, fileContent, 'utf-8');
+        return {
+            success: true,
+            from: path.relative(libraryPath, sourcePath),
+            to: path.relative(libraryPath, destPath),
+        };
+    },
+};
+// ============================================================================
+// Helper Functions
+// ============================================================================
+function slugify(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 50);
+}
+async function fileExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/tools 2/auth.d.ts

@@ -0,0 +1,35 @@
+export interface AuthData {
+    api_key: string;
+    user_email: string;
+    user_id: string;
+    created_at: string;
+}
+export interface AuthResult {
+    authenticated: boolean;
+    user_email?: string;
+    user_id?: string;
+    message: string;
+    verification_url?: string;
+    user_code?: string;
+}
+export declare const authTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            action: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handler(args: unknown): Promise<AuthResult>;
+};
+/**
+ * Load saved API key from auth file
+ * Used by other tools that need authenticated access
+ */
+export declare function loadApiKey(): Promise<string | null>;