import type OpenAIOrignal from 'openai' import type AnthropicOriginal from '@anthropic-ai/sdk' import type { ResponseCreateParamsWithTools } from 'openai/lib/ResponsesParser' import type { FormattedMessage, FormattedContent, FormattedAudioContent, FormattedImageContent, FormattedDocumentContent, } from './types' import type { JsonType } from '@posthog/core' import { v4 as uuidv4 } from 'uuid' import { isString } from './typeGuards' import { redactBase64DataUrl } from './sanitization' import { isFullAiCaptureEnabled, type FullAiCaptureGate } from './captureAiEvent' import { isPrivacyModeEnabled, type PrivacyModeGate } from './privacyMode' export { isPrivacyModeEnabled } type ChatCompletionCreateParamsBase = OpenAIOrignal.Chat.Completions.ChatCompletionCreateParams type MessageCreateParams = AnthropicOriginal.Messages.MessageCreateParams type ResponseCreateParams = OpenAIOrignal.Responses.ResponseCreateParams type EmbeddingCreateParams = OpenAIOrignal.EmbeddingCreateParams type TranscriptionCreateParams = OpenAIOrignal.Audio.Transcriptions.TranscriptionCreateParams const TOKEN_PROPERTY_KEYS = new Set([ '$ai_input_tokens', '$ai_output_tokens', '$ai_cache_read_input_tokens', '$ai_cache_creation_input_tokens', '$ai_total_tokens', '$ai_reasoning_tokens', ]) /** * Whether the caller supplied their own token counts, which override the ones the SDK * derived from the provider response. */ export function hasTokenOverrides(posthogProperties?: Record): boolean { return !!posthogProperties && Object.keys(posthogProperties).some((key) => TOKEN_PROPERTY_KEYS.has(key)) } export function getTokensSource(posthogProperties?: Record): string { return hasTokenOverrides(posthogProperties) ? 'passthrough' : 'sdk' } // limit large outputs by truncating to 200kb (approx 200k bytes) export const MAX_OUTPUT_SIZE = 200000 const STRING_FORMAT = 'utf8' // Reused across calls to avoid per-invocation allocation; truncate() runs // hundreds of times for prompts with many parts. const sharedTextEncoder = new TextEncoder() const sharedTextDecoder = new TextDecoder(STRING_FORMAT, { fatal: false }) export const utf8ByteLength = (str: string): number => sharedTextEncoder.encode(str).byteLength /** * Safely converts content to a string, preserving structure for objects/arrays. * - If content is already a string, returns it as-is * - If content is an object or array, stringifies it with JSON.stringify to preserve structure * - Otherwise, converts to string with String() * * This prevents the "[object Object]" bug when objects are naively converted to strings. * * @param content - The content to convert to a string * @returns A string representation that preserves structure for complex types */ export function toContentString(content: unknown): string { if (typeof content === 'string') { return content } if (content !== undefined && content !== null && typeof content === 'object') { try { return JSON.stringify(content) } catch { // Fallback for circular refs, BigInt, or objects with throwing toJSON try { return String(content) } catch { // Custom coercion can throw, and null-prototype objects may have none. return '' } } } return String(content) } export interface MonitoringEventPropertiesWithDefaults { distinctId?: string traceId: string properties?: Record privacyMode: boolean groups?: Record modelOverride?: string providerOverride?: string costOverride?: CostOverride captureImmediate?: boolean /** * Per-event options for posthog-node, such as `{ process_person_profile: false }`. posthog-node 5 * has no per-event options, so each option it knows is sent the way that version reads it, and * other keys are dropped. An event with no distinct id always has person processing turned off. */ options?: Record } export type MonitoringEventProperties = Partial export type MonitoringParams = { [K in keyof MonitoringEventProperties as `posthog${Capitalize}`]: MonitoringEventProperties[K] } export interface CostOverride { inputCost: number outputCost: number } export const getModelParams = ( params: | (( | ChatCompletionCreateParamsBase | MessageCreateParams | ResponseCreateParams | ResponseCreateParamsWithTools | EmbeddingCreateParams | TranscriptionCreateParams ) & MonitoringParams) | null, responseServiceTier?: string | null ): Record => { if (!params) { return {} } const modelParams: Record = {} const paramKeys = [ 'temperature', 'max_tokens', 'max_completion_tokens', 'top_p', 'frequency_penalty', 'presence_penalty', 'n', 'stop', 'stream', 'streaming', 'language', 'response_format', 'timestamp_granularities', ] as const for (const key of paramKeys) { if (key in params && (params as any)[key] !== undefined) { modelParams[key] = (params as any)[key] } } // Only the tier the provider served may appear here: a requested tier can be refused, // and cost processing prices from this value. if (responseServiceTier != null) { modelParams.service_tier = responseServiceTier } return modelParams } export const formatResponseAnthropic = (response: any): FormattedMessage[] => { const output: FormattedMessage[] = [] const content: FormattedContent = [] for (const choice of response.content ?? []) { if (choice?.type === 'text' && choice?.text) { content.push({ type: 'text', text: choice.text }) } else if (choice?.type === 'thinking' && choice?.thinking) { // redacted_thinking blocks only carry encrypted data, so they are not captured content.push({ type: 'reasoning', text: choice.thinking }) } else if (choice?.type === 'tool_use' && choice?.name && choice?.id) { content.push({ type: 'function', id: choice.id, function: { name: choice.name, arguments: choice.input || {}, }, }) } } if (content.length > 0) { output.push({ role: 'assistant', content, }) } return output } export const formatResponseOpenAI = (response: any): FormattedMessage[] => { const output: FormattedMessage[] = [] if (response.choices) { for (const choice of response.choices) { const content: FormattedContent = [] let role = 'assistant' if (choice.message) { if (choice.message.role) { role = choice.message.role } if (choice.message.content) { content.push({ type: 'text', text: choice.message.content }) } // A refused request carries its text in `refusal` and leaves `content` empty if (choice.message.refusal) { content.push({ type: 'refusal', refusal: choice.message.refusal }) } if (choice.message.tool_calls) { for (const toolCall of choice.message.tool_calls) { // Custom tools carry their free-form text in `custom.input`, with no `function` object. const call = toolCall.type === 'custom' ? toolCall.custom : toolCall.function if (!call) { continue } content.push({ type: 'function', id: toolCall.id, function: { name: call.name, arguments: toolCall.type === 'custom' ? call.input : call.arguments, }, }) } } // Handle audio output (gpt-4o-audio-preview) if (choice.message.audio) { content.push({ type: 'audio', ...choice.message.audio, }) } } if (content.length > 0) { output.push({ role, content, }) } } } // Handle Responses API format if (response.output) { const content: FormattedContent = [] let role = 'assistant' for (const item of response.output) { if (item.type === 'message') { role = item.role if (item.content && Array.isArray(item.content)) { for (const contentItem of item.content) { if (contentItem.type === 'output_text' && contentItem.text) { content.push({ type: 'text', text: contentItem.text }) } else if (contentItem.text) { content.push({ type: 'text', text: contentItem.text }) } else if (contentItem.type === 'refusal' && contentItem.refusal) { content.push({ type: 'refusal', refusal: contentItem.refusal }) } else if (contentItem.type === 'input_image' && contentItem.image_url) { content.push({ type: 'image', image: contentItem.image_url, }) } } } else if (item.content) { content.push({ type: 'text', text: String(item.content) }) } } else if (item.type === 'function_call' || item.type === 'custom_tool_call') { content.push({ type: 'function', id: item.call_id || item.id || '', function: { name: item.name, arguments: item.type === 'custom_tool_call' ? item.input : item.arguments || {}, }, }) } else if (item.type === 'image_generation_call' && item.result) { content.push({ type: 'image', image: item.result }) } } if (content.length > 0) { output.push({ role, content, }) } } return output } export const buildInlineDataBlock = ( mimeType: string, data: string ): FormattedAudioContent | FormattedImageContent | FormattedDocumentContent => { if (mimeType.startsWith('audio/')) { return { type: 'audio', mime_type: mimeType, data } } if (mimeType.startsWith('image/')) { return { type: 'image', inline_data: { mime_type: mimeType, data } } } return { type: 'document', inline_data: { mime_type: mimeType, data } } } export const uint8ArrayToBase64 = (data: Uint8Array): string => { if (typeof Buffer !== 'undefined') { return Buffer.from(data).toString('base64') } let binary = '' for (let i = 0; i < data.length; i++) { binary += String.fromCharCode(data[i]) } return btoa(binary) } export const formatInlineDataBlock = ( inlineData: { mimeType?: string; mime_type?: string; data?: unknown }, client?: FullAiCaptureGate ): FormattedAudioContent | FormattedImageContent | FormattedDocumentContent => { const mimeType = inlineData.mimeType || inlineData.mime_type || 'application/octet-stream' let data = inlineData.data if (data instanceof Uint8Array) { data = uint8ArrayToBase64(data) } data = isFullAiCaptureEnabled(client) ? data : redactBase64DataUrl(data, mimeType) return buildInlineDataBlock(mimeType, String(data ?? '')) } export const formatResponseGemini = (response: any, client?: FullAiCaptureGate): FormattedMessage[] => { const output: FormattedMessage[] = [] if (response.candidates && Array.isArray(response.candidates)) { for (const candidate of response.candidates) { if (candidate.content && candidate.content.parts) { const content: FormattedContent = [] for (const part of candidate.content.parts) { if (part.thought === true && part.text) { content.push({ type: 'reasoning', text: part.text }) } else if (part.text) { content.push({ type: 'text', text: part.text }) } else if (part.functionCall) { content.push({ type: 'function', ...(part.functionCall.id != null ? { id: part.functionCall.id } : {}), function: { name: part.functionCall.name, arguments: part.functionCall.args, }, }) } else if (part.inlineData) { content.push(formatInlineDataBlock(part.inlineData, client)) } } if (content.length > 0) { output.push({ role: 'assistant', content, }) } } else if (candidate.text) { output.push({ role: 'assistant', content: [{ type: 'text', text: candidate.text }], }) } } } else if (response.text) { output.push({ role: 'assistant', content: [{ type: 'text', text: response.text }], }) } return output } export const mergeSystemPrompt = (params: MessageCreateParams & MonitoringParams, provider: string): any => { if (provider == 'anthropic') { const messages = params.messages || [] if (!(params as any).system) { return messages } const systemMessage = (params as any).system return [{ role: 'system', content: systemMessage }, ...messages] } return params.messages } export const withPrivacyMode = (client: PrivacyModeGate, privacyMode: boolean, input: any): any => { return isPrivacyModeEnabled(client, privacyMode) ? null : input } function toSafeString(input: unknown): string { if (input === undefined || input === null) { return '' } if (typeof input === 'string') { return input } try { return JSON.stringify(input) } catch { console.warn('Failed to stringify input', input) return '' } } export const truncate = (input: unknown, client?: FullAiCaptureGate, maxBytes = MAX_OUTPUT_SIZE): string => { const str = toSafeString(input) if (str === '') { return '' } if (isFullAiCaptureEnabled(client)) { return str } // Check if we need to truncate and ensure STRING_FORMAT is respected const buffer = sharedTextEncoder.encode(str) if (buffer.length <= maxBytes) { // Ensure STRING_FORMAT is respected return sharedTextDecoder.decode(buffer) } // Truncate the buffer and ensure a valid string is returned. // fatal: false means we get U+FFFD at the end if truncation broke the encoding. const truncatedBuffer = buffer.slice(0, maxBytes) let truncatedStr = sharedTextDecoder.decode(truncatedBuffer) if (truncatedStr.endsWith('\uFFFD')) { truncatedStr = truncatedStr.slice(0, -1) } return `${truncatedStr}... [truncated]` } /** * Calculate web search count from raw API response. * * Uses a two-tier detection strategy: * Priority 1 (Exact Count): Count actual web search calls when available * Priority 2 (Binary Detection): Return 1 if web search indicators are present, 0 otherwise * * @param result - Raw API response from any provider (OpenAI, Perplexity, OpenRouter, Gemini, etc.) * @returns Number of web searches performed (exact count or binary 1/0) */ export function calculateWebSearchCount(result: unknown): number { if (!result || typeof result !== 'object') { return 0 } // Priority 1: Exact Count // Check for OpenAI Responses API web_search_call items if ('output' in result && Array.isArray(result.output)) { let count = 0 for (const item of result.output) { if (typeof item === 'object' && item !== null && 'type' in item && item.type === 'web_search_call') { count++ } } if (count > 0) { return count } } // Priority 2: Binary Detection (1 or 0) // Check for citations at root level (Perplexity) if ('citations' in result && Array.isArray(result.citations) && result.citations.length > 0) { return 1 } // Check for search_results at root level (Perplexity via OpenRouter) if ('search_results' in result && Array.isArray(result.search_results) && result.search_results.length > 0) { return 1 } // Check for usage.search_context_size (Perplexity via OpenRouter) if ('usage' in result && typeof result.usage === 'object' && result.usage !== null) { if ('search_context_size' in result.usage && result.usage.search_context_size) { return 1 } } // Check for annotations with url_citation in choices[].message or choices[].delta (OpenAI/Perplexity) if ('choices' in result && Array.isArray(result.choices)) { for (const choice of result.choices) { if (typeof choice === 'object' && choice !== null) { // Check both message (non-streaming) and delta (streaming) for annotations const content = ('message' in choice ? choice.message : null) || ('delta' in choice ? choice.delta : null) if (typeof content === 'object' && content !== null && 'annotations' in content) { const annotations = content.annotations if (Array.isArray(annotations)) { const hasUrlCitation = annotations.some((ann: unknown) => { return typeof ann === 'object' && ann !== null && 'type' in ann && ann.type === 'url_citation' }) if (hasUrlCitation) { return 1 } } } } } } // Check for annotations in output[].content[] (OpenAI Responses API) if ('output' in result && Array.isArray(result.output)) { for (const item of result.output) { if (typeof item === 'object' && item !== null && 'content' in item) { const content = item.content if (Array.isArray(content)) { for (const contentItem of content) { if (typeof contentItem === 'object' && contentItem !== null && 'annotations' in contentItem) { const annotations = contentItem.annotations if (Array.isArray(annotations)) { const hasUrlCitation = annotations.some((ann: unknown) => { return typeof ann === 'object' && ann !== null && 'type' in ann && ann.type === 'url_citation' }) if (hasUrlCitation) { return 1 } } } } } } } } // Check for grounding_metadata (Gemini) if ('candidates' in result && Array.isArray(result.candidates)) { for (const candidate of result.candidates) { if ( typeof candidate === 'object' && candidate !== null && 'grounding_metadata' in candidate && candidate.grounding_metadata ) { return 1 } } } return 0 } /** * Extract available tool calls from the request parameters. * These are the tools provided to the LLM, not the tool calls in the response. */ export const extractAvailableToolCalls = (provider: string, params: any): unknown[] | null => { if (provider === 'anthropic') { if (params.tools) { return params.tools } return null } else if (provider === 'gemini') { if (params.config && params.config.tools) { return params.config.tools } return null } else if (provider === 'openai') { if (params.tools) { return params.tools } return null } else if (provider === 'vercel') { if (params.tools) { return params.tools } return null } return null } export enum AIEvent { Generation = '$ai_generation', Embedding = '$ai_embedding', } export function sanitizeValues(obj: any): any { if (obj === undefined || obj === null) { return obj } const jsonSafe = JSON.parse(JSON.stringify(obj)) if (typeof jsonSafe === 'string') { // Sanitize lone surrogates by round-tripping through UTF-8 return new TextDecoder().decode(new TextEncoder().encode(jsonSafe)) } else if (Array.isArray(jsonSafe)) { return jsonSafe.map(sanitizeValues) } else if (jsonSafe && typeof jsonSafe === 'object') { return Object.fromEntries(Object.entries(jsonSafe).map(([k, v]) => [k, sanitizeValues(v)])) } return jsonSafe } const POSTHOG_PARAMS_MAP: Record = { posthogDistinctId: 'distinctId', posthogTraceId: 'traceId', posthogProperties: 'properties', posthogPrivacyMode: 'privacyMode', posthogGroups: 'groups', posthogModelOverride: 'modelOverride', posthogProviderOverride: 'providerOverride', posthogCostOverride: 'costOverride', posthogCaptureImmediate: 'captureImmediate', posthogOptions: 'options', } export function extractPosthogParams(body: T & MonitoringParams): { providerParams: T posthogParams: MonitoringEventPropertiesWithDefaults } { const providerParams: Record = {} const posthogParams: Record = {} for (const [key, value] of Object.entries(body)) { if (POSTHOG_PARAMS_MAP[key as keyof MonitoringParams]) { posthogParams[POSTHOG_PARAMS_MAP[key as keyof MonitoringParams]] = value } else if (key.startsWith('posthog')) { console.warn(`Unknown Posthog parameter ${key}`) } else { providerParams[key] = value } } return { providerParams: providerParams as T, posthogParams: addDefaults(posthogParams), } } function addDefaults(params: MonitoringEventProperties): MonitoringEventPropertiesWithDefaults { return { ...params, privacyMode: params.privacyMode ?? false, traceId: params.traceId ?? uuidv4(), } } export function formatOpenAIResponsesInput(input: unknown, instructions?: string | null): FormattedMessage[] { const messages: FormattedMessage[] = [] if (instructions) { messages.push({ role: 'system', content: instructions, }) } if (Array.isArray(input)) { for (const item of input) { if (typeof item === 'string') { messages.push({ role: 'user', content: item }) } else if (item && typeof item === 'object') { const obj = item as Record const role = isString(obj.role) ? obj.role : 'user' // Handle content properly - preserve structure for objects/arrays const content = obj.content ?? obj.text ?? item messages.push({ role, content: toContentString(content) }) } else { messages.push({ role: 'user', content: toContentString(item) }) } } } else if (typeof input === 'string') { messages.push({ role: 'user', content: input }) } else if (input) { messages.push({ role: 'user', content: toContentString(input) }) } return messages }