[turnipdabeets]

💡 Motivation and Context

Rename PostHogConfig.apiKey to projectToken, so KMP uses the same name as posthog-ios 4.0 and posthog-flutter. The iOS actual already calls PostHogConfig(projectToken:) (#87). Android/JVM still pass the value to posthog-android's apiKey. Only the KMP public API changes.

This ships alongside #89 in the same breaking 0.x release.

Caller code	After this PR
PostHogConfig("phc_...")	Compiles, no warning
PostHogConfig(projectToken = "phc_...")	New form
PostHogConfig(apiKey = "phc_...", ...)	Compiles with a deprecation warning (deprecated Companion.invoke with the same parameters)
config.apiKey	Compiles with a deprecation warning (ReplaceWith("projectToken"))
config.copy(apiKey = ...)	Breaks. Use copy(projectToken = ...)

• A deprecated copy(apiKey = ...) overload would clash with the generated copy on the JVM (same parameter types), so that call is the one source break.
• JVM binary compatibility holds: the constructor signatures are unchanged and getApiKey() still exists as a deprecated getter. The existing HIDDEN constructor and copy overloads stay as they are.
• The deprecation message matches posthog-flutter: "Deprecated in favor of projectToken. This will be removed in the next major version."

Docs follow-up: posthog.com contents/docs/libraries/kmp/index.mdx still uses apiKey at lines 89, 114, 136, 152, 166, 271, 501, 535, 566, 636, and in the config table at line 650. Those need a separate posthog.com PR.

💚 How did you test it?

• Added PostHogConfigTest.deprecatedApiKeyAliasesProjectToken. It checks that the deprecated factory builds the same config as projectToken and that apiKey reads it back.
• Ran these locally on macOS, and all passed: ./gradlew detekt :posthog-kmp:testAndroid :sample:androidApp:assembleDebug :posthog-kmp:jvmTest :posthog-kmp:jsTest :posthog-kmp:wasmJsBrowserTest :sample:wasmJsBrowserDistribution :posthog-kmp:iosSimulatorArm64Test :posthog-kmp:macosArm64Test, then ./gradlew build allTests.
• Compiled a test with the deprecation suppression removed. It showed warnings for PostHogConfig(apiKey = ...) and config.apiKey, and no warning for positional PostHogConfig("phc_...").

📝 Checklist

• I reviewed the submitted code.
• I added tests to verify the changes.
• I updated the docs if needed. (posthog.com follow-up listed above)
• No breaking change or entry added to the changelog.

If releasing new changes

• Ran pnpm change to generate a change intent file (written by hand in the same format: .changeset/project-token-rename.md)

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

• Claude Code made this change at the maintainer's direction. It started on chore!: raise minimum iOS deployment target to 15 #89's branch and was then split out into this PR.
• I chose a deprecated Companion.invoke factory over a secondary constructor. A constructor with an apiKey parameter and the same types would clash with the primary constructor. With the factory, the real constructor still wins resolution for positional and projectToken calls.

Follow-up once PostHog/posthog-android#835 is released

The Android and JVM actuals pass the token positionally (PostHog.android.kt:8, PostHog.jvm.kt:16), so they compile against the current pins and the release that deprecates apiKey, with no warning. After #835 ships:

• bump posthog-android (currently 3.66.0) and posthog-core (currently 6.38.0) in gradle/libs.versions.toml
• switch coreConfig.apiKey to coreConfig.projectToken in the JVM prefs file path (PostHog.jvm.kt:41). It's the same trimmed value, so existing prefs files are still found.

🤖 Generated with Claude Code

[sampo-s-bot]

⚠️ No changeset detected

No new .sampo/changesets/*.md files were detected in this PR. To add one:

• run sampo add
• follow the prompts to pick the affected packages and describe the change
• commit the generated file to this pull request, and it will be detected automatically

If this PR isn't supposed to introduce any changes (e.g., documentation updates), you can ignore this message.

[marandaneto]

The code looks good; no qualifying findings. Verdict: correct.

[marandaneto]

For clarity, config.copy(apiKey = "...") becomes a compilation error after updating; callers must use config.copy(projectToken = "..."). This is a source compatibility break, not a JVM binary compatibility break for already-compiled callers. Since the SDK is still below 1.0, this breaking change is acceptable, but it is worth making the migration explicit in the changeset. The current changeset already mentions the copy(apiKey = ...) exception; adding the replacement would make the required action clearer.