coaiajs 0.3.2 → 0.4.0

package/dist/src/cli.js

@@ -44,6 +44,15 @@ function globals(cmd) {
 }
 function output(data, cmd) {
     if (globals(cmd).json) {
+        if (typeof data === 'string') {
+            try {
+                console.log(formatJson(JSON.parse(data)));
+                return;
+            }
+            catch {
+                // Non-JSON strings are valid command results.
+            }
+        }
         console.log(formatJson(data));
     }
     else if (typeof data === 'string') {
@@ -53,6 +62,16 @@ function output(data, cmd) {
         console.log(formatJson(data));
     }
 }
+function parseJsonValue(value) {
+    if (typeof value !== 'string')
+        return value;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}
 async function readStdin() {
     if (process.stdin.isTTY)
         return '';
@@ -242,21 +261,36 @@ function registerFuseCommands(program) {
     comments
         .command('list')
         .description('List comments')
+        .option('--object-type <type>', 'Filter by object type')
+        .option('--object-id <id>', 'Filter by object ID')
         .option('--trace-id <id>', 'Filter by trace ID')
+        .option('--author-user-id <id>', 'Filter by author user ID')
         .option('--page <n>', 'Page number', parseInt)
         .option('--limit <n>', 'Results per page', parseInt)
         .action(actionHandler(async (opts, cmd) => {
-        const result = await callModule('langfuse', 'listComments', opts);
+        const result = await callModule('langfuse', 'listComments', {
+            objectType: opts.objectType ?? (opts.traceId ? 'TRACE' : undefined),
+            objectId: opts.objectId ?? opts.traceId,
+            authorUserId: opts.authorUserId,
+            page: opts.page,
+            limit: opts.limit,
+        });
         output(result, cmd);
     }));
     comments
         .command('post')
         .description('Post a comment')
-        .option('--trace-id <id>', 'Trace ID')
-        .option('--content <text>', 'Comment content')
-        .option('--author <name>', 'Author name')
+        .requiredOption('--content <text>', 'Comment content')
+        .requiredOption('--object-type <type>', 'Object type')
+        .requiredOption('--object-id <id>', 'Object ID')
+        .option('--author-user-id <id>', 'Author user ID')
         .action(actionHandler(async (opts, cmd) => {
-        const result = await callModule('langfuse', 'postComment', opts);
+        const result = await callModule('langfuse', 'createComment', {
+            text: opts.content,
+            objectType: opts.objectType,
+            objectId: opts.objectId,
+            authorUserId: opts.authorUserId,
+        });
         output(result, cmd);
     }));
     // ── prompts ──────────────────────────────────────────────────────────
@@ -276,19 +310,40 @@ function registerFuseCommands(program) {
         .argument('<name>', 'Prompt name')
         .option('--version <n>', 'Prompt version', parseInt)
         .option('--label <label>', 'Prompt deployment label')
+        .option('--md', 'Markdown output (default)')
         .action(actionHandler(async (name, opts, cmd) => {
-        const result = await callModule('langfuse', 'getPrompt', name, opts);
-        output(result, cmd);
+        const result = await callModule('langfuse', 'getPrompt', name, {
+            version: opts.version,
+            label: opts.label,
+        });
+        if (globals(cmd).json) {
+            console.log(formatJson(typeof result === 'string' ? JSON.parse(result) : result));
+        }
+        else {
+            const markdown = await callModule('langfuse', 'formatPromptMarkdown', result);
+            console.log(markdown);
+        }
     }));
     prompts
         .command('create')
         .description('Create a prompt')
-        .option('--name <name>', 'Prompt name')
-        .option('--prompt <text>', 'Prompt text')
-        .option('--model <model>', 'Model name')
+        .requiredOption('--name <name>', 'Prompt name')
+        .requiredOption('--prompt <text>', 'Prompt text')
+        .option('--type <type>', 'Prompt type (text|chat)', 'text')
+        .option('--labels <labels>', 'Comma-separated labels')
+        .option('--tags <tags>', 'Comma-separated tags')
+        .option('--commit-message <text>', 'Commit message')
         .option('--config <json>', 'Config JSON')
         .action(actionHandler(async (opts, cmd) => {
-        const result = await callModule('langfuse', 'createPrompt', opts);
+        const result = await callModule('langfuse', 'createPrompt', {
+            name: opts.name,
+            content: opts.type === 'chat' ? parseJsonValue(opts.prompt) : opts.prompt,
+            promptType: opts.type,
+            labels: opts.labels ? String(opts.labels).split(',').map((v) => v.trim()) : undefined,
+            tags: opts.tags ? String(opts.tags).split(',').map((v) => v.trim()) : undefined,
+            commitMessage: opts.commitMessage,
+            config: parseJsonValue(opts.config),
+        });
         output(result, cmd);
     }));
     // ── datasets ─────────────────────────────────────────────────────────
@@ -313,38 +368,26 @@ function registerFuseCommands(program) {
     datasets
         .command('create')
         .description('Create a dataset')
-        .option('--name <name>', 'Dataset name')
+        .requiredOption('--name <name>', 'Dataset name')
         .option('--description <text>', 'Description')
+        .option('--metadata <json>', 'Metadata JSON')
         .action(actionHandler(async (opts, cmd) => {
-        const result = await callModule('langfuse', 'createDataset', opts);
+        const result = await callModule('langfuse', 'createDataset', {
+            ...opts,
+            metadata: parseJsonValue(opts.metadata),
+        });
         output(result, cmd);
     }));
     // ── sessions ─────────────────────────────────────────────────────────
-    const sessions = fuse.command('sessions').description('Session management');
-    sessions
-        .command('create')
-        .description('Create a session')
-        .option('--id <id>', 'Session ID')
-        .option('--project-id <id>', 'Project ID')
-        .action(actionHandler(async (opts, cmd) => {
-        const result = await callModule('langfuse', 'createSession', opts);
-        output(result, cmd);
-    }));
-    sessions
-        .command('addnode')
-        .description('Add a node to a session')
-        .option('--session-id <id>', 'Session ID')
-        .option('--trace-id <id>', 'Trace ID')
-        .action(actionHandler(async (opts, cmd) => {
-        const result = await callModule('langfuse', 'addSessionNode', opts);
-        output(result, cmd);
-    }));
+    // Langfuse v4 has no session entity endpoint. Sessions are reconstructed
+    // from observations sharing a sessionId.
+    const sessions = fuse.command('sessions').description('Session observation views');
     sessions
         .command('view')
-        .description('View a session')
+        .description('View traces reconstructed from observations in a session')
         .argument('<sessionId>', 'Session ID')
         .action(actionHandler(async (sessionId, opts, cmd) => {
-        const result = await callModule('langfuse', 'viewSession', sessionId);
+        const result = await callModule('langfuse', 'sessionView', sessionId);
         output(result, cmd);
     }));
     // ── scores ───────────────────────────────────────────────────────────
@@ -352,11 +395,11 @@ function registerFuseCommands(program) {
     scores
         .command('create')
         .description('Create a score')
-        .option('--name <name>', 'Score name')
+        .requiredOption('--name <name>', 'Score name')
         .option('--trace-id <id>', 'Trace ID')
         .option('--observation-id <id>', 'Observation ID')
-        .option('--value <n>', 'Score value', parseFloat)
-        .option('--data-type <type>', 'Data type (NUMERIC|CATEGORICAL|BOOLEAN)')
+        .requiredOption('--value <n>', 'Score value', parseFloat)
+        .option('--config-id <id>', 'Score config ID')
         .option('--comment <text>', 'Comment')
         .action(actionHandler(async (opts, cmd) => {
         const result = await callModule('langfuse', 'createScore', opts);
@@ -365,22 +408,32 @@ function registerFuseCommands(program) {
     scores
         .command('apply')
         .description('Apply a score config')
-        .option('--config <name>', 'Score config name')
-        .option('--trace-id <id>', 'Trace ID')
-        .option('--value <n>', 'Score value', parseFloat)
+        .requiredOption('--config <name>', 'Score config name or ID')
+        .requiredOption('--trace-id <id>', 'Trace ID')
+        .requiredOption('--value <n>', 'Score value', parseFloat)
+        .option('--observation-id <id>', 'Observation ID')
+        .option('--comment <text>', 'Comment')
         .action(actionHandler(async (opts, cmd) => {
-        const result = await callModule('langfuse', 'applyScore', opts);
+        const result = await callModule('langfuse', 'applyScoreConfig', opts.config, 'trace', opts.traceId, opts.value, opts.observationId, opts.comment);
         output(result, cmd);
     }));
     scores
         .command('list')
-        .description('List scores')
+        .description('List scores through Scores API v3')
         .option('--trace-id <id>', 'Filter by trace ID')
+        .option('--observation-id <id>', 'Filter by observation ID (requires trace ID)')
+        .option('--session-id <id>', 'Filter by session ID')
         .option('--name <name>', 'Filter by name')
-        .option('--page <n>', 'Page number', parseInt)
-        .option('--limit <n>', 'Results per page', parseInt)
+        .option('--from <timestamp>', 'Inclusive score timestamp')
+        .option('--to <timestamp>', 'Exclusive score timestamp')
+        .option('--cursor <cursor>', 'Cursor from a prior response')
+        .option('--limit <n>', 'Results per request (max 100)', parseInt)
         .action(actionHandler(async (opts, cmd) => {
-        const result = await callModule('langfuse', 'listScores', opts);
+        const result = await callModule('langfuse', 'listScores', {
+            ...opts,
+            fromTimestamp: opts.from,
+            toTimestamp: opts.to,
+        });
         output(result, cmd);
     }));
     // ── score-configs ────────────────────────────────────────────────────
@@ -405,14 +458,21 @@ function registerFuseCommands(program) {
     scc
         .command('create')
         .description('Create a score config')
-        .option('--name <name>', 'Config name')
-        .option('--data-type <type>', 'NUMERIC | CATEGORICAL | BOOLEAN')
+        .requiredOption('--name <name>', 'Config name')
+        .requiredOption('--data-type <type>', 'NUMERIC | CATEGORICAL | BOOLEAN')
         .option('--description <text>', 'Description')
         .option('--min <n>', 'Min value (NUMERIC)', parseFloat)
         .option('--max <n>', 'Max value (NUMERIC)', parseFloat)
         .option('--categories <json>', 'Categories JSON (CATEGORICAL)')
         .action(actionHandler(async (opts, cmd) => {
-        const result = await callModule('langfuse', 'createScoreConfig', opts);
+        const result = await callModule('langfuse', 'createScoreConfig', {
+            name: opts.name,
+            dataType: opts.dataType,
+            description: opts.description,
+            minValue: opts.min,
+            maxValue: opts.max,
+            categories: parseJsonValue(opts.categories),
+        });
         output(result, cmd);
     }));
     scc
@@ -420,7 +480,7 @@ function registerFuseCommands(program) {
         .description('Export score configs')
         .option('--output <path>', 'Output file path')
         .action(actionHandler(async (opts, cmd) => {
-        const result = await callModule('langfuse', 'exportScoreConfigs', opts);
+        const result = await callModule('langfuse', 'exportScoreConfigs', opts.output);
         output(result, cmd);
     }));
     scc
@@ -435,46 +495,30 @@ function registerFuseCommands(program) {
         .command('presets')
         .description('List available presets')
         .action(actionHandler(async (opts, cmd) => {
-        const result = await callModule('langfuse', 'listScoreConfigPresets');
+        const result = await callModule('langfuse', 'getBuiltInPresets');
         output(result, cmd);
     }));
     scc
         .command('apply')
-        .description('Apply a preset')
+        .description('Install a preset')
         .argument('<preset>', 'Preset name')
         .action(actionHandler(async (preset, opts, cmd) => {
-        const result = await callModule('langfuse', 'applyScoreConfigPreset', preset);
-        output(result, cmd);
-    }));
-    scc
-        .command('available')
-        .description('Show available score types')
-        .action(actionHandler(async (opts, cmd) => {
-        const result = await callModule('langfuse', 'availableScoreTypes');
-        output(result, cmd);
-    }));
-    scc
-        .command('show')
-        .description('Show a score config in detail')
-        .argument('<name>', 'Config name')
-        .action(actionHandler(async (name, opts, cmd) => {
-        const result = await callModule('langfuse', 'showScoreConfig', name);
+        const result = await callModule('langfuse', 'installPreset', preset);
         output(result, cmd);
     }));
     // ── traces ───────────────────────────────────────────────────────────
     const traces = fuse.command('traces').description('Trace operations');
     traces
         .command('list')
-        .description('List traces with optional filters')
+        .description('List traces reconstructed from Langfuse v4 observations')
         .option('--session-id <id>', 'Filter by session ID')
         .option('--user-id <id>', 'Filter by user ID')
         .option('--name <name>', 'Filter by trace name')
         .option('--tags <tags>', 'Comma-separated tags to filter by')
-        .option('--from <timestamp>', 'From timestamp (ISO 8601)')
-        .option('--to <timestamp>', 'To timestamp (ISO 8601)')
-        .option('--order-by <field>', 'Order by field')
-        .option('--page <n>', 'Page number', parseInt)
-        .option('--limit <n>', 'Items per page (default 50)', parseInt)
+        .option('--from <timestamp>', 'Observation start time from (ISO 8601)')
+        .option('--to <timestamp>', 'Observation start time to (ISO 8601)')
+        .option('--cursor <cursor>', 'Cursor from a prior response')
+        .option('--limit <n>', 'Items per request (default 50)', parseInt)
         .action(actionHandler(async (opts, cmd) => {
         const filters = {
             sessionId: opts.sessionId,
@@ -483,8 +527,7 @@ function registerFuseCommands(program) {
             tags: opts.tags ? opts.tags.split(',').map((t) => t.trim()) : undefined,
             fromTimestamp: opts.from,
             toTimestamp: opts.to,
-            orderBy: opts.orderBy,
-            page: opts.page,
+            cursor: opts.cursor,
             limit: opts.limit,
         };
         const raw = await callModule('langfuse', 'listTraces', filters);
@@ -498,25 +541,44 @@ function registerFuseCommands(program) {
     }));
     traces
         .command('create')
-        .description('Create a trace')
-        .option('--name <name>', 'Trace name')
+        .description('Create a complete root observation through OpenTelemetry')
+        .requiredOption('--name <name>', 'Trace and root observation name')
+        .option('--trace-id <id>', 'Trace ID (UUID or 32 hexadecimal characters)')
         .option('--session-id <id>', 'Session ID')
-        .option('--input <json>', 'Input JSON')
+        .option('--user-id <id>', 'User ID')
+        .option('--input <json>', 'Root observation input JSON')
+        .option('--output <json>', 'Root observation output JSON')
         .option('--metadata <json>', 'Metadata JSON')
+        .option('--tags <tags>', 'Comma-separated tags')
+        .option('--version <version>', 'Version')
+        .option('--environment <environment>', 'Environment')
         .action(actionHandler(async (opts, cmd) => {
-        const result = await callModule('langfuse', 'createTrace', opts);
+        const result = await callModule('langfuse', 'createTrace', {
+            ...opts,
+            tags: opts.tags ? String(opts.tags).split(',').map((v) => v.trim()) : undefined,
+        });
         output(result, cmd);
     }));
     traces
         .command('add-observation')
-        .description('Add an observation to a trace')
-        .option('--trace-id <id>', 'Trace ID')
-        .option('--name <name>', 'Observation name')
-        .option('--type <type>', 'Type: generation | span | event')
+        .description('Export a complete immutable observation through OpenTelemetry')
+        .requiredOption('--trace-id <id>', 'Trace ID')
+        .requiredOption('--name <name>', 'Observation name')
+        .option('--type <type>', 'Type: generation | span | event', 'event')
+        .option('--parent-id <id>', 'Parent observation ID')
         .option('--input <json>', 'Input JSON')
         .option('--output <json>', 'Output JSON')
+        .option('--metadata <json>', 'Metadata JSON')
+        .option('--trace-name <name>', 'Propagated trace name')
+        .option('--session-id <id>', 'Propagated session ID')
+        .option('--user-id <id>', 'Propagated user ID')
+        .option('--tags <tags>', 'Comma-separated propagated tags')
+        .option('--model <model>', 'Model name for generation observations')
         .action(actionHandler(async (opts, cmd) => {
-        const result = await callModule('langfuse', 'addObservation', opts);
+        const result = await callModule('langfuse', 'addObservation', {
+            ...opts,
+            tags: opts.tags ? String(opts.tags).split(',').map((v) => v.trim()) : undefined,
+        });
         output(result, cmd);
     }));
     traces
@@ -533,15 +595,6 @@ function registerFuseCommands(program) {
         const result = await callModule('langfuse', 'addObservations', data);
         output(result, cmd);
     }));
-    traces
-        .command('patch-output')
-        .description('Patch trace output')
-        .option('--trace-id <id>', 'Trace ID')
-        .option('--output <json>', 'Output JSON')
-        .action(actionHandler(async (opts, cmd) => {
-        const result = await callModule('langfuse', 'patchTraceOutput', opts);
-        output(result, cmd);
-    }));
     traces
         .command('session-view')
         .description('View traces by session')
@@ -580,9 +633,18 @@ function registerFuseCommands(program) {
         .command('upload')
         .description('Upload a media file')
         .argument('<file>', 'File path')
-        .option('--trace-id <id>', 'Associate with trace')
+        .requiredOption('--trace-id <id>', 'Associate with trace')
+        .option('--observation-id <id>', 'Associate with observation')
+        .option('--field <field>', 'Attach to input, output, or metadata', 'input')
+        .option('--content-type <type>', 'MIME type override')
         .action(actionHandler(async (file, opts, cmd) => {
-        const result = await callModule('langfuse', 'uploadMedia', resolve(file), opts);
+        const result = await callModule('langfuse', 'uploadAndAttachMedia', {
+            filePath: resolve(file),
+            traceId: opts.traceId,
+            observationId: opts.observationId,
+            field: opts.field,
+            contentType: opts.contentType,
+        });
         output(result, cmd);
     }));
     media
@@ -598,12 +660,21 @@ function registerFuseCommands(program) {
     datasetItems
         .command('create')
         .description('Create a dataset item')
-        .option('--dataset <name>', 'Dataset name')
-        .option('--input <json>', 'Input JSON')
+        .requiredOption('--dataset <name>', 'Dataset name')
+        .requiredOption('--input <json>', 'Input JSON')
         .option('--expected <json>', 'Expected output JSON')
         .option('--metadata <json>', 'Metadata JSON')
+        .option('--source-trace-id <id>', 'Source trace ID')
+        .option('--source-observation-id <id>', 'Source observation ID')
         .action(actionHandler(async (opts, cmd) => {
-        const result = await callModule('langfuse', 'createDatasetItem', opts);
+        const result = await callModule('langfuse', 'createDatasetItem', {
+            datasetName: opts.dataset,
+            input: parseJsonValue(opts.input),
+            expectedOutput: parseJsonValue(opts.expected),
+            metadata: parseJsonValue(opts.metadata),
+            sourceTraceId: opts.sourceTraceId,
+            sourceObservationId: opts.sourceObservationId,
+        });
         output(result, cmd);
     }));
 }