@posthog/ai 7.16.15 → 7.17.0

package/dist/index.d.ts

@@ -6,7 +6,7 @@ import { ResponseCreateParamsWithTools, ExtractParsedContentFromParams } from 'o
 import { LanguageModelV2, LanguageModelV3 } from '@ai-sdk/provider';
 import AnthropicOriginal, { APIPromise as APIPromise$1 } from '@anthropic-ai/sdk';
 import { Stream as Stream$1 } from '@anthropic-ai/sdk/streaming';
-import { GoogleGenAI, GenerateContentParameters, GenerateContentResponse, EmbedContentParameters, EmbedContentResponse, GoogleGenAIOptions } from '@google/genai';
+import { GoogleGenAI, GenerateContentParameters, GenerateContentResponse, EmbedContentParameters, EmbedContentResponse, GoogleGenAIOptions, Tool } from '@google/genai';
 import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
 import { Serialized } from '@langchain/core/load/serializable';
 import { ChainValues } from '@langchain/core/utils/types';
@@ -14,7 +14,20 @@ import { LLMResult } from '@langchain/core/outputs';
 import { AgentAction, AgentFinish } from '@langchain/core/agents';
 import { DocumentInterface } from '@langchain/core/documents';
 import { BaseMessage } from '@langchain/core/messages';
+import { ChatCompletionTool } from 'openai/resources/chat/completions';
 
+/**
+ * Token usage information for AI model responses
+ */
+interface TokenUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    reasoningTokens?: unknown;
+    cacheReadInputTokens?: unknown;
+    cacheCreationInputTokens?: unknown;
+    webSearchCount?: number;
+    rawUsage?: unknown;
+}
 /**
  * Options for fetching a prompt
  */
@@ -91,6 +104,10 @@ interface CostOverride {
     inputCost: number;
     outputCost: number;
 }
+declare enum AIEvent {
+    Generation = "$ai_generation",
+    Embedding = "$ai_embedding"
+}
 
 declare const Chat: typeof OpenAI.Chat;
 declare const Completions: typeof OpenAI.Chat.Completions;
@@ -418,4 +435,68 @@ declare class Prompts {
     private fetchPromptFromApi;
 }
 
-export { PostHogAnthropic as Anthropic, PostHogAzureOpenAI as AzureOpenAI, PostHogGoogleGenAI as GoogleGenAI, LangChainCallbackHandler, PostHogOpenAI as OpenAI, type PromptCodeFallbackResult, type PromptRemoteResult, type PromptResult, Prompts, wrapVercelLanguageModel as withTracing };
+type AnthropicTool = AnthropicOriginal.Tool;
+/**
+ * Options for `captureAiGeneration`. Mirrors the `$ai_generation` event shape
+ * directly so that any caller — first-party SDK wrappers and external code
+ * alike — produces an identical event.
+ */
+interface CaptureAiGenerationOptions {
+    distinctId?: string;
+    /** Auto-generated when omitted. */
+    traceId?: string;
+    /** Defaults to `$ai_generation`. */
+    eventType?: AIEvent;
+    /** Required for the event to be useful, but accepted as optional so SDK wrappers can pass through whatever they detect. */
+    model?: string;
+    provider: string;
+    input: unknown;
+    output: unknown;
+    /** Maps to `$ai_model_parameters` (temperature, max_tokens, top_p, …). */
+    modelParameters?: Record<string, unknown>;
+    baseURL?: string;
+    httpStatus?: number;
+    /** Wall-clock latency in seconds. */
+    latency?: number;
+    /** Time from request start to the first streamed token, in seconds. */
+    timeToFirstToken?: number;
+    usage?: TokenUsage;
+    /** Extra event properties merged into the captured event. */
+    properties?: Record<string, unknown>;
+    /** Mapping of group type to group id, matching `EventMessage.groups`. */
+    groups?: Record<string, string | number>;
+    privacyMode?: boolean;
+    /**
+     * For SDK wrappers: overrides the auto-detected model. External callers
+     * should pass `model` directly instead.
+     */
+    modelOverride?: string;
+    /**
+     * For SDK wrappers: overrides the auto-detected provider. External callers
+     * should pass `provider` directly instead.
+     */
+    providerOverride?: string;
+    costOverride?: CostOverride;
+    tools?: ChatCompletionTool[] | AnthropicTool[] | Tool[] | null;
+    stopReason?: string;
+    /** When set, the event is captured as an error. */
+    error?: unknown;
+    /** Awaits delivery instead of batching. Useful in serverless environments. */
+    captureImmediate?: boolean;
+}
+/**
+ * Capture an `$ai_generation` (or `$ai_embedding`) event to PostHog.
+ *
+ * This is the canonical primitive that every `@posthog/ai` wrapper
+ * (`withTracing`, `OpenAI`, `Anthropic`, `GoogleGenAI`, …) funnels through, so
+ * external code can use it directly to instrument LLM calls made through
+ * arbitrary clients (Cloudflare Workers AI, custom HTTP, etc.) and get the
+ * same events the SDK wrappers produce.
+ *
+ * When `error` is set, the event is captured as an error. If the error is an
+ * object, it is mutated in place to set `__posthog_previously_captured_error`
+ * so callers can re-throw the original error reference safely.
+ */
+declare const captureAiGeneration: (client: PostHog, options: CaptureAiGenerationOptions) => Promise<void>;
+
+export { AIEvent, PostHogAnthropic as Anthropic, PostHogAzureOpenAI as AzureOpenAI, type CaptureAiGenerationOptions, PostHogGoogleGenAI as GoogleGenAI, LangChainCallbackHandler, PostHogOpenAI as OpenAI, type PromptCodeFallbackResult, type PromptRemoteResult, type PromptResult, Prompts, captureAiGeneration, wrapVercelLanguageModel as withTracing };