diff --git a/openspec/changes/archive/2026-11-12-name-project-token-env-var/.openspec.yaml b/openspec/changes/archive/2026-11-12-name-project-token-env-var/.openspec.yaml new file mode 100644 index 00000000..55ab199b --- /dev/null +++ b/openspec/changes/archive/2026-11-12-name-project-token-env-var/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-11-12 diff --git a/openspec/changes/archive/2026-11-12-name-project-token-env-var/proposal.md b/openspec/changes/archive/2026-11-12-name-project-token-env-var/proposal.md new file mode 100644 index 00000000..a85b78ca --- /dev/null +++ b/openspec/changes/archive/2026-11-12-name-project-token-env-var/proposal.md @@ -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. diff --git a/openspec/changes/archive/2026-11-12-name-project-token-env-var/specs/setup/spec.md b/openspec/changes/archive/2026-11-12-name-project-token-env-var/specs/setup/spec.md new file mode 100644 index 00000000..dc4640de --- /dev/null +++ b/openspec/changes/archive/2026-11-12-name-project-token-env-var/specs/setup/spec.md @@ -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" diff --git a/openspec/changes/archive/2026-11-12-name-project-token-env-var/tasks.md b/openspec/changes/archive/2026-11-12-name-project-token-env-var/tasks.md new file mode 100644 index 00000000..2bcbe23e --- /dev/null +++ b/openspec/changes/archive/2026-11-12-name-project-token-env-var/tasks.md @@ -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 diff --git a/openspec/specs/setup/spec.md b/openspec/specs/setup/spec.md index 4328421e..7a2ba152 100644 --- a/openspec/specs/setup/spec.md +++ b/openspec/specs/setup/spec.md @@ -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"