@telvok/librarian-mcp 1.5.3 → 2.0.0

package/dist/tools/auth.js

@@ -0,0 +1,379 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { getLibraryPath } from '../library/storage.js';
+// ============================================================================
+// Constants
+// ============================================================================
+const TELVOK_API_URL = process.env.TELVOK_API_URL || 'https://telvok.com';
+// ============================================================================
+// Tool Definition
+// ============================================================================
+export const authTool = {
+    name: 'auth',
+    title: 'Manage Authentication',
+    description: `Handle Telvok library authentication.
+
+USE THIS TOOL WHEN:
+- Any library operation fails with "authentication required"
+- User wants to access marketplace features (buy, publish, sync)
+- Checking if we're logged in before marketplace operations
+- Key is expiring soon (< 7 days) → use refresh action
+
+Actions:
+- login: Start device code flow. Returns code for telvok.com/device
+- complete: After user authorizes, finish login and save credentials
+- refresh: Rotate API key before expiration (call when < 7 days left)
+- status: Check if authenticated and show expiration
+- logout: Remove credentials AND revoke key on server (key becomes immediately invalid)
+- revoke: Same as logout - immediately invalidates the API key everywhere
+
+TRIGGER PATTERNS:
+- "auth required" error → auth({ action: 'login' })
+- User completed browser auth → auth({ action: 'complete' })
+- Expiring soon warning → auth({ action: 'refresh' })
+- Key compromised → auth({ action: 'revoke' }) to immediately invalidate`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            action: {
+                type: 'string',
+                enum: ['login', 'complete', 'logout', 'status', 'refresh', 'revoke'],
+                description: 'Auth action to perform',
+            },
+        },
+        required: ['action'],
+    },
+    outputSchema: {
+        type: 'object',
+        properties: {
+            authenticated: { type: 'boolean' },
+            user_email: { type: 'string' },
+            user_id: { type: 'string' },
+            message: { type: 'string' },
+            verification_url: { type: 'string' },
+            user_code: { type: 'string' },
+            expires_at: { type: 'string' },
+            days_until_expiry: { type: 'number' },
+        },
+        required: ['authenticated', 'message'],
+    },
+    async handler(args) {
+        const { action } = args;
+        const libraryPath = getLibraryPath();
+        const authFile = path.join(libraryPath, '.auth');
+        const pendingFile = path.join(libraryPath, '.auth-pending');
+        switch (action) {
+            case 'status':
+                return await checkStatus(authFile);
+            case 'logout':
+            case 'revoke':
+                // Both logout and revoke now invalidate the key server-side
+                return await revokeAndLogout(authFile);
+            case 'login':
+                return await login(authFile, pendingFile);
+            case 'complete':
+                return await completeLogin(authFile, pendingFile);
+            case 'refresh':
+                return await refreshKey(authFile);
+            default:
+                throw new Error(`Unknown action: ${action}`);
+        }
+    },
+};
+// ============================================================================
+// Action Handlers
+// ============================================================================
+async function checkStatus(authFile) {
+    try {
+        const content = await fs.readFile(authFile, 'utf-8');
+        const data = JSON.parse(content);
+        let message = `Authenticated as ${data.user_email}`;
+        let daysUntilExpiry;
+        // Check expiration
+        if (data.expires_at) {
+            const expiresAt = new Date(data.expires_at);
+            const now = new Date();
+            const msUntilExpiry = expiresAt.getTime() - now.getTime();
+            daysUntilExpiry = Math.floor(msUntilExpiry / (1000 * 60 * 60 * 24));
+            if (daysUntilExpiry <= 0) {
+                return {
+                    authenticated: false,
+                    message: 'API key has expired. Use auth({ action: "login" }) to get a new key.',
+                };
+            }
+            else if (daysUntilExpiry <= 7) {
+                message += ` ⚠️ Key expires in ${daysUntilExpiry} days! Use auth({ action: "refresh" }) to renew.`;
+            }
+            else {
+                message += ` (expires in ${daysUntilExpiry} days)`;
+            }
+        }
+        return {
+            authenticated: true,
+            user_email: data.user_email,
+            user_id: data.user_id,
+            message,
+            expires_at: data.expires_at,
+            days_until_expiry: daysUntilExpiry,
+        };
+    }
+    catch {
+        return {
+            authenticated: false,
+            message: 'Not authenticated. Use auth({ action: "login" }) to connect your Telvok account.',
+        };
+    }
+}
+async function revokeAndLogout(authFile) {
+    // Read current credentials to revoke server-side
+    let authData = null;
+    try {
+        const content = await fs.readFile(authFile, 'utf-8');
+        authData = JSON.parse(content);
+    }
+    catch {
+        return {
+            authenticated: false,
+            message: 'Already logged out.',
+        };
+    }
+    // Try to revoke on server (but don't fail if server is down)
+    let serverRevoked = false;
+    if (authData?.api_key) {
+        try {
+            const response = await fetch(`${TELVOK_API_URL}/api/auth/revoke`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Authorization': `Bearer ${authData.api_key}`,
+                },
+            });
+            if (response.ok) {
+                serverRevoked = true;
+            }
+            else if (response.status === 401) {
+                // Key already invalid, that's fine
+                serverRevoked = true;
+            }
+        }
+        catch {
+            // Server unreachable, still delete local file
+        }
+    }
+    // Always delete local file
+    try {
+        await fs.unlink(authFile);
+    }
+    catch {
+        // File already gone
+    }
+    const message = serverRevoked
+        ? 'Logged out and API key revoked. The key is now invalid everywhere.'
+        : 'Logged out locally. Note: Could not reach server to revoke key (it will expire in 90 days).';
+    return {
+        authenticated: false,
+        message,
+    };
+}
+async function login(authFile, pendingFile) {
+    // Check if already authenticated
+    try {
+        const content = await fs.readFile(authFile, 'utf-8');
+        const data = JSON.parse(content);
+        // Check if key is expired
+        if (data.expires_at && new Date(data.expires_at) < new Date()) {
+            // Key expired, allow new login
+            await fs.unlink(authFile).catch(() => { });
+        }
+        else {
+            return {
+                authenticated: true,
+                user_email: data.user_email,
+                user_id: data.user_id,
+                message: `Already authenticated as ${data.user_email}. Use auth({ action: "logout" }) first to switch accounts.`,
+            };
+        }
+    }
+    catch {
+        // Not authenticated, proceed with login
+    }
+    // Request a new device code
+    try {
+        const response = await fetch(`${TELVOK_API_URL}/api/auth/device`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+        });
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+            throw new Error(error.error || `HTTP ${response.status}`);
+        }
+        const data = await response.json();
+        // Save device code to pending file for later completion
+        const libraryPath = getLibraryPath();
+        await fs.mkdir(libraryPath, { recursive: true });
+        await fs.writeFile(pendingFile, JSON.stringify({
+            device_code: data.device_code,
+            user_code: data.user_code,
+            verification_url: data.verification_url,
+            created_at: new Date().toISOString(),
+        }, null, 2), 'utf-8');
+        // Return immediately with direct auth URL
+        const directAuthUrl = `${TELVOK_API_URL}/auth/${data.device_code}`;
+        return {
+            authenticated: false,
+            verification_url: directAuthUrl,
+            user_code: data.user_code,
+            message: `Click to authorize: ${directAuthUrl}\n\nAfter authorizing, call auth({ action: "complete" }) to finish.`,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to start login: ${message}`);
+    }
+}
+async function completeLogin(authFile, pendingFile) {
+    // Read pending device code
+    let deviceCode;
+    try {
+        const content = await fs.readFile(pendingFile, 'utf-8');
+        const pending = JSON.parse(content);
+        deviceCode = pending.device_code;
+    }
+    catch {
+        return {
+            authenticated: false,
+            message: 'No pending login. Call auth({ action: "login" }) first.',
+        };
+    }
+    // Poll for completion (try a few times)
+    for (let attempt = 0; attempt < 3; attempt++) {
+        try {
+            const response = await fetch(`${TELVOK_API_URL}/api/auth/device/poll`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ device_code: deviceCode }),
+            });
+            const data = await response.json();
+            if (data.status === 'pending') {
+                await sleep(2000);
+                continue;
+            }
+            if (data.status === 'expired') {
+                await fs.unlink(pendingFile).catch(() => { });
+                throw new Error('Code expired. Please call auth({ action: "login" }) to get a new code.');
+            }
+            if (data.status === 'success') {
+                // Save credentials including expiration
+                const authData = {
+                    api_key: data.api_key,
+                    user_email: data.user.email,
+                    user_id: data.user.id,
+                    created_at: new Date().toISOString(),
+                    expires_at: data.expires_at,
+                };
+                await fs.writeFile(authFile, JSON.stringify(authData, null, 2), { encoding: 'utf-8', mode: 0o600 });
+                await fs.unlink(pendingFile).catch(() => { });
+                return {
+                    authenticated: true,
+                    user_email: data.user.email,
+                    user_id: data.user.id,
+                    expires_at: data.expires_at,
+                    message: `Successfully authenticated as ${data.user.email}`,
+                };
+            }
+            throw new Error(`Unexpected status: ${data.status}`);
+        }
+        catch (error) {
+            if (error instanceof Error && (error.message.includes('expired') || error.message.includes('Unexpected'))) {
+                throw error;
+            }
+            // Network error, try again
+            await sleep(1000);
+        }
+    }
+    return {
+        authenticated: false,
+        message: 'Authorization not yet complete. Make sure you authorized at telvok.com/device, then call auth({ action: "complete" }) again.',
+    };
+}
+async function refreshKey(authFile) {
+    // Read current credentials
+    let authData;
+    try {
+        const content = await fs.readFile(authFile, 'utf-8');
+        authData = JSON.parse(content);
+    }
+    catch {
+        return {
+            authenticated: false,
+            message: 'Not authenticated. Use auth({ action: "login" }) first.',
+        };
+    }
+    // Call refresh endpoint
+    try {
+        const response = await fetch(`${TELVOK_API_URL}/api/auth/refresh`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${authData.api_key}`,
+            },
+        });
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+            if (response.status === 401) {
+                // Key expired or invalid, need to re-login
+                await fs.unlink(authFile).catch(() => { });
+                return {
+                    authenticated: false,
+                    message: 'Key expired or invalid. Use auth({ action: "login" }) to get a new key.',
+                };
+            }
+            throw new Error(error.error || `HTTP ${response.status}`);
+        }
+        const data = await response.json();
+        // Update stored credentials
+        authData.api_key = data.api_key;
+        authData.expires_at = data.expires_at;
+        await fs.writeFile(authFile, JSON.stringify(authData, null, 2), { encoding: 'utf-8', mode: 0o600 });
+        const expiresAt = new Date(data.expires_at);
+        const daysUntilExpiry = Math.floor((expiresAt.getTime() - Date.now()) / (1000 * 60 * 60 * 24));
+        return {
+            authenticated: true,
+            user_email: authData.user_email,
+            user_id: authData.user_id,
+            expires_at: data.expires_at,
+            days_until_expiry: daysUntilExpiry,
+            message: `Key refreshed! New key expires in ${daysUntilExpiry} days.`,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to refresh key: ${message}`);
+    }
+}
+// ============================================================================
+// Helpers
+// ============================================================================
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+/**
+ * Load saved API key from auth file
+ * Used by other tools that need authenticated access
+ */
+export async function loadApiKey() {
+    try {
+        const libraryPath = getLibraryPath();
+        const authFile = path.join(libraryPath, '.auth');
+        const content = await fs.readFile(authFile, 'utf-8');
+        const data = JSON.parse(content);
+        // Check if expired
+        if (data.expires_at && new Date(data.expires_at) < new Date()) {
+            return null;
+        }
+        return data.api_key;
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,28 @@
+interface BountyClaimResult {
+    success: boolean;
+    message: string;
+    bounty?: {
+        id: string;
+        title: string;
+        amount_cents: number;
+        claimed_at: string;
+    };
+    setup_url?: string;
+}
+export declare const bountyClaimTool: {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            bounty_id: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handler(args: unknown): Promise<BountyClaimResult>;
+};
+export {};

package/dist/tools/bounty-claim.js

@@ -0,0 +1,92 @@
+// ============================================================================
+// Bounty Claim Tool
+// Claim a bounty to work on it
+// ============================================================================
+import { loadApiKey } from './auth.js';
+const TELVOK_API_URL = process.env.TELVOK_API_URL || 'https://telvok.com';
+// ============================================================================
+// Tool Definition
+// ============================================================================
+export const bountyClaimTool = {
+    name: 'bounty_claim',
+    title: 'Claim Bounty',
+    description: `Claim a bounty to commit to fulfilling it.
+
+USE THIS TOOL WHEN:
+- User found a bounty they can fulfill from bounty_list()
+- User says "I'll take that bounty" or "claim this"
+
+After claiming: publish book → submit with bounty_submit() → get paid on approval.
+First come, first served. Requires Stripe Connect for payment.
+
+TRIGGER PATTERNS:
+- "Claim that bounty" → bounty_claim({ bounty_id: "<id from bounty_list>" })
+- User wants to fulfill a bounty → bounty_claim({ bounty_id: "..." })
+
+Example:
+- bounty_claim({ bounty_id: "abc123" })`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            bounty_id: {
+                type: 'string',
+                description: 'ID of the bounty to claim',
+            },
+        },
+        required: ['bounty_id'],
+    },
+    async handler(args) {
+        const { bounty_id } = args;
+        if (!bounty_id || typeof bounty_id !== 'string') {
+            return {
+                success: false,
+                message: 'bounty_id 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/bounties/${bounty_id}/claim`, {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${apiKey}`,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({}),
+            });
+            const data = await response.json();
+            if (!response.ok) {
+                // Check for payment setup required
+                if (data.setup_url) {
+                    return {
+                        success: false,
+                        message: `Payment setup required to claim bounties. Complete setup at:\n\n${data.setup_url}`,
+                        setup_url: data.setup_url,
+                    };
+                }
+                return {
+                    success: false,
+                    message: data.error || `Failed to claim bounty: HTTP ${response.status}`,
+                };
+            }
+            return {
+                success: true,
+                bounty: data.bounty,
+                message: data.message || `Bounty claimed! Now publish a book with library_publish() and submit it with bounty_submit({ bounty_id: "${bounty_id}", library_slug: "your-book-slug" })`,
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                success: false,
+                message: `Failed to claim bounty: ${message}`,
+            };
+        }
+    },
+};

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

@@ -0,0 +1,47 @@
+interface BountyCreateResult {
+    success: boolean;
+    message: string;
+    bounty?: {
+        id: string;
+        title: string;
+        amount_cents: number;
+        expires_at: string;
+    };
+    checkout_url?: string;
+}
+export declare const bountyCreateTool: {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            title: {
+                type: string;
+                description: string;
+            };
+            description: {
+                type: string;
+                description: string;
+            };
+            amount_cents: {
+                type: string;
+                description: string;
+            };
+            tags: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            expires_days: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handler(args: unknown): Promise<BountyCreateResult>;
+};
+export {};

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}`,
+            };
+        }
+    },
+};