@telvok/librarian-mcp 1.5.4 → 2.0.0

package/dist/tools/bounty-create.js

@@ -0,0 +1,118 @@
+// ============================================================================
+// Bounty Create Tool
+// Create a bounty on the Telvok marketplace
+// ============================================================================
+import { loadApiKey } from './auth.js';
+const TELVOK_API_URL = process.env.TELVOK_API_URL || 'https://telvok.com';
+// ============================================================================
+// Tool Definition
+// ============================================================================
+export const bountyCreateTool = {
+    name: 'bounty_create',
+    title: 'Create Bounty',
+    description: `Create a knowledge bounty when you need specific expertise.
+
+USE THIS TOOL WHEN:
+- User needs knowledge that doesn't exist in marketplace
+- User says "I'd pay for someone to explain X"
+- Searching shows no results for a topic user needs
+
+Sellers claim bounties, publish relevant books, and get paid when you approve.
+Bounty held in escrow until approval. Platform fee: 20%. Minimum: $5 (500 cents)
+
+TRIGGER PATTERNS:
+- Need expertise that doesn't exist → bounty_create({ title: "...", amount_cents: 2000 })
+- "I'd pay for auth patterns" → bounty_create({ title: "Auth best practices", amount_cents: 2000 })
+
+Examples:
+- bounty_create({ title: "Stripe webhook patterns", amount_cents: 2000 })
+- bounty_create({ title: "Auth best practices", description: "Need JWT refresh patterns", amount_cents: 5000, tags: ["auth", "jwt"] })`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            title: {
+                type: 'string',
+                description: 'What knowledge you need (3+ characters)',
+            },
+            description: {
+                type: 'string',
+                description: 'Additional details about what you need',
+            },
+            amount_cents: {
+                type: 'number',
+                description: 'Bounty amount in cents (minimum 500 = $5)',
+            },
+            tags: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Tags to help sellers find your bounty',
+            },
+            expires_days: {
+                type: 'number',
+                description: 'Days until bounty expires (default: 30)',
+            },
+        },
+        required: ['title', 'amount_cents'],
+    },
+    async handler(args) {
+        const { title, description, amount_cents, tags, expires_days } = args;
+        // Validate inputs
+        if (!title || typeof title !== 'string' || title.length < 3) {
+            return {
+                success: false,
+                message: 'Title must be at least 3 characters',
+            };
+        }
+        if (!amount_cents || typeof amount_cents !== 'number' || amount_cents < 500) {
+            return {
+                success: false,
+                message: 'Minimum bounty amount is $5 (500 cents)',
+            };
+        }
+        // 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/bounties`, {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${apiKey}`,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    title,
+                    description,
+                    amount_cents,
+                    tags,
+                    expires_days,
+                }),
+            });
+            const data = await response.json();
+            if (!response.ok) {
+                return {
+                    success: false,
+                    message: data.error || `Failed to create bounty: HTTP ${response.status}`,
+                };
+            }
+            const amount = `$${(amount_cents / 100).toFixed(2)}`;
+            return {
+                success: true,
+                bounty: data.bounty,
+                checkout_url: data.checkout_url,
+                message: `Bounty created! Complete payment to activate:\n\n${data.checkout_url}\n\nBounty: "${title}" (${amount})`,
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                success: false,
+                message: `Failed to create bounty: ${message}`,
+            };
+        }
+    },
+};

package/dist/tools/bounty-list.d.ts

@@ -0,0 +1,50 @@
+interface BountyItem {
+    id: string;
+    title: string;
+    description: string | null;
+    amount: string;
+    amount_cents: number;
+    tags: string[] | null;
+    status: string;
+    created_at: string;
+    expires_at: string;
+}
+interface BountyListResult {
+    success: boolean;
+    message: string;
+    bounties: BountyItem[];
+    total: number;
+}
+export declare const bountyListTool: {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            query: {
+                type: string;
+                description: string;
+            };
+            status: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            tags: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+            };
+        };
+        required: never[];
+    };
+    handler(args: unknown): Promise<BountyListResult>;
+};
+export {};

package/dist/tools/bounty-list.js

