diff --git a/.claude/skills/integration-javascript_node/.posthog-wizard b/.claude/skills/integration-javascript_node/.posthog-wizard
new file mode 100644
index 000000000..e69de29bb
diff --git a/.claude/skills/integration-javascript_node/SKILL.md b/.claude/skills/integration-javascript_node/SKILL.md
new file mode 100644
index 000000000..a83b4745e
--- /dev/null
+++ b/.claude/skills/integration-javascript_node/SKILL.md
@@ -0,0 +1,58 @@
+---
+name: integration-javascript_node
+description: PostHog integration for server-side Node.js applications using posthog-node
+metadata:
+ author: PostHog
+ version: 1.21.1
+---
+
+# PostHog integration for JavaScript Node
+
+This skill helps you add PostHog analytics to JavaScript Node applications.
+
+## Workflow
+
+Follow these steps in order to complete the integration:
+
+1. `basic-integration-1.0-begin.md` - PostHog Setup - Begin ← **Start here**
+2. `basic-integration-1.1-edit.md` - PostHog Setup - Edit
+3. `basic-integration-1.2-revise.md` - PostHog Setup - Revise
+4. `basic-integration-1.3-conclude.md` - PostHog Setup - Conclusion
+
+## Reference files
+
+- `references/node.md` - Node.js - docs
+- `references/posthog-node.md` - PostHog Node.js SDK
+- `references/identify-users.md` - Identify users - docs
+- `references/basic-integration-1.0-begin.md` - PostHog setup - begin
+- `references/basic-integration-1.1-edit.md` - PostHog setup - edit
+- `references/basic-integration-1.2-revise.md` - PostHog setup - revise
+- `references/basic-integration-1.3-conclude.md` - PostHog setup - conclusion
+
+The example project shows the target implementation pattern. Consult the documentation for API details.
+
+## Key principles
+
+- **Environment variables**: Always use environment variables for PostHog keys. Never hardcode them.
+- **Minimal changes**: Add PostHog code alongside existing integrations. Don't replace or restructure existing code.
+- **Match the example**: Your implementation should follow the example project's patterns as closely as possible.
+
+## Framework guidelines
+
+- posthog-node is the Node.js server-side SDK package name – do NOT use posthog-js on the server
+- Include enableExceptionAutocapture: true in the PostHog constructor options
+- Add posthog.capture() calls in route handlers for meaningful user actions – every route that creates, updates, or deletes data should track an event with contextual properties
+- Add posthog.captureException(err, distinctId) in the application's error handler (e.g., Express error middleware, Fastify setErrorHandler, Koa app.on('error'))
+- In long-running servers, the SDK batches events automatically – do NOT set flushAt or flushInterval unless you have a specific reason to
+- For short-lived processes (scripts, CLIs, serverless), set flushAt to 1 and flushInterval to 0 to send events immediately
+- Reverse proxy is NOT needed for server-side Node.js – only client-side JavaScript needs a proxy to avoid ad blockers
+- Remember that source code is available in the node_modules directory
+- Check package.json for type checking or build scripts to validate changes
+
+## Identifying users
+
+Identify users during login and signup events. Refer to the example code and documentation for the correct identify pattern for this framework. If both frontend and backend code exist, pass the client-side session and distinct ID using `X-POSTHOG-DISTINCT-ID` and `X-POSTHOG-SESSION-ID` headers to maintain correlation.
+
+## Error tracking
+
+Add PostHog error tracking to relevant files, particularly around critical user flows and API boundaries.
diff --git a/.claude/skills/integration-javascript_node/references/basic-integration-1.0-begin.md b/.claude/skills/integration-javascript_node/references/basic-integration-1.0-begin.md
new file mode 100644
index 000000000..49db3cb9f
--- /dev/null
+++ b/.claude/skills/integration-javascript_node/references/basic-integration-1.0-begin.md
@@ -0,0 +1,56 @@
+---
+title: PostHog Setup - Begin
+description: Start the event tracking setup process by analyzing the project and creating an event tracking plan
+---
+
+We're making an event tracking plan for this project.
+
+This is the first of several phases — plan the events, implement them, revise and validate changes, then conclude by creating a dashboard and writing a setup report.
+
+## Task list
+
+As soon as you've read this description and have a rough sense of the work, make a single **call `TaskCreate` immediately** before reading any reference file or beginning analysis. The user is watching the task pane and shouldn't see it sit empty.
+
+It's fine if your first list is incomplete or imprecise. Seed it with whatever high-level items you can infer from the overview above, then call `TaskCreate` again (or `TaskUpdate` to refine existing items) every time your understanding sharpens: after a phase reveals work you didn't anticipate, after planning surfaces concrete sub-items, after you hit something new. Use `TaskUpdate` to mark items `in_progress` when you start them and `completed` when you finish. Keeping the list current matters more than getting it right on the first call.
+
+Keep task titles broad and job-oriented. Describe the purpose or area of work with wording like "Planning event tracking", "Identifying users", "Installing PostHog", "Capturing events", or "Creating dashboards", not the specific files, paths, or symbols involved. Adjust the task names according to the user's project and context.
+
+Before proceeding, find any existing `posthog.capture()` code. Make note of event name formatting.
+
+From the project's file list, select between 10 and 15 files that might have interesting business value for event tracking, especially conversion and churn events. Also look for additional files related to login that could be used for identifying users, along with error handling. Read the files. If a file is already well-covered by PostHog events, replace it with another option. Do not spawn subagents.
+
+Look for opportunities to track client-side events.
+
+**IMPORTANT: Server-side events are REQUIRED** if the project includes any instrumentable server-side code. If the project has API routes (e.g., `app/api/**/route.ts`) or Server Actions, you MUST include server-side events for critical business operations like:
+
+ - Payment/checkout completion
+ - Webhook handlers
+ - Authentication endpoints
+
+Do not skip server-side events - they capture actions that cannot be tracked client-side.
+
+Create a new file with a JSON array at the root of the project: .posthog-events.json. It should include one object for each event we want to add: event name, event description, and the file path we want to place the event in. If events already exist, don't duplicate them; supplement them.
+
+Track actions only, not pageviews. These can be captured automatically. Exceptions can be made for "viewed"-type events that correspond to the top of a conversion funnel.
+
+As you review files, make an internal note of opportunities to identify users and catch errors. We'll need them for the next step.
+
+## Status
+
+Before beginning a phase of the setup, you will send a status message with the exact prefix '[STATUS]', as in:
+
+[STATUS] Checking project structure.
+
+Status to report in this phase:
+
+- Checking project structure
+- Verifying PostHog dependencies
+- Generating events based on project
+
+## Abort statuses
+
+If and only if the instructions have `[ABORT]` states specified, and you clearly match the conditions for an abort, emit the abort message. Do NOT attempt to exit or halt yourself — the wizard's middleware catches `[ABORT]` and terminates the run for you.
+
+---
+
+**Upon completion, continue with:** [basic-integration-1.1-edit.md](basic-integration-1.1-edit.md)
\ No newline at end of file
diff --git a/.claude/skills/integration-javascript_node/references/basic-integration-1.1-edit.md b/.claude/skills/integration-javascript_node/references/basic-integration-1.1-edit.md
new file mode 100644
index 000000000..ca9d70e66
--- /dev/null
+++ b/.claude/skills/integration-javascript_node/references/basic-integration-1.1-edit.md
@@ -0,0 +1,37 @@
+---
+title: PostHog Setup - Edit
+description: Implement PostHog event tracking in the identified files, following best practices and the example project
+---
+
+For each of the files and events noted in .posthog-events.json, make edits to capture events using PostHog. Make sure to set up any helper files needed. Carefully examine the included example project code: your implementation should match it as closely as possible. Do not spawn subagents.
+
+Use environment variables for PostHog keys. Do not hardcode PostHog keys.
+
+If a file already has existing integration code for other tools or services, don't overwrite or remove that code. Place PostHog code below it.
+
+For each event, add useful properties, and use your access to the PostHog source code to ensure correctness. You also have access to documentation about creating new events with PostHog. Consider this documentation carefully and follow it closely before adding events. Your integration should be based on documented best practices. Carefully consider how the user project's framework version may impact the correct PostHog integration approach.
+
+Remember that you can find the source code for any dependency in the node_modules directory. This may be necessary to properly populate property names. There are also example project code files available via the PostHog MCP; use these for reference.
+
+Where possible, add calls for PostHog's identify() function on the client side upon events like logins and signups. Use the contents of login and signup forms to identify users on submit. If there is server-side code, pass the client-side session and distinct ID to the server-side code to identify the user. On the server side, make sure events have a matching distinct ID where relevant.
+
+It's essential to do this in both client code and server code, so that user behavior from both domains is easy to correlate.
+
+You should also add PostHog exception capture error tracking to these files where relevant.
+
+Remember: Do not alter the fundamental architecture of existing files. Make your additions minimal and targeted.
+
+Remember the documentation and example project resources you were provided at the beginning. Read them now.
+
+## Status
+
+Status to report in this phase:
+
+- Inserting PostHog capture code
+- A status message for each file whose edits you are planning, including a high level summary of changes
+- A status message for each file you have edited
+
+
+---
+
+**Upon completion, continue with:** [basic-integration-1.2-revise.md](basic-integration-1.2-revise.md)
\ No newline at end of file
diff --git a/.claude/skills/integration-javascript_node/references/basic-integration-1.2-revise.md b/.claude/skills/integration-javascript_node/references/basic-integration-1.2-revise.md
new file mode 100644
index 000000000..5ac72f06f
--- /dev/null
+++ b/.claude/skills/integration-javascript_node/references/basic-integration-1.2-revise.md
@@ -0,0 +1,22 @@
+---
+title: PostHog Setup - Revise
+description: Review and fix any errors in the PostHog integration implementation
+---
+
+Check the project for errors. Read the package.json file for any type checking or build scripts that may provide input about what to fix. Remember that you can find the source code for any dependency in the node_modules directory. Do not spawn subagents.
+
+Ensure that any components created were actually used.
+
+Once all other tasks are complete, run any linter or prettier-like scripts found in the package.json, but ONLY on the files you have edited or created during this session. Do not run formatting or linting across the entire project's codebase.
+
+## Status
+
+Status to report in this phase:
+
+- Finding and correcting errors
+- Report details of any errors you fix
+- Linting, building and prettying
+
+---
+
+**Upon completion, continue with:** [basic-integration-1.3-conclude.md](basic-integration-1.3-conclude.md)
\ No newline at end of file
diff --git a/.claude/skills/integration-javascript_node/references/basic-integration-1.3-conclude.md b/.claude/skills/integration-javascript_node/references/basic-integration-1.3-conclude.md
new file mode 100644
index 000000000..39339f5a5
--- /dev/null
+++ b/.claude/skills/integration-javascript_node/references/basic-integration-1.3-conclude.md
@@ -0,0 +1,40 @@
+---
+title: PostHog Setup - Conclusion
+description: Review and fix any errors in the PostHog integration implementation
+---
+
+Use the PostHog MCP to create a new dashboard named "Analytics basics (wizard)" based on the events created here. Keep the `(wizard)` tag with that exact casing so anyone browsing PostHog can see the wizard created this dashboard, and so a quick search for `(wizard)` surfaces every wizard-created artifact in one go. Make sure to use the exact same event names as implemented in the code. Populate it with up to five insights, with special emphasis on things like conversion funnels, churn events, and other business critical insights.
+
+Search for a file called `.posthog-events.json` and read it for available events.
+
+Do not spawn subagents.
+
+Create the file posthog-setup-report.md. It should include a summary of the integration edits, a table with the event names, event descriptions, and files where events were added, along with a list of links for the dashboard and insights created. Follow this format:
+
+
+# PostHog post-wizard report
+
+The wizard has completed a deep integration of your project. [Detailed summary of changes]
+
+[table of events/descriptions/files]
+
+## Next steps
+
+We've built some insights and a dashboard for you to keep an eye on user behavior, based on the events we just instrumented:
+
+[links]
+
+### Agent skill
+
+We've left an agent skill folder in your project. You can use this context for further agent development when using Claude Code. This will help ensure the model provides the most up-to-date approaches for integrating PostHog.
+
+
+
+Upon completion, remove .posthog-events.json.
+
+## Status
+
+Status to report in this phase:
+
+- Configured dashboard: [insert PostHog dashboard URL]
+- Created setup report: [insert full local file path]
\ No newline at end of file
diff --git a/.claude/skills/integration-javascript_node/references/identify-users.md b/.claude/skills/integration-javascript_node/references/identify-users.md
new file mode 100644
index 000000000..564ead280
--- /dev/null
+++ b/.claude/skills/integration-javascript_node/references/identify-users.md
@@ -0,0 +1,271 @@
+# Identify users - Docs
+
+Linking events to specific users enables you to build a full picture of how they're using your product across different sessions, devices, and platforms.
+
+This is straightforward to do when [capturing backend events](/docs/product-analytics/capture-events?tab=Node.js.md), as you associate events to a specific user using a `distinct_id`, which is a required argument.
+
+However, in the frontend of a [web](/docs/libraries/js/features.md#capturing-events) or [mobile app](/docs/libraries/ios.md#capturing-events), a `distinct_id` is not a required argument — PostHog's SDKs will generate an anonymous `distinct_id` for you automatically and you can capture events anonymously, provided you use the appropriate [configuration](/docs/libraries/js/features.md#capturing-anonymous-events).
+
+To link events to specific users, call `identify`:
+
+PostHog AI
+
+### Web
+
+```javascript
+posthog.identify(
+ 'distinct_id', // Replace 'distinct_id' with your user's unique identifier
+ { email: 'max@hedgehogmail.com', name: 'Max Hedgehog' } // optional: set additional person properties
+);
+```
+
+### Android
+
+```kotlin
+PostHog.identify(
+ distinctId = distinctID, // Replace 'distinctID' with your user's unique identifier
+ // optional: set additional person properties
+ userProperties = mapOf(
+ "name" to "Max Hedgehog",
+ "email" to "max@hedgehogmail.com"
+ )
+)
+```
+
+### iOS
+
+```swift
+PostHogSDK.shared.identify("distinct_id", // Replace "distinct_id" with your user's unique identifier
+ userProperties: ["name": "Max Hedgehog", "email": "max@hedgehogmail.com"]) // optional: set additional person properties
+```
+
+### React Native
+
+```jsx
+posthog.identify('distinct_id', { // Replace "distinct_id" with your user's unique identifier
+ email: 'max@hedgehogmail.com', // optional: set additional person properties
+ name: 'Max Hedgehog'
+})
+```
+
+### Dart
+
+```dart
+await Posthog().identify(
+ userId: 'distinct_id', // Replace "distinct_id" with your user's unique identifier
+ userProperties: {
+ email: "max@hedgehogmail.com", // optional: set additional person properties
+ name: "Max Hedgehog"
+});
+```
+
+Events captured after calling `identify` are identified events and this creates a person profile if one doesn't exist already.
+
+Due to the cost of processing them, anonymous events can be up to 4x cheaper than identified events, so it's recommended you only capture identified events when needed.
+
+## How identify works
+
+When a user starts browsing your website or app, PostHog automatically assigns them an **anonymous ID**, which is stored locally.
+
+Provided you've [configured persistence](/docs/libraries/js/persistence.md) to use cookies or `localStorage`, this enables us to track anonymous users – even across different sessions.
+
+By calling `identify` with a `distinct_id` of your choice (usually the user's ID in your database, or their email), you link the anonymous ID and distinct ID together.
+
+Thus, all past and future events made with that anonymous ID are now associated with the distinct ID.
+
+This enables you to do things like associate events with a user from before they log in for the first time, or associate their events across different devices or platforms.
+
+Using identify in the backend
+
+Although you can call `identify` using our backend SDKs, it is used most in frontends. This is because there is no concept of anonymous sessions in the backend SDKs, so calling `identify` only updates person profiles.
+
+## Best practices when using `identify`
+
+### 1\. Call `identify` as soon as you're able to
+
+In your frontend, you should call `identify` as soon as you're able to.
+
+Typically, this is every time your **app loads** for the first time, and directly after your **users log in**.
+
+This ensures that events sent during your users' sessions are correctly associated with them.
+
+You only need to call `identify` once per session, and you should avoid calling it multiple times unnecessarily.
+
+If you call `identify` multiple times with the same data without reloading the page in between, PostHog will ignore the subsequent calls.
+
+### 2\. Use unique strings for distinct IDs
+
+If two users have the same distinct ID, their data is merged and they are considered one user in PostHog. Two common ways this can happen are:
+
+- Your logic for generating IDs does not generate sufficiently strong IDs and you can end up with a clash where 2 users have the same ID.
+- There's a bug, typo, or mistake in your code leading to most or all users being identified with generic IDs like `null`, `true`, or `distinctId`.
+
+PostHog also has built-in protections to stop the most common distinct ID mistakes.
+
+### 3\. Reset after logout
+
+If a user logs out on your frontend, you should call `reset()` to unlink any future events made on that device with that user.
+
+This is important if your users are sharing a computer, as otherwise all of those users are grouped together into a single user due to shared cookies between sessions.
+
+**We strongly recommend you call `reset` on logout even if you don't expect users to share a computer.**
+
+You can do that like so:
+
+PostHog AI
+
+### Web
+
+```javascript
+posthog.reset()
+```
+
+### iOS
+
+```swift
+PostHogSDK.shared.reset()
+```
+
+### Android
+
+```kotlin
+PostHog.reset()
+```
+
+### React Native
+
+```jsx
+posthog.reset()
+```
+
+### Dart
+
+```dart
+Posthog().reset()
+```
+
+If you *also* want to reset the `device_id` so that the device will be considered a new device in future events, you can pass `true` as an argument:
+
+Web
+
+PostHog AI
+
+```javascript
+posthog.reset(true)
+```
+
+### 4\. Person profiles and properties
+
+You'll notice that one of the parameters in the `identify` method is a `properties` object.
+
+This enables you to set [person properties](/docs/product-analytics/person-properties.md).
+
+Whenever possible, we recommend passing in all person properties you have available each time you call identify, as this ensures their person profile on PostHog is up to date.
+
+Person properties can also be set being adding a `$set` property to a event `capture` call.
+
+See our [person properties docs](/docs/product-analytics/person-properties.md) for more details on how to work with them and best practices.
+
+### 5\. Use deep links between platforms
+
+We recommend you call `identify` [as soon as you're able](#1-call-identify-as-soon-as-youre-able), typically when a user signs up or logs in.
+
+This doesn't work if one or both platforms are unauthenticated. Some examples of such cases are:
+
+- Onboarding and signup flows before authentication.
+- Unauthenticated web pages redirecting to authenticated mobile apps.
+- Authenticated web apps prompting an app download.
+
+In these cases, you can use a [deep link](https://developer.android.com/training/app-links/deep-linking) on Android and [universal links](https://developer.apple.com/documentation/xcode/supporting-universal-links-in-your-app) on iOS to identify users.
+
+1. Use `posthog.get_distinct_id()` to get the current distinct ID. Even if you cannot call identify because the user is unauthenticated, this will return an anonymous distinct ID generated by PostHog.
+2. Add the distinct ID to the deep link as query parameters, along with other properties like UTM parameters.
+3. When the user is redirected to the app, parse the deep link and handle the following cases:
+
+- The mobile app is already authenticated. In this case, call [`posthog.alias()`](/docs/libraries/js/features.md#alias) with the distinct ID from the web. This associates the two distinct IDs as a single person.
+- The mobile app is unauthenticated. In this case, call [`posthog.identify()`](/docs/libraries/js/features.md#identifying-users) with the distinct ID from the web so pre-login mobile events stay connected to the web session. When the user later logs in on mobile, call `identify()` again with your canonical user ID.
+
+As long as you associate the distinct IDs with `posthog.identify()` or `posthog.alias()`, you can track events generated across platforms.
+
+Here's an example implementation for handling deep links from web to mobile:
+
+PostHog AI
+
+### iOS
+
+```swift
+import PostHog
+class DeepLinkIdentityManager {
+ static let shared = DeepLinkIdentityManager()
+ // MARK: - Deep Link Received
+ func handleDeepLink(_ url: URL, isAuthenticatedOnMobile: Bool) {
+ guard let webDistinctId = URLComponents(url: url, resolvingAgainstBaseURL: true)?
+ .queryItems?.first(where: { $0.name == "ph_distinct_id" })?.value else {
+ return
+ }
+ if isAuthenticatedOnMobile {
+ // The mobile app already knows the current user.
+ // Alias the incoming web distinct ID to that user.
+ PostHogSDK.shared.alias(webDistinctId)
+ } else {
+ // Reuse the web distinct ID until login on mobile.
+ PostHogSDK.shared.identify(webDistinctId)
+ }
+ }
+ // MARK: - Login/Signup
+ func handleLogin(canonicalUserId: String) {
+ // Switch from the web distinct ID (or a mobile anon ID)
+ // to your canonical user ID.
+ PostHogSDK.shared.identify(canonicalUserId)
+ // Set user properties, track signup event, etc.
+ }
+ func handleLogout() {
+ PostHogSDK.shared.reset()
+ }
+}
+```
+
+### Android
+
+```kotlin
+import android.net.Uri
+import com.posthog.PostHog
+object DeepLinkIdentityManager {
+ // Deep Link Received
+ fun handleDeepLink(uri: Uri, isAuthenticatedOnMobile: Boolean) {
+ val webDistinctId = uri.getQueryParameter("ph_distinct_id") ?: return
+ if (isAuthenticatedOnMobile) {
+ // The mobile app already knows the current user.
+ // Alias the incoming web distinct ID to that user.
+ PostHog.alias(webDistinctId)
+ } else {
+ // Reuse the web distinct ID until login on mobile.
+ PostHog.identify(webDistinctId)
+ }
+ }
+ // Login/Signup
+ fun handleLogin(canonicalUserId: String) {
+ // Switch from the web distinct ID (or a mobile anon ID)
+ // to your canonical user ID.
+ PostHog.identify(canonicalUserId)
+ // Set user properties, track signup event, etc.
+ }
+ fun handleLogout() {
+ PostHog.reset()
+ }
+}
+```
+
+## Further reading
+
+- [Identifying users docs](/docs/product-analytics/identify.md)
+- [How person processing works](/docs/how-posthog-works/ingestion-pipeline.md#2-person-processing)
+- [An introductory guide to identifying users in PostHog](/tutorials/identifying-users-guide.md)
+
+### Community questions
+
+Ask a question
+
+### Was this page useful?
+
+HelpfulCould be better
\ No newline at end of file
diff --git a/.claude/skills/integration-javascript_node/references/node.md b/.claude/skills/integration-javascript_node/references/node.md
new file mode 100644
index 000000000..676fa797e
--- /dev/null
+++ b/.claude/skills/integration-javascript_node/references/node.md
@@ -0,0 +1,840 @@
+# Node.js - Docs
+
+If you're working with Node.js (versions 20+), the official `posthog-node` library is the simplest way to integrate your software with PostHog. This library uses an internal queue to make calls fast and non-blocking. It also batches requests and flushes asynchronously, making it perfect to use in any part of your web app or other server-side application that needs performance. And in addition to event capture, [feature flags](/docs/feature-flags.md) are supported as well.
+
+## Installation
+
+Run either `npm` or `yarn` in terminal to add it to your project:
+
+PostHog AI
+
+### npm
+
+```bash
+npm install posthog-node --save
+```
+
+### Yarn
+
+```bash
+yarn add posthog-node
+```
+
+### pnpm
+
+```bash
+pnpm add posthog-node
+```
+
+### Bun
+
+```bash
+bun add posthog-node
+```
+
+In your app, set your project token **before** making any calls.
+
+Node.js
+
+PostHog AI
+
+```javascript
+import { PostHog } from 'posthog-node'
+const client = new PostHog(
+ '',
+ { host: 'https://us.i.posthog.com' }
+)
+await client.shutdown()
+```
+
+You can find your project token and instance address in the [project settings](https://app.posthog.com/project/settings) page in PostHog.
+
+> **Note:** As a rule of thumb, we do not recommend hardcoding API keys or tokens. Setting it as an environment variable is preferred.
+
+## Identifying users
+
+> **Identifying users is required.** Backend events need a `distinct_id` that matches the ID your frontend uses when calling `posthog.identify()`. Without this, backend events are orphaned — they can't be linked to frontend event captures, [session replays](/docs/session-replay.md), [LLM traces](/docs/ai-engineering.md), or [error tracking](/docs/error-tracking.md).
+>
+> See our guide on [identifying users](/docs/getting-started/identify-users.md) for how to set this up.
+
+### Options
+
+| Variable | Description | Default value |
+| --- | --- | --- |
+| host | Your PostHog host | https://us.i.posthog.com/ |
+| flushAt | After how many capture calls we should flush the queue (in one batch) | 20 |
+| flushInterval | After how many ms we should flush the queue | 10000 |
+| personalApiKey | An optional [personal API key](/docs/api/overview.md#personal-api-keys-recommended) for evaluating feature flags locally. Note: Providing this will trigger periodic calls to the feature flags service, even if you're not using feature flags. | null |
+| featureFlagsPollingInterval | Interval in milliseconds specifying how often feature flags should be fetched from the PostHog API | 300000 |
+| requestTimeout | Timeout in milliseconds for any calls | 10000 |
+| maxCacheSize | Maximum size of cache that deduplicates $feature_flag_called calls per user. | 50000 |
+| disableGeoip | When true, disables automatic GeoIP resolution for events and feature flags. | true |
+| evaluation_contexts | Evaluation context tags that constrain which feature flags are evaluated. When set, only flags with matching evaluation context tags (or no evaluation context tags) will be returned. This helps reduce unnecessary flag evaluations and improves performance. See [evaluation contexts documentation](/docs/feature-flags/evaluation-contexts.md) for more details. Available in version 5.10.0+. The legacy parameter evaluation_environments (version 5.9.6+) is also supported for backward compatibility. | undefined |
+
+> **Note:** When using PostHog in an AWS Lambda function or a similar serverless function environment, make sure you set `flushAt` to `1` and `flushInterval` to `0`. Also, remember to always call `await posthog.shutdown()` at the end to flush and send all pending events.
+
+## Capturing events
+
+You can send custom events using `capture`:
+
+Node.js
+
+PostHog AI
+
+```javascript
+client.capture({
+ distinctId: 'distinct_id_of_the_user',
+ event: 'user signed up',
+})
+```
+
+> **Tip:** We recommend using a `[object] [verb]` format for your event names, where `[object]` is the entity that the behavior relates to, and `[verb]` is the behavior itself. For example, `project created`, `user signed up`, or `invite sent`.
+
+### Setting event properties
+
+Optionally, you can include additional information with the event by including a [properties](/docs/data/events.md#event-properties) object:
+
+Node.js
+
+PostHog AI
+
+```javascript
+client.capture({
+ distinctId: 'distinct_id_of_the_user',
+ event: 'user signed up',
+ properties: {
+ login_type: 'email',
+ is_free_trial: true,
+ },
+})
+```
+
+### Capturing pageviews
+
+If you're aiming for a backend-only implementation of PostHog and won't be capturing events from your frontend, you can send `$pageview` events from your backend like so:
+
+Node.js
+
+PostHog AI
+
+```javascript
+client.capture({
+ distinctId: 'distinct_id_of_the_user',
+ event: '$pageview',
+ properties: {
+ $current_url: 'https://example.com',
+ },
+})
+```
+
+## Person profiles and properties
+
+The Node SDK captures identified events by default. These create [person profiles](/docs/data/persons.md). To set [person properties](/docs/data/user-properties.md) in these profiles, include them when capturing an event using `$set` and `$set_once`:
+
+Node.js
+
+PostHog AI
+
+```javascript
+client.capture({
+ distinctId: 'distinct_id_of_the_user',
+ event: 'movie_played',
+ properties: {
+ $set: { name: 'Max Hedgehog' },
+ $set_once: { initial_url: '/blog' },
+ },
+})
+```
+
+For more details on the difference between `$set` and `$set_once`, see our [person properties docs](/docs/data/user-properties.md#what-is-the-difference-between-set-and-set_once).
+
+To capture [anonymous events](/docs/data/anonymous-vs-identified-events.md) without person profiles, set the event's `$process_person_profile` property to `false`:
+
+Node.js
+
+PostHog AI
+
+```javascript
+client.capture({
+ distinctId: 'distinct_id_of_the_user',
+ event: 'movie_played',
+ properties: {
+ $process_person_profile: false,
+ },
+})
+```
+
+## Alias
+
+Sometimes, you want to assign multiple distinct IDs to a single user. This is helpful when your primary distinct ID is inaccessible. For example, if a distinct ID used on the frontend is not available in your backend.
+
+In this case, you can use `alias` to assign another distinct ID to the same user.
+
+Node.js
+
+PostHog AI
+
+```javascript
+client.alias({
+ distinctId: 'distinct_id',
+ alias: 'alias_id',
+})
+```
+
+We strongly recommend reading our docs on [alias](/docs/data/identify.md#alias-assigning-multiple-distinct-ids-to-the-same-user) to best understand how to correctly use this method.
+
+## Super properties
+
+> Requires `posthog-node` version >= 5.25.0.
+
+Super properties are properties that are automatically included with every event captured by the client. Use `register` to set them:
+
+Node.js
+
+PostHog AI
+
+```javascript
+client.register({
+ app_version: '1.2.0',
+ environment: 'production',
+})
+// Both events include app_version and environment
+client.capture({
+ distinctId: 'distinct_id',
+ event: 'page_viewed',
+})
+client.capture({
+ distinctId: 'distinct_id',
+ event: 'button_clicked',
+})
+```
+
+If an event sets a property with the same key as a super property, the event's property takes precedence:
+
+Node.js
+
+PostHog AI
+
+```javascript
+client.register({ environment: 'production' })
+// This event is captured with environment='staging'
+client.capture({
+ distinctId: 'distinct_id',
+ event: 'page_viewed',
+ properties: { environment: 'staging' },
+})
+```
+
+To remove a super property, use `unregister`:
+
+Node.js
+
+PostHog AI
+
+```javascript
+client.unregister('environment')
+```
+
+Super properties are **global** — they apply to every event for the lifetime of the client instance. For properties that should only apply to a specific scope (e.g. a single request or transaction), use [contexts](#contexts) instead.
+
+## Contexts
+
+> Requires `posthog-node` version >= 5.17.0.
+
+The Node SDK uses nested contexts for managing state that's shared across events. Contexts are useful for adding properties to multiple events (including exceptions) during a single user's interaction with your product.
+
+You can enter a context using `withContext`:
+
+Node.js
+
+PostHog AI
+
+```javascript
+posthog.withContext(
+ {
+ distinctId: 'user-123',
+ properties: { transactionId: 'abc123' }
+ },
+ () => {
+ // This event is captured with the distinct ID and properties set above
+ posthog.capture({ event: 'order_processed' })
+ }
+)
+```
+
+Contexts are persisted across function calls. If you enter one and then call a function and capture an event in the called function, it uses the context properties set in the parent context:
+
+Node.js
+
+PostHog AI
+
+```javascript
+function someFunction() {
+ // When called from `outerFunction`, this event is captured
+ // with transactionId='abc123'
+ posthog.capture({ event: 'order_processed' })
+}
+function outerFunction() {
+ posthog.withContext(
+ { properties: { transactionId: 'abc123' } },
+ () => {
+ someFunction()
+ }
+ )
+}
+```
+
+By default, each context inherits from parent contexts. To disable nesting (where child contexts is fresh and has no properties), pass `{ fresh: true }`:
+
+Node.js
+
+PostHog AI
+
+```javascript
+posthog.withContext(
+ {
+ properties: {
+ someKey: 'value-1',
+ someOtherKey: 'another-value'
+ }
+ },
+ () => {
+ posthog.withContext(
+ { properties: { someKey: 'value-2' } },
+ () => {
+ // Captured with someKey='value-2', someOtherKey='another-value'
+ posthog.capture({ event: 'order_processed' })
+ },
+ )
+ // Captured with someKey='value-1', someOtherKey='another-value'
+ posthog.capture({ event: 'order_completed' })
+ }
+)
+```
+
+> **Note:** Properties passed directly to `capture` calls override context state in the final event.
+
+### Identification context
+
+Contexts can be associated with a distinct ID:
+
+Node.js
+
+PostHog AI
+
+```javascript
+posthog.withContext(
+ { distinctId: 'user-123' },
+ () => {
+ // Associated with "user-123"
+ posthog.capture({ event: 'order_processed' })
+ // Overrides to "another-user"
+ posthog.capture({
+ distinctId: 'another-user',
+ event: 'order_processed'
+ })
+ }
+)
+```
+
+### Session context
+
+Node.js
+
+PostHog AI
+
+```javascript
+posthog.withContext(
+ { sessionId: 'some-session' },
+ () => {
+ // Associated with session "some-session"
+ posthog.capture({ event: 'image_uploaded' })
+ // Overrides to "next-session"
+ posthog.capture({
+ event: 'image_uploaded',
+ properties: { $sessionId: 'next-session' }
+ })
+ }
+)
+```
+
+### Custom context parameters
+
+Node.js
+
+PostHog AI
+
+```javascript
+posthog.withContext(
+ { flightNumber: 'TAC313' },
+ () => {
+ // Associated with flightNumber TAC313
+ posthog.capture({ event: 'flight_cancelled' })
+ // Overrides to PL7714
+ posthog.capture({
+ event: 'flight_cancelled',
+ properties: { flightNumber: 'PL7714' }
+ })
+ }
+)
+```
+
+## Feature flags
+
+PostHog's [feature flags](/docs/feature-flags.md) enable you to safely deploy and roll back new features as well as target specific users and groups with them.
+
+There are two steps to implement feature flags in Node:
+
+### Step 1: Evaluate flags once
+
+Call `client.evaluateFlags()` once for the user, then read values from the returned snapshot.
+
+#### Boolean feature flags
+
+Node.js
+
+PostHog AI
+
+```javascript
+const flags = await client.evaluateFlags('distinct_id_of_your_user')
+if (flags.isEnabled('flag-key')) {
+ // Do something differently for this user
+ // Optional: fetch the payload
+ const matchedFlagPayload = flags.getFlagPayload('flag-key')
+}
+```
+
+#### Multivariate feature flags
+
+Node.js
+
+PostHog AI
+
+```javascript
+const flags = await client.evaluateFlags('distinct_id_of_your_user')
+const enabledVariant = flags.getFlag('flag-key')
+if (enabledVariant === 'variant-key') { // replace 'variant-key' with the key of your variant
+ // Do something differently for this user
+ // Optional: fetch the payload
+ const matchedFlagPayload = flags.getFlagPayload('flag-key')
+}
+```
+
+`flags.getFlag()` returns the variant string for multivariate flags, `true` for enabled boolean flags, `false` for disabled flags, and `undefined` when the flag wasn't returned by the evaluation.
+
+> **Note:** `client.isFeatureEnabled()`, `client.getFeatureFlag()`, `client.getFeatureFlagPayload()`, and `capture({ sendFeatureFlags: true })` still work during the migration period, but they're deprecated. Prefer `evaluateFlags()` for new code.
+
+### Step 2: Include feature flag information when capturing events
+
+If you want use your feature flag to breakdown or filter events in your [insights](/docs/product-analytics/insights.md), you'll need to include feature flag information in those events. This ensures that the feature flag value is attributed correctly to the event.
+
+> **Note:** This step is only required for events captured using our server-side SDKs or [API](/docs/api.md).
+
+There are two methods you can use to include feature flag information in your events:
+
+#### Method 1: Pass the evaluated flags snapshot to `capture()`
+
+Pass the same `flags` object that you used for branching. This attaches the exact flag values from that evaluation and doesn't make another `/flags` request.
+
+Node.js
+
+PostHog AI
+
+```javascript
+const flags = await client.evaluateFlags('distinct_id_of_your_user')
+if (flags.isEnabled('flag-key')) {
+ // Do something differently for this user
+}
+client.capture({
+ distinctId: 'distinct_id_of_your_user',
+ event: 'event_name',
+ flags,
+})
+```
+
+By default, this attaches every flag in the snapshot using `$feature/` properties and `$active_feature_flags`.
+
+To reduce event property bloat, pass a filtered snapshot:
+
+Node.js
+
+PostHog AI
+
+```javascript
+// Attach only flags accessed with isEnabled() or getFlag() before this call
+client.capture({
+ distinctId: 'distinct_id_of_your_user',
+ event: 'event_name',
+ flags: flags.onlyAccessed(),
+})
+// Attach only specific flags
+client.capture({
+ distinctId: 'distinct_id_of_your_user',
+ event: 'event_name',
+ flags: flags.only(['checkout-flow', 'new-dashboard']),
+})
+```
+
+`onlyAccessed()` is order-dependent. If you call it before accessing any flags with `isEnabled()` or `getFlag()`, no feature flag properties are attached.
+
+#### Method 2: Include the `$feature/feature_flag_name` property manually
+
+In the event properties, include `$feature/feature_flag_name: variant_key`:
+
+Node.js
+
+PostHog AI
+
+```javascript
+client.capture({
+ distinctId: 'distinct_id_of_your_user',
+ event: 'event_name',
+ properties: {
+ // Replace feature-flag-key with your flag key and 'variant-key' with the key of your variant
+ '$feature/feature-flag-key': 'variant-key',
+ },
+})
+```
+
+### Evaluating only specific flags
+
+By default, `evaluateFlags()` evaluates every flag for the user. If you only need a few flags, pass `flagKeys` to request only those flags:
+
+Node.js
+
+PostHog AI
+
+```javascript
+const flags = await client.evaluateFlags('distinct_id_of_your_user', {
+ flagKeys: ['checkout-flow', 'new-dashboard'],
+})
+```
+
+### Sending `$feature_flag_called` events
+
+Capturing `$feature_flag_called` events enables PostHog to know when a flag was accessed by a user and provide [analytics and insights](/docs/product-analytics/insights.md) on the flag. With `evaluateFlags()`, the SDK sends this event when you call `flags.isEnabled()` or `flags.getFlag()` for a flag.
+
+The SDK deduplicates these events per `(distinct_id, flag, value)` in a local cache. If you reinitialize the PostHog client, the cache resets and `$feature_flag_called` events may be sent again. PostHog handles duplicates, so duplicate `$feature_flag_called` events don't affect your analytics.
+
+`flags.getFlagPayload()` doesn't send `$feature_flag_called` events and doesn't count as an access for `onlyAccessed()`.
+
+### Advanced: Overriding server properties
+
+Sometimes, you may want to evaluate feature flags using [person properties](/docs/product-analytics/person-properties.md), [groups](/docs/product-analytics/group-analytics.md), or group properties that haven't been ingested yet, or were set incorrectly earlier.
+
+You can provide properties to evaluate the flag with by using the `person properties`, `groups`, and `group properties` arguments. PostHog will then use these values to evaluate the flag, instead of any properties currently stored on your PostHog server.
+
+For example:
+
+Node.js
+
+PostHog AI
+
+```javascript
+const flags = await client.evaluateFlags('distinct_id_of_the_user', {
+ personProperties: {
+ property_name: 'value',
+ },
+ groups: {
+ your_group_type: 'your_group_id',
+ another_group_type: 'your_group_id',
+ },
+ groupProperties: {
+ your_group_type: {
+ group_property_name: 'value',
+ },
+ another_group_type: {
+ group_property_name: 'value',
+ },
+ },
+})
+if (flags.isEnabled('flag-key')) {
+ // Do something differently for this user
+}
+```
+
+### Overriding GeoIP properties
+
+By default, a user's GeoIP properties are set using the IP address they use to capture events on the frontend. You may want to override the these properties when evaluating feature flags. A common reason to do this is when you're not using PostHog on your frontend, so the user has no GeoIP properties.
+
+You can override GeoIP properties by including them in the `person_properties` parameter when evaluating feature flags. This is useful when you're evaluating flags on your backend and want to use the client's location instead of your server's location.
+
+The following GeoIP properties can be overridden:
+
+- `$geoip_country_code`
+- `$geoip_country_name`
+- `$geoip_city_name`
+- `$geoip_city_confidence`
+- `$geoip_continent_code`
+- `$geoip_continent_name`
+- `$geoip_latitude`
+- `$geoip_longitude`
+- `$geoip_postal_code`
+- `$geoip_subdivision_1_code`
+- `$geoip_subdivision_1_name`
+- `$geoip_subdivision_2_code`
+- `$geoip_subdivision_2_name`
+- `$geoip_subdivision_3_code`
+- `$geoip_subdivision_3_name`
+- `$geoip_time_zone`
+
+Simply include any of these properties in the `person_properties` parameter alongside your other person properties when calling feature flags.
+
+### Request timeout
+
+You can configure the `feature_flag_request_timeout_ms` parameter when initializing your PostHog client to set a flag request timeout. This helps prevent your code from being blocked if PostHog's servers are too slow to respond. By default, this is set to 3 seconds.
+
+JavaScript
+
+PostHog AI
+
+```javascript
+const client = new PostHog('', {
+ api_host: 'https://us.i.posthog.com',
+ feature_flag_request_timeout_ms: 3000, // Time in milliseconds. Defaults to 3000 (3 seconds).
+})
+```
+
+> **Note:** For remote config flags, see the [remote config documentation](/docs/feature-flags/remote-config.md). Remote config requires the [Feature Flags secure API key](/docs/feature-flags/remote-config.md#step-1-find-your-feature-flags-secure-api-key) passed as the `personalApiKey` option.
+
+### Local evaluation
+
+Evaluating feature flags requires making a request to PostHog for each flag. However, you can improve performance by evaluating flags locally. Instead of making a request for each flag, PostHog will periodically request and store feature flag definitions locally, enabling you to evaluate flags without making additional requests.
+
+It is best practice to use local evaluation flags when possible, since this enables you to resolve flags faster and with fewer API calls.
+
+For details on how to implement local evaluation, see our [local evaluation guide](/docs/feature-flags/local-evaluation.md).
+
+Node.js
+
+PostHog AI
+
+```javascript
+const flags = await client.evaluateFlags('user distinct id', {
+ groups: { organization: 'google' },
+ groupProperties: { organization: { is_authorized: true } },
+})
+const flagValue = flags.getFlag('flag-key')
+```
+
+#### Reloading feature flags
+
+When initializing PostHog, you can configure the interval at which feature flags are polled (fetched from the server). However, if you need to force a reload, you can use `reloadFeatureFlags`:
+
+Node.js
+
+PostHog AI
+
+```javascript
+await client.reloadFeatureFlags()
+// Do something with feature flags here
+```
+
+#### Distributed environments
+
+In multi-worker or edge environments, you can implement custom caching for flag definitions using Redis, Cloudflare KV, or other storage backends. This enables sharing definitions across workers and coordinating fetches. See our guide for [local evaluation in distributed environments](/docs/feature-flags/local-evaluation/distributed-environments?tab=Node.js.md) for details.
+
+## Experiments (A/B tests)
+
+Since [experiments](/docs/experiments/start-here.md) use feature flags, the code for running an experiment is very similar to the feature flags code:
+
+Node.js
+
+PostHog AI
+
+```javascript
+const flags = await client.evaluateFlags('user_distinct_id')
+const variant = flags.getFlag('experiment-feature-flag-key')
+if (variant === 'variant-name') {
+ // Do something
+}
+```
+
+It's also possible to [run experiments without using feature flags](/docs/experiments/running-experiments-without-feature-flags.md).
+
+## Group analytics
+
+Group analytics enable you to associate an event with a group (e.g. teams, organizations, etc.). Read the [group analytics guide](/docs/product-analytics/group-analytics.md) for more information.
+
+To create a group or update its properties, use `groupIdentify`:
+
+Node.js
+
+PostHog AI
+
+```javascript
+client.groupIdentify({
+ groupType: 'company',
+ groupKey: 'company_id_in_your_db',
+ properties: {
+ name: 'Awesome Inc',
+ employees: 11,
+ },
+ // optional distinct ID to associate event with an existing person
+ distinctId: 'xyz'
+})
+```
+
+`name` is a special property which is used in the PostHog UI for the name of the group. If you don't specify a `name` property, the group ID is used instead.
+
+If the optional `distinctId` parameter is not provided in the group identify call, it defaults to `${groupType}_${groupKey}` (e.g., `$company_company_id_in_your_db` in the example above). This default behavior results in each group appearing as a separate person in PostHog. To avoid this, it's often more practical to use a consistent `distinctId`, such as `group_identifier`.
+
+Once a group is created, you can use the `capture` method and pass in the `groups` parameter to capture an event with group analytics.
+
+Node.js
+
+PostHog AI
+
+```javascript
+client.capture({
+ event: 'some_event',
+ distinctId: 'user_distinct_id',
+ groups: { company: 'company_id_in_your_db' },
+})
+```
+
+## GeoIP properties
+
+Before `posthog-node` v3.0, we added GeoIP properties to all incoming events by default. We also used these properties for feature flag evaluation, based on the IP address of the request. This isn't ideal since they are created based on your server IP address, rather than the user's, leading to incorrect location resolution.
+
+As of `posthog-node` v3.0, the default now is to disregard the server IP, not add the GeoIP properties, and not use the values for feature flag evaluations.
+
+You can go back to previous behavior by setting `disableGeoip` to false in your initialization:
+
+Node.js
+
+PostHog AI
+
+```javascript
+const posthog = new PostHog('', {
+ host: 'https://us.i.posthog.com',
+ disableGeoip: false
+})
+```
+
+The list of properties that this overrides:
+
+1. `$geoip_city_name`
+2. `$geoip_country_name`
+3. `$geoip_country_code`
+4. `$geoip_continent_name`
+5. `$geoip_continent_code`
+6. `$geoip_postal_code`
+7. `$geoip_time_zone`
+
+You can also explicitly chose to enable or disable GeoIP for a single capture request like so:
+
+Node.js
+
+PostHog AI
+
+```javascript
+client.capture({
+ distinctId: distinctId,
+ event: 'your_event',
+ disableGeoip: `true`,
+})
+```
+
+## Shutdown
+
+You should call `shutdown` on your program's exit to exit cleanly:
+
+Node.js
+
+PostHog AI
+
+```javascript
+// Stop pending pollers and flush any remaining events
+await client.shutdown()
+```
+
+## Debug mode
+
+If you're not seeing the expected events being captured, the feature flags being evaluated, or the surveys being shown, you can enable debug mode to see what's happening.
+
+You can enable debug mode by calling the `debug()` method in your code. This will enable verbose logs about the inner workings of the SDK.
+
+Node.js
+
+PostHog AI
+
+```javascript
+client.debug()
+```
+
+## Handling errors thrown by the SDK
+
+If you are experiencing issues with the SDK it could be a number of things from an incorrectly configured API key, to some other network related issues.
+
+The SDK does not throw errors for things happening in the background to ensure it doesn't affect your process. You can however hook into the errors to get more information:
+
+Node.js
+
+PostHog AI
+
+```javascript
+client.on("error", (err) => {
+ // Whatever handling you want
+ console.error("PostHog had an error!", err)
+})
+```
+
+## Short-lived processes like serverless environments
+
+The Node SDK is designed to queue and batch requests in the background to optimize API calls and network time. As serverless environments like AWS Lambda or [Vercel Functions](/docs/libraries/vercel.md) are short-lived, we provide a few options to ensure all events are captured.
+
+First, we recommend using the `captureImmediate` method instead of `capture` to ensure the event is captured before the function shuts down. It guarantees the HTTP request finishes before your function continues (or shuts down).
+
+Second, we recommend setting `flushAt` to `1` and `flushInterval` to `0` to ensure the events are sent immediately. These set the queue to flush immediately, both in terms of events and time.
+
+Third, we provide a method `shutdown()` which can be awaited to ensure all queued events are sent to the API. For example:
+
+Node.js
+
+PostHog AI
+
+```javascript
+export const handler() {
+ client.capture({
+ distinctId: 'distinct_id_of_the_user',
+ event: 'thing_happened'
+ })
+ client.capture({
+ distinctId: 'distinct_id_of_the_user',
+ event: 'other_thing_happened'
+ })
+ // So far 2 events are queued but not sent
+ // Calling shutdown, flushed the queue but batched into 1 API call for maximum efficiency
+ await client.shutdown()
+}
+```
+
+This is also useful for shutting down a standard Node.js app.
+
+## AI Observability
+
+You can capture LLM usage and performance data by combining the `posthog-node` and `@posthog/ai` libraries. These work with LLM providers like OpenAI and Vercel's AI SDKs. Learn more in our [AI Observability docs](/docs/ai-observability.md).
+
+## Error tracking
+
+You can capture errors using the `posthog-node` library. This enables you to see stack traces, source code, and watch associated session recordings to improve your application stability. Learn more in our [error tracking docs](/docs/error-tracking/installation/node.md).
+
+## Upgrading from V1 to V2
+
+V2.x.x of the Node.js library is completely rewritten in Typescript and is based on a new JS core shared with other JavaScript based libraries with the goal of ensuring new features and fixes reach the different libraries at the same pace.
+
+With the release of V2, the API was kept mostly the same but with some small changes and deprecations:
+
+1. The minimum PostHog version requirement is 1.38
+2. The `callback` parameter passed as an optional last argument to most of the methods is no longer supported
+3. The method signature for `isFeatureEnabled` and `getFeatureFlag` is slightly modified. See the above documentation for each method for more details.
+4. For specific changes, [see the CHANGELOG](https://github.com/PostHog/posthog-js/blob/main/packages/node/CHANGELOG.md)
+
+### Community questions
+
+Ask a question
+
+### Was this page useful?
+
+HelpfulCould be better
\ No newline at end of file
diff --git a/.claude/skills/integration-javascript_node/references/posthog-node.md b/.claude/skills/integration-javascript_node/references/posthog-node.md
new file mode 100644
index 000000000..958fda4c9
--- /dev/null
+++ b/.claude/skills/integration-javascript_node/references/posthog-node.md
@@ -0,0 +1,1450 @@
+# PostHog Node.js SDK
+
+**SDK Version:** 5.36.2
+
+PostHog Node.js SDK allows you to capture events and send them to PostHog from your Node.js applications.
+
+## Categories
+
+- Initialization
+- Identification
+- Capture
+- Error tracking
+- Privacy
+- Feature flags
+- Context
+
+## PostHog
+
+### Other methods
+
+#### getLibraryId()
+
+**Release Tag:** public
+
+### Returns
+
+- `string`
+
+### Examples
+
+```node
+// Generated example for getLibraryId
+posthog.getLibraryId();
+```
+
+---
+
+#### enterContext()
+
+**Release Tag:** public
+
+Set context without a callback wrapper.
+Uses `AsyncLocalStorage.enterWith()` to attach context to the current async execution context. The context lives until that async context ends.
+Must be called in the same async scope that makes PostHog calls. Calling this outside a request-scoped async context will leak context across unrelated work. Prefer `withContext()` when you can wrap code in a callback — it creates an isolated scope that cleans up automatically.
+
+### Parameters
+
+- **`data`** (`Partial`) - Context data to apply (distinctId, sessionId, properties)
+- **`options?`** (`ContextOptions`) - Context options (fresh: true to start with clean context instead of inheriting)
+
+### Returns
+
+- `void`
+
+### Examples
+
+```node
+// Generated example for enterContext
+posthog.enterContext();
+```
+
+---
+
+#### flush()
+
+**Release Tag:** public
+
+### Returns
+
+- `Promise`
+
+### Examples
+
+```node
+// Generated example for flush
+posthog.flush();
+```
+
+---
+
+#### prepareEventMessage()
+
+**Release Tag:** public
+
+### Parameters
+
+- **`props`** (`EventMessage`)
+
+### Returns
+
+- `Promise<{
+ distinctId: string;
+ event: string;
+ properties: PostHogEventProperties;
+ options: PostHogCaptureOptions;
+ }>`
+
+### Examples
+
+```node
+// Generated example for prepareEventMessage
+posthog.prepareEventMessage();
+```
+
+---
+
+#### fetch()
+
+**Release Tag:** public
+
+### Parameters
+
+- **`url`** (`string`)
+- **`options`** (`PostHogFetchOptions`)
+
+### Returns
+
+- `Promise`
+
+### Examples
+
+```node
+// Generated example for fetch
+posthog.fetch();
+```
+
+---
+
+#### getSurveysStateless()
+
+**Release Tag:** public
+
+* ** SURVEYS *
+
+### Returns
+
+- `Promise`
+
+### Examples
+
+```node
+// Generated example for getSurveysStateless
+posthog.getSurveysStateless();
+```
+
+---
+
+#### on()
+
+**Release Tag:** public
+
+### Parameters
+
+- **`event`** (`string`)
+- **`cb`** (`(...args: any[]) => void`)
+
+### Returns
+
+- `() => void`
+
+### Examples
+
+```node
+// Generated example for on
+posthog.on();
+```
+
+---
+
+#### optIn()
+
+**Release Tag:** public
+
+### Returns
+
+- `Promise`
+
+### Examples
+
+```node
+// Generated example for optIn
+posthog.optIn();
+```
+
+---
+
+#### optOut()
+
+**Release Tag:** public
+
+### Returns
+
+- `Promise`
+
+### Examples
+
+```node
+// Generated example for optOut
+posthog.optOut();
+```
+
+---
+
+#### register()
+
+**Release Tag:** public
+
+### Parameters
+
+- **`properties`** (`PostHogEventProperties`)
+
+### Returns
+
+- `Promise`
+
+### Examples
+
+```node
+// Generated example for register
+posthog.register();
+```
+
+---
+
+#### unregister()
+
+**Release Tag:** public
+
+### Parameters
+
+- **`property`** (`string`)
+
+### Returns
+
+- `Promise`
+
+### Examples
+
+```node
+// Generated example for unregister
+posthog.unregister();
+```
+
+---
+
+### Initialization methods
+
+#### PostHog()
+
+**Release Tag:** public
+
+Initialize a new PostHog client instance.
+
+### Parameters
+
+- **`apiKey`** (`string`) - Your PostHog project API key
+- **`options?`** (`PostHogOptions`) - Configuration options for the client
+
+### Returns
+
+- `any`
+
+### Examples
+
+#### Basic initialization
+
+```node
+// Basic initialization
+const client = new PostHogBackendClient(
+ 'your-api-key',
+ { host: 'https://app.posthog.com' }
+)
+```
+
+#### With personal API key
+
+```node
+// With personal API key
+const client = new PostHogBackendClient(
+ 'your-api-key',
+ {
+ host: 'https://app.posthog.com',
+ personalApiKey: 'your-personal-api-key'
+ }
+)
+```
+
+---
+
+#### debug()
+
+**Release Tag:** public
+
+Enable or disable debug logging.
+
+### Parameters
+
+- **`enabled?`** (`boolean`) - Whether to enable debug logging
+
+### Returns
+
+- `void`
+
+### Examples
+
+#### Enable debug logging
+
+```node
+// Enable debug logging
+client.debug(true)
+```
+
+#### Disable debug logging
+
+```node
+// Disable debug logging
+client.debug(false)
+```
+
+---
+
+#### getLibraryVersion()
+
+**Release Tag:** public
+
+Get the library version from package.json.
+
+### Returns
+
+- `string`
+
+### Examples
+
+```node
+// Get version
+const version = client.getLibraryVersion()
+console.log(`Using PostHog SDK version: ${version}`)
+```
+
+---
+
+#### getPersistedProperty()
+
+**Release Tag:** public
+
+Get a persisted property value from memory storage.
+
+### Parameters
+
+- **`key`** (`PostHogPersistedProperty`) - The property key to retrieve
+
+### Returns
+
+**Union of:**
+- `any`
+- `undefined`
+
+### Examples
+
+#### Get user ID
+
+```node
+// Get user ID
+const userId = client.getPersistedProperty('userId')
+```
+
+#### Get session ID
+
+```node
+// Get session ID
+const sessionId = client.getPersistedProperty('sessionId')
+```
+
+---
+
+#### setPersistedProperty()
+
+**Release Tag:** public
+
+Set a persisted property value in memory storage.
+
+### Parameters
+
+- **`key`** (`PostHogPersistedProperty`) - The property key to set
+- **`value`** (`any | null`) - The value to store (null to remove)
+
+### Returns
+
+- `void`
+
+### Examples
+
+#### Set user ID
+
+```node
+// Set user ID
+client.setPersistedProperty('userId', 'user_123')
+```
+
+#### Set session ID
+
+```node
+// Set session ID
+client.setPersistedProperty('sessionId', 'session_456')
+```
+
+---
+
+#### shutdown()
+
+**Release Tag:** public
+
+Shuts down the PostHog instance and ensures all events are sent.
+Call shutdown() once before the process exits to ensure that all events have been sent and all promises have resolved. Do not use this function if you intend to keep using this PostHog instance after calling it. Use flush() for per-request cleanup instead.
+
+### Parameters
+
+- **`shutdownTimeoutMs?`** (`number`) - Maximum time to wait for shutdown in milliseconds
+
+### Returns
+
+- `Promise`
+
+### Examples
+
+```node
+// shutdown before process exit
+process.on('SIGINT', async () => {
+ await posthog.shutdown()
+ process.exit(0)
+})
+```
+
+---
+
+### Identification methods
+
+#### alias()
+
+**Release Tag:** public
+
+Create an alias to link two distinct IDs together.
+
+### Parameters
+
+- **`data`** (`{
+ distinctId: string;
+ alias: string;
+ disableGeoip?: boolean;
+ }`) - The alias data containing distinctId and alias
+
+### Returns
+
+- `void`
+
+### Examples
+
+```node
+// Link an anonymous user to an identified user
+client.alias({
+ distinctId: 'anonymous_123',
+ alias: 'user_456'
+})
+```
+
+---
+
+#### aliasImmediate()
+
+**Release Tag:** public
+
+Create an alias to link two distinct IDs together immediately (synchronously).
+
+### Parameters
+
+- **`data`** (`{
+ distinctId: string;
+ alias: string;
+ disableGeoip?: boolean;
+ }`) - The alias data containing distinctId and alias
+
+### Returns
+
+- `Promise`
+
+### Examples
+
+```node
+// Link an anonymous user to an identified user immediately
+await client.aliasImmediate({
+ distinctId: 'anonymous_123',
+ alias: 'user_456'
+})
+```
+
+---
+
+#### getCustomUserAgent()
+
+**Release Tag:** public
+
+Get the custom user agent string for this client.
+
+### Returns
+
+- `string`
+
+### Examples
+
+```node
+// Get user agent
+const userAgent = client.getCustomUserAgent()
+// Returns: "posthog-node/5.7.0"
+```
+
+---
+
+#### groupIdentify()
+
+**Release Tag:** public
+
+Create or update a group and its properties.
+
+### Parameters
+
+- **`{ groupType, groupKey, properties, distinctId, disableGeoip }`** (`GroupIdentifyMessage`)
+
+### Returns
+
+- `void`
+
+### Examples
+
+#### Create a company group
+
+```node
+// Create a company group
+client.groupIdentify({
+ groupType: 'company',
+ groupKey: 'acme-corp',
+ properties: {
+ name: 'Acme Corporation',
+ industry: 'Technology',
+ employee_count: 500
+ },
+ distinctId: 'user_123'
+})
+```
+
+#### Update organization properties
+
+```node
+// Update organization properties
+client.groupIdentify({
+ groupType: 'organization',
+ groupKey: 'org-456',
+ properties: {
+ plan: 'enterprise',
+ region: 'US-West'
+ }
+})
+```
+
+---
+
+#### identify()
+
+**Release Tag:** public
+
+Identify a user and set their properties.
+
+### Parameters
+
+- **`{ distinctId, properties, disableGeoip }`** (`IdentifyMessage`)
+
+### Returns
+
+- `void`
+
+### Examples
+
+#### Basic identify with properties
+
+```node
+// Basic identify with properties
+client.identify({
+ distinctId: 'user_123',
+ properties: {
+ name: 'John Doe',
+ email: 'john@example.com',
+ plan: 'premium'
+ }
+})
+```
+
+#### Using $set and $set_once
+
+```node
+// Using $set and $set_once
+client.identify({
+ distinctId: 'user_123',
+ properties: {
+ $set: { name: 'John Doe', email: 'john@example.com' },
+ $set_once: { first_login: new Date().toISOString() }
+ $anon_distinct_id: 'anonymous_user_456'
+ }
+})
+```
+
+---
+
+#### identifyImmediate()
+
+**Release Tag:** public
+
+Identify a user and set their properties immediately (synchronously).
+
+### Parameters
+
+- **`{ distinctId, properties, disableGeoip }`** (`IdentifyMessage`)
+
+### Returns
+
+- `Promise`
+
+### Examples
+
+```node
+// Basic immediate identify
+await client.identifyImmediate({
+ distinctId: 'user_123',
+ properties: {
+ name: 'John Doe',
+ email: 'john@example.com'
+ }
+})
+```
+
+---
+
+### Capture methods
+
+#### capture()
+
+**Release Tag:** public
+
+Capture an event manually.
+
+### Parameters
+
+- **`props`** (`EventMessage`) - The event properties
+
+### Returns
+
+- `void`
+
+### Examples
+
+```node
+// Basic capture
+client.capture({
+ distinctId: 'user_123',
+ event: 'button_clicked',
+ properties: { button_color: 'red' }
+})
+```
+
+---
+
+#### captureImmediate()
+
+**Release Tag:** public
+
+Capture an event immediately (synchronously).
+
+### Parameters
+
+- **`props`** (`EventMessage`) - The event properties
+
+### Returns
+
+- `Promise`
+
+### Examples
+
+#### Basic immediate capture
+
+```node
+// Basic immediate capture
+await client.captureImmediate({
+ distinctId: 'user_123',
+ event: 'button_clicked',
+ properties: { button_color: 'red' }
+})
+```
+
+#### With feature flags
+
+```node
+// With feature flags
+await client.captureImmediate({
+ distinctId: 'user_123',
+ event: 'user_action',
+ sendFeatureFlags: true
+})
+```
+
+#### With custom feature flags options
+
+```node
+// With custom feature flags options
+await client.captureImmediate({
+ distinctId: 'user_123',
+ event: 'user_action',
+ sendFeatureFlags: {
+ onlyEvaluateLocally: true,
+ personProperties: { plan: 'premium' },
+ groupProperties: { org: { tier: 'enterprise' } }
+ flagKeys: ['flag1', 'flag2']
+ }
+})
+```
+
+---
+
+### Error tracking methods
+
+#### captureException()
+
+**Release Tag:** public
+
+Capture an error exception as an event.
+
+### Parameters
+
+- **`error`** (`unknown`) - The error to capture
+- **`distinctId?`** (`string`) - Optional user distinct ID
+- **`additionalProperties?`** (`Record`) - Optional additional properties to include
+- **`uuid?`** (`EventMessage['uuid']`) - Optional event UUID
+- **`flags?`** (`FeatureFlagEvaluations`) - Optional `FeatureFlagEvaluations` snapshot to attach the same flag context as your other events
+
+### Returns
+
+- `void`
+
+### Examples
+
+#### Capture an error with user ID
+
+```node
+// Capture an error with user ID
+try {
+ // Some risky operation
+ riskyOperation()
+} catch (error) {
+ client.captureException(error, 'user_123')
+}
+```
+
+#### Capture with additional properties
+
+```node
+// Capture with additional properties
+try {
+ apiCall()
+} catch (error) {
+ client.captureException(error, 'user_123', {
+ endpoint: '/api/users',
+ method: 'POST',
+ status_code: 500
+ })
+}
+```
+
+---
+
+#### captureExceptionImmediate()
+
+**Release Tag:** public
+
+Capture an error exception as an event immediately (synchronously).
+
+### Parameters
+
+- **`error`** (`unknown`) - The error to capture
+- **`distinctId?`** (`string`) - Optional user distinct ID
+- **`additionalProperties?`** (`Record`) - Optional additional properties to include
+- **`flags?`** (`FeatureFlagEvaluations`) - Optional `FeatureFlagEvaluations` snapshot to attach the same flag context as your other events
+
+### Returns
+
+- `Promise`
+
+### Examples
+
+#### Capture an error immediately with user ID
+
+```node
+// Capture an error immediately with user ID
+try {
+ // Some risky operation
+ riskyOperation()
+} catch (error) {
+ await client.captureExceptionImmediate(error, 'user_123')
+}
+```
+
+#### Capture with additional properties
+
+```node
+// Capture with additional properties
+try {
+ apiCall()
+} catch (error) {
+ await client.captureExceptionImmediate(error, 'user_123', {
+ endpoint: '/api/users',
+ method: 'POST',
+ status_code: 500
+ })
+}
+```
+
+---
+
+### Privacy methods
+
+#### disable()
+
+**Release Tag:** public
+
+Disable the PostHog client (opt-out).
+
+### Returns
+
+- `Promise`
+
+### Examples
+
+```node
+// Disable client
+await client.disable()
+// Client is now disabled and will not capture events
+```
+
+---
+
+#### enable()
+
+**Release Tag:** public
+
+Enable the PostHog client (opt-in).
+
+### Returns
+
+- `Promise`
+
+### Examples
+
+```node
+// Enable client
+await client.enable()
+// Client is now enabled and will capture events
+```
+
+---
+
+### Feature flags methods
+
+#### evaluateFlags()
+
+**Release Tag:** public
+
+Evaluate all feature flags for a user in a single call and return a snapshot. Branch on `.isEnabled()` / `.getFlag()`, then pass the same snapshot to `capture()` via the `flags` option so the captured event carries the exact flag values the code branched on.
+Prefer this over repeated `isFeatureEnabled()` / `getFeatureFlag()` calls and over `capture({ sendFeatureFlags: true })` — it consolidates flag evaluation into a single `/flags` request per incoming request.
+**Local evaluation is transparent.** When the poller can resolve a flag from cached definitions, no network call is made and the snapshot's `$feature_flag_called` events are tagged `locally_evaluated: true`.
+**Trim the request.** Pass `flagKeys` to scope the underlying `/flags` request to a subset of flags — useful when you only need a few flags and want to reduce the response payload.
+**Trim the event payload.** Use `flags.only([...])` or `flags.onlyAccessed()` to filter which flags get attached to a captured event without re-fetching.
+
+### Parameters
+
+- **`options?`** (`AllFlagsOptions`) - Optional configuration for flag evaluation. Supports the same fields as `getAllFlags()`, including `flagKeys` to scope the `/flags` request.
+
+### Returns
+
+- `Promise`
+
+### Examples
+
+####
+
+```node
+Basic usage:
+
+const flags = await client.evaluateFlags('user_123', {
+ personProperties: { plan: 'enterprise' },
+})
+if (flags.isEnabled('new-dashboard')) {
+ renderNewDashboard()
+}
+client.capture({ distinctId: 'user_123', event: 'page_viewed', flags })
+```
+
+####
+
+```node
+Scope the request to specific keys:
+
+const flags = await client.evaluateFlags('user_123', {
+ flagKeys: ['new-dashboard', 'checkout-flow'],
+ personProperties: { plan: 'enterprise' },
+})
+```
+
+####
+
+```node
+Attach only the flags the developer actually checked:
+
+const flags = await client.evaluateFlags('user_123')
+if (flags.isEnabled('new-dashboard')) { ... }
+client.capture({ distinctId: 'user_123', event: 'page_viewed', flags: flags.onlyAccessed() })
+```
+
+####
+
+```node
+Use to avoid repeating the distinctId:
+
+await client.withContext({ distinctId: 'user_123' }, async () => {
+ const flags = await client.evaluateFlags()
+ if (flags.isEnabled('new-dashboard')) { ... }
+ client.capture({ event: 'page_viewed', flags })
+})
+```
+
+---
+
+#### getAllFlags()
+
+**Release Tag:** public
+
+Get all feature flag values for a specific user.
+
+### Parameters
+
+- **`options?`** (`AllFlagsOptions`) - Optional configuration for flag evaluation
+
+### Returns
+
+- `Promise>`
+
+### Examples
+
+#### Get all flags for a user
+
+```node
+// Get all flags for a user
+const allFlags = await client.getAllFlags('user_123')
+console.log('User flags:', allFlags)
+// Output: { 'flag-1': 'variant-a', 'flag-2': false, 'flag-3': 'variant-b' }
+```
+
+#### With specific flag keys
+
+```node
+// With specific flag keys
+const specificFlags = await client.getAllFlags('user_123', {
+ flagKeys: ['flag-1', 'flag-2']
+})
+```
+
+#### With groups and properties
+
+```node
+// With groups and properties
+const orgFlags = await client.getAllFlags('user_123', {
+ groups: { organization: 'acme-corp' },
+ personProperties: { plan: 'enterprise' }
+})
+```
+
+---
+
+#### getAllFlagsAndPayloads()
+
+**Release Tag:** public
+
+Get all feature flag values and payloads for a specific user.
+
+### Parameters
+
+- **`options?`** (`AllFlagsOptions`) - Optional configuration for flag evaluation
+
+### Returns
+
+- `Promise`
+
+### Examples
+
+#### Get all flags and payloads for a user
+
+```node
+// Get all flags and payloads for a user
+const result = await client.getAllFlagsAndPayloads('user_123')
+console.log('Flags:', result.featureFlags)
+console.log('Payloads:', result.featureFlagPayloads)
+```
+
+#### With specific flag keys
+
+```node
+// With specific flag keys
+const result = await client.getAllFlagsAndPayloads('user_123', {
+ flagKeys: ['flag-1', 'flag-2']
+})
+```
+
+#### Only evaluate locally
+
+```node
+// Only evaluate locally
+const result = await client.getAllFlagsAndPayloads('user_123', {
+ onlyEvaluateLocally: true
+})
+```
+
+---
+
+#### getFeatureFlag()
+
+**Release Tag:** deprecated
+
+Get the value of a feature flag for a specific user.
+
+### Parameters
+
+- **`key`** (`string`) - The feature flag key
+- **`distinctId`** (`string`) - The user's distinct ID
+- **`options?`** (`{
+ groups?: Record;
+ personProperties?: Record;
+ groupProperties?: Record>;
+ onlyEvaluateLocally?: boolean;
+ sendFeatureFlagEvents?: boolean;
+ disableGeoip?: boolean;
+ }`) - Optional configuration for flag evaluation
+
+### Returns
+
+**Union of:**
+- `Promise`
+
+### Examples
+
+#### Basic feature flag check
+
+```node
+// Basic feature flag check
+const flagValue = await client.getFeatureFlag('new-feature', 'user_123')
+if (flagValue === 'variant-a') {
+ // Show variant A
+} else if (flagValue === 'variant-b') {
+ // Show variant B
+} else {
+ // Flag is disabled or not found
+}
+```
+
+#### With groups and properties
+
+```node
+// With groups and properties
+const flagValue = await client.getFeatureFlag('org-feature', 'user_123', {
+ groups: { organization: 'acme-corp' },
+ personProperties: { plan: 'enterprise' },
+ groupProperties: { organization: { tier: 'premium' } }
+})
+```
+
+#### Only evaluate locally
+
+```node
+// Only evaluate locally
+const flagValue = await client.getFeatureFlag('local-flag', 'user_123', {
+ onlyEvaluateLocally: true
+})
+```
+
+---
+
+#### getFeatureFlagPayload()
+
+**Release Tag:** deprecated
+
+Get the payload for a feature flag.
+
+### Parameters
+
+- **`key`** (`string`) - The feature flag key
+- **`distinctId`** (`string`) - The user's distinct ID
+- **`matchValue?`** (`FeatureFlagValue`) - Optional match value to get payload for
+- **`options?`** (`{
+ groups?: Record;
+ personProperties?: Record;
+ groupProperties?: Record>;
+ onlyEvaluateLocally?: boolean;
+ sendFeatureFlagEvents?: boolean;
+ disableGeoip?: boolean;
+ }`) - Optional configuration for flag evaluation
+
+### Returns
+
+**Union of:**
+- `Promise`
+
+### Examples
+
+#### Get payload for a feature flag
+
+```node
+// Get payload for a feature flag
+const payload = await client.getFeatureFlagPayload('flag-key', 'user_123')
+if (payload) {
+ console.log('Flag payload:', payload)
+}
+```
+
+#### Get payload with specific match value
+
+```node
+// Get payload with specific match value
+const payload = await client.getFeatureFlagPayload('flag-key', 'user_123', 'variant-a')
+```
+
+#### With groups and properties
+
+```node
+// With groups and properties
+const payload = await client.getFeatureFlagPayload('org-flag', 'user_123', undefined, {
+ groups: { organization: 'acme-corp' },
+ personProperties: { plan: 'enterprise' }
+})
+```
+
+---
+
+#### getFeatureFlagResult()
+
+**Release Tag:** public
+
+Get the result of evaluating a feature flag, including its value and payload. This is more efficient than calling getFeatureFlag and getFeatureFlagPayload separately when you need both.
+
+### Parameters
+
+- **`key`** (`string`) - The feature flag key
+- **`options?`** (`FlagEvaluationOptions`) - Optional configuration for flag evaluation
+
+### Returns
+
+**Union of:**
+- `Promise`
+
+### Examples
+
+#### Get flag result
+
+```node
+// Get flag result
+const result = await client.getFeatureFlagResult('my-flag', 'user_123')
+if (result) {
+ console.log('Flag enabled:', result.enabled)
+ console.log('Variant:', result.variant)
+ console.log('Payload:', result.payload)
+}
+```
+
+#### With groups and properties
+
+```node
+// With groups and properties
+const result = await client.getFeatureFlagResult('org-feature', 'user_123', {
+ groups: { organization: 'acme-corp' },
+ personProperties: { plan: 'enterprise' }
+})
+```
+
+---
+
+#### getRemoteConfigPayload()
+
+**Release Tag:** public
+
+Get the remote config payload for a feature flag.
+
+### Parameters
+
+- **`flagKey`** (`string`) - The feature flag key
+
+### Returns
+
+**Union of:**
+- `Promise`
+
+### Examples
+
+```node
+// Get remote config payload
+const payload = await client.getRemoteConfigPayload('flag-key')
+if (payload) {
+ console.log('Remote config payload:', payload)
+}
+```
+
+---
+
+#### isFeatureEnabled()
+
+**Release Tag:** deprecated
+
+Check if a feature flag is enabled for a specific user.
+
+### Parameters
+
+- **`key`** (`string`) - The feature flag key
+- **`distinctId`** (`string`) - The user's distinct ID
+- **`options?`** (`{
+ groups?: Record;
+ personProperties?: Record;
+ groupProperties?: Record>;
+ onlyEvaluateLocally?: boolean;
+ sendFeatureFlagEvents?: boolean;
+ disableGeoip?: boolean;
+ }`) - Optional configuration for flag evaluation
+
+### Returns
+
+**Union of:**
+- `Promise`
+
+### Examples
+
+#### Basic feature flag check
+
+```node
+// Basic feature flag check
+const isEnabled = await client.isFeatureEnabled('new-feature', 'user_123')
+if (isEnabled) {
+ // Feature is enabled
+ console.log('New feature is active')
+} else {
+ // Feature is disabled
+ console.log('New feature is not active')
+}
+```
+
+#### With groups and properties
+
+```node
+// With groups and properties
+const isEnabled = await client.isFeatureEnabled('org-feature', 'user_123', {
+ groups: { organization: 'acme-corp' },
+ personProperties: { plan: 'enterprise' }
+})
+```
+
+---
+
+#### isLocalEvaluationReady()
+
+**Release Tag:** public
+
+Check if local evaluation of feature flags is ready.
+
+### Returns
+
+- `boolean`
+
+### Examples
+
+```node
+// Check if ready
+if (client.isLocalEvaluationReady()) {
+ // Local evaluation is ready, can evaluate flags locally
+ const flag = await client.getFeatureFlag('flag-key', 'user_123')
+} else {
+ // Local evaluation not ready, will use remote evaluation
+ const flag = await client.getFeatureFlag('flag-key', 'user_123')
+}
+```
+
+---
+
+#### overrideFeatureFlags()
+
+**Release Tag:** public
+
+Override feature flags locally. Useful for testing and local development. Overridden flags take precedence over both local evaluation and remote evaluation.
+
+### Parameters
+
+- **`overrides`** (`OverrideFeatureFlagsOptions`) - Flag overrides configuration
+
+### Returns
+
+- `void`
+
+### Examples
+
+```node
+// Clear all overrides
+client.overrideFeatureFlags(false)
+
+// Enable a list of flags (sets them to true)
+client.overrideFeatureFlags(['flag-a', 'flag-b'])
+
+// Set specific flag values/variants
+client.overrideFeatureFlags({ 'my-flag': 'variant-a', 'other-flag': true })
+
+// Set both flags and payloads
+client.overrideFeatureFlags({
+ flags: { 'my-flag': 'variant-a' },
+ payloads: { 'my-flag': { discount: 20 } }
+})
+```
+
+---
+
+#### reloadFeatureFlags()
+
+**Release Tag:** public
+
+Reload feature flag definitions from the server for local evaluation.
+
+### Returns
+
+- `Promise`
+
+### Examples
+
+#### Force reload of feature flags
+
+```node
+// Force reload of feature flags
+await client.reloadFeatureFlags()
+console.log('Feature flags reloaded')
+```
+
+#### Reload before checking a specific flag
+
+```node
+// Reload before checking a specific flag
+await client.reloadFeatureFlags()
+const flag = await client.getFeatureFlag('flag-key', 'user_123')
+```
+
+---
+
+#### waitForLocalEvaluationReady()
+
+**Release Tag:** public
+
+Wait for local evaluation of feature flags to be ready.
+
+### Parameters
+
+- **`timeoutMs?`** (`number`) - Timeout in milliseconds (default: 30000)
+
+### Returns
+
+- `Promise`
+
+### Examples
+
+#### Wait for local evaluation
+
+```node
+// Wait for local evaluation
+const isReady = await client.waitForLocalEvaluationReady()
+if (isReady) {
+ console.log('Local evaluation is ready')
+} else {
+ console.log('Local evaluation timed out')
+}
+```
+
+#### Wait with custom timeout
+
+```node
+// Wait with custom timeout
+const isReady = await client.waitForLocalEvaluationReady(10000) // 10 seconds
+```
+
+---
+
+### Context methods
+
+#### getContext()
+
+**Release Tag:** public
+
+Get the current context data.
+
+### Returns
+
+**Union of:**
+- `ContextData`
+- `undefined`
+
+### Examples
+
+```node
+// Get current context within a withContext block
+posthog.withContext({ distinctId: 'user_123' }, () => {
+ const context = posthog.getContext()
+ console.log(context?.distinctId) // 'user_123'
+})
+```
+
+---
+
+#### withContext()
+
+**Release Tag:** public
+
+Run a function with specific context that will be applied to all events captured within that context. It propagates the context to all subsequent calls down the call stack. Context properties like tags and sessionId will be automatically attached to all events. By default, nested contexts inherit from parent contexts. Use `{ fresh: true }` to start with a clean context.
+
+### Parameters
+
+- **`data`** (`Partial`) - Context data to apply (sessionId, distinctId, properties, enableExceptionAutocapture)
+- **`fn`** (`() => T`) - Function to run with the context
+- **`options?`** (`ContextOptions`) - Context options (fresh: true to start with clean context instead of inheriting)
+
+### Returns
+
+- `T`
+
+### Examples
+
+```node
+posthog.withContext({ distinctId: 'user_123' }, () => {
+ posthog.capture({ event: 'button clicked' })
+})
+```
+
+---
\ No newline at end of file
diff --git a/.gitignore b/.gitignore
index d9bad3af3..514b39df0 100644
--- a/.gitignore
+++ b/.gitignore
@@ -28,4 +28,4 @@ Cargo.lock
/target
/data
*.node
-.env
+.env
\ No newline at end of file
diff --git a/apps/api/package.json b/apps/api/package.json
index 81d7ec0c9..016e7b67b 100644
--- a/apps/api/package.json
+++ b/apps/api/package.json
@@ -37,6 +37,7 @@
"ioredis": "5.7.0",
"luxon": "^3.5.0",
"mongoose": "^8.5.2",
+ "posthog-node": "^5.37.0",
"reflect-metadata": "^0.2.2",
"rxjs": "^7.8.1",
"skia-canvas": "3.0.8",
diff --git a/apps/api/src/guild/leaderboards/guild-leaderboard.controller.ts b/apps/api/src/guild/leaderboards/guild-leaderboard.controller.ts
index 70eeb3474..cd140d60d 100644
--- a/apps/api/src/guild/leaderboards/guild-leaderboard.controller.ts
+++ b/apps/api/src/guild/leaderboards/guild-leaderboard.controller.ts
@@ -18,6 +18,8 @@ import {
import { Guild } from "@statsify/schemas";
import { GuildLeaderboardDto, GuildRankingDto } from "#dtos";
import { GuildLeaderboardService } from "./guild-leaderboard.service.js";
+import { captureSampled } from "../../posthog.js";
+import { randomUUID } from "node:crypto";
@Controller("/guild/leaderboards")
export class GuildLeaderboardController {
@@ -45,6 +47,15 @@ export class GuildLeaderboardController {
type = LeaderboardQuery.PAGE;
}
+ captureSampled({
+ distinctId: randomUUID(),
+ event: "guild leaderboard viewed",
+ properties: {
+ field,
+ query_type: type,
+ },
+ });
+
const leaderboard = await this.guildLeaderboardService.getLeaderboard(
Guild,
field,
diff --git a/apps/api/src/index.ts b/apps/api/src/index.ts
index 648d33c1a..c252971e8 100644
--- a/apps/api/src/index.ts
+++ b/apps/api/src/index.ts
@@ -20,6 +20,7 @@ import { ValidationPipe } from "@nestjs/common";
import { config } from "@statsify/util";
import { join } from "node:path";
import { mkdir } from "node:fs/promises";
+import { posthog } from "./posthog.js";
const directory = import.meta.dirname;
@@ -28,6 +29,14 @@ const handleError = logger.error.bind(logger);
process.on("uncaughtException", handleError);
process.on("unhandledRejection", handleError);
+process.on("SIGTERM", async () => {
+ await posthog?.shutdown();
+ process.exit(0);
+});
+process.on("SIGINT", async () => {
+ await posthog?.shutdown();
+ process.exit(0);
+});
const sentryDsn = await config("sentry.apiDsn", { required: false });
diff --git a/apps/api/src/player/leaderboards/player-leaderboard.controller.ts b/apps/api/src/player/leaderboards/player-leaderboard.controller.ts
index 567d5f4cf..a51ac60bc 100644
--- a/apps/api/src/player/leaderboards/player-leaderboard.controller.ts
+++ b/apps/api/src/player/leaderboards/player-leaderboard.controller.ts
@@ -23,6 +23,8 @@ import {
import { Player } from "@statsify/schemas";
import { PlayerLeaderboardDto, PlayerRankingsDto } from "#dtos";
import { PlayerLeaderboardService } from "./player-leaderboard.service.js";
+import { captureSampled } from "../../posthog.js";
+import { randomUUID } from "node:crypto";
@Controller("/player/leaderboards")
@ApiTags("Player Leaderboards")
@@ -53,6 +55,15 @@ export class PlayerLeaderboardsController {
type = LeaderboardQuery.PAGE;
}
+ captureSampled({
+ distinctId: randomUUID(),
+ event: "player leaderboard viewed",
+ properties: {
+ field,
+ query_type: type,
+ },
+ });
+
return this.playerLeaderboardService.getLeaderboard(Player, field, input, type);
}
diff --git a/apps/api/src/player/player.controller.ts b/apps/api/src/player/player.controller.ts
index 552b8c0df..ceced8887 100644
--- a/apps/api/src/player/player.controller.ts
+++ b/apps/api/src/player/player.controller.ts
@@ -31,6 +31,7 @@ import {
} from "@statsify/api-client";
import { PlayerService } from "./player.service.js";
+import { posthog } from "../posthog.js";
@Controller("/player")
@ApiTags("Player")
@@ -76,6 +77,16 @@ export class PlayerController {
public async deletePlayer(@Query() { player }: PlayerDto) {
const deleted = await this.playerService.delete(player);
+ if (deleted) {
+ posthog?.capture({
+ distinctId: "admin",
+ event: "player deleted",
+ properties: {
+ player_tag: player,
+ },
+ });
+ }
+
return {
success: deleted,
};
diff --git a/apps/api/src/posthog.ts b/apps/api/src/posthog.ts
new file mode 100644
index 000000000..a3ada8095
--- /dev/null
+++ b/apps/api/src/posthog.ts
@@ -0,0 +1,46 @@
+/**
+ * Copyright (c) Statsify
+ *
+ * This source code is licensed under the GNU GPL v3 license found in the
+ * LICENSE file in the root directory of this source tree.
+ * https://github.com/Statsify/statsify/blob/main/LICENSE
+ */
+
+import { PostHog } from "posthog-node";
+import { config, isSampled } from "@statsify/util";
+
+const apiKey = await config("posthog.apiKey", { required: false });
+const enabled = await config("posthog.enabled", { required: false });
+const sampleRate = await config("posthog.sampleRate", { default: 0.25 });
+
+let posthog: PostHog | undefined;
+
+if (apiKey && enabled) {
+ posthog = new PostHog(apiKey, {
+ host: await config("posthog.host", { default: "https://us.i.posthog.com" }),
+ enableExceptionAutocapture: false,
+ });
+}
+
+interface SampledCaptureOptions {
+ distinctId: string;
+ event: string;
+ properties?: Record;
+}
+
+/**
+ * Captures a high-volume event, deterministically sampled at `posthog.sampleRate`
+ * and captured without person processing to keep cost down.
+ */
+export function captureSampled({ distinctId, event, properties }: SampledCaptureOptions) {
+ if (!posthog) return;
+ if (!isSampled(distinctId, sampleRate)) return;
+
+ posthog.capture({
+ distinctId,
+ event,
+ properties: { ...properties, $process_person_profile: false },
+ });
+}
+
+export { posthog };
diff --git a/apps/api/src/session/session.controller.ts b/apps/api/src/session/session.controller.ts
index 2a6cb84e0..4569ab5a3 100644
--- a/apps/api/src/session/session.controller.ts
+++ b/apps/api/src/session/session.controller.ts
@@ -22,6 +22,7 @@ import {
} from "@statsify/api-client";
import { PlayerDto, SessionDto, UserIdDto } from "#dtos";
import { SessionService } from "./session.service.js";
+import { posthog } from "../posthog.js";
@Controller("/session")
@ApiTags("session")
@@ -51,6 +52,15 @@ export class SessionController {
@Query() { player: tag }: PlayerDto
) {
const player = await this.sessionService.getAndReset(tag);
+
+ posthog?.capture({
+ distinctId: player?.uuid ?? tag,
+ event: "session reset",
+ properties: {
+ player_tag: tag,
+ },
+ });
+
return { success: !!player, player };
}
@@ -63,6 +73,12 @@ export class SessionController {
@Query() { id }: UserIdDto
) {
await this.sessionService.delete(id);
+
+ posthog?.capture({
+ distinctId: id,
+ event: "session deleted",
+ });
+
return { success: true };
}
}
diff --git a/apps/discord-bot/package.json b/apps/discord-bot/package.json
index 7fb74f2e5..33e595109 100644
--- a/apps/discord-bot/package.json
+++ b/apps/discord-bot/package.json
@@ -28,6 +28,7 @@
"fuse.js": "^7.0.0",
"luxon": "^3.5.0",
"mongoose": "^8.5.2",
+ "posthog-node": "^5.37.0",
"reflect-metadata": "^0.2.2",
"skia-canvas": "3.0.8",
"tiny-discord": "https://github.com/timotejroiko/tiny-discord.git#f6d020085ea88e33ebaf6ce323930deffe74fb0d",
diff --git a/apps/discord-bot/src/commands/unverify.command.ts b/apps/discord-bot/src/commands/unverify.command.ts
index a85f9312f..9764230a6 100644
--- a/apps/discord-bot/src/commands/unverify.command.ts
+++ b/apps/discord-bot/src/commands/unverify.command.ts
@@ -15,6 +15,7 @@ import {
IMessage,
MemberService,
} from "@statsify/discord";
+import { PosthogService } from "../posthog.js";
import { STATUS_COLORS } from "@statsify/logger";
import { config } from "@statsify/util";
@@ -25,7 +26,8 @@ const SUPPORT_BOT_MEMBER_ROLE_ID = await config("supportBot.memberRole");
export class UnverifyCommand {
public constructor(
private readonly apiService: ApiService,
- private readonly memberService: MemberService
+ private readonly memberService: MemberService,
+ private readonly posthogService: PosthogService
) {}
public async run(context: CommandContext): Promise {
@@ -36,6 +38,14 @@ export class UnverifyCommand {
await this.apiService.unverifyUser(userId);
+ this.posthogService.capture({
+ distinctId: userId,
+ event: "user unverified",
+ properties: {
+ minecraft_uuid: user.uuid,
+ },
+ });
+
await this.memberService
.removeRole(SUPPORT_BOT_GUILD_ID, userId, SUPPORT_BOT_MEMBER_ROLE_ID)
.then(() => this.apiService.updateUser(userId, { serverMember: false }))
diff --git a/apps/discord-bot/src/commands/verify.command.ts b/apps/discord-bot/src/commands/verify.command.ts
index 4f1245a05..f69500091 100644
--- a/apps/discord-bot/src/commands/verify.command.ts
+++ b/apps/discord-bot/src/commands/verify.command.ts
@@ -25,6 +25,7 @@ import {
InteractionResponseType,
TextInputStyle,
} from "discord-api-types/v10";
+import { PosthogService } from "../posthog.js";
import { STATUS_COLORS } from "@statsify/logger";
import { config } from "@statsify/util";
@@ -57,7 +58,8 @@ const VERIFY_BUTTON = new ButtonBuilder()
export class VerifyCommand {
public constructor(
private readonly apiService: ApiService,
- private readonly memberService: MemberService
+ private readonly memberService: MemberService,
+ private readonly posthogService: PosthogService
) {}
public async run(): Promise {
@@ -109,6 +111,23 @@ export class VerifyCommand {
const player = await this.apiService.getPlayer(user.uuid as string);
+ this.posthogService.identify({
+ distinctId: userId,
+ properties: {
+ $set: { minecraft_uuid: user.uuid, minecraft_username: player.username },
+ $set_once: { verified_at: new Date().toISOString() },
+ },
+ });
+
+ this.posthogService.capture({
+ distinctId: userId,
+ event: "user verified",
+ properties: {
+ minecraft_uuid: user.uuid,
+ minecraft_username: player.username,
+ },
+ });
+
const displayName = this.apiService.emojiDisplayName(t, player.displayName);
const embed = new EmbedBuilder()
diff --git a/apps/discord-bot/src/index.ts b/apps/discord-bot/src/index.ts
index 7bfbafbb6..c2b41d756 100644
--- a/apps/discord-bot/src/index.ts
+++ b/apps/discord-bot/src/index.ts
@@ -13,6 +13,7 @@ import { Container } from "typedi";
import { FontLoaderService } from "#services";
import { InteractionServer, RestClient, WebsocketShard } from "tiny-discord";
import { Logger } from "@statsify/logger";
+import { PosthogService } from "./posthog.js";
import { VerifyCommand } from "#commands/verify.command";
import { config } from "@statsify/util";
import { join } from "node:path";
@@ -21,9 +22,18 @@ const directory = import.meta.dirname;
const logger = new Logger("discord-bot");
const handleError = logger.error.bind(logger);
+const posthog = Container.get(PosthogService);
process.on("uncaughtException", handleError);
process.on("unhandledRejection", handleError);
+process.on("SIGTERM", async () => {
+ await posthog.shutdown();
+ process.exit(0);
+});
+process.on("SIGINT", async () => {
+ await posthog.shutdown();
+ process.exit(0);
+});
const sentryDsn = await config("sentry.discordBotDsn", { required: false });
diff --git a/apps/discord-bot/src/lib/command.listener.ts b/apps/discord-bot/src/lib/command.listener.ts
index d42bbf4f6..1c68178d2 100644
--- a/apps/discord-bot/src/lib/command.listener.ts
+++ b/apps/discord-bot/src/lib/command.listener.ts
@@ -17,6 +17,7 @@ import {
Interaction,
} from "@statsify/discord";
import { Container } from "typedi";
+import { PosthogService } from "../posthog.js";
import { STATUS_COLORS } from "@statsify/logger";
import { User, UserTier } from "@statsify/schemas";
import { config, formatTime } from "@statsify/util";
@@ -32,6 +33,7 @@ const port = await config("discordBot.port", { required: false });
export class CommandListener extends AbstractCommandListener {
private cooldowns: Map>;
private readonly apiService: ApiService;
+ private readonly posthogService: PosthogService;
private static instance: CommandListener;
private constructor(
@@ -48,6 +50,7 @@ export class CommandListener extends AbstractCommandListener {
);
this.apiService = Container.get(ApiService);
+ this.posthogService = Container.get(PosthogService);
this.cooldowns = new Map();
}
@@ -103,6 +106,23 @@ export class CommandListener extends AbstractCommandListener {
context,
preconditions,
message: this.getTipResponse(commandName, user),
+ onComplete: (result) => {
+ this.posthogService.captureSampled({
+ distinctId: id,
+ event: "command executed",
+ properties: {
+ command: commandName,
+ locale,
+ tier: user?.tier ?? UserTier.NONE,
+ serverMember: user?.serverMember ?? false,
+ verified: !!user?.uuid,
+ guild_id: interaction.getGuildId() ?? null,
+ ok: result.ok,
+ error_kind: result.errorKind,
+ duration_ms: result.durationMs,
+ },
+ });
+ },
});
}
diff --git a/apps/discord-bot/src/posthog.ts b/apps/discord-bot/src/posthog.ts
new file mode 100644
index 000000000..43808c953
--- /dev/null
+++ b/apps/discord-bot/src/posthog.ts
@@ -0,0 +1,73 @@
+/**
+ * Copyright (c) Statsify
+ *
+ * This source code is licensed under the GNU GPL v3 license found in the
+ * LICENSE file in the root directory of this source tree.
+ * https://github.com/Statsify/statsify/blob/main/LICENSE
+ */
+
+import { PostHog } from "posthog-node";
+import { Service } from "typedi";
+import { config, isSampled } from "@statsify/util";
+
+const apiKey = await config("posthog.apiKey", { required: false });
+const enabled = await config("posthog.enabled", { required: false });
+const sampleRate = await config("posthog.sampleRate", { default: 0.25 });
+const host = await config("posthog.host", { default: "https://us.i.posthog.com" });
+
+interface CaptureOptions {
+ distinctId: string;
+ event: string;
+ properties?: Record;
+}
+
+interface IdentifyOptions {
+ distinctId: string;
+ properties?: Record;
+}
+
+@Service()
+export class PosthogService {
+ private readonly client?: PostHog;
+
+ public constructor() {
+ if (apiKey && enabled) {
+ this.client = new PostHog(apiKey, {
+ host,
+ enableExceptionAutocapture: false,
+ });
+ }
+ }
+
+ /**
+ * Captures an event at 100%, with person processing enabled. Use for
+ * conversion/churn events.
+ */
+ public capture(options: CaptureOptions) {
+ this.client?.capture(options);
+ }
+
+ public identify(options: IdentifyOptions) {
+ this.client?.identify(options);
+ }
+
+ /**
+ * Captures a high-volume event, deterministically sampled at
+ * `posthog.sampleRate` and captured without person processing to keep
+ * cost down.
+ */
+ public captureSampled({ distinctId, event, properties }: CaptureOptions) {
+ if (!this.client) return;
+ if (!isSampled(distinctId, sampleRate)) return;
+
+ this.client.capture({
+ distinctId,
+ event,
+ properties: { ...properties, $process_person_profile: false },
+ });
+ }
+
+ public shutdown() {
+ return this.client?.shutdown();
+ }
+}
diff --git a/apps/verify-server/package.json b/apps/verify-server/package.json
index 9d16b078c..e2865cdf4 100644
--- a/apps/verify-server/package.json
+++ b/apps/verify-server/package.json
@@ -20,6 +20,7 @@
"@swc/helpers": "^0.5.23",
"@typegoose/typegoose": "^12.6.0",
"minecraft-protocol": "1.61.0",
- "mongoose": "^8.5.2"
+ "mongoose": "^8.5.2",
+ "posthog-node": "^5.37.0"
}
}
diff --git a/apps/verify-server/src/index.ts b/apps/verify-server/src/index.ts
index 0ce9286a3..2fb4dd57d 100644
--- a/apps/verify-server/src/index.ts
+++ b/apps/verify-server/src/index.ts
@@ -15,6 +15,7 @@ import { createServer } from "minecraft-protocol";
import { generateCode } from "./generate-code.js";
import { getLogoPath } from "@statsify/assets";
import { getModelForClass } from "@typegoose/typegoose";
+import { posthog } from "./posthog.js";
import { readFileSync } from "node:fs";
const logger = new Logger("verify-server");
@@ -23,6 +24,14 @@ const handleError = logger.error.bind(logger);
process.on("uncaughtException", handleError);
process.on("unhandledRejection", handleError);
+process.on("SIGTERM", async () => {
+ await posthog?.shutdown();
+ process.exit(0);
+});
+process.on("SIGINT", async () => {
+ await posthog?.shutdown();
+ process.exit(0);
+});
const codeCreatedMessage = (code: string, time: Date) => {
// Add on the expirey time to the time provided by mongo
@@ -90,6 +99,15 @@ server.on("login", async (client) => {
const code = await generateCode(verifyCodesModel);
const verifyCode = await verifyCodesModel.create(new VerifyCode(uuid, code));
+ posthog?.capture({
+ distinctId: uuid,
+ event: "verification code requested",
+ properties: {
+ minecraft_username: client.username,
+ minecraft_uuid: uuid,
+ },
+ });
+
client.end(codeCreatedMessage(verifyCode.code, verifyCode.expireAt));
logger.verbose(`${client.username} has been assigned to the code ${verifyCode.code}`);
} catch (error) {
diff --git a/apps/verify-server/src/posthog.ts b/apps/verify-server/src/posthog.ts
new file mode 100644
index 000000000..3d6f223aa
--- /dev/null
+++ b/apps/verify-server/src/posthog.ts
@@ -0,0 +1,24 @@
+/**
+ * Copyright (c) Statsify
+ *
+ * This source code is licensed under the GNU GPL v3 license found in the
+ * LICENSE file in the root directory of this source tree.
+ * https://github.com/Statsify/statsify/blob/main/LICENSE
+ */
+
+import { PostHog } from "posthog-node";
+import { config } from "@statsify/util";
+
+const apiKey = await config("posthog.apiKey", { required: false });
+const enabled = await config("posthog.enabled", { required: false });
+
+let posthog: PostHog | undefined;
+
+if (apiKey && enabled) {
+ posthog = new PostHog(apiKey, {
+ host: await config("posthog.host", { default: "https://us.i.posthog.com" }),
+ enableExceptionAutocapture: false,
+ });
+}
+
+export { posthog };
diff --git a/config.schema.js b/config.schema.js
index 4317d8ae2..a6e96459e 100644
--- a/config.schema.js
+++ b/config.schema.js
@@ -69,5 +69,11 @@ export default {
supportBotDsn: "",
tracesSampleRate: 1,
},
+ posthog: {
+ apiKey: "",
+ host: "https://us.i.posthog.com",
+ enabled: false,
+ sampleRate: 0.25,
+ },
environment: "dev",
};
diff --git a/packages/discord/src/command/abstract-command.listener.ts b/packages/discord/src/command/abstract-command.listener.ts
index 90527fdb1..e6f6052d3 100644
--- a/packages/discord/src/command/abstract-command.listener.ts
+++ b/packages/discord/src/command/abstract-command.listener.ts
@@ -34,12 +34,19 @@ export type InteractionHook = (
export type CommandPrecondition = () => void;
+export interface CommandExecutionResult {
+ ok: boolean;
+ errorKind: "none" | "handled" | "exception";
+ durationMs: number;
+}
+
export interface ExecuteCommandOptions {
commandName: string;
command: CommandResolvable;
context: CommandContext;
preconditions?: CommandPrecondition[];
message?: IMessage | Message;
+ onComplete?: (result: CommandExecutionResult) => void;
}
export abstract class AbstractCommandListener {
@@ -128,8 +135,10 @@ export abstract class AbstractCommandListener {
context,
preconditions = [],
message,
+ onComplete,
}: ExecuteCommandOptions) {
const transaction = Sentry.getCurrentHub().getScope()?.getTransaction();
+ const start = Date.now();
try {
for (const precondition of preconditions) {
@@ -138,22 +147,32 @@ export abstract class AbstractCommandListener {
const response = await command.execute(context);
- if (typeof response !== "object") return;
+ if (typeof response !== "object") {
+ onComplete?.({ ok: true, errorKind: "none", durationMs: Date.now() - start });
+ return;
+ }
+
transaction?.finish();
context.reply({
...message,
...response,
});
+
+ onComplete?.({ ok: true, errorKind: "none", durationMs: Date.now() - start });
} catch (err) {
if (err instanceof Message) {
transaction?.finish();
- return context.reply(err);
+ context.reply(err);
+ onComplete?.({ ok: false, errorKind: "handled", durationMs: Date.now() - start });
+ return;
}
this.logger.error(`An error occurred when running "${commandName}"`);
this.logger.error(err);
transaction?.finish();
+
+ onComplete?.({ ok: false, errorKind: "exception", durationMs: Date.now() - start });
}
}
diff --git a/packages/util/src/config.ts b/packages/util/src/config.ts
index b3c71297e..c8d672f45 100644
--- a/packages/util/src/config.ts
+++ b/packages/util/src/config.ts
@@ -6,6 +6,7 @@
* https://github.com/Statsify/statsify/blob/main/LICENSE
*/
+import { createHash } from "node:crypto";
import { join } from "node:path";
import { existsSync } from "node:fs";
import type { DeepFlatten } from "./flatten.js";
@@ -230,6 +231,27 @@ export interface Config {
tracesSampleRate?: number;
};
+ posthog?: {
+ /**
+ * The PostHog project API key
+ */
+ apiKey?: string;
+ /**
+ * The PostHog ingestion host
+ * @example https://us.i.posthog.com
+ */
+ host: string;
+ /**
+ * Whether PostHog analytics capture is enabled
+ */
+ enabled?: boolean;
+ /**
+ * The fraction (0-1) of high-volume events to sample
+ * @example 0.25
+ */
+ sampleRate: number;
+ };
+
/**
* The current environment the bot is running in
* @example dev
@@ -325,3 +347,21 @@ export const config = async (
return value;
};
+
+/**
+ * Deterministically decides whether an entity should be sampled, using a
+ * stable hash so the same `distinctId` always produces the same result for
+ * a given `rate`. Used to keep analytics sampling consistent across apps.
+ *
+ * @param distinctId The id to hash, e.g. a PostHog distinct id
+ * @param rate The fraction (0-1) of ids that should be sampled in
+ */
+export const isSampled = (distinctId: string, rate: number): boolean => {
+ if (rate >= 1) return true;
+ if (rate <= 0) return false;
+
+ const hash = createHash("sha256").update(distinctId).digest();
+ const normalized = hash.readUInt32BE(0) / 2 ** 32;
+
+ return normalized < rate;
+};
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 183491aaa..067351321 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -137,6 +137,9 @@ importers:
mongoose:
specifier: ^8.5.2
version: 8.18.0(socks@2.8.7)
+ posthog-node:
+ specifier: ^5.37.0
+ version: 5.37.0(rxjs@7.8.2)
reflect-metadata:
specifier: ^0.2.2
version: 0.2.2
@@ -207,6 +210,9 @@ importers:
mongoose:
specifier: ^8.5.2
version: 8.18.0(socks@2.8.7)
+ posthog-node:
+ specifier: ^5.37.0
+ version: 5.37.0(rxjs@7.8.2)
reflect-metadata:
specifier: ^0.2.2
version: 0.2.2
@@ -439,6 +445,9 @@ importers:
mongoose:
specifier: ^8.5.2
version: 8.18.0(socks@2.8.7)
+ posthog-node:
+ specifier: ^5.37.0
+ version: 5.37.0(rxjs@7.8.2)
assets/private:
dependencies:
@@ -2307,6 +2316,12 @@ packages:
'@polka/url@1.0.0-next.29':
resolution: {integrity: sha512-wwQAWhWSuHaag8c4q/KN/vCoeOJYshAIvMQwD4GpSb3OiZklFfvAgmj0VCBBImRpuF/aFgIRzllXlVX93Jevww==}
+ '@posthog/core@1.32.3':
+ resolution: {integrity: sha512-vwOEMfZvGv5XxNWV7p9I52NSmvFNMhyW2IHpIoUHW5jLkgUrknzJW1H/qxVGSIrNNVQkfsoaDFzDhJdg10pgrA==}
+
+ '@posthog/types@1.386.3':
+ resolution: {integrity: sha512-LqJoiQi2eyWn7rCUgnn+D+F3Efp6+04o72bjSX6kWHx0nFaYNC/nJuAIRliDTY/X7GPIUAaHAcSjbMI/9wfX1Q==}
+
'@radix-ui/primitive@1.1.3':
resolution: {integrity: sha512-JTF99U/6XIjCBo0wqkU5sK10glYe27MRRsfwoiq5zzOEZLHU3A3KCMa5X/azekYRCJ0HlwI0crAXS/5dEHTzDg==}
@@ -4959,6 +4974,15 @@ packages:
resolution: {integrity: sha512-FfR8sjd4em2T6fb3I2MwAJU7HWVMr9zba+enmQeeWFfCbm+UOC/0X4DS8XtpUTMwWMGbjKYP7xjfNekzyGmB3A==}
engines: {node: ^10 || ^12 || >=14}
+ posthog-node@5.37.0:
+ resolution: {integrity: sha512-wFwWGcqAqZ1WJRlNNYc92veV83d1lOQcP4Lq0q7Kar9GdZLPpiFYHeudyybYJnjZjkI9v06vLvY/Og5CZIfByg==}
+ engines: {node: ^20.20.0 || >=22.22.0}
+ peerDependencies:
+ rxjs: ^7.0.0
+ peerDependenciesMeta:
+ rxjs:
+ optional: true
+
prelude-ls@1.2.1:
resolution: {integrity: sha512-vkcDPrRZo1QZLbn5RLGPpg/WmIQ65qoWWhcGKf/b5eplkkarX0m9z8ppCat4mlOqUsWpyNuYgO3VRyrYHSzX5g==}
engines: {node: '>= 0.8.0'}
@@ -7156,6 +7180,12 @@ snapshots:
'@polka/url@1.0.0-next.29': {}
+ '@posthog/core@1.32.3':
+ dependencies:
+ '@posthog/types': 1.386.3
+
+ '@posthog/types@1.386.3': {}
+
'@radix-ui/primitive@1.1.3': {}
'@radix-ui/react-arrow@1.1.7(@types/react-dom@19.2.3(@types/react@19.2.16))(@types/react@19.2.16)(react-dom@19.2.1(react@19.2.1))(react@19.2.1)':
@@ -9759,6 +9789,12 @@ snapshots:
picocolors: 1.1.1
source-map-js: 1.2.1
+ posthog-node@5.37.0(rxjs@7.8.2):
+ dependencies:
+ '@posthog/core': 1.32.3
+ optionalDependencies:
+ rxjs: 7.8.2
+
prelude-ls@1.2.1: {}
pretty-ms@9.3.0:
diff --git a/posthog-setup-report.md b/posthog-setup-report.md
new file mode 100644
index 000000000..f43a97059
--- /dev/null
+++ b/posthog-setup-report.md
@@ -0,0 +1,33 @@
+
+# PostHog post-wizard report
+
+The wizard has completed a deep integration of PostHog analytics across three apps in the Statsify monorepo: the NestJS REST API (`apps/api`), the Discord bot (`apps/discord-bot`), and the Minecraft verification server (`apps/verify-server`). Each app received a singleton PostHog client (`posthog.ts`) initialized from environment variables, plus event captures in route handlers and command listeners. User identification is performed on successful verification, linking Discord user IDs to Minecraft UUIDs. Exception tracking was added to the API's global Sentry interceptor. All apps handle graceful PostHog shutdown on SIGTERM/SIGINT.
+
+| Event | Description | File |
+|---|---|---|
+| `command executed` | A Discord slash command was successfully executed | `apps/discord-bot/src/lib/command.listener.ts` |
+| `user verified` | A Discord user successfully linked their Minecraft account | `apps/discord-bot/src/commands/verify.command.ts` |
+| `user unverified` | A Discord user unlinked their Minecraft account | `apps/discord-bot/src/commands/unverify.command.ts` |
+| `session reset` | A user reset their stat-tracking session | `apps/api/src/session/session.controller.ts` |
+| `session deleted` | A user deleted their stat-tracking session | `apps/api/src/session/session.controller.ts` |
+| `player deleted` | A player's cached data was deleted by an admin | `apps/api/src/player/player.controller.ts` |
+| `verification code requested` | A Minecraft player joined the verify server to get a code | `apps/verify-server/src/index.ts` |
+| `player leaderboard viewed` | A player leaderboard was queried | `apps/api/src/player/leaderboards/player-leaderboard.controller.ts` |
+| `guild leaderboard viewed` | A guild leaderboard was queried | `apps/api/src/guild/leaderboards/guild-leaderboard.controller.ts` |
+
+## Next steps
+
+We've built some insights and a dashboard for you to keep an eye on user behavior, based on the events we just instrumented:
+
+- [Analytics basics (wizard) — Dashboard](https://us.posthog.com/project/362720/dashboard/1708250)
+- [Verification funnel (wizard)](https://us.posthog.com/project/362720/insights/TmgNktO5) — Conversion from Minecraft server join → Discord link
+- [Command usage over time (wizard)](https://us.posthog.com/project/362720/insights/7RcMKJt0) — Total Discord commands executed per day
+- [Verifications vs unverifications (wizard)](https://us.posthog.com/project/362720/insights/S49eMaFY) — User account-linking churn signal
+- [Session activity (wizard)](https://us.posthog.com/project/362720/insights/2Vilts99) — Session resets and deletions over time
+- [Leaderboard usage (wizard)](https://us.posthog.com/project/362720/insights/scCT1KC1) — Player and guild leaderboard engagement
+
+### Agent skill
+
+We've left an agent skill folder in your project. You can use this context for further agent development when using Claude Code. This will help ensure the model provides the most up-to-date approaches for integrating PostHog.
+
+