fix(langchain): handle null tokenUsage

[hassiebp]

Disclaimer: Experimental PR review

Greptile Summary

This PR adds v4 deprecation notices across all package READMEs, ships two bug fixes (environment-validation false-positive suppression and a TypeError crash guard in the LangChain callback), and bumps all packages to 3.38.6.

• Deprecation notices: Each package's README now has a prominent [!IMPORTANT] banner directing users to the v4 TypeScript SDK docs, replacing the older v2 migration note in the root README.
• Environment validation fix (langfuse-core/src/index.ts): The invalid-environment error is now suppressed when _isLocalEventExportEnabled is true, preventing false-positive warnings during local testing with arbitrary environment names.
• LangChain null-safety fix (langfuse-langchain/src/callback.ts): Adds ?? {} so llmUsage is never undefined; previously, if both extractUsageMetadata and output.llmOutput?.[\"tokenUsage\"] were nullish, the subsequent \"promptTokens\" in llmUsage expression would throw a TypeError at runtime.
• Version bumps: All packages advance from 3.38.4 → 3.38.6; the apparent skip of 3.38.5 is expected — the git history shows v3.38.5 was tagged as an intermediate release within this PR's commit range before two additional fixes brought it to 3.38.6.

Confidence Score: 5/5

Safe to merge — all code changes are targeted bug fixes with no regressions introduced

Both code changes are correct: the ?? {} fallback prevents a real runtime crash path, and the !_isLocalEventExportEnabled guard correctly uses the raw constructor param (before this.isLocalEventExportEnabled is assigned). Version skipping is explained by the git history. No P0/P1 findings.

No files require special attention

Important Files Changed

Filename	Overview
README.md	Adds v4 deprecation notice and removes the now-stale v2 migration notice
langfuse-core/src/index.ts	Suppresses spurious environment-pattern validation error when local event export is enabled; uses the raw constructor param (not this.isLocalEventExportEnabled) which is correct at this point in the constructor
langfuse-langchain/src/callback.ts	Adds ?? {} fallback for llmUsage to prevent a runtime TypeError from the in operator when both usage sources are undefined
langfuse-core/package.json	Version bumped to 3.38.6 (reflecting two incremental releases that landed within this PR's commit range)
langfuse-langchain/package.json	Version and peer dependency ranges bumped to 3.38.6 consistently
lerna.json	Monorepo version set to 3.38.6 to match all package versions

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[LangfuseCoreStateless constructor] --> B{environment set?}
    B -- No --> E[skip validation]
    B -- Yes --> C{matches ENVIRONMENT_PATTERN or whitelisted?}
    C -- Yes --> E
    C -- No --> D{_isLocalEventExportEnabled?}
    D -- Yes --> E[skip validation - new: suppress false-positive]
    D -- No --> F[emit error: Invalid tracing environment]

    G[handleLLMEnd] --> H[extractUsageMetadata]
    H -- UsageMetadata --> I[llmUsage = UsageMetadata]
    H -- undefined --> J{output.llmOutput tokenUsage?}
    J -- value --> I
    J -- undefined --> K[llmUsage = empty object - new: prevents TypeError]
    I --> L[build usageDetails via in operator]
    K --> L

Loading

_{Reviews (1): Last reviewed commit: "fix(langchain): handle null tokenUsage" | Re-trigger Greptile}

[github-actions]

@claude review

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
langfuse-js	Error		Mar 31, 2026 3:55pm

[chatgpt-codex-connector]

💡 Codex Review

langfuse-js/langfuse-core/src/index.ts

Line 251 in aacc785

!_isLocalEventExportEnabled

Validate environment using effective export mode

The added && !_isLocalEventExportEnabled check suppresses invalid-environment diagnostics based on the raw constructor flag, not the finalized mode. In LangfuseCoreStateless the instance can later disable local export when _projectId is missing, which means the SDK falls back to server ingestion while still skipping this validation warning; with an invalid environment, events can be rejected server-side without the expected error message.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".