@@ -0,0 +1,116 @@
+// ============================================================================
+// Bounty List Tool
+// List open bounties on the Telvok marketplace
+// ============================================================================
+const TELVOK_API_URL = process.env.TELVOK_API_URL || 'https://telvok.com';
+// ============================================================================
+// Tool Definition
+// ============================================================================
+export const bountyListTool = {
+    name: 'bounty_list',
+    title: 'List Bounties',
+    description: `Browse bounties to find knowledge requests you can fulfill.
+
+USE THIS TOOL WHEN:
+- User wants to earn by sharing expertise
+- Looking for topics people will pay for
+- User asks "what bounties are available"
+
+Claim a bounty → publish relevant book → get paid when approved.
+
+TRIGGER PATTERNS:
+- "What bounties can I fulfill?" → bounty_list()
+- Looking for earning opportunities → bounty_list({ query: "<user expertise>" })
+- "Show stripe bounties" → bounty_list({ query: "stripe" })
+
+Examples:
+- bounty_list() - Show all open bounties
+- bounty_list({ query: "stripe" }) - Search for Stripe-related bounties
+- bounty_list({ tags: ["auth", "security"] }) - Filter by tags`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            query: {
+                type: 'string',
+                description: 'Search terms to filter bounties',
+            },
+            status: {
+                type: 'string',
+                enum: ['open', 'all'],
+                description: 'Filter by status (default: open)',
+            },
+            tags: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Filter by tags',
+            },
+            limit: {
+                type: 'number',
+                description: 'Maximum results (default: 20, max: 50)',
+            },
+        },
+        required: [],
+    },
+    async handler(args) {
+        const { query, status = 'open', tags, limit = 20 } = (args || {});
+        try {
+            // Build query params
+            const params = new URLSearchParams();
+            params.set('status', status);
+            params.set('limit', String(Math.min(limit, 50)));
+            if (query) {
+                params.set('query', query);
+            }
+            if (tags && tags.length > 0) {
+                params.set('tags', tags.join(','));
+            }
+            const response = await fetch(`${TELVOK_API_URL}/api/bounties?${params}`, {
+                method: 'GET',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+            });
+            const data = await response.json();
+            if (!response.ok) {
+                return {
+                    success: false,
+                    message: data.error || `Failed to fetch bounties: HTTP ${response.status}`,
+                    bounties: [],
+                    total: 0,
+                };
+            }
+            const bounties = data.bounties || [];
+            const total = data.total || 0;
+            if (bounties.length === 0) {
+                const queryMsg = query ? ` for "${query}"` : '';
+                return {
+                    success: true,
+                    message: `No open bounties found${queryMsg}. Check back later or try different search terms.`,
+                    bounties: [],
+                    total: 0,
+                };
+            }
+            // Format summary
+            const summary = bounties.map((b, i) => {
+                const tagsStr = b.tags?.length ? ` [${b.tags.join(', ')}]` : '';
+                return `${i + 1}. **${b.title}** - ${b.amount}${tagsStr}\n   ${b.description?.slice(0, 100) || 'No description'}${(b.description?.length || 0) > 100 ? '...' : ''}`;
+            }).join('\n');
+            const queryMsg = query ? ` for "${query}"` : '';
+            return {
+                success: true,
+                bounties,
+                total,
+                message: `Found ${total} bounty(s)${queryMsg}:\n\n${summary}\n\nUse bounty_claim({ bounty_id: "..." }) to claim a bounty.`,
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                success: false,
+                message: `Failed to fetch bounties: ${message}`,
+                bounties: [],
+                total: 0,
+            };
+        }
+    },
+};

package/dist/tools/bounty-submit.d.ts

@@ -0,0 +1,34 @@
+interface BountySubmitResult {
+    success: boolean;
+    message: string;
+    bounty?: {
+        id: string;
+        title: string;
+        status: string;
+    };
+    library?: {
+        slug: string;
+        name: string;
+    };
+}
+export declare const bountySubmitTool: {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            bounty_id: {
+                type: string;
+                description: string;
+            };
+            library_slug: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handler(args: unknown): Promise<BountySubmitResult>;
+};
+export {};

package/dist/tools/bounty-submit.js

