feat(client): add typed Metrics API wrapper (v1/v2)

[suekou]

Thanks for creating a great tool!

Problem

I use Langfuse tracing regularly and occasionally rely on the Metrics API for aggregated analytics.
While the generated API client already exposes api.metrics and api.metricsV2, both endpoints accept the query payload as a JSON string (query URL param). In TS/JS this ends up as query: string, which lacks type safety and makes constructing and maintaining metrics queries cumbersome and error-prone.

This PR is intended as an ergonomic improvement proposal for Metrics queries. If there is a preferred direction for the SDK, feel free to close/supersede it.

Changes

• Add MetricsManager to @langfuse/client and expose it as langfuse.metrics
• Provide typed query payloads (MetricsQueryV1, MetricsQueryV2, etc.) and a serializer
• Add convenience methods:
  • metrics.query(...) / metrics.queryRaw(...) for v1
  • metrics.queryV2(...) / metrics.queryRawV2(...) for v2
• Add integration tests to validate serialization and request options passthrough

Release info Sub-libraries affected

Bump level

• Major
• Minor
• Patch

Libraries affected

• All of them
• langfuse
• langfuse-node

Changelog notes

• Added langfuse.metrics typed wrapper for Metrics API queries (v1/v2)

---

Important

Adds MetricsManager to LangfuseClient for typed Metrics API queries with v1/v2 support and integration tests.

• Behavior:
  • Adds MetricsManager to LangfuseClient for typed Metrics API queries.
  • Provides metrics.query(...) and metrics.queryV2(...) for v1 and v2 queries.
  • Supports raw query execution with metrics.queryRaw(...) and metrics.queryRawV2(...).
• Types:
  • Introduces MetricsQueryV1, MetricsQueryV2, and related types in types.ts.
  • Adds serializeMetricsQuery() for query serialization.
• Tests:
  • Adds integration tests in metrics.integration.test.ts to validate query serialization and request options.

^{This description was created by for d9b9c4f. You can customize this summary. It will automatically update as commits are pushed.}

Disclaimer: Experimental PR review

Greptile Overview

Greptile Summary

This PR adds a typed wrapper for the Langfuse Metrics API, providing type-safe query construction and improved developer experience. The implementation introduces MetricsManager which serializes typed query objects into the JSON string format required by the underlying API endpoints.

Key Changes

• Added comprehensive TypeScript types for Metrics API v1 and v2 query structures (MetricsQueryV1, MetricsQueryV2, filters, dimensions, etc.)
• Implemented MetricsManager class with convenience methods: query(), queryV2(), queryRaw(), queryRawV2()
• Integrated MetricsManager into LangfuseClient as langfuse.metrics property
• Added thorough integration tests validating serialization and request options passthrough
• All exports properly structured and documented with TSDoc comments

Design Quality

• Clean architecture following existing SDK patterns (consistent with PromptManager, ScoreManager, etc.)
• Type extraction using Parameters<> utility type ensures automatic sync with underlying API client types
• Provides both high-level typed methods and low-level queryRaw methods for advanced use cases
• Well-documented with code examples in JSDoc comments

Confidence Score: 5/5

• This PR is safe to merge with no issues found
• Code follows established patterns, includes comprehensive tests, proper TypeScript typing, and thorough documentation. No logic errors, security issues, or breaking changes detected.
• No files require special attention

Important Files Changed

Filename	Overview
packages/client/src/metrics/types.ts	Added comprehensive type definitions for Metrics API v1/v2 queries with proper documentation
packages/client/src/metrics/MetricsManager.ts	Implemented typed wrapper for Metrics API with convenience methods for v1 and v2 endpoints
packages/client/src/LangfuseClient.ts	Integrated MetricsManager into LangfuseClient with proper initialization and documentation

Sequence Diagram

sequenceDiagram
    participant User
    participant LangfuseClient
    participant MetricsManager
    participant serializeMetricsQuery
    participant LangfuseAPIClient
    participant API as Metrics API

    User->>LangfuseClient: new LangfuseClient(params)
    LangfuseClient->>MetricsManager: new MetricsManager({ apiClient })
    LangfuseClient-->>User: langfuse

    alt V1 Query (Typed)
        User->>MetricsManager: langfuse.metrics.query(queryObject, options)
        MetricsManager->>serializeMetricsQuery: serializeMetricsQuery(queryObject)
        serializeMetricsQuery-->>MetricsManager: JSON string
        MetricsManager->>MetricsManager: queryRaw(serializedQuery, options)
        MetricsManager->>LangfuseAPIClient: metrics.metrics({ query }, options)
        LangfuseAPIClient->>API: GET /api/public/metrics?query=...
        API-->>LangfuseAPIClient: MetricsResponse
        LangfuseAPIClient-->>MetricsManager: MetricsResponse
        MetricsManager-->>User: MetricsResponse
    else V2 Query (Typed)
        User->>MetricsManager: langfuse.metrics.queryV2(queryObject, options)
        MetricsManager->>serializeMetricsQuery: serializeMetricsQuery(queryObject)
        serializeMetricsQuery-->>MetricsManager: JSON string
        MetricsManager->>MetricsManager: queryRawV2(serializedQuery, options)
        MetricsManager->>LangfuseAPIClient: metricsV2.metrics({ query }, options)
        LangfuseAPIClient->>API: GET /api/public/v2/metrics?query=...
        API-->>LangfuseAPIClient: MetricsV2Response
        LangfuseAPIClient-->>MetricsManager: MetricsV2Response
        MetricsManager-->>User: MetricsV2Response
    else Raw Query (Advanced)
        User->>MetricsManager: langfuse.metrics.queryRaw(jsonString, options)
        MetricsManager->>LangfuseAPIClient: metrics.metrics({ query }, options)
        LangfuseAPIClient->>API: GET /api/public/metrics?query=...
        API-->>LangfuseAPIClient: MetricsResponse
        LangfuseAPIClient-->>MetricsManager: MetricsResponse
        MetricsManager-->>User: MetricsResponse
    end

Loading

_{(2/5) Greptile learns from your feedback when you react with thumbs up/down!}

[vercel]

@suekou is attempting to deploy a commit to the langfuse Team on Vercel.

A member of the Team first needs to authorize it.

[CLAassistant]

All committers have signed the CLA.

[greptile-apps]

_{3 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}