feat!: rename PostHogConfig.apiKey to projectToken

.changeset/project-token-rename.md

@@ -0,0 +1,5 @@
+---
+"posthog-kmp": minor
+---
+
+**Breaking:** rename `PostHogConfig.apiKey` to `projectToken`; `apiKey` still compiles with a deprecation warning, but `copy(apiKey = ...)` must change to `copy(projectToken = ...)`

posthog-kmp/src/androidHostTest/kotlin/com/posthog/kmp/PostHogAndroidTest.kt

@@ -145,7 +145,7 @@ class PostHogAndroidTest {
 
     @Test
     fun testSendFeatureFlagEventFallsBackToConfig() {
-        currentConfig = PostHogConfig(apiKey = "key", sendFeatureFlagEvent = false)
+        currentConfig = PostHogConfig(projectToken = "key", sendFeatureFlagEvent = false)
 
         PostHog.isFeatureEnabled("test_flag")
         assertMethodCalled("isFeatureEnabled", "test_flag", false, false)

posthog-kmp/src/androidMain/kotlin/com/posthog/kmp/PostHog.android.kt

@@ -5,10 +5,7 @@ import com.posthog.android.PostHogAndroidConfig
 import com.posthog.android.replay.PostHogSessionReplayConfig
 
 internal actual fun platformSetup(config: PostHogConfig, context: PostHogContext) {
-    val androidConfig = PostHogAndroidConfig(
-        apiKey = config.apiKey,
-        host = config.host
-    ).apply {
+    val androidConfig = PostHogAndroidConfig(config.projectToken, config.host).apply {
         sdkName = SDK_NAME
         sdkVersion = PostHogKmpVersion.VERSION
 

posthog-kmp/src/appleMain/kotlin/com/posthog/kmp/PostHog.apple.kt

@@ -27,7 +27,7 @@ import swiftPMImport.com.posthog.posthog.kmp.PostHogSDK
 
 @Suppress("UNUSED_PARAMETER")
 internal actual fun platformSetup(config: PostHogConfig, context: PostHogContext) {
-    val nativeConfig = NativePostHogConfig(projectToken = config.apiKey, host = config.host).apply {
+    val nativeConfig = NativePostHogConfig(projectToken = config.projectToken, host = config.host).apply {
         debug = config.debug
         captureApplicationLifecycleEvents = config.captureApplicationLifecycleEvents
         captureScreenViews = config.captureScreenViews

posthog-kmp/src/appleTest/kotlin/com/posthog/kmp/PostHogAppleTest.kt

@@ -17,7 +17,7 @@ class PostHogAppleTest {
         val events = mutableListOf<PostHogEvent>()
         PostHog.setup(
             PostHogConfig(
-                apiKey = "apple-unit-test",
+                projectToken = "apple-unit-test",
                 host = "http://127.0.0.1:9",
                 preloadFeatureFlags = false,
                 captureApplicationLifecycleEvents = false,

posthog-kmp/src/commonMain/kotlin/com/posthog/kmp/PostHog.kt

@@ -11,7 +11,7 @@ import kotlin.concurrent.Volatile
  *
  * ```kotlin
  * // Initialize PostHog
- * PostHog.setup(PostHogConfig(apiKey = "phc_your_api_key"), PostHogContext())
+ * PostHog.setup(PostHogConfig(projectToken = "phc_your_project_token"), PostHogContext())
  *
  * // Capture events
  * PostHog.capture("button_clicked", mapOf("button_name" to "submit"))

posthog-kmp/src/commonMain/kotlin/com/posthog/kmp/PostHogConfig.kt

@@ -5,7 +5,9 @@ import kotlin.reflect.KClass
 /**
  * Configuration options for PostHog SDK initialization.
  *
- * @property apiKey Your PostHog project API key (required)
+ * @property projectToken Your PostHog project token (required), which starts with `phc_`.
+ *   Find it in your project settings: https://us.posthog.com/settings/project-details#variables.
+ *   Formerly named `apiKey`. Example: `PostHogConfig(projectToken = "phc_your_project_token")`.
  * @property host PostHog instance URL (defaults to US cloud)
  * @property debug Enable debug logging
  * @property captureApplicationLifecycleEvents Automatically capture app lifecycle events
@@ -25,7 +27,7 @@ import kotlin.reflect.KClass
  * @property errorTracking Error tracking configuration (platform dependent)
  */
 public data class PostHogConfig(
-    val apiKey: String,
+    val projectToken: String,
     val host: String = "https://us.i.posthog.com",
     val debug: Boolean = false,
     val captureApplicationLifecycleEvents: Boolean = true,
@@ -64,7 +66,7 @@ public data class PostHogConfig(
         autocapture: Boolean = false,
         beforeSend: List<PostHogBeforeSend> = emptyList()
     ) : this(
-        apiKey = apiKey,
+        projectToken = apiKey,
         host = host,
         debug = debug,
         captureApplicationLifecycleEvents = captureApplicationLifecycleEvents,
@@ -103,7 +105,7 @@ public data class PostHogConfig(
         sessionRecording: SessionRecordingConfig? = null,
         autocapture: Boolean = false
     ) : this(
-        apiKey = apiKey,
+        projectToken = apiKey,
         host = host,
         debug = debug,
         captureApplicationLifecycleEvents = captureApplicationLifecycleEvents,
@@ -125,7 +127,7 @@ public data class PostHogConfig(
 
     @Deprecated("Retained for binary compatibility", level = DeprecationLevel.HIDDEN)
     public fun copy(
-        apiKey: String = this.apiKey,
+        apiKey: String = this.projectToken,
         host: String = this.host,
         debug: Boolean = this.debug,
         captureApplicationLifecycleEvents: Boolean = this.captureApplicationLifecycleEvents,
@@ -143,7 +145,7 @@ public data class PostHogConfig(
         autocapture: Boolean = this.autocapture,
         beforeSend: List<PostHogBeforeSend> = this.beforeSend
     ): PostHogConfig = PostHogConfig(
-        apiKey = apiKey,
+        projectToken = apiKey,
         host = host,
         debug = debug,
         captureApplicationLifecycleEvents = captureApplicationLifecycleEvents,
@@ -165,7 +167,7 @@ public data class PostHogConfig(
 
     @Deprecated("Retained for binary compatibility", level = DeprecationLevel.HIDDEN)
     public fun copy(
-        apiKey: String = this.apiKey,
+        apiKey: String = this.projectToken,
         host: String = this.host,
         debug: Boolean = this.debug,
         captureApplicationLifecycleEvents: Boolean = this.captureApplicationLifecycleEvents,
@@ -182,7 +184,7 @@ public data class PostHogConfig(
         sessionRecording: SessionRecordingConfig? = this.sessionRecording,
         autocapture: Boolean = this.autocapture
     ): PostHogConfig = PostHogConfig(
-        apiKey = apiKey,
+        projectToken = apiKey,
         host = host,
         debug = debug,
         captureApplicationLifecycleEvents = captureApplicationLifecycleEvents,
@@ -202,12 +204,63 @@ public data class PostHogConfig(
         errorTracking = errorTracking
     )
 
+    /** Deprecated alias for [projectToken]. */
+    @Deprecated(
+        "Deprecated in favor of projectToken. This will be removed in the next major version.",
+        ReplaceWith("projectToken")
+    )
+    val apiKey: String get() = projectToken
+
     public companion object {
         /** PostHog US Cloud instance */
         public const val HOST_US: String = "https://us.i.posthog.com"
 
         /** PostHog EU Cloud instance */
         public const val HOST_EU: String = "https://eu.i.posthog.com"
+
+        /** Deprecated named-argument form of the [PostHogConfig] constructor that takes `apiKey`. */
+        @Deprecated(
+            "Deprecated in favor of projectToken. This will be removed in the next major version."
+        )
+        public operator fun invoke(
+            apiKey: String,
+            host: String = "https://us.i.posthog.com",
+            debug: Boolean = false,
+            captureApplicationLifecycleEvents: Boolean = true,
+            captureScreenViews: Boolean = false,
+            captureDeepLinks: Boolean = true,
+            sendFeatureFlagEvent: Boolean = true,
+            preloadFeatureFlags: Boolean = true,
+            flushAt: Int = 20,
+            flushIntervalSeconds: Int = 30,
+            maxQueueSize: Int = 1000,
+            maxBatchSize: Int = 50,
+            optOut: Boolean = false,
+            personProfiles: PersonProfiles = PersonProfiles.IDENTIFIED_ONLY,
+            sessionRecording: SessionRecordingConfig? = null,
+            autocapture: Boolean = false,
+            beforeSend: List<PostHogBeforeSend> = emptyList(),
+            errorTracking: ErrorTrackingConfig? = null
+        ): PostHogConfig = PostHogConfig(
+            projectToken = apiKey,
+            host = host,
+            debug = debug,
+            captureApplicationLifecycleEvents = captureApplicationLifecycleEvents,
+            captureScreenViews = captureScreenViews,
+            captureDeepLinks = captureDeepLinks,
+            sendFeatureFlagEvent = sendFeatureFlagEvent,
+            preloadFeatureFlags = preloadFeatureFlags,
+            flushAt = flushAt,
+            flushIntervalSeconds = flushIntervalSeconds,
+            maxQueueSize = maxQueueSize,
+            maxBatchSize = maxBatchSize,
+            optOut = optOut,
+            personProfiles = personProfiles,
+            sessionRecording = sessionRecording,
+            autocapture = autocapture,
+            beforeSend = beforeSend,
+            errorTracking = errorTracking
+        )
     }
 }
 

posthog-kmp/src/commonTest/kotlin/com/posthog/kmp/PostHogConfigTest.kt

@@ -11,17 +11,26 @@ class PostHogConfigTest {
 
     @Test
     fun defaultsToUsCloudHost() {
-        assertEquals(PostHogConfig.HOST_US, PostHogConfig(apiKey = "phc_test").host)
+        assertEquals(PostHogConfig.HOST_US, PostHogConfig(projectToken = "phc_test").host)
+    }
+
+    @Suppress("DEPRECATION")
+    @Test
+    fun deprecatedApiKeyAliasesProjectToken() {
+        val config = PostHogConfig(apiKey = "phc_test")
+
+        assertEquals(PostHogConfig(projectToken = "phc_test"), config)
+        assertEquals("phc_test", config.apiKey)
     }
 
     @Test
     fun defaultsToIdentifiedOnlyPersonProfiles() {
-        assertEquals(PersonProfiles.IDENTIFIED_ONLY, PostHogConfig(apiKey = "phc_test").personProfiles)
+        assertEquals(PersonProfiles.IDENTIFIED_ONLY, PostHogConfig(projectToken = "phc_test").personProfiles)
     }
 
     @Test
     fun defaultsErrorTrackingToNull() {
-        assertNull(PostHogConfig(apiKey = "phc_test").errorTracking)
+        assertNull(PostHogConfig(projectToken = "phc_test").errorTracking)
     }
 
     @Test
@@ -43,7 +52,7 @@ class PostHogConfigTest {
             inAppExcludes = listOf("ThirdParty"),
             inAppByDefault = false
         )
-        val config = PostHogConfig(apiKey = "phc_test", errorTracking = errorTracking)
+        val config = PostHogConfig(projectToken = "phc_test", errorTracking = errorTracking)
 
         assertEquals(errorTracking, config.copy(debug = true).errorTracking)
     }
@@ -61,14 +70,14 @@ class PostHogConfigTest {
     @Test
     fun beforeSendWithoutCallbacksPreservesEvent() {
         val event = PostHogEvent("checkout", "user-1", mapOf("plan" to "paid"))
-        val config = PostHogConfig(apiKey = "key")
+        val config = PostHogConfig(projectToken = "key")
         assertSame(event, config.runBeforeSend(event))
     }
 
     @Test
     fun beforeSendCallbacksRunInOrder() {
         val config = PostHogConfig(
-            apiKey = "phc_test",
+            projectToken = "phc_test",
             beforeSend = listOf(
                 PostHogBeforeSend { it.copy(properties = it.properties + ("first" to true)) },
                 PostHogBeforeSend {
@@ -85,7 +94,7 @@ class PostHogConfigTest {
     @Test
     fun copyPreservesBeforeSendCallbacks() {
         val callback = PostHogBeforeSend { it }
-        val config = PostHogConfig(apiKey = "phc_test", beforeSend = listOf(callback))
+        val config = PostHogConfig(projectToken = "phc_test", beforeSend = listOf(callback))
 
         val copy = config.copy(debug = true)
 
@@ -98,7 +107,7 @@ class PostHogConfigTest {
         var sentinelCalled = false
         val failure = IllegalStateException("failed")
         val config = PostHogConfig(
-            apiKey = "phc_test",
+            projectToken = "phc_test",
             beforeSend = listOf(
                 PostHogBeforeSend { it.copy(event = "transformed") },
                 PostHogBeforeSend { throw failure },
@@ -123,7 +132,7 @@ class PostHogConfigTest {
     fun beforeSendStopsAfterDroppedEvent() {
         var finalCallbackCalled = false
         val config = PostHogConfig(
-            apiKey = "phc_test",
+            projectToken = "phc_test",
             beforeSend = listOf(
                 PostHogBeforeSend { null },
                 PostHogBeforeSend {

posthog-kmp/src/jsMain/kotlin/com/posthog/kmp/PostHog.js.kt

@@ -69,7 +69,7 @@ internal actual fun platformSetup(config: PostHogConfig, context: PostHogContext
     // advanced_disable_feature_flags (without _on_first_load) would disable flag evaluation permanently
     options["advanced_disable_feature_flags_on_first_load"] = !config.preloadFeatureFlags
 
-    PostHogJs.init(config.apiKey, options)
+    PostHogJs.init(config.projectToken, options)
 
     val instance: dynamic = PostHogJs
     if (instance._overrideSDKInfo != null) {

posthog-kmp/src/jsTest/kotlin/com/posthog/kmp/PostHogJsTest.kt

@@ -292,7 +292,7 @@ class PostHogJsTest {
 
     @Test
     fun testSendFeatureFlagEventFallsBackToConfig() {
-        currentConfig = PostHogConfig(apiKey = "key", sendFeatureFlagEvent = false)
+        currentConfig = PostHogConfig(projectToken = "key", sendFeatureFlagEvent = false)
 
         PostHog.getFeatureFlag("test_flag")
         val call = getCall("getFeatureFlag")
@@ -308,7 +308,7 @@ class PostHogJsTest {
         fakeJs.init = { apiKey: String, options: dynamic ->
             calledMethods.add("init" to arrayOf<dynamic>(apiKey, options))
         }
-        PostHog.setup(PostHogConfig(apiKey = "key", preloadFeatureFlags = false), PostHogContext())
+        PostHog.setup(PostHogConfig(projectToken = "key", preloadFeatureFlags = false), PostHogContext())
 
         val call = getCall("init")
         assertEquals("key", call[0] as String)
@@ -323,7 +323,7 @@ class PostHogJsTest {
             calledMethods.add("init" to arrayOf<dynamic>(apiKey, options))
         }
         PostHog.setup(
-            PostHogConfig(apiKey = "key", errorTracking = ErrorTrackingConfig(autoCapture = true)),
+            PostHogConfig(projectToken = "key", errorTracking = ErrorTrackingConfig(autoCapture = true)),
             PostHogContext()
         )
 
@@ -337,7 +337,7 @@ class PostHogJsTest {
         }
         PostHog.setup(
             PostHogConfig(
-                apiKey = "key",
+                projectToken = "key",
                 beforeSend = listOf(
                     PostHogBeforeSend {
                         it.copy(
@@ -378,7 +378,7 @@ class PostHogJsTest {
         }
         PostHog.setup(
             PostHogConfig(
-                apiKey = "key",
+                projectToken = "key",
                 beforeSend = listOf(
                     PostHogBeforeSend { it.copy(event = "transformed") },
                     PostHogBeforeSend { throw IllegalStateException("failed") },
@@ -405,7 +405,7 @@ class PostHogJsTest {
             calledMethods.add("init" to arrayOf<dynamic>(options))
         }
         PostHog.setup(
-            PostHogConfig(apiKey = "key", beforeSend = listOf(PostHogBeforeSend {
+            PostHogConfig(projectToken = "key", beforeSend = listOf(PostHogBeforeSend {
                 callbackCalled = true
                 it
             })),

posthog-kmp/src/jvmMain/kotlin/com/posthog/kmp/PostHog.jvm.kt

@@ -13,10 +13,7 @@ import java.io.File
  */
 @Suppress("UNUSED_PARAMETER")
 internal actual fun platformSetup(config: PostHogConfig, context: PostHogContext) {
-    val coreConfig = com.posthog.PostHogConfig(
-        apiKey = config.apiKey,
-        host = config.host
-    ).apply {
+    val coreConfig = com.posthog.PostHogConfig(config.projectToken, config.host).apply {
         sdkName = SDK_NAME
         sdkVersion = PostHogKmpVersion.VERSION
 

posthog-kmp/src/jvmTest/kotlin/com/posthog/kmp/PostHogFilePreferencesTest.kt

@@ -13,7 +13,7 @@ import kotlin.test.assertTrue
 
 class PostHogFilePreferencesTest {
 
-    private val config = com.posthog.PostHogConfig(apiKey = "test-key")
+    private val config = com.posthog.PostHogConfig("test-key")
 
     @get:Rule
     val tempFolder = TemporaryFolder()
@@ -125,7 +125,7 @@ class PostHogFilePreferencesTest {
     fun writeFailurePreservesInMemoryStateAndLogsWarning() {
         val parent = tempFolder.newFile()
         val warnings = mutableListOf<String>()
-        val failingConfig = com.posthog.PostHogConfig(apiKey = "key").apply {
+        val failingConfig = com.posthog.PostHogConfig("key").apply {
             logger = object : com.posthog.internal.PostHogLogger {
                 override fun log(message: String) {
                     warnings.add(message)