Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-11-12
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
## Why

The `setup` spec settles what the project credential is called on every configuration surface it
names — an options object, a provider's props, a manifest or `Info.plist` key — but it says nothing
about the environment variable an SDK reads when it is initialized without an explicit token. The
SDKs that read one diverge: posthog-php's `PostHog::init()` and its Laravel package now read
`POSTHOG_PROJECT_TOKEN` and fall back to `POSTHOG_API_KEY`
([posthog-php#311](https://github.com/PostHog/posthog-php/pull/311)), and `@posthog/mcp` reads
`POSTHOG_PROJECT_TOKEN`, while posthog-rs and the posthog-rails logs setup still read only
`POSTHOG_API_KEY`. posthog-php#311 flags this as a gap in the spec rather than a divergence from it.

An app configuring two PostHog SDKs should not need two differently named variables for the same
project token, and the name the spec already picked for the option is the name the variable should
carry.

## What Changes

- New **Project token environment variable name** requirement in `setup`: where an SDK reads the
project token from the environment, the variable is `POSTHOG_PROJECT_TOKEN`; an SDK that already
reads `POSTHOG_API_KEY` keeps it as a deprecated fallback under the existing alias rules; a blank
value falls back as if unset. Reading no environment variable at all stays conformant — the
requirement names the variable, it does not require one.

## Capabilities

### New Capabilities

_None._

### Modified Capabilities

- `setup`: new **Project token environment variable name** requirement.

## Impact

- **posthog-php**: already matches, as of #311 (`PostHog::ENV_PROJECT_TOKEN`, with
`POSTHOG_API_KEY` deprecated).
- **@posthog/mcp**: already reads `POSTHOG_PROJECT_TOKEN`.
- **posthog-rs**, **posthog-ruby** (the Rails logs setup and the install generator template), and the
`@posthog/ai` integrations read `POSTHOG_API_KEY` and would add the new name with the old one as a
fallback. None has to drop the old name.
- SDKs that take the token only from code (posthog-js browser, the mobile SDKs) are unaffected.
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
## ADDED Requirements

### Requirement: Project token environment variable name

Where an SDK reads the project token from an environment variable — a server SDK initialized without an explicit token, a framework integration's generated configuration, or an executable the SDK ships — the variable SHALL be named `POSTHOG_PROJECT_TOKEN`, the environment spelling of the `projectToken` option name. An SDK that reads the token only from code is conformant: this requirement names the variable, it does not require reading one.

An SDK that already reads `POSTHOG_API_KEY` SHALL add `POSTHOG_PROJECT_TOKEN` and keep the old variable as a deprecated fallback in the same release, under the rules of "Deprecated project credential alias": the fallback resolves to the same value, is documented as deprecated naming `POSTHOG_PROJECT_TOKEN` as the replacement, and MAY be removed only in a major version released after the one that added the new name. `POSTHOG_PROJECT_TOKEN` SHALL win when both are set. A `POSTHOG_PROJECT_TOKEN` that is unset, empty, or only whitespace SHALL fall back as if it were unset, rather than initializing the SDK with a blank token.

An explicit token passed in code SHALL win over both variables.

#### Scenario: The project token environment variable configures the SDK
- **GIVEN** an SDK that reads the project token from the environment
- **AND** `POSTHOG_PROJECT_TOKEN` is set to "test-token"
- **WHEN** setup is called with no project token in code
- **THEN** the SDK should be initialized with project token "test-token"

#### Scenario: The deprecated variable is read only when the new one is blank
- **GIVEN** an SDK that reads the project token from the environment and still supports `POSTHOG_API_KEY`
- **AND** `POSTHOG_PROJECT_TOKEN` is set to " "
- **AND** `POSTHOG_API_KEY` is set to "old-token"
- **WHEN** setup is called with no project token in code
- **THEN** the SDK should be initialized with project token "old-token"

#### Scenario: The project token variable wins over the deprecated one
- **GIVEN** an SDK that reads the project token from the environment and still supports `POSTHOG_API_KEY`
- **AND** `POSTHOG_PROJECT_TOKEN` is set to "new-token"
- **AND** `POSTHOG_API_KEY` is set to "old-token"
- **WHEN** setup is called with no project token in code
- **THEN** the SDK should be initialized with project token "new-token"
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
## 1. Spec delta

- [x] 1.1 Add **Project token environment variable name** to `setup`, with scenarios for the new
variable, the deprecated fallback, and precedence

## 2. Validation

- [x] 2.1 Run `openspec validate --specs --strict`
- [x] 2.2 Archive the change and sync the delta into `openspec/specs/setup/spec.md`

## 3. Downstream follow-ups (separate changes, not this one)

- [ ] 3.1 posthog-rs, posthog-ruby and `@posthog/ai` read `POSTHOG_PROJECT_TOKEN` first
- [ ] 3.2 posthog-sdk-test-harness: step bindings for the environment-variable scenarios
28 changes: 28 additions & 0 deletions openspec/specs/setup/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -215,3 +215,31 @@ Renaming the option SHALL NOT change anything below the public configuration sur
- **AND** flush is called
- **THEN** the mock server should have received a batch with API key "test-token"
- **AND** the batch should contain an event named "Earlier"

### Requirement: Project token environment variable name

Where an SDK reads the project token from an environment variable — a server SDK initialized without an explicit token, a framework integration's generated configuration, or an executable the SDK ships — the variable SHALL be named `POSTHOG_PROJECT_TOKEN`, the environment spelling of the `projectToken` option name. An SDK that reads the token only from code is conformant: this requirement names the variable, it does not require reading one.

An SDK that already reads `POSTHOG_API_KEY` SHALL add `POSTHOG_PROJECT_TOKEN` and keep the old variable as a deprecated fallback in the same release, under the rules of "Deprecated project credential alias": the fallback resolves to the same value, is documented as deprecated naming `POSTHOG_PROJECT_TOKEN` as the replacement, and MAY be removed only in a major version released after the one that added the new name. `POSTHOG_PROJECT_TOKEN` SHALL win when both are set. A `POSTHOG_PROJECT_TOKEN` that is unset, empty, or only whitespace SHALL fall back as if it were unset, rather than initializing the SDK with a blank token.

An explicit token passed in code SHALL win over both variables.

#### Scenario: The project token environment variable configures the SDK
- **GIVEN** an SDK that reads the project token from the environment
- **AND** `POSTHOG_PROJECT_TOKEN` is set to "test-token"
- **WHEN** setup is called with no project token in code
- **THEN** the SDK should be initialized with project token "test-token"

#### Scenario: The deprecated variable is read only when the new one is blank
- **GIVEN** an SDK that reads the project token from the environment and still supports `POSTHOG_API_KEY`
- **AND** `POSTHOG_PROJECT_TOKEN` is set to " "
- **AND** `POSTHOG_API_KEY` is set to "old-token"
- **WHEN** setup is called with no project token in code
- **THEN** the SDK should be initialized with project token "old-token"

#### Scenario: The project token variable wins over the deprecated one
- **GIVEN** an SDK that reads the project token from the environment and still supports `POSTHOG_API_KEY`
- **AND** `POSTHOG_PROJECT_TOKEN` is set to "new-token"
- **AND** `POSTHOG_API_KEY` is set to "old-token"
- **WHEN** setup is called with no project token in code
- **THEN** the SDK should be initialized with project token "new-token"
Loading