@@ -0,0 +1,94 @@
+// ============================================================================
+// Bounty Submit Tool
+// Submit a book to fulfill a claimed bounty
+// ============================================================================
+import { loadApiKey } from './auth.js';
+const TELVOK_API_URL = process.env.TELVOK_API_URL || 'https://telvok.com';
+// ============================================================================
+// Tool Definition
+// ============================================================================
+export const bountySubmitTool = {
+    name: 'bounty_submit',
+    title: 'Submit Bounty',
+    description: `Submit your published book to fulfill a claimed bounty.
+
+USE THIS TOOL WHEN:
+- User has claimed a bounty AND published a book to fulfill it
+- User says "submit my book for the bounty"
+
+The bounty creator reviews and approves (releasing payment) or rejects.
+
+TRIGGER PATTERNS:
+- After library_publish() for a bounty → bounty_submit({ bounty_id: "...", library_slug: "..." })
+- "Submit my book for the bounty" → bounty_submit({ bounty_id: "...", library_slug: "..." })
+
+Example:
+- bounty_submit({ bounty_id: "abc123", library_slug: "my-webhook-patterns" })`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            bounty_id: {
+                type: 'string',
+                description: 'ID of the bounty you claimed',
+            },
+            library_slug: {
+                type: 'string',
+                description: 'Slug of your published book that fulfills the bounty',
+            },
+        },
+        required: ['bounty_id', 'library_slug'],
+    },
+    async handler(args) {
+        const { bounty_id, library_slug } = args;
+        if (!bounty_id || typeof bounty_id !== 'string') {
+            return {
+                success: false,
+                message: 'bounty_id is required',
+            };
+        }
+        if (!library_slug || typeof library_slug !== 'string') {
+            return {
+                success: false,
+                message: 'library_slug is required. Publish a book first with library_publish().',
+            };
+        }
+        // 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/bounties/${bounty_id}/submit`, {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${apiKey}`,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({ library_slug }),
+            });
+            const data = await response.json();
+            if (!response.ok) {
+                return {
+                    success: false,
+                    message: data.error || `Failed to submit: HTTP ${response.status}`,
+                };
+            }
+            return {
+                success: true,
+                bounty: data.bounty,
+                library: data.library,
+                message: data.message || `Submitted "${library_slug}" for bounty review. The creator will approve or reject your submission.`,
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                success: false,
+                message: `Failed to submit: ${message}`,
+            };
+        }
+    },
+};

package/dist/tools/brief.d.ts

@@ -7,15 +7,31 @@ export interface BriefEntry {
     created: string;
     hits: number;
     last_hit: string | null;
+    source?: 'local' | 'cloud' | 'packages';
+    book_name?: string;
+    book_slug?: string;
+}
+export interface MarketplaceBook {
+    slug: string;
+    name: string;
+    description: string;
+    pricing: string;
+    price: string;
+    entries: number;
 }
 export interface BriefResult {
     entries: BriefEntry[];
     total: number;
     message: string;
     libraryPath: string;
+    library?: {
+        books: MarketplaceBook[];
+        total: number;
+    };
 }
 export declare const briefTool: {
     name: string;
+    title: string;
     description: string;
     inputSchema: {
         type: "object";
@@ -29,8 +45,86 @@ export declare const briefTool: {
                 description: string;
                 default: number;
             };
+            include_library: {
+                type: string;
+                description: string;
+                default: boolean;
+            };
         };
         required: never[];
     };
+    outputSchema: {
+        type: "object";
+        properties: {
+            entries: {
+                type: string;
+                items: {
+                    type: string;
+                    properties: {
+                        title: {
+                            type: string;
+                        };
+                        preview: {
+                            type: string;
+                        };
+                        path: {
+                            type: string;
+                        };
+                        hits: {
+                            type: string;
+                        };
+                        source: {
+                            type: string;
+                            enum: string[];
+                        };
+                        book_name: {
+                            type: string;
+                        };
+                    };
+                };
+            };
+            total: {
+                type: string;
+            };
+            message: {
+                type: string;
+            };
+            libraryPath: {
+                type: string;
+            };
+            library: {
+                type: string;
+                properties: {
+                    books: {
+                        type: string;
+                        items: {
+                            type: string;
+                            properties: {
+                                slug: {
+                                    type: string;
+                                };
+                                name: {
+                                    type: string;
+                                };
+                                description: {
+                                    type: string;
+                                };
+                                pricing: {
+                                    type: string;
+                                };
+                                entries: {
+                                    type: string;
+                                };
+                            };
+                        };
+                    };
+                    total: {
+                        type: string;
+                    };
+                };
+            };
+        };
+        required: string[];
+    };
     handler(args: unknown): Promise<BriefResult>;
 };