From 05624fca97b2f2c7daa91bbe9b2e2a7ed72b074e Mon Sep 17 00:00:00 2001 From: "posthog[bot]" <206114724+posthog[bot]@users.noreply.github.com> Date: Thu, 12 Nov 2026 07:04:10 +0000 Subject: [PATCH] feat(setup): name the project token environment variable The setup spec settles the project token's name on every configuration surface it names, but not on the environment variable an SDK reads when it is initialized without an explicit token. posthog-php now reads POSTHOG_PROJECT_TOKEN with POSTHOG_API_KEY as a deprecated fallback, and @posthog/mcp reads POSTHOG_PROJECT_TOKEN, while posthog-rs and the posthog-rails logs setup read only POSTHOG_API_KEY. Pin POSTHOG_PROJECT_TOKEN as the name, keep POSTHOG_API_KEY as a deprecated fallback under the existing alias rules, and treat a blank value as unset. Tested: openspec validate setup --type spec --strict (no errors; pre-existing length warnings only), then openspec archive. Co-Authored-By: Claude Opus 5 Generated-By: PostHog Desktop Task-Id: 3ed34237-1d4d-4d16-b517-7f4622b1c9f5 --- .../.openspec.yaml | 2 + .../proposal.md | 42 +++++++++++++++++++ .../specs/setup/spec.md | 29 +++++++++++++ .../tasks.md | 14 +++++++ openspec/specs/setup/spec.md | 28 +++++++++++++ 5 files changed, 115 insertions(+) create mode 100644 openspec/changes/archive/2026-11-12-name-project-token-env-var/.openspec.yaml create mode 100644 openspec/changes/archive/2026-11-12-name-project-token-env-var/proposal.md create mode 100644 openspec/changes/archive/2026-11-12-name-project-token-env-var/specs/setup/spec.md create mode 100644 openspec/changes/archive/2026-11-12-name-project-token-env-var/tasks.md 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"