chore: deprecate APIs that 4.0 hides or removes

.changeset/deprecate-apis-removed-in-v4.md

@@ -0,0 +1,21 @@
+---
+'posthog-ios': minor
+---
+
+Deprecate APIs that PostHog 4.0 hides or removes, and announce iOS 15 as the minimum iOS version in 4.0.
+
+Becoming SDK-internal in 4.0 (wrapper SDKs can keep using them by importing PostHog with `@_spi(PostHogInternal)`):
+
+- `PostHogSessionManager.shared` and `setSessionId(_:)`: use `PostHogSDK.getSessionId()`, `startSession()` and `endSession()`.
+- `dateToMillis(_:)` and `imageToBase64(_:_:)`
+
+Removed from the public API in 4.0:
+
+- `UIColor.hexDescription(_:)`
+
+These also change in 4.0 but show no deprecation warning in 3.x, because the SDK uses them internally:
+
+- Becoming SDK-internal: `postHogSdkName`, `postHogVersion`, `PostHogConfig.storageManager` and `PostHogConfig.snapshotEndpoint`.
+- Removed from the public API: `toISO8601String(_:)`, `toISO8601Date(_:)`, `sanitizeDictionary(_:)`, `deleteSafely(_:)`, `postHogiOSSdkName`, `UIColor.init(hex:)`, `Gzip`, `GzipError`, `CompressionLevel` and `ReachabilityError`.
+
+PostHog 4.0 raises the minimum iOS deployment target from 13.0 to 15.0. The macOS, tvOS, watchOS and visionOS minimums are unchanged.

PostHog/PostHogSessionManager.swift

@@ -24,6 +24,7 @@ import Foundation
     }
 
     /// Session manager used by `PostHogSDK.shared`.
+    @available(*, deprecated, message: "PostHogSessionManager becomes SDK-internal in PostHog 4.0. Use PostHogSDK.shared.getSessionId(), startSession() and endSession() instead. From 4.0, wrapper SDKs must import PostHog with @_spi(PostHogInternal) to use it.")
     @objc public static var shared: PostHogSessionManager {
         PostHogSDK.shared.sessionManager
     }
@@ -74,6 +75,7 @@ import Foundation
     /// Use with care: changing the session ID affects analytics session attribution and session replay.
     ///
     /// - Parameter sessionId: Session ID to use for subsequent events.
+    @available(*, deprecated, message: "PostHogSessionManager becomes SDK-internal in PostHog 4.0. Use PostHogSDK.shared.getSessionId(), startSession() and endSession() instead. From 4.0, wrapper SDKs must import PostHog with @_spi(PostHogInternal) to use it.")
     @objc public func setSessionId(_ sessionId: String) {
         setSessionIdInternal(sessionId, at: now(), reason: .customSessionId)
     }

PostHog/Replay/Date+Util.swift

@@ -17,6 +17,7 @@ extension Date {
 ///
 /// - Parameter date: Date to convert.
 /// - Returns: Milliseconds since 1970-01-01 00:00:00 UTC.
+@available(*, deprecated, message: "dateToMillis(_:) becomes SDK-internal in PostHog 4.0. Use Int64(date.timeIntervalSince1970 * 1000) instead. From 4.0, wrapper SDKs must import PostHog with @_spi(PostHogInternal) to use it.")
 public func dateToMillis(_ date: Date) -> Int64 {
     date.toMillis()
 }

PostHog/Replay/UIImage+Util.swift

@@ -37,6 +37,7 @@
     ///   - image: Image to encode.
     ///   - compressionQuality: Compression quality from `0.0` to `1.0`. Defaults to `0.3`.
     /// - Returns: A `data:image/...;base64` string, or `nil` if encoding fails.
+    @available(*, deprecated, message: "imageToBase64(_:_:) becomes SDK-internal in PostHog 4.0. From 4.0, wrapper SDKs must import PostHog with @_spi(PostHogInternal) to use it.")
     public func imageToBase64(_ image: UIImage, _ compressionQuality: CGFloat = 0.3) -> String? {
         image.toBase64(compressionQuality)
     }

PostHog/Surveys/Utils/Survey+Util.swift

@@ -71,6 +71,7 @@
 
          - Returns: A new `String` with the color's hexadecimal value.
          */
+        @available(*, deprecated, message: "UIColor.hexDescription(_:) is removed from the public API in PostHog 4.0.")
         func hexDescription(_ includeAlpha: Bool = false) -> String {
             guard cgColor.numberOfComponents == 4 else {
                 return "Color not RGB."