@telvok/librarian-mcp 1.5.4 → 2.3.0

package/dist/tools 2/marketplace-publish.js

@@ -0,0 +1,377 @@
+// ============================================================================
+// Marketplace Publish Tool
+// Publish local entries as a book on Telvok marketplace
+// ============================================================================
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { glob } from 'glob';
+import matter from 'gray-matter';
+import { loadApiKey } from './auth.js';
+import { getLibraryPath, getLocalPath } from '../library/storage.js';
+const TELVOK_API_URL = process.env.TELVOK_API_URL || 'https://telvok.com';
+// ============================================================================
+// Tool Definition
+// ============================================================================
+export const marketplacePublishTool = {
+    name: 'marketplace_publish',
+    description: `Publish local entries as a book on Telvok marketplace.
+
+Collects entries from .librarian/local/ and publishes them as a book.
+Users can browse and purchase your book on telvok.com.
+
+Required fields:
+- name: Book title
+- pricing: { type: "open" | "one_time" | "subscription", price_cents? }
+- consumption: How buyers access content ("inline" | "reference" | "download")
+- attestation: { original_work: true, no_secrets: true, terms_accepted: true }
+
+Consumption types:
+- "inline": Full content in API responses (all pricing)
+- "reference": README + pointers to entries (all pricing)
+- "download": Download to local library (only for free/open books)
+
+Use preview: true to see what would be published without actually publishing.
+
+Examples:
+- Preview: marketplace_publish({ name: "My Book", pricing: { type: "open" }, preview: true })
+- Publish: marketplace_publish({ name: "My Book", pricing: { type: "open" }, consumption: "download", attestation: { original_work: true, no_secrets: true, terms_accepted: true } })`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            name: {
+                type: 'string',
+                description: 'Book title (3-100 characters)',
+            },
+            description: {
+                type: 'string',
+                description: 'Short description of the book (optional, max 500 chars)',
+            },
+            pricing: {
+                type: 'object',
+                properties: {
+                    type: {
+                        type: 'string',
+                        enum: ['open', 'one_time', 'subscription'],
+                        description: 'Pricing model',
+                    },
+                    price_cents: {
+                        type: 'number',
+                        description: 'Price in cents (required for paid, min 100 = $1.00)',
+                    },
+                },
+                required: ['type'],
+                description: 'Pricing configuration',
+            },
+            consumption: {
+                type: 'string',
+                enum: ['inline', 'reference', 'download'],
+                description: 'How buyers access content. download only for free books.',
+            },
+            attestation: {
+                type: 'object',
+                properties: {
+                    original_work: { type: 'boolean', description: 'Confirm this is original work' },
+                    no_secrets: { type: 'boolean', description: 'Confirm no secrets/credentials' },
+                    terms_accepted: { type: 'boolean', description: 'Accept marketplace terms' },
+                },
+                required: ['original_work', 'no_secrets', 'terms_accepted'],
+                description: 'Required confirmations before publishing',
+            },
+            preview: {
+                type: 'boolean',
+                description: 'If true, show what would be published without publishing',
+            },
+            entries: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Specific entry filenames to include (omit for all local/)',
+            },
+            tags: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Category/topic tags (max 10)',
+            },
+            license: {
+                type: 'string',
+                enum: ['open', 'open_attributed', 'personal'],
+                description: 'License type (default: personal)',
+            },
+        },
+        required: ['name', 'pricing'],
+    },
+    async handler(args) {
+        const { name, description, pricing, consumption, attestation, preview, entries: entryFilter, tags, license } = args;
+        // Validate name
+        if (!name || typeof name !== 'string' || name.trim().length < 3) {
+            throw new Error('Book name is required (minimum 3 characters)');
+        }
+        if (name.trim().length > 100) {
+            throw new Error('Book name must be 100 characters or less');
+        }
+        // Validate pricing
+        if (!pricing || !pricing.type) {
+            throw new Error('Pricing type is required');
+        }
+        if (!['open', 'one_time', 'subscription'].includes(pricing.type)) {
+            throw new Error('Pricing type must be: open, one_time, or subscription');
+        }
+        if (pricing.type !== 'open' && (!pricing.price_cents || pricing.price_cents < 100)) {
+            throw new Error('Paid books require price_cents >= 100 ($1.00)');
+        }
+        // Collect entries from local/ (needed for preview and publish)
+        const collectedEntries = await collectLocalEntries(entryFilter);
+        if (collectedEntries.length === 0) {
+            return {
+                success: false,
+                message: 'No entries found in .librarian/local/. Use record() to create entries first.',
+            };
+        }
+        // Format pricing display
+        const pricingDisplay = pricing.type === 'open'
+            ? 'Free'
+            : `$${((pricing.price_cents || 0) / 100).toFixed(2)}`;
+        // Handle preview mode - return summary without publishing
+        if (preview) {
+            return {
+                success: true,
+                preview: true,
+                message: `Preview of "${name.trim()}" - NOT published`,
+                summary: {
+                    name: name.trim(),
+                    pricing: { type: pricing.type, display: pricingDisplay },
+                    entries_count: collectedEntries.length,
+                    entries: collectedEntries.map(e => ({
+                        title: e.title,
+                        file: path.basename(e.originalPath),
+                    })),
+                },
+                next_steps: 'To publish, add consumption type and attestation fields.',
+            };
+        }
+        // Validate consumption type (required for actual publish)
+        if (!consumption) {
+            return {
+                success: false,
+                message: 'Consumption type required. Choose how buyers access your content:',
+                options: {
+                    inline: 'Content returned in API responses (best for small entries)',
+                    reference: 'README + pointers to entries (best for larger books)',
+                    download: 'Download to local library (only for free/open books)',
+                },
+            };
+        }
+        if (!['inline', 'reference', 'download'].includes(consumption)) {
+            return {
+                success: false,
+                message: 'Invalid consumption type. Must be: inline, reference, or download',
+            };
+        }
+        if (consumption === 'download' && pricing.type !== 'open') {
+            return {
+                success: false,
+                message: 'Download is only for free books. Paid content uses inline or reference.',
+                next_steps: "Use pricing.type: 'open' for download, or consumption: 'inline'/'reference' for paid.",
+            };
+        }
+        // Validate attestation (required for actual publish)
+        if (!attestation) {
+            return {
+                success: false,
+                message: 'Attestation required. Please confirm:',
+                required: {
+                    original_work: 'This is my original work or I have rights to publish',
+                    no_secrets: 'Contains no secrets, credentials, or sensitive data',
+                    terms_accepted: 'I accept the Telvok marketplace terms',
+                },
+            };
+        }
+        const failedAttestations = [];
+        if (!attestation.original_work)
+            failedAttestations.push('original_work');
+        if (!attestation.no_secrets)
+            failedAttestations.push('no_secrets');
+        if (!attestation.terms_accepted)
+            failedAttestations.push('terms_accepted');
+        if (failedAttestations.length > 0) {
+            return {
+                success: false,
+                message: `All attestation fields must be true to publish. Failed: ${failedAttestations.join(', ')}`,
+            };
+        }
+        // Check authentication
+        const apiKey = await loadApiKey();
+        if (!apiKey) {
+            return {
+                success: false,
+                message: 'Not authenticated. Run auth({ action: "login" }) to connect your Telvok account first.',
+            };
+        }
+        // Format entries for API
+        const apiEntries = collectedEntries.map(e => ({
+            title: e.title,
+            content: e.content,
+            intent: e.intent,
+            context: e.context,
+            reasoning: e.reasoning,
+            example: e.example,
+        }));
+        // Build request body
+        const requestBody = {
+            name: name.trim(),
+            description: description?.trim(),
+            pricing,
+            consumption,
+            entries: apiEntries,
+            tags: tags || [],
+            license_type: license || 'personal',
+            attestation,
+        };
+        try {
+            const response = await fetch(`${TELVOK_API_URL}/api/publish`, {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${apiKey}`,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify(requestBody),
+            });
+            const data = await response.json();
+            if (!response.ok) {
+                // Handle Stripe Connect requirement
+                if (data.error === 'stripe_connect_required') {
+                    return {
+                        success: false,
+                        message: `Stripe Connect required to sell paid content.\n\nComplete setup at: ${data.setup_url}`,
+                        setup_url: data.setup_url,
+                    };
+                }
+                // Handle validation errors
+                if (data.error === 'validation_error') {
+                    const details = Object.entries(data.details || {})
+                        .map(([k, v]) => `  - ${k}: ${v}`)
+                        .join('\n');
+                    return {
+                        success: false,
+                        message: `Validation failed:\n${details}`,
+                    };
+                }
+                return {
+                    success: false,
+                    message: data.error || `Publish failed: HTTP ${response.status}`,
+                };
+            }
+            return {
+                success: true,
+                message: data.message || `Published "${data.book?.name}" with ${data.entries_count} entries`,
+                book: data.book,
+                entries_count: data.entries_count,
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Publish failed: ${message}`);
+        }
+    },
+};
+// ============================================================================
+// Entry Collection
+// ============================================================================
+async function collectLocalEntries(filter) {
+    const libraryPath = getLibraryPath();
+    const localPath = getLocalPath(libraryPath);
+    const entries = [];
+    try {
+        const files = await glob(path.join(localPath, '**/*.md'), { nodir: true });
+        for (const filePath of files) {
+            const filename = path.basename(filePath);
+            // If filter specified, only include matching files
+            if (filter && filter.length > 0) {
+                const matchesFilter = filter.some(f => filename === f ||
+                    filename === f + '.md' ||
+                    filePath.endsWith(f) ||
+                    filePath.endsWith(f + '.md'));
+                if (!matchesFilter)
+                    continue;
+            }
+            try {
+                const content = await fs.readFile(filePath, 'utf-8');
+                const parsed = parseEntryFile(content, filePath);
+                if (parsed) {
+                    entries.push({
+                        ...parsed,
+                        originalPath: filePath,
+                    });
+                }
+            }
+            catch {
+                // Skip files that can't be parsed
+            }
+        }
+    }
+    catch {
+        // No local directory yet
+    }
+    return entries;
+}
+function parseEntryFile(content, filePath) {
+    const { data: frontmatter, content: body } = matter(content);
+    const trimmedBody = body.trim();
+    if (!trimmedBody)
+        return null;
+    // Extract title from frontmatter, H1, or filename
+    let title = frontmatter.title;
+    if (!title) {
+        const headingMatch = trimmedBody.match(/^#\s+(.+)$/m);
+        if (headingMatch) {
+            title = headingMatch[1].trim();
+        }
+        else {
+            // Use filename as title, converting hyphens to spaces
+            title = path.basename(filePath, '.md')
+                .replace(/-/g, ' ')
+                .replace(/\b\w/g, l => l.toUpperCase());
+        }
+    }
+    // Extract sections from body
+    const sections = extractSections(trimmedBody);
+    return {
+        title,
+        content: sections.main || trimmedBody,
+        intent: frontmatter.intent || undefined,
+        context: frontmatter.context || undefined,
+        reasoning: sections.reasoning,
+        example: sections.example,
+    };
+}
+function extractSections(body) {
+    const result = {
+        main: body,
+    };
+    // Find ## Reasoning section
+    const reasoningMatch = body.match(/##\s*Reasoning\s*\n([\s\S]*?)(?=##|$)/i);
+    if (reasoningMatch) {
+        result.reasoning = reasoningMatch[1].trim();
+    }
+    // Find ## Example section
+    const exampleMatch = body.match(/##\s*Example\s*\n([\s\S]*?)(?=##|$)/i);
+    if (exampleMatch) {
+        result.example = exampleMatch[1].trim();
+    }
+    // Main content is everything after title until first ## section
+    const mainMatch = body.match(/^#\s+.+\n\n?([\s\S]*?)(?=##|$)/);
+    if (mainMatch) {
+        result.main = mainMatch[1].trim();
+    }
+    else {
+        // If no H1 header, take content before first ## section
+        const beforeSections = body.match(/^([\s\S]*?)(?=##)/);
+        if (beforeSections) {
+            result.main = beforeSections[1].trim();
+        }
+    }
+    return result;
+}
+// ============================================================================
+// Export
+// ============================================================================
+export default marketplacePublishTool;

package/dist/tools 2/marketplace-search.d.ts

@@ -0,0 +1,57 @@
+interface BookResult {
+    slug: string;
+    name: string;
+    description: string;
+    pricing: 'open' | 'one_time' | 'subscription';
+    price: string;
+    entries: number;
+    rating: number | null;
+    tags: string[];
+}
+interface SearchResult {
+    books: BookResult[];
+    total: number;
+    message: string;
+}
+export declare const marketplaceSearchTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            query: {
+                type: string;
+                description: string;
+            };
+            filters: {
+                type: string;
+                properties: {
+                    pricing: {
+                        type: string;
+                        enum: string[];
+                        description: string;
+                    };
+                    tags: {
+                        type: string;
+                        items: {
+                            type: string;
+                        };
+                        description: string;
+                    };
+                    min_rating: {
+                        type: string;
+                        description: string;
+                    };
+                };
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+            };
+        };
+        required: never[];
+    };
+    handler(args: unknown): Promise<SearchResult>;
+};
+export {};

package/dist/tools 2/marketplace-search.js

@@ -0,0 +1,96 @@
+// ============================================================================
+// Marketplace Search Tool
+// Search for books on the Telvok marketplace
+// ============================================================================
+const TELVOK_API_URL = process.env.TELVOK_API_URL || 'https://telvok.com';
+// ============================================================================
+// Tool Definition
+// ============================================================================
+export const marketplaceSearchTool = {
+    name: 'marketplace_search',
+    description: `Search Telvok marketplace for knowledge books.
+
+Find books created by other users that you can import into your library.
+
+Examples:
+- marketplace_search({ query: "react hooks" })
+- marketplace_search({ query: "python", filters: { pricing: "open" } })
+- marketplace_search({ query: "auth", limit: 5 })
+
+Filters:
+- pricing: "open" (free), "one_time" (paid once), "subscription" (ongoing)
+- tags: Array of tags to match
+- min_rating: Minimum quality score (0-5)`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            query: {
+                type: 'string',
+                description: 'Search terms to find books',
+            },
+            filters: {
+                type: 'object',
+                properties: {
+                    pricing: {
+                        type: 'string',
+                        enum: ['open', 'one_time', 'subscription'],
+                        description: 'Filter by pricing type',
+                    },
+                    tags: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Filter by tags',
+                    },
+                    min_rating: {
+                        type: 'number',
+                        description: 'Minimum quality rating (0-5)',
+                    },
+                },
+                description: 'Optional filters to narrow results',
+            },
+            limit: {
+                type: 'number',
+                description: 'Maximum results to return (default: 10)',
+            },
+        },
+        required: [], // Query is optional - empty returns all books (browse mode)
+    },
+    async handler(args) {
+        const { query = '', filters, limit = 10 } = args;
+        try {
+            const response = await fetch(`${TELVOK_API_URL}/api/search`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ query, filters, limit }),
+            });
+            if (!response.ok) {
+                const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+                throw new Error(error.error || `Search failed: HTTP ${response.status}`);
+            }
+            const data = await response.json();
+            // Format results for agent consumption
+            const books = data.books || [];
+            const total = data.total || 0;
+            if (books.length === 0) {
+                const queryMsg = query ? `for "${query}"` : 'matching your filters';
+                return {
+                    books: [],
+                    total: 0,
+                    message: `No books found ${queryMsg}. Try different search terms or filters.`,
+                };
+            }
+            // Build helpful summary
+            const summary = books.map((b, i) => `${i + 1}. **${b.name}** (${b.price}) - ${b.entries} entries\n   ${b.description?.slice(0, 100)}${b.description?.length > 100 ? '...' : ''}`).join('\n');
+            const queryMsg = query ? `for "${query}"` : 'in marketplace';
+            return {
+                books,
+                total,
+                message: `Found ${total} book(s) ${queryMsg}:\n\n${summary}\n\nUse marketplace_buy({ slug: "..." }) to purchase a book.`,
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Marketplace search failed: ${message}`);
+        }
+    },
+};

package/dist/tools 2/my-books.d.ts

@@ -0,0 +1,50 @@
+interface PublishedBook {
+    slug: string;
+    name: string;
+    entries_count: number;
+    pricing: {
+        type: string;
+        display: string;
+    };
+    created_at: string;
+    url: string;
+}
+interface PurchasedBook {
+    slug: string;
+    name: string;
+    author: string;
+    entries_count: number;
+    pricing: {
+        type: string;
+        display: string;
+    };
+    purchased_at: string;
+    status: string;
+}
+interface MyBooksResult {
+    success: boolean;
+    message: string;
+    published?: PublishedBook[];
+    purchased?: PurchasedBook[];
+    summary?: {
+        published_count: number;
+        purchased_count: number;
+    };
+}
+export declare const myBooksTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            filter: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+        };
+        required: never[];
+    };
+    handler(args: unknown): Promise<MyBooksResult>;
+};
+export default myBooksTool;

package/dist/tools 2/my-books.js

@@ -0,0 +1,107 @@
+// ============================================================================
+// My Books Tool
+// View published and purchased books from Telvok marketplace
+// ============================================================================
+import { loadApiKey } from './auth.js';
+const TELVOK_API_URL = process.env.TELVOK_API_URL || 'https://telvok.com';
+// ============================================================================
+// Tool Definition
+// ============================================================================
+export const myBooksTool = {
+    name: 'my_books',
+    description: `View your published and purchased books from Telvok marketplace.
+
+Shows:
+- Published: Books you've created and published
+- Purchased: Books you've bought or claimed (active status)
+
+Requires authentication. Run auth({ action: "login" }) first if not connected.
+
+Examples:
+- my_books() - Show all your books
+- my_books({ filter: "published" }) - Only your published books
+- my_books({ filter: "purchased" }) - Only books you've bought`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            filter: {
+                type: 'string',
+                enum: ['all', 'published', 'purchased'],
+                description: 'Filter results (default: all)',
+            },
+        },
+        required: [],
+    },
+    async handler(args) {
+        const { filter = 'all' } = (args || {});
+        // Validate filter
+        if (filter && !['all', 'published', 'purchased'].includes(filter)) {
+            return {
+                success: false,
+                message: 'Invalid filter. Must be: all, published, or purchased',
+            };
+        }
+        // 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 url = new URL(`${TELVOK_API_URL}/api/my-books`);
+            if (filter && filter !== 'all') {
+                url.searchParams.set('filter', filter);
+            }
+            const response = await fetch(url.toString(), {
+                method: 'GET',
+                headers: {
+                    'Authorization': `Bearer ${apiKey}`,
+                },
+            });
+            const data = await response.json();
+            if (!response.ok) {
+                return {
+                    success: false,
+                    message: data.error || `Failed to fetch books: HTTP ${response.status}`,
+                };
+            }
+            // Format output message
+            const publishedCount = data.published?.length || 0;
+            const purchasedCount = data.purchased?.length || 0;
+            let message = '';
+            if (filter === 'published') {
+                message = publishedCount === 0
+                    ? 'You haven\'t published any books yet.'
+                    : `You have ${publishedCount} published book${publishedCount === 1 ? '' : 's'}.`;
+            }
+            else if (filter === 'purchased') {
+                message = purchasedCount === 0
+                    ? 'You haven\'t purchased any books yet.'
+                    : `You have ${purchasedCount} purchased book${purchasedCount === 1 ? '' : 's'}.`;
+            }
+            else {
+                const total = publishedCount + purchasedCount;
+                message = total === 0
+                    ? 'No books yet. Publish with marketplace_publish() or browse with marketplace_search().'
+                    : `${publishedCount} published, ${purchasedCount} purchased.`;
+            }
+            return {
+                success: true,
+                message,
+                published: data.published,
+                purchased: data.purchased,
+                summary: data.summary,
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to fetch books: ${message}`);
+        }
+    },
+};
+// ============================================================================
+// Export
+// ============================================================================
+export default myBooksTool;