@posthog/ai 7.19.7 → 7.20.0

package/dist/index.d.ts

@@ -479,6 +479,19 @@ interface CaptureAiGenerationOptions {
     costOverride?: CostOverride;
     tools?: ChatCompletionTool[] | AnthropicTool[] | Tool[] | null;
     stopReason?: string;
+    /**
+     * Provider-assigned ID for the generation (e.g. OpenAI's `chatcmpl-…` /
+     * `resp_…`). Maps to `$ai_completion_id`. Response IDs generalize across
+     * providers, so this lives in the shared schema rather than under
+     * `providerMetadata`.
+     */
+    completionId?: string;
+    /**
+     * Provider-specific response metadata that has no place in the shared,
+     * provider-agnostic `$ai_*` schema (e.g. OpenAI's `system_fingerprint` and
+     * `request_id`). Maps to `$ai_provider_metadata`; omitted when empty.
+     */
+    providerMetadata?: Record<string, unknown>;
     /** When set, the event is captured as an error. */
     error?: unknown;
     /** Awaits delivery instead of batching. Useful in serverless environments. */

package/dist/index.mjs

@@ -709,7 +709,7 @@ function formatOpenAIResponsesInput(input, instructions) {
   return messages;
 }
 
-var version = "7.19.7";
+var version = "7.20.0";
 
 const DEFAULT_MAX_DEPTH = 3;
 const MAX_STACK_LINES = 20;
@@ -870,6 +870,12 @@ const captureAiGeneration = async (client, options) => {
     ...(options.tools ? {
       $ai_tools: options.tools
     } : {}),
+    ...(options.completionId ? {
+      $ai_completion_id: options.completionId
+    } : {}),
+    ...(options.providerMetadata && Object.keys(options.providerMetadata).length > 0 ? {
+      $ai_provider_metadata: options.providerMetadata
+    } : {}),
     ...errorData,
     ...costOverrideData
   };
@@ -893,6 +899,32 @@ const captureAiGeneration = async (client, options) => {
 function isResponseTokenChunk(chunk) {
   return chunk.type === 'response.output_item.added' || chunk.type === 'response.content_part.added' || chunk.type === 'response.output_text.delta' || chunk.type === 'response.reasoning_text.delta' || chunk.type === 'response.reasoning_summary_text.delta' || chunk.type === 'response.audio.delta' || chunk.type === 'response.audio.transcript.delta' || chunk.type === 'response.refusal.delta';
 }
+/**
+ * Reads the OpenAI SDK's `_request_id` field from a response object. The SDK
+ * attaches the `x-request-id` response header here, but it is not part of the
+ * public response types, so it has to be read through a cast. Used to populate
+ * `$ai_provider_metadata.request_id`.
+ */
+function extractRequestId(result) {
+  return result?._request_id ?? undefined;
+}
+/**
+ * Assembles the `$ai_provider_metadata` blob for OpenAI / Azure OpenAI events.
+ * Provider-specific fields (system fingerprint, request id) live here rather
+ * than in the shared, provider-agnostic `$ai_*` namespace. Only keys with a
+ * truthy value are included, and `undefined` is returned when there is nothing
+ * to report so the property can be omitted from the event entirely.
+ */
+function buildProviderMetadata(fields) {
+  const metadata = {};
+  if (fields.systemFingerprint) {
+    metadata.system_fingerprint = fields.systemFingerprint;
+  }
+  if (fields.requestId) {
+    metadata.request_id = fields.requestId;
+  }
+  return Object.keys(metadata).length > 0 ? metadata : undefined;
+}
 
 const Chat = OpenAI.Chat;
 const Completions = Chat.Completions;
@@ -939,6 +971,10 @@ let WrappedCompletions$1 = class WrappedCompletions extends Completions {
         if ('tee' in value) {
           const [stream1, stream2] = value.tee();
           (async () => {
+            // Hoisted so the catch block can surface whatever was accumulated
+            // from the streamed chunks before the failure.
+            let completionIdFromResponse;
+            let systemFingerprintFromResponse;
             try {
               const contentBlocks = [];
               let accumulatedContent = '';
@@ -954,10 +990,16 @@ let WrappedCompletions$1 = class WrappedCompletions extends Completions {
               const toolCallsInProgress = new Map();
               let rawUsageData;
               for await (const chunk of stream1) {
-                // Extract model from chunk (Chat Completions chunks have model field)
+                // Extract model and completion metadata from chunk (Chat Completions chunks carry these fields)
                 if (!modelFromResponse && chunk.model) {
                   modelFromResponse = chunk.model;
                 }
+                if (!completionIdFromResponse && chunk.id) {
+                  completionIdFromResponse = chunk.id;
+                }
+                if (!systemFingerprintFromResponse && chunk.system_fingerprint) {
+                  systemFingerprintFromResponse = chunk.system_fingerprint;
+                }
                 const choice = chunk?.choices?.[0];
                 if (choice?.finish_reason) {
                   stopReason = choice.finish_reason;
@@ -1073,7 +1115,11 @@ let WrappedCompletions$1 = class WrappedCompletions extends Completions {
                   rawUsage: rawUsageData
                 },
                 stopReason,
-                tools: availableTools
+                tools: availableTools,
+                completionId: completionIdFromResponse,
+                providerMetadata: buildProviderMetadata({
+                  systemFingerprint: systemFingerprintFromResponse
+                })
               });
             } catch (error) {
               await captureAiGeneration(this.phClient, {
@@ -1089,6 +1135,13 @@ let WrappedCompletions$1 = class WrappedCompletions extends Completions {
                   inputTokens: 0,
                   outputTokens: 0
                 },
+                // If the stream fails mid-flight, surface whatever completion
+                // metadata the consumed chunks already provided so the error
+                // event can still be correlated to OpenAI's Logs dashboard.
+                completionId: completionIdFromResponse,
+                providerMetadata: buildProviderMetadata({
+                  systemFingerprint: systemFingerprintFromResponse
+                }),
                 error
               });
               throw error;
@@ -1124,7 +1177,12 @@ let WrappedCompletions$1 = class WrappedCompletions extends Completions {
               rawUsage: result.usage
             },
             stopReason: result.choices[0]?.finish_reason ?? undefined,
-            tools: availableTools
+            tools: availableTools,
+            completionId: result.id,
+            providerMetadata: buildProviderMetadata({
+              systemFingerprint: result.system_fingerprint,
+              requestId: extractRequestId(result)
+            })
           });
         }
         return result;
@@ -1171,6 +1229,9 @@ let WrappedResponses$1 = class WrappedResponses extends Responses {
         if ('tee' in value && typeof value.tee === 'function') {
           const [stream1, stream2] = value.tee();
           (async () => {
+            // Hoisted so the catch block can surface the completion ID that
+            // was accumulated from the streamed chunks before the failure.
+            let completionIdFromResponse;
             try {
               let finalContent = [];
               let modelFromResponse;
@@ -1188,10 +1249,13 @@ let WrappedResponses$1 = class WrappedResponses extends Responses {
                   firstTokenTime = Date.now();
                 }
                 if ('response' in chunk && chunk.response) {
-                  // Extract model from response object in chunk (for stored prompts)
+                  // Extract model and completion ID from the response object in the chunk (for stored prompts)
                   if (!modelFromResponse && chunk.response.model) {
                     modelFromResponse = chunk.response.model;
                   }
+                  if (!completionIdFromResponse && chunk.response.id) {
+                    completionIdFromResponse = chunk.response.id;
+                  }
                   const chunkWebSearchCount = calculateWebSearchCount(chunk.response);
                   if (chunkWebSearchCount > 0 && chunkWebSearchCount > (usage.webSearchCount ?? 0)) {
                     usage.webSearchCount = chunkWebSearchCount;
@@ -1237,7 +1301,8 @@ let WrappedResponses$1 = class WrappedResponses extends Responses {
                   rawUsage: rawUsageData
                 },
                 stopReason,
-                tools: availableTools
+                tools: availableTools,
+                completionId: completionIdFromResponse
               });
             } catch (error) {
               await captureAiGeneration(this.phClient, {
@@ -1253,6 +1318,9 @@ let WrappedResponses$1 = class WrappedResponses extends Responses {
                   inputTokens: 0,
                   outputTokens: 0
                 },
+                // Surface the completion ID from any chunks consumed before
+                // the stream failed so the error event remains correlatable.
+                completionId: completionIdFromResponse,
                 error
               });
               throw error;
@@ -1289,7 +1357,11 @@ let WrappedResponses$1 = class WrappedResponses extends Responses {
               rawUsage: result.usage
             },
             stopReason: result.status ?? undefined,
-            tools: availableTools
+            tools: availableTools,
+            completionId: result.id,
+            providerMetadata: buildProviderMetadata({
+              requestId: extractRequestId(result)
+            })
           });
         }
         return result;
@@ -1347,7 +1419,11 @@ let WrappedResponses$1 = class WrappedResponses extends Responses {
             cacheReadInputTokens: result.usage?.input_tokens_details?.cached_tokens ?? 0,
             rawUsage: result.usage
           },
-          stopReason: result.status ?? undefined
+          stopReason: result.status ?? undefined,
+          completionId: result.id,
+          providerMetadata: buildProviderMetadata({
+            requestId: extractRequestId(result)
+          })
         });
         return result;
       }, async error => {
@@ -1603,6 +1679,10 @@ class WrappedCompletions extends AzureOpenAI.Chat.Completions {
         if ('tee' in value) {
           const [stream1, stream2] = value.tee();
           (async () => {
+            // Hoisted so the catch block can surface whatever was accumulated
+            // from the streamed chunks before the failure.
+            let completionIdFromResponse;
+            let systemFingerprintFromResponse;
             try {
               const contentBlocks = [];
               let accumulatedContent = '';
@@ -1615,10 +1695,16 @@ class WrappedCompletions extends AzureOpenAI.Chat.Completions {
               // Map to track in-progress tool calls
               const toolCallsInProgress = new Map();
               for await (const chunk of stream1) {
-                // Extract model from response if not in params
+                // Extract model and completion metadata from chunk (Chat Completions chunks carry these fields)
                 if (!modelFromResponse && chunk.model) {
                   modelFromResponse = chunk.model;
                 }
+                if (!completionIdFromResponse && chunk.id) {
+                  completionIdFromResponse = chunk.id;
+                }
+                if (!systemFingerprintFromResponse && chunk.system_fingerprint) {
+                  systemFingerprintFromResponse = chunk.system_fingerprint;
+                }
                 const choice = chunk?.choices?.[0];
                 // Handle text content
                 const deltaContent = choice?.delta?.content;
@@ -1715,7 +1801,11 @@ class WrappedCompletions extends AzureOpenAI.Chat.Completions {
                 baseURL: this.baseURL,
                 modelParameters: getModelParams(body),
                 httpStatus: 200,
-                usage
+                usage,
+                completionId: completionIdFromResponse,
+                providerMetadata: buildProviderMetadata({
+                  systemFingerprint: systemFingerprintFromResponse
+                })
               });
             } catch (error) {
               await captureAiGeneration(this.phClient, {
@@ -1731,6 +1821,13 @@ class WrappedCompletions extends AzureOpenAI.Chat.Completions {
                   inputTokens: 0,
                   outputTokens: 0
                 },
+                // If the stream fails mid-flight, surface whatever completion
+                // metadata the consumed chunks already provided so the error
+                // event can still be correlated to OpenAI's Logs dashboard.
+                completionId: completionIdFromResponse,
+                providerMetadata: buildProviderMetadata({
+                  systemFingerprint: systemFingerprintFromResponse
+                }),
                 error: error
               });
               throw error;
@@ -1760,7 +1857,12 @@ class WrappedCompletions extends AzureOpenAI.Chat.Completions {
               outputTokens: result.usage?.completion_tokens ?? 0,
               reasoningTokens: result.usage?.completion_tokens_details?.reasoning_tokens ?? 0,
               cacheReadInputTokens: result.usage?.prompt_tokens_details?.cached_tokens ?? 0
-            }
+            },
+            completionId: result.id,
+            providerMetadata: buildProviderMetadata({
+              systemFingerprint: result.system_fingerprint,
+              requestId: extractRequestId(result)
+            })
           });
         }
         return result;
@@ -1807,6 +1909,9 @@ class WrappedResponses extends AzureOpenAI.Responses {
         if ('tee' in value && typeof value.tee === 'function') {
           const [stream1, stream2] = value.tee();
           (async () => {
+            // Hoisted so the catch block can surface the completion ID that
+            // was accumulated from the streamed chunks before the failure.
+            let completionIdFromResponse;
             try {
               let finalContent = [];
               let modelFromResponse;
@@ -1821,10 +1926,13 @@ class WrappedResponses extends AzureOpenAI.Responses {
                   firstTokenTime = Date.now();
                 }
                 if ('response' in chunk && chunk.response) {
-                  // Extract model from response if not in params (for stored prompts)
+                  // Extract model and completion ID from the response object in the chunk (for stored prompts)
                   if (!modelFromResponse && chunk.response.model) {
                     modelFromResponse = chunk.response.model;
                   }
+                  if (!completionIdFromResponse && chunk.response.id) {
+                    completionIdFromResponse = chunk.response.id;
+                  }
                 }
                 if (chunk.type === 'response.completed' && 'response' in chunk && chunk.response?.output && chunk.response.output.length > 0) {
                   finalContent = chunk.response.output;
@@ -1851,7 +1959,8 @@ class WrappedResponses extends AzureOpenAI.Responses {
                 baseURL: this.baseURL,
                 modelParameters: getModelParams(body),
                 httpStatus: 200,
-                usage
+                usage,
+                completionId: completionIdFromResponse
               });
             } catch (error) {
               await captureAiGeneration(this.phClient, {
@@ -1867,6 +1976,9 @@ class WrappedResponses extends AzureOpenAI.Responses {
                   inputTokens: 0,
                   outputTokens: 0
                 },
+                // Surface the completion ID from any chunks consumed before
+                // the stream failed so the error event remains correlatable.
+                completionId: completionIdFromResponse,
                 error: error
               });
               throw error;
@@ -1895,7 +2007,11 @@ class WrappedResponses extends AzureOpenAI.Responses {
               outputTokens: result.usage?.output_tokens ?? 0,
               reasoningTokens: result.usage?.output_tokens_details?.reasoning_tokens ?? 0,
               cacheReadInputTokens: result.usage?.input_tokens_details?.cached_tokens ?? 0
-            }
+            },
+            completionId: result.id,
+            providerMetadata: buildProviderMetadata({
+              requestId: extractRequestId(result)
+            })
           });
         }
         return result;
@@ -1946,7 +2062,11 @@ class WrappedResponses extends AzureOpenAI.Responses {
           outputTokens: result.usage?.output_tokens ?? 0,
           reasoningTokens: result.usage?.output_tokens_details?.reasoning_tokens ?? 0,
           cacheReadInputTokens: result.usage?.input_tokens_details?.cached_tokens ?? 0
-        }
+        },
+        completionId: result.id,
+        providerMetadata: buildProviderMetadata({
+          requestId: extractRequestId(result)
+        })
       });
       return result;
     }, async error => {