@posthog/ai 8.1.11 → 8.2.1

package/LICENSE

@@ -324,3 +324,30 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+---
+
+Some files in this codebase contain code from MCPCat/mcpcat-typescript-sdk.
+In such cases it is explicitly stated in the file header. This license only applies to the relevant code in such cases.
+
+MIT License
+
+Copyright (c) 2025 MCPcat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,156 +1,13 @@
-# PostHog Node AI
+# PostHog AI package
 
-TypeScript SDK for LLM observability with PostHog.
+Please see the main [PostHog docs](https://posthog.com/docs).
 
-[SEE FULL DOCS](https://posthog.com/docs/ai-engineering/observability)
+SDK usage examples and code snippets live in the official documentation so they stay up to date.
 
-## Installation
+## Documentation
 
-Provider SDKs are optional peer dependencies, so you only install the SDK for the integration you use. Install `@posthog/ai` alongside it:
-
-```bash
-npm install @posthog/ai openai            # OpenAI / Azure OpenAI
-npm install @posthog/ai @anthropic-ai/sdk # Anthropic
-npm install @posthog/ai @google/genai     # Google Gemini
-npm install @posthog/ai @langchain/core   # LangChain
-# Vercel AI SDK (withTracing), captureAiGeneration, and OpenTelemetry need no provider SDK
-```
-
-Import each integration from its subpath:
-
-| Integration | Import from | Peer to install |
-| --- | --- | --- |
-| OpenAI / Azure OpenAI | `@posthog/ai/openai` | `openai` |
-| Anthropic | `@posthog/ai/anthropic` | `@anthropic-ai/sdk` |
-| Google Gemini | `@posthog/ai/gemini` | `@google/genai` |
-| LangChain | `@posthog/ai/langchain` | `@langchain/core` |
-| Vercel AI SDK (`withTracing`) | `@posthog/ai` | — |
-| Custom (`captureAiGeneration`) | `@posthog/ai` | — |
-
-## Direct Provider Usage
-
-```typescript
-import { OpenAI } from '@posthog/ai/openai'
-import { PostHog } from 'posthog-node'
-
-const phClient = new PostHog('<YOUR_PROJECT_API_KEY>', { host: 'https://us.i.posthog.com' })
-
-const client = new OpenAI({
-  apiKey: '<YOUR_OPENAI_API_KEY>',
-  posthog: phClient,
-})
-
-const completion = await client.chat.completions.create({
-  model: 'gpt-5-mini',
-  messages: [{ role: 'user', content: 'Tell me a fun fact about hedgehogs' }],
-  posthogDistinctId: 'user_123', // optional
-  posthogTraceId: 'trace_123', // optional
-  posthogProperties: { conversation_id: 'abc123', paid: true }, //optional
-  posthogGroups: { company: 'company_id_in_your_db' }, // optional
-  posthogPrivacyMode: false, // optional
-})
-
-console.log(completion.choices[0].message.content)
-
-// YOU HAVE TO HAVE THIS OR THE CLIENT MAY NOT SEND EVENTS
-await phClient.shutdown()
-```
-
-## Custom and unsupported providers
-
-For LLM calls that don't go through one of the wrapped clients — direct Cloudflare Workers AI bindings, TanStack AI adapters, custom HTTP clients — use `captureAiGeneration` to emit the same `$ai_generation` events the wrappers produce.
-
-```typescript
-import { captureAiGeneration } from '@posthog/ai'
-import { PostHog } from 'posthog-node'
-
-const phClient = new PostHog('<YOUR_PROJECT_API_KEY>', { host: 'https://us.i.posthog.com' })
-
-const start = Date.now()
-const result = await env.AI.run('@cf/zai-org/glm-4.7-flash', { messages, reasoning_effort: 'high' })
-
-await captureAiGeneration(phClient, {
-  distinctId: 'user_123',
-  traceId: 'trace_abc',
-  provider: 'cloudflare-workers-ai',
-  model: '@cf/zai-org/glm-4.7-flash',
-  input: messages,
-  output: result.response,
-  modelParameters: { reasoning_effort: 'high' },
-  usage: { inputTokens: result.usage?.prompt_tokens, outputTokens: result.usage?.completion_tokens },
-  latency: (Date.now() - start) / 1000,
-  properties: { feature: 'transcript-toc' },
-})
-
-await phClient.shutdown()
-```
-
-`captureAiGeneration` is the same primitive that every other `@posthog/ai` wrapper funnels through, so the resulting events are indistinguishable from those produced by `withTracing`, `OpenAI`, `Anthropic`, etc.
-
-## OpenTelemetry
-
-`@posthog/ai/otel` provides two ways to send AI traces to PostHog via OpenTelemetry. Both automatically filter to AI-related spans only (`gen_ai.*`, `llm.*`, `ai.*`, `traceloop.*`) and PostHog converts them into `$ai_generation` events server-side. `projectToken` is required; a blank token disables the OpenTelemetry integration as a defensive no-op. This works with any LLM provider SDK that supports OpenTelemetry.
-
-```bash
-npm install @posthog/ai @opentelemetry/sdk-node @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-http
-```
-
-### PostHogSpanProcessor (recommended)
-
-A self-contained `SpanProcessor` that handles batching and export internally. Use this when your setup accepts a span processor.
-
-```typescript
-import { NodeSDK } from '@opentelemetry/sdk-node'
-import { PostHogSpanProcessor } from '@posthog/ai/otel'
-import { generateText } from 'ai'
-import { openai } from '@ai-sdk/openai'
-
-const sdk = new NodeSDK({
-  spanProcessors: [
-    new PostHogSpanProcessor({
-      projectToken: '<YOUR_PROJECT_TOKEN>',
-      host: 'https://us.i.posthog.com', // optional, defaults to https://us.i.posthog.com
-    }),
-  ],
-})
-sdk.start()
-
-const result = await generateText({
-  model: openai('gpt-5-mini'),
-  prompt: 'Write a short haiku about debugging',
-  experimental_telemetry: {
-    isEnabled: true,
-    functionId: 'my-awesome-function',
-    metadata: {
-      posthog_distinct_id: 'user_123',
-      conversation_id: 'abc123',
-    },
-  },
-})
-
-await sdk.shutdown()
-```
-
-### PostHogTraceExporter
-
-A `TraceExporter` for APIs that only accept an exporter, such as Vercel's `registerOTel`.
-
-```typescript
-import { PostHogTraceExporter } from '@posthog/ai/otel'
-import { registerOTel } from '@vercel/otel'
-
-registerOTel({
-  serviceName: 'my-app',
-  traceExporter: new PostHogTraceExporter({
-    projectToken: '<YOUR_PROJECT_TOKEN>',
-    host: 'https://us.i.posthog.com', // optional, defaults to https://us.i.posthog.com
-  }),
-})
-```
-
-LLM Observability [docs](https://posthog.com/docs/ai-engineering/observability)
-
-Please see the main [PostHog docs](https://www.posthog.com/docs).
+- [AI observability installation docs](https://posthog.com/docs/ai-observability/installation)
+- [AI observability docs](https://posthog.com/docs/ai-observability)
 
 ## Questions?
 

package/dist/anthropic/index.cjs

@@ -299,7 +299,7 @@ function addDefaults(params) {
   };
 }
 
-var version = "8.1.11";
+var version = "8.2.1";
 
 const DEFAULT_MAX_DEPTH = 3;
 const MAX_STACK_LINES = 20;
@@ -352,6 +352,44 @@ function truncateStack(stack) {
   return [...lines.slice(0, MAX_STACK_LINES), '... (truncated)'].join('\n');
 }
 
+// Warn when a wrapper's base_url points at the PostHog AI Gateway: the gateway
+// emits its own $ai_generation, so each call would be captured (and, for billable
+// products, billed) twice. We only warn — the wrapper's event carries data the
+// gateway never sees (groups, custom properties, trace hierarchy).
+
+// Keep in sync with the gateway's deployed hosts (see services/llm-gateway in the
+// main repo). gateway.us.posthog.com is live today; the rest are listed ahead of
+// any traffic moving to them.
+const POSTHOG_AI_GATEWAY_HOSTS = ['gateway.posthog.com', 'gateway.us.posthog.com', 'gateway.eu.posthog.com', 'ai-gateway.us.posthog.com', 'ai-gateway.eu.posthog.com'];
+
+// Swap for the dedicated AI Gateway page once it ships.
+const GATEWAY_DOCS_URL = 'https://posthog.com/docs/ai-observability';
+const extractHost = baseURL => {
+  try {
+    // Tolerate bare hosts that omit a scheme, e.g. "gateway.us.posthog.com/v1".
+    const hasScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(baseURL);
+    return new URL(hasScheme ? baseURL : `https://${baseURL}`).hostname.toLowerCase();
+  } catch {
+    return undefined;
+  }
+};
+const isPostHogAiGatewayUrl = baseURL => {
+  if (!baseURL) {
+    return false;
+  }
+  const host = extractHost(baseURL);
+  return host !== undefined && POSTHOG_AI_GATEWAY_HOSTS.includes(host);
+};
+
+// Warns on every gateway call by design: the misconfiguration is impossible to
+// miss that way, and a doubled bill is worse than noisy logs.
+const warnIfPostHogAiGateway = baseURL => {
+  if (!isPostHogAiGatewayUrl(baseURL)) {
+    return;
+  }
+  console.warn('[PostHog] The PostHog AI wrapper is pointed at the PostHog AI Gateway. ' + 'Both capture $ai_generation, so every call is double-counted and double-billed. ' + `Use one or the other — see ${GATEWAY_DOCS_URL}.`);
+};
+
 /**
  * Options for `captureAiGeneration`. Mirrors the `$ai_generation` event shape
  * directly so that any caller — first-party SDK wrappers and external code
@@ -375,6 +413,7 @@ const captureAiGeneration = async (client, options) => {
   if (!client.capture) {
     return;
   }
+  warnIfPostHogAiGateway(options.baseURL);
   const traceId = options.traceId ?? uuid.v4();
   const eventType = options.eventType ?? AIEvent.Generation;
   const privacyMode = options.privacyMode ?? false;