@telvok/librarian-mcp 1.5.4 → 2.0.0

package/dist/tools/library-buy.d.ts

@@ -0,0 +1,31 @@
+interface BuyResult {
+    success: boolean;
+    message: string;
+    checkout_url?: string;
+    already_owned?: boolean;
+    free_access?: boolean;
+    book?: {
+        slug: string;
+        name: string;
+        entries?: number;
+        price?: string;
+        pricing_type?: string;
+    };
+}
+export declare const libraryBuyTool: {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            slug: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handler(args: unknown): Promise<BuyResult>;
+};
+export {};

package/dist/tools/library-buy.js

@@ -0,0 +1,104 @@
+// ============================================================================
+// Marketplace Buy Tool
+// Purchase or claim books from the Telvok library
+// ============================================================================
+import { loadApiKey } from './auth.js';
+const TELVOK_API_URL = process.env.TELVOK_API_URL || 'https://telvok.com';
+// ============================================================================
+// Tool Definition
+// ============================================================================
+export const libraryBuyTool = {
+    name: 'library_buy',
+    title: 'Purchase Book',
+    description: `Purchase or claim a book from Telvok marketplace.
+
+USE THIS TOOL WHEN:
+- User wants to buy a book from library_search() results
+- Claiming a free (open) book
+- User says "get", "buy", "purchase", or "claim" a book
+
+Free books: Instantly added to library. Paid: Returns checkout URL.
+
+TRIGGER PATTERNS:
+- "Buy that book" → library_buy({ slug: "<slug from search>" })
+- "Get the free one" → library_buy({ slug: "..." })
+- User selects from library_search results → library_buy({ slug: "..." })
+
+Example:
+- library_buy({ slug: "react-best-practices" })`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            slug: {
+                type: 'string',
+                description: 'Book slug from library_search results',
+            },
+        },
+        required: ['slug'],
+    },
+    async handler(args) {
+        const { slug } = args;
+        if (!slug || typeof slug !== 'string') {
+            throw new Error('Book slug is required');
+        }
+        // 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/purchase`, {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${apiKey}`,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({ slug }),
+            });
+            const data = await response.json();
+            if (!response.ok) {
+                return {
+                    success: false,
+                    message: data.error || `Purchase failed: HTTP ${response.status}`,
+                };
+            }
+            // Handle different response types
+            if (data.already_owned) {
+                return {
+                    success: true,
+                    already_owned: true,
+                    message: data.message || `You already own '${data.book?.name || slug}'`,
+                    book: data.book,
+                };
+            }
+            if (data.free_access) {
+                return {
+                    success: true,
+                    free_access: true,
+                    message: data.message || `'${data.book?.name || slug}' added to your library (${data.book?.entries || 0} entries)`,
+                    book: data.book,
+                };
+            }
+            if (data.checkout_url) {
+                return {
+                    success: true,
+                    checkout_url: data.checkout_url,
+                    message: `Complete your purchase:\n\n${data.checkout_url}\n\nBook: ${data.book?.name || slug} (${data.book?.price || 'paid'})`,
+                    book: data.book,
+                };
+            }
+            // Unexpected response
+            return {
+                success: false,
+                message: 'Unexpected response from purchase API',
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Purchase failed: ${message}`);
+        }
+    },
+};

package/dist/tools/library-download.d.ts

@@ -0,0 +1,27 @@
+interface DownloadResult {
+    success: boolean;
+    message: string;
+    book?: {
+        slug: string;
+        name: string;
+        entries: number;
+    };
+    path?: string;
+}
+export declare const libraryDownloadTool: {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            slug: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handler(args: unknown): Promise<DownloadResult>;
+};
+export {};

package/dist/tools/library-download.js

@@ -0,0 +1,177 @@
+// ============================================================================
+// Marketplace Download Tool
+// Download purchased books to local library
+// ============================================================================
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { loadApiKey } from './auth.js';
+import { getLibraryPath, getPackagesPath } from '../library/storage.js';
+const TELVOK_API_URL = process.env.TELVOK_API_URL || 'https://telvok.com';
+// ============================================================================
+// Tool Definition
+// ============================================================================
+export const libraryDownloadTool = {
+    name: 'library_download',
+    title: 'Download Free Book',
+    description: `Download a FREE (open) book for offline access.
+
+USE THIS TOOL WHEN:
+- User wants to download a free book they own
+- Need offline access to open-source book content
+- User says "download that book"
+
+Downloads to .librarian/packages/{slug}/. Only works for FREE books.
+Paid books are cloud-only - use brief({ include_library: true }) instead.
+
+TRIGGER PATTERNS:
+- "Download that free book" → library_download({ slug: "..." })
+- After library_buy() on free book → library_download({ slug: "..." })
+
+Example:
+- library_download({ slug: "react-best-practices" })`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            slug: {
+                type: 'string',
+                description: 'Book slug to download',
+            },
+        },
+        required: ['slug'],
+    },
+    async handler(args) {
+        const { slug } = args;
+        if (!slug || typeof slug !== 'string') {
+            throw new Error('Book slug is required');
+        }
+        // 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 {
+            // Fetch content from API
+            const response = await fetch(`${TELVOK_API_URL}/api/content/${slug}`, {
+                method: 'GET',
+                headers: {
+                    'Authorization': `Bearer ${apiKey}`,
+                },
+            });
+            const data = await response.json();
+            if (!response.ok) {
+                return {
+                    success: false,
+                    message: data.error || `Download failed: HTTP ${response.status}`,
+                };
+            }
+            // Check if book is paid - reject download for paid content
+            const pricingType = data.book?.pricing_type;
+            if (pricingType && pricingType !== 'open') {
+                return {
+                    success: false,
+                    message: `Paid content cannot be downloaded locally. '${data.book.name}' is a ${pricingType === 'subscription' ? 'subscription' : 'paid'} book.\n\nTo access content from paid books, use:\n  brief({ query: "your search", include_library: true })`,
+                };
+            }
+            // Save entries to packages directory
+            const libraryPath = getLibraryPath();
+            const packagesPath = getPackagesPath(libraryPath);
+            const bookPath = path.join(packagesPath, slug);
+            // Create directory
+            await fs.mkdir(bookPath, { recursive: true });
+            // Clean up existing .md files to remove orphaned entries from deleted content
+            try {
+                const existingFiles = await fs.readdir(bookPath);
+                for (const file of existingFiles) {
+                    if (file.endsWith('.md')) {
+                        await fs.unlink(path.join(bookPath, file));
+                    }
+                }
+            }
+            catch {
+                // Directory might be new or empty, ignore errors
+            }
+            // Write each entry as a markdown file
+            const entries = data.entries || [];
+            for (const entry of entries) {
+                const filename = slugify(entry.title) + '.md';
+                const content = formatEntry(entry);
+                await fs.writeFile(path.join(bookPath, filename), content, 'utf-8');
+            }
+            // Write metadata file
+            const metadata = {
+                slug: data.book.slug,
+                name: data.book.name,
+                description: data.book.description,
+                version: data.book.version,
+                downloaded_at: new Date().toISOString(),
+                entry_count: entries.length,
+            };
+            await fs.writeFile(path.join(bookPath, '_metadata.json'), JSON.stringify(metadata, null, 2), 'utf-8');
+            return {
+                success: true,
+                message: `Downloaded '${data.book.name}' (${entries.length} entries) to ${bookPath}`,
+                book: {
+                    slug: data.book.slug,
+                    name: data.book.name,
+                    entries: entries.length,
+                },
+                path: bookPath,
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Download failed: ${message}`);
+        }
+    },
+};
+// ============================================================================
+// Helpers
+// ============================================================================
+function slugify(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '')
+        .substring(0, 50);
+}
+function formatEntry(entry) {
+    const lines = [];
+    // Frontmatter
+    lines.push('---');
+    if (entry.intent)
+        lines.push(`intent: "${entry.intent.replace(/"/g, '\\"')}"`);
+    if (entry.context)
+        lines.push(`context: "${entry.context.replace(/"/g, '\\"')}"`);
+    lines.push(`created: "${new Date().toISOString()}"`);
+    lines.push('source: "library"');
+    lines.push('hits: 0');
+    lines.push('last_hit: null');
+    lines.push('---');
+    lines.push('');
+    // Title
+    lines.push(`# ${entry.title}`);
+    lines.push('');
+    // Insight/content
+    if (entry.insight) {
+        lines.push(entry.insight);
+        lines.push('');
+    }
+    // Reasoning
+    if (entry.reasoning) {
+        lines.push('## Reasoning');
+        lines.push('');
+        lines.push(entry.reasoning);
+        lines.push('');
+    }
+    // Example
+    if (entry.example) {
+        lines.push('## Example');
+        lines.push('');
+        lines.push(entry.example);
+        lines.push('');
+    }
+    return lines.join('\n');
+}

package/dist/tools/library-publish.d.ts

@@ -0,0 +1,112 @@
+interface PublishResult {
+    success: boolean;
+    message: string;
+    book?: {
+        id?: string;
+        slug: string;
+        name: string;
+        url: string;
+    };
+    entries_count?: number;
+    setup_url?: string;
+    preview?: boolean;
+    summary?: {
+        name: string;
+        pricing: {
+            type: string;
+            display: string;
+        };
+        entries_count: number;
+        entries: Array<{
+            title: string;
+            file: string;
+        }>;
+    };
+    next_steps?: string;
+    options?: Record<string, string>;
+    required?: Record<string, string>;
+}
+export declare const libraryPublishTool: {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            name: {
+                type: string;
+                description: string;
+            };
+            description: {
+                type: string;
+                description: string;
+            };
+            pricing: {
+                type: string;
+                properties: {
+                    type: {
+                        type: string;
+                        enum: string[];
+                        description: string;
+                    };
+                    price_cents: {
+                        type: string;
+                        description: string;
+                    };
+                };
+                required: string[];
+                description: string;
+            };
+            consumption: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            attestation: {
+                type: string;
+                properties: {
+                    original_work: {
+                        type: string;
+                        description: string;
+                    };
+                    no_secrets: {
+                        type: string;
+                        description: string;
+                    };
+                    terms_accepted: {
+                        type: string;
+                        description: string;
+                    };
+                };
+                required: string[];
+                description: string;
+            };
+            preview: {
+                type: string;
+                description: string;
+            };
+            entries: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            tags: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            license: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handler(args: unknown): Promise<PublishResult>;
+};
+export default libraryPublishTool;