@juspay/neurolink 12.59.0 → 13.0.1

package/dist/telemetry/attributes.js

@@ -1,8 +1,13 @@
+import { MIN_STRING_BUDGET_CHARS, REDACTED_VALUE, TRUNCATION_NOTE_ALLOWANCE_CHARS, } from "../constants/telemetry.js";
+import { messageRole } from "./chatMessages.js";
+import { binaryPlaceholder, declaredMimeType, describeDataUrls, isBinaryKey, redactSecretAssignments, redactSensitiveEntry, } from "./spanSanitizer.js";
+import { capStrings, stringify } from "./spanSerialization.js";
 export const ATTR = {
     // GenAI standard (OpenTelemetry semantic conventions)
     GEN_AI_SYSTEM: "gen_ai.system",
     GEN_AI_MODEL: "gen_ai.request.model",
     GEN_AI_OPERATION: "gen_ai.operation.name",
+    GEN_AI_OBSERVATION: "gen_ai.observation.type",
     GEN_AI_INPUT_TOKENS: "gen_ai.usage.input_tokens",
     GEN_AI_OUTPUT_TOKENS: "gen_ai.usage.output_tokens",
     GEN_AI_FINISH_REASON: "gen_ai.response.finish_reason",
@@ -10,22 +15,20 @@ export const ATTR = {
     GEN_AI_TOOL_NAME: "gen_ai.tool.name",
     GEN_AI_TEMPERATURE: "gen_ai.request.temperature",
     GEN_AI_MAX_TOKENS: "gen_ai.request.max_tokens",
-    // NeuroLink custom
-    NL_PROVIDER: "neurolink.provider",
-    NL_MODEL: "neurolink.model",
-    NL_STREAM_MODE: "neurolink.stream_mode",
-    NL_TOOL_COUNT: "neurolink.tool_count",
-    NL_MESSAGE_COUNT: "neurolink.message_count",
-    NL_HAS_TOOLS: "neurolink.has_tools",
-    NL_INPUT_LENGTH: "neurolink.input_length",
-    NL_OUTPUT_LENGTH: "neurolink.output_length",
-    NL_REQUEST_ID: "neurolink.request_id",
-    NL_PATH: "neurolink.path",
-    NL_HAS_MEMORY: "neurolink.has_conversation_memory",
-    NL_COST: "neurolink.cost",
-    NL_STRUCTURED_OUTPUT: "neurolink.structured_output",
-    NL_HAS_FALLBACK: "neurolink.has_fallback",
-    // MCP
+    NL_PROVIDER: "sdk.provider",
+    NL_MODEL: "sdk.model",
+    NL_STREAM_MODE: "stream_mode",
+    NL_TOOL_COUNT: "tool_count",
+    NL_MESSAGE_COUNT: "message_count",
+    NL_HAS_TOOLS: "has_tools",
+    NL_INPUT_LENGTH: "input_length",
+    NL_OUTPUT_LENGTH: "output_length",
+    NL_REQUEST_ID: "request_id",
+    NL_PATH: "path",
+    NL_HAS_MEMORY: "has_conversation_memory",
+    NL_COST: "cost",
+    NL_STRUCTURED_OUTPUT: "structured_output",
+    NL_HAS_FALLBACK: "has_fallback",
     MCP_SERVER_ID: "mcp.server_id",
     MCP_TOOL_NAME: "mcp.tool_name",
     MCP_TIMEOUT_MS: "mcp.timeout_ms",
@@ -114,30 +117,6 @@ export const ATTR = {
     AR_DESCRIPTION: "autoresearch.description",
     AR_ERROR_CODE: "autoresearch.error_code",
 };
-/**
- * Langfuse observation/trace attribute names recognised by `@langfuse/otel`'s
- * LangfuseSpanProcessor (already registered on the global TracerProvider). They
- * let native (non-AI-SDK) provider paths emit spans that render as proper
- * generation / tool observations — the same data the Vercel AI SDK's
- * `experimental_telemetry` produced before providers moved to native SDKs.
- */
-export const LANGFUSE_ATTR = {
-    TRACE_NAME: "langfuse.trace.name",
-    TRACE_INPUT: "langfuse.trace.input",
-    TRACE_OUTPUT: "langfuse.trace.output",
-    TRACE_TAGS: "langfuse.trace.tags",
-    TRACE_METADATA: "langfuse.trace.metadata",
-    OBSERVATION_TYPE: "langfuse.observation.type",
-    OBSERVATION_INPUT: "langfuse.observation.input",
-    OBSERVATION_OUTPUT: "langfuse.observation.output",
-    OBSERVATION_METADATA: "langfuse.observation.metadata",
-    OBSERVATION_MODEL_NAME: "langfuse.observation.model.name",
-    OBSERVATION_MODEL_PARAMETERS: "langfuse.observation.model.parameters",
-    OBSERVATION_USAGE_DETAILS: "langfuse.observation.usage_details",
-    OBSERVATION_LEVEL: "langfuse.observation.level",
-    OBSERVATION_STATUS_MESSAGE: "langfuse.observation.status_message",
-    OBSERVATION_COMPLETION_START_TIME: "langfuse.observation.completion_start_time",
-};
 /** Default ceiling for serialized span attribute values. */
 export const SPAN_ATTRIBUTE_MAX_CHARS = 40_000;
 /** Smallest ceiling accepted, so the system and question openings still fit. */
@@ -158,16 +137,12 @@ export function spanAttributeMaxChars() {
 const SYSTEM_PROMPT_FLOOR_CHARS = 2_000;
 /** Room the current question always gets in a model-request attribute. */
 const QUESTION_FLOOR_CHARS = 4_000;
-/** Room for the "...[truncated N chars]" note, kept outside that opening. */
-const TRUNCATION_NOTE_ALLOWANCE_CHARS = 48;
-const MIN_SHRINKABLE_STRING_CHARS = 64;
-const REDACTED_VALUE = "[REDACTED]";
 const REDACTION_FAILED_VALUE = "[content omitted: redaction failed]";
-const SENSITIVE_KEY_PATTERN = /(authorization|password|passwd|secret|apikey|privatekey|token|credential|signature)/;
+const SENSITIVE_KEY_PATTERN = /(authorization|password|passwd|secret|apikey|privatekey|tokens?$|credential|signature)/;
 const COOKIE_KEY_PATTERN = /^(set)?cookies?$/;
 // Cheap pre-check: text without any of these is returned untouched, so the
 // common case costs one regex scan and stays byte-identical.
-const SENSITIVE_HINT_PATTERN = /authorization|password|passwd|secret|api[_-]?key|private[_-]?key|token|credential|signature|cookie|bearer/i;
+const SENSITIVE_HINT_PATTERN = /authorization|password|passwd|secret|api[_-]?key|private[_-]?key|token|credential|signature|cookie|bearer|sk-|gh[pousr]_|github_pat_|AKIA|xox[baprs]-/i;
 function isSensitiveKey(key) {
     const normalized = key.replace(/[_-]/g, "").toLowerCase();
     return (SENSITIVE_KEY_PATTERN.test(normalized) ||
@@ -190,10 +165,7 @@ function redactText(text) {
     if (!SENSITIVE_HINT_PATTERN.test(text)) {
         return text;
     }
-    let redacted = text
-        .replace(/\bBearer\s+[\w.\-+/=]{16,}/gi, `Bearer ${REDACTED_VALUE}`)
-        .replace(/\b(access_token|refresh_token|id_token|api_key|apikey|client_secret|password|signature|credential)=([^&\s"]+)/gi, `$1=${REDACTED_VALUE}`)
-        .replace(/"([^"\\]{1,80})"(\s*:\s*)"(?:[^"\\]|\\.)*"/g, (match, key, separator) => isSensitiveKey(key) ? `"${key}"${separator}"${REDACTED_VALUE}"` : match);
+    let redacted = redactSecretAssignments(text.replace(/\bBearer\s+[\w.\-+/=]{16,}/gi, `Bearer ${REDACTED_VALUE}`)).replace(/"([^"\\]{1,80})"(\s*:\s*)"(?:[^"\\]|\\.)*"/g, (match, key, separator) => isSensitiveKey(key) ? `"${key}"${separator}"${REDACTED_VALUE}"` : match);
     ESCAPED_QUOTE_BACKSLASHES.forEach((backslashes, index) => {
         const quote = `${"\\".repeat(backslashes)}"`;
         redacted = redacted.replace(ESCAPED_PAIR_PATTERNS[index], (match, key, separator) => isSensitiveKey(key)
@@ -204,7 +176,7 @@ function redactText(text) {
 }
 function redactNode(value, ancestors) {
     if (typeof value === "string") {
-        return redactText(value);
+        return redactText(describeDataUrls(value));
     }
     if (value === null || typeof value !== "object") {
         return value;
@@ -212,6 +184,9 @@ function redactNode(value, ancestors) {
     if (ancestors.has(value)) {
         return "[circular]";
     }
+    if (value instanceof ArrayBuffer || ArrayBuffer.isView(value)) {
+        return binaryPlaceholder(value, undefined);
+    }
     ancestors.add(value);
     try {
         if ("toJSON" in value && typeof value.toJSON === "function") {
@@ -222,15 +197,18 @@ function redactNode(value, ancestors) {
         }
         // No prototype, so a key named __proto__ is data rather than an assignment.
         const redacted = Object.create(null);
+        const mimeType = declaredMimeType(value);
         for (const [key, entry] of Object.entries(value)) {
-            // Counts and flags under a sensitive-looking name (input_tokens: 5) are
-            // not credentials; only text and structures are masked.
-            redacted[key] =
-                isSensitiveKey(key) &&
-                    (typeof entry === "string" ||
-                        (typeof entry === "object" && entry !== null))
-                    ? REDACTED_VALUE
-                    : redactNode(entry, ancestors);
+            if (isSensitiveKey(key) &&
+                (typeof entry === "string" ||
+                    (typeof entry === "object" && entry !== null))) {
+                redacted[key] = redactSensitiveEntry(key, entry);
+                continue;
+            }
+            const placeholder = isBinaryKey(key)
+                ? binaryPlaceholder(entry, mimeType)
+                : undefined;
+            redacted[key] = placeholder ?? redactNode(entry, ancestors);
         }
         return redacted;
     }
@@ -239,12 +217,10 @@ function redactNode(value, ancestors) {
     }
 }
 /**
- * Returns a copy of `value` with credentials masked: values under keys such as
- * `access_token`, `password`, `authorization` or `set-cookie`, bearer tokens
- * and `name=value` credentials inside text. Content with nothing sensitive in
- * it serializes exactly as it did before. Throws only if the value cannot be
- * walked; callers on the tracing path use `spanContentAttribute`, which turns
- * that into an omitted value instead of a leak or a failed turn.
+ * @description Returns a copy of a value with credentials masked: values under keys such as `access_token`, `password`, `authorization` or `set-cookie`, bearer tokens, and `name=value` credentials inside text. Purely numeric values after a credential-looking name (e.g. `max_tokens: 4096`) are left alone.
+ * @param value {JsonValue | object} - Content to redact; objects and arrays are walked recursively.
+ * @returns {JsonValue | object} A redacted copy, serializing exactly as the input when nothing in it is sensitive.
+ * @throws {Error} When the value cannot be walked; tracing callers use `spanContentAttribute`, which turns that into an omitted value.
  */
 export function redactSpanContent(value) {
     return redactNode(value, new WeakSet());
@@ -257,70 +233,26 @@ function redactSafely(value) {
         return REDACTION_FAILED_VALUE;
     }
 }
-const MAX_SHRINK_ATTEMPTS = 200;
-/**
- * Cuts the longest string inside `root` down by at least `excess` characters,
- * in place, and says whether it found one worth cutting. Only ever called on
- * the copy `redactSpanContent` made, never on the caller's own data.
- */
-function shrinkLongestString(root, excess) {
-    let owner;
-    let ownerKey = "";
-    let longestText = "";
-    const visited = new Set();
-    const pending = [root];
-    while (pending.length > 0) {
-        const node = pending.pop();
-        if (node === undefined || visited.has(node)) {
-            continue;
-        }
-        visited.add(node);
-        for (const [key, entry] of Object.entries(node)) {
-            if (typeof entry === "string") {
-                if (entry.length > longestText.length &&
-                    entry.length > MIN_SHRINKABLE_STRING_CHARS) {
-                    longestText = entry;
-                    owner = node;
-                    ownerKey = key;
-                }
-            }
-            else if (entry !== null && typeof entry === "object") {
-                pending.push(entry);
-            }
-        }
-    }
-    if (owner === undefined) {
-        return false;
-    }
-    const keep = Math.max(MIN_SHRINKABLE_STRING_CHARS / 2, longestText.length - excess - TRUNCATION_NOTE_ALLOWANCE_CHARS);
-    Reflect.set(owner, ownerKey, `${longestText.slice(0, keep)}...[truncated ${longestText.length - keep} chars]`);
-    return true;
-}
 /**
  * `spanJsonAttribute` for content a person or model wrote or a tool returned
  * (arguments, results, answers), with credentials masked first. Use the plain
  * form for metadata such as usage counts and server ids.
  *
- * A structured value over the cap is shortened by trimming its longest
- * strings, so the attribute stays valid JSON instead of ending mid-token.
+ * A structured value over the cap is shortened by cutting every string to a
+ * per-string budget in one walk, tightening the budget only if the result
+ * still does not fit, so the attribute stays valid JSON instead of ending
+ * mid-token.
  */
 export function spanContentAttribute(value, maxChars = spanAttributeMaxChars()) {
     const redacted = redactSafely(value);
     if (redacted === null || typeof redacted !== "object") {
         return spanJsonAttribute(redacted, maxChars);
     }
-    let serialized;
-    try {
-        serialized = JSON.stringify(redacted) ?? String(redacted);
-    }
-    catch {
-        return spanJsonAttribute(redacted, maxChars);
-    }
-    for (let attempt = 0; serialized.length > maxChars && attempt < MAX_SHRINK_ATTEMPTS; attempt++) {
-        if (!shrinkLongestString(redacted, serialized.length - maxChars)) {
-            break;
-        }
-        serialized = JSON.stringify(redacted);
+    let serialized = stringify(redacted);
+    let budget = Math.floor(maxChars / 4);
+    while (serialized.length > maxChars && budget >= MIN_STRING_BUDGET_CHARS) {
+        serialized = stringify(capStrings(redacted, budget));
+        budget = Math.floor(budget / 4);
     }
     return spanJsonAttribute(serialized, maxChars);
 }
@@ -331,16 +263,7 @@ export function spanContentAttribute(value, maxChars = spanAttributeMaxChars())
  * JSON-stringified with a String() fallback for circular structures.
  */
 export function spanJsonAttribute(value, maxChars = spanAttributeMaxChars()) {
-    let serialized;
-    try {
-        serialized =
-            typeof value === "string"
-                ? value
-                : (JSON.stringify(value) ?? String(value));
-    }
-    catch {
-        serialized = String(value);
-    }
+    const serialized = stringify(value);
     if (serialized.length > maxChars) {
         const truncationSuffix = `...[truncated ${serialized.length - maxChars} chars]`;
         const keepLength = Math.max(0, maxChars - truncationSuffix.length);
@@ -427,21 +350,9 @@ export function spanModelRequestAttribute(rawRequest, maxChars = spanAttributeMa
             }
             : {}),
         ...(rawRequest.prompt !== undefined
-            ? { prompt: redactText(rawRequest.prompt) }
+            ? { prompt: redactText(describeDataUrls(rawRequest.prompt)) }
             : {}),
     };
-    const serialize = (value) => {
-        try {
-            return typeof value === "string"
-                ? value
-                : (JSON.stringify(value) ?? String(value));
-        }
-        catch {
-            return String(value);
-        }
-    };
-    // Sizes are measured as JSON, which is what the attribute carries: escaping
-    // makes a JSON string longer than its text.
     const jsonLength = (value) => {
         try {
             return (JSON.stringify(value) ?? "null").length;
@@ -488,23 +399,22 @@ export function spanModelRequestAttribute(rawRequest, maxChars = spanAttributeMa
         }
         let copy;
         try {
-            copy = JSON.parse(serialize(message));
+            copy = JSON.parse(stringify(message));
         }
         catch {
             copy = undefined;
         }
         if (copy !== null && typeof copy === "object") {
-            for (let attempt = 0; jsonLength(copy) > budget && attempt < MAX_SHRINK_ATTEMPTS; attempt++) {
-                if (!shrinkLongestString(copy, jsonLength(copy) - budget)) {
-                    break;
-                }
+            for (let stringBudget = Math.floor(budget / 4); jsonLength(copy) > budget && stringBudget >= MIN_STRING_BUDGET_CHARS; stringBudget = Math.floor(stringBudget / 4)) {
+                capStrings(copy, stringBudget);
             }
             if (jsonLength(copy) <= budget) {
                 return copy;
             }
         }
         return {
-            truncatedMessage: fitText(serialize(message), Math.max(0, budget - 32)),
+            role: messageRole(message),
+            content: fitText(stringify(message), Math.max(0, budget - 32)),
         };
     };
     const messages = request.messages ?? [];
@@ -532,8 +442,8 @@ export function spanModelRequestAttribute(rawRequest, maxChars = spanAttributeMa
         }
         turnComplete = false;
         if (turn.length === 0 && remaining > 64) {
-            const excerpt = fitText(serialize(messages[index]), remaining - 32);
-            turn.unshift({ truncatedMessage: excerpt });
+            const excerpt = fitText(stringify(messages[index]), remaining - 32);
+            turn.unshift({ role: messageRole(messages[index]), content: excerpt });
             remaining -= jsonLength(excerpt) + 32;
         }
         break;
@@ -560,26 +470,30 @@ export function spanModelRequestAttribute(rawRequest, maxChars = spanAttributeMa
     }
     const omittedMessages = messages.length - kept.length;
     remaining += systemFloor;
-    const body = {};
+    const leading = [];
     if (request.system !== undefined) {
-        body.system =
-            jsonLength(request.system) <= remaining
+        leading.push({
+            role: "system",
+            content: jsonLength(request.system) <= remaining
                 ? request.system
-                : fitText(serialize(request.system), Math.max(0, remaining));
-    }
-    if (request.messages !== undefined) {
-        body.messages = kept;
+                : fitText(stringify(request.system), Math.max(0, remaining)),
+        });
     }
     if (omittedMessages > 0) {
-        body.omittedMessages = omittedMessages;
-    }
-    if (prompt !== undefined) {
-        body.prompt = prompt;
+        leading.push({
+            role: "system",
+            content: `[${omittedMessages} earlier messages omitted]`,
+        });
     }
+    const conversation = [
+        ...leading,
+        ...kept,
+        ...(prompt !== undefined ? [{ role: "user", content: prompt }] : []),
+    ];
     try {
-        return JSON.stringify(body);
+        return JSON.stringify(conversation);
     }
     catch {
-        return spanJsonAttribute(body, maxChars);
+        return spanJsonAttribute(conversation, maxChars);
     }
 }

package/dist/telemetry/chatMessages.d.ts

@@ -0,0 +1,13 @@
+import type { AssistantOutput } from "../types/index.js";
+/**
+ * @description Reads the role of a chat message, treating anything without a string role as a user message.
+ * @param message {T} - Message of any provider shape.
+ * @returns {string} The message role, or `user` when it declares none.
+ */
+export declare function messageRole<T>(message: T): string;
+/**
+ * @description Shapes a model response as an assistant message array that Langfuse renders as a conversation.
+ * @param output {AssistantOutput | undefined} - A text string, a reply with `text`, `reasoning` and `toolCalls`, a message array, or provider content parts.
+ * @returns {object[] | undefined} `[{ role: "assistant", content, tool_calls? }]`, the input untouched when it is already a message array, or `undefined` when there is no output.
+ */
+export declare function assistantMessages(output: AssistantOutput | undefined): object[] | undefined;

package/dist/telemetry/chatMessages.js

@@ -0,0 +1,59 @@
+import { stringify } from "./spanSerialization.js";
+function chatToolCall(call) {
+    const args = call.args ?? call.input ?? call.arguments ?? call.function?.arguments;
+    return {
+        id: call.id ?? call.toolCallId,
+        type: "function",
+        function: {
+            name: call.name ?? call.toolName ?? call.function?.name,
+            arguments: typeof args === "string" ? args : stringify(args ?? {}),
+        },
+    };
+}
+function isChatMessages(output) {
+    return (output.length > 0 &&
+        output.every((entry) => "role" in entry && typeof entry.role === "string"));
+}
+function isAssistantReply(output) {
+    return (typeof output === "object" &&
+        !Array.isArray(output) &&
+        ("text" in output || "toolCalls" in output));
+}
+/**
+ * @description Reads the role of a chat message, treating anything without a string role as a user message.
+ * @param message {T} - Message of any provider shape.
+ * @returns {string} The message role, or `user` when it declares none.
+ */
+export function messageRole(message) {
+    return typeof message === "object" &&
+        message !== null &&
+        "role" in message &&
+        typeof message.role === "string"
+        ? message.role
+        : "user";
+}
+/**
+ * @description Shapes a model response as an assistant message array that Langfuse renders as a conversation.
+ * @param output {AssistantOutput | undefined} - A text string, a reply with `text`, `reasoning` and `toolCalls`, a message array, or provider content parts.
+ * @returns {object[] | undefined} `[{ role: "assistant", content, tool_calls? }]`, the input untouched when it is already a message array, or `undefined` when there is no output.
+ */
+export function assistantMessages(output) {
+    if (output === undefined) {
+        return undefined;
+    }
+    if (Array.isArray(output) && isChatMessages(output)) {
+        return output;
+    }
+    if (!isAssistantReply(output)) {
+        return [{ role: "assistant", content: output }];
+    }
+    const toolCalls = (output.toolCalls ?? []).map(chatToolCall);
+    return [
+        {
+            role: "assistant",
+            content: output.text ?? "",
+            ...(output.reasoning ? { reasoning: output.reasoning } : {}),
+            ...(toolCalls.length > 0 ? { tool_calls: toolCalls } : {}),
+        },
+    ];
+}

package/dist/telemetry/index.d.ts

@@ -1,20 +1,6 @@
-export { TelemetryService } from "./telemetryService.js";
 export { tracers } from "./tracers.js";
-export { withSpan, withClientSpan, withStreamSpan, withClientStreamSpan, } from "./withSpan.js";
-export { ATTR, LANGFUSE_ATTR, SPAN_ATTRIBUTE_MAX_CHARS, redactSpanContent, spanAttributeMaxChars, spanContentAttribute, spanJsonAttribute, spanModelRequestAttribute, } from "./attributes.js";
-/**
- * Initialize telemetry for NeuroLink
- * Reuses an existing global TracerProvider when one is already registered,
- * otherwise bootstraps Neurolink telemetry when an exporter endpoint is configured.
- */
-export declare function initializeTelemetry(): Promise<import("./telemetryService.js").TelemetryService>;
-/**
- * Get telemetry status
- */
-export declare function getTelemetryStatus(): Promise<{
-    enabled: boolean;
-    initialized: boolean;
-    endpoint?: string;
-    service?: string;
-    version?: string;
-}>;
+export { withSpan, withClientSpan, withStreamSpan, withClientStreamSpan, StepSpans, withStepSpan, } from "./withSpan.js";
+export { ATTR, SPAN_ATTRIBUTE_MAX_CHARS, redactSpanContent, spanAttributeMaxChars, spanContentAttribute, spanJsonAttribute, spanModelRequestAttribute, } from "./attributes.js";
+export { assistantMessages } from "./chatMessages.js";
+export { observationLevel, observe, observeGeneration, observeTrace, usageDetails, } from "./observation.js";
+export { generationName, stepSpanName, toolSpanName, } from "./observationNames.js";

package/dist/telemetry/index.js

@@ -1,27 +1,6 @@
-// Optional Telemetry Infrastructure (Phase 2)
-export { TelemetryService } from "./telemetryService.js";
 export { tracers } from "./tracers.js";
-export { withSpan, withClientSpan, withStreamSpan, withClientStreamSpan, } from "./withSpan.js";
-export { ATTR, LANGFUSE_ATTR, SPAN_ATTRIBUTE_MAX_CHARS, redactSpanContent, spanAttributeMaxChars, spanContentAttribute, spanJsonAttribute, spanModelRequestAttribute, } from "./attributes.js";
-import { logger } from "../utils/logger.js";
-/**
- * Initialize telemetry for NeuroLink
- * Reuses an existing global TracerProvider when one is already registered,
- * otherwise bootstraps Neurolink telemetry when an exporter endpoint is configured.
- */
-export async function initializeTelemetry() {
-    const { TelemetryService } = await import("./telemetryService.js");
-    const telemetry = TelemetryService.getInstance();
-    if (telemetry.isEnabled()) {
-        await telemetry.initialize();
-        logger.info("[NeuroLink] Telemetry initialized");
-    }
-    return telemetry;
-}
-/**
- * Get telemetry status
- */
-export async function getTelemetryStatus() {
-    const { TelemetryService } = await import("./telemetryService.js");
-    return TelemetryService.getInstance().getStatus();
-}
+export { withSpan, withClientSpan, withStreamSpan, withClientStreamSpan, StepSpans, withStepSpan, } from "./withSpan.js";
+export { ATTR, SPAN_ATTRIBUTE_MAX_CHARS, redactSpanContent, spanAttributeMaxChars, spanContentAttribute, spanJsonAttribute, spanModelRequestAttribute, } from "./attributes.js";
+export { assistantMessages } from "./chatMessages.js";
+export { observationLevel, observe, observeGeneration, observeTrace, usageDetails, } from "./observation.js";
+export { generationName, stepSpanName, toolSpanName, } from "./observationNames.js";

package/dist/telemetry/observation.d.ts

@@ -0,0 +1,37 @@
+import type { Span } from "@opentelemetry/api";
+import type { GenerationRecord, ObservationAttributes, ObservationLevel, ObservationType, RawUsageObject, TraceContent } from "../types/index.js";
+/**
+ * @description Stamps Langfuse observation attributes on a span, plus a `gen_ai.observation.type` marker so the exporter pipeline recognizes it whatever its tracer scope. Input and output are credential-masked and capped at `SPAN_ATTRIBUTE_MAX_CHARS` before serialization.
+ * @param span {Span} - Span to describe.
+ * @param type {ObservationType} - Observation type Langfuse renders the span as.
+ * @param attrs {ObservationAttributes} - Input, output, model, parameters, usage, cost, level and metadata to record.
+ * @returns {void} Nothing.
+ */
+export declare function observe(span: Span, type: ObservationType, attrs: ObservationAttributes): void;
+/**
+ * @description Sets the trace-level input, output and metadata on a span, credential-masked and capped like `observe`. Each metadata entry is written as its own `langfuse.trace.metadata.<key>` attribute, redacted like input and output.
+ * @param span {Span} - Span whose trace is described.
+ * @param io {TraceContent} - Trace input, output and metadata.
+ * @returns {void} Nothing.
+ */
+export declare function observeTrace(span: Span, io: TraceContent): void;
+/**
+ * @description Maps any provider's token usage onto Langfuse usage-detail keys.
+ * @param usage {RawUsageObject | undefined | null} - Token usage in any naming convention NeuroLink normalizes.
+ * @returns {Record<string, number>} `input`, `output` and `total`, plus `cache_read_input_tokens`, `cache_creation_input_tokens` and `reasoning` when reported.
+ */
+export declare function usageDetails(usage: RawUsageObject | undefined | null): Record<string, number>;
+/**
+ * @description Picks the Langfuse level for a model call that finished without throwing.
+ * @param finishReason {string | undefined} - Provider finish reason, in any casing.
+ * @param aborted {boolean | undefined} - Whether the caller aborted or closed the call early.
+ * @returns {ObservationLevel | undefined} `"WARNING"` for truncated, filtered, aborted or empty output, otherwise `undefined`.
+ */
+export declare function observationLevel(finishReason?: string, aborted?: boolean): ObservationLevel | undefined;
+/**
+ * @description Records a model request on its span as a Langfuse generation: model, defined parameters, input, output, usage, cost and level. Safe to call once with the request and again with the response; unset fields leave earlier values in place.
+ * @param span {Span} - Span of one model request.
+ * @param call {GenerationRecord} - What was sent and what came back.
+ * @returns {void} Nothing.
+ */
+export declare function observeGeneration(span: Span, call: GenerationRecord): void;