feat!: send events through capture v1 and add captureAi

.changeset/v4-major-release.md

@@ -25,6 +25,19 @@ PostHog iOS 4.0: see the [migration guide](https://github.com/PostHog/posthog-io
 - **Breaking:** remove `PostHogDataMode.cellular` — use `.any`
 - **Breaking:** move `postHogSdkName`, `postHogVersion`, `PostHogConfig.snapshotEndpoint`, `PostHogSessionManager`, `PostHogStorageManager` and `PostHogConfig.storageManager` behind `@_spi(PostHogInternal)` — use `PostHogSDK` session and identity methods
 - **Breaking:** remove `dateToMillis(_:)`, `imageToBase64(_:_:)`, `toISO8601String(_:)`, `toISO8601Date(_:)`, `sanitizeDictionary(_:)`, `deleteSafely(_:)`, `postHogiOSSdkName`, `Gzip`, `GzipError`, `CompressionLevel`, `ReachabilityError`, `ReachabilityChangedNotification`, `UIColor.init(hex:)` and `UIColor.hexDescription(_:)` from the public API
+- **Breaking:** send analytics events to capture V1 (`/i/v1/analytics/events`) with the project token in an `Authorization: Bearer` header, replacing any `Authorization` from `requestHeaders` — serve this path on reverse proxies and self-hosted instances
+- **Breaking:** follow only 307 and 308 redirects to the same origin as `host`, at most 5 times, and drop events on any other redirect
+- **Breaking:** drop an event whose distinct ID is over 200 UTF-8 bytes instead of shortening the ID
+- **Breaking:** disable the SDK at setup when `projectToken` is a personal API key (`phx_...`) — use your project token (`phc_...`)
+- **Breaking:** pause sending for at most 30 seconds on `Retry-After`, including session replay and logs
+- **Breaking:** send `$process_person_profile`, `$cookieless_mode`, `$ignore_sent_at` and `$product_tour_id` as capture options, so PostHog drops an event whose option value it can't read
+- **Breaking:** let registered super properties override SDK properties such as `$os`, and let super and event properties override `$is_identified`, `$process_person_profile`, `$geoip_disable` and the session replay debug values
+- **Breaking:** rename `maxRetries` to `pushNotificationSubscriptionMaxRetries`
+- Add per-event capture options with `capture(..., timestamp:options:)` and `PostHogEvent.options`, also accepted by `screen`, `identify`, `setPersonProperties`, `alias`, `group` and `captureException`
+- Add `captureAi(...)` to send AI events such as `$ai_generation` to `/i/v1/ai/events`, tuned with `captureAiCompression`, `captureAiMaxQueueSize`, `captureAiTimeout` and `captureAiMaxEventBytes`
+- Change the wait after a failed send to double from 1 second up to 30 seconds with jitter, for events, session replay and logs
+- Cap analytics batches at 5 MiB per request and send a larger event on its own
+- Log the name, UUID and reason of each event PostHog drops when `debug` is on
 - Add `SessionReplay`, `CrashReporting` and `Surveys` Swift package traits (on by default) that remove the feature and its public API when turned off
 - Change network reachability detection to `NWPathMonitor`, so a path needing user action counts as reachable, queues pause while cellular data is off for the app, and early events may omit `$network_wifi` and `$network_cellular`
 - Change the replay screen name to the visible screen, reporting the view name for SwiftUI screens and no longer using a plain `UIViewController`'s `title`

PostHog.xcodeproj/project.pbxproj

@@ -106,6 +106,8 @@
 		6A0C1F2E3B4D5A6B7C8D9E02 /* PostHogOptOutPersistenceTest.swift in Sources */ = {isa = PBXBuildFile; fileRef = 6A0C1F2E3B4D5A6B7C8D9E01 /* PostHogOptOutPersistenceTest.swift */; };
 		A1C081010000000000000001 /* PostHogReplayBatchBoundaryTest.swift in Sources */ = {isa = PBXBuildFile; fileRef = A1C081010000000000000002 /* PostHogReplayBatchBoundaryTest.swift */; };
 		690FF0E92AEFD3BD00A0B06B /* PostHogQueueTest.swift in Sources */ = {isa = PBXBuildFile; fileRef = 690FF0E82AEFD3BD00A0B06B /* PostHogQueueTest.swift */; };
+		A1C0DE0000000000000000F2 /* PostHogCaptureV1Test.swift in Sources */ = {isa = PBXBuildFile; fileRef = A1C0DE0000000000000000F1 /* PostHogCaptureV1Test.swift */; };
+		A1C0DE00000000000000FAB2 /* PostHogWrapperEventTest.swift in Sources */ = {isa = PBXBuildFile; fileRef = A1C0DE00000000000000FAB1 /* PostHogWrapperEventTest.swift */; };
 		690FF0EF2AEFF23D00A0B06B /* OHHTTPStubsSwift in Frameworks */ = {isa = PBXBuildFile; productRef = 690FF0EE2AEFF23D00A0B06B /* OHHTTPStubsSwift */; };
 		690FF0F12AEFF24200A0B06B /* OHHTTPStubs in Frameworks */ = {isa = PBXBuildFile; productRef = 690FF0F02AEFF24200A0B06B /* OHHTTPStubs */; };
 		E1A0B0203A0D000100000001 /* CwlCatchException in Frameworks */ = {isa = PBXBuildFile; productRef = E1A0B0213A0D000100000001 /* CwlCatchException */; };
@@ -961,6 +963,8 @@
 		6A0C1F2E3B4D5A6B7C8D9E01 /* PostHogOptOutPersistenceTest.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PostHogOptOutPersistenceTest.swift; sourceTree = "<group>"; };
 		A1C081010000000000000002 /* PostHogReplayBatchBoundaryTest.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PostHogReplayBatchBoundaryTest.swift; sourceTree = "<group>"; };
 		690FF0E82AEFD3BD00A0B06B /* PostHogQueueTest.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PostHogQueueTest.swift; sourceTree = "<group>"; };
+		A1C0DE0000000000000000F1 /* PostHogCaptureV1Test.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PostHogCaptureV1Test.swift; sourceTree = "<group>"; };
+		A1C0DE00000000000000FAB1 /* PostHogWrapperEventTest.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PostHogWrapperEventTest.swift; sourceTree = "<group>"; };
 		690FF0F42AF0F06100A0B06B /* PostHogSDKTest.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PostHogSDKTest.swift; sourceTree = "<group>"; };
 		690FF1732AF3CE8A00A0B06B /* PostHogExampleWatchOS.xcodeproj */ = {isa = PBXFileReference; lastKnownFileType = "wrapper.pb-project"; name = PostHogExampleWatchOS.xcodeproj; path = PostHogExampleWatchOS/PostHogExampleWatchOS.xcodeproj; sourceTree = "<group>"; };
 		69261D122AD5685B00232EC7 /* PostHogRemoteConfig.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PostHogRemoteConfig.swift; sourceTree = "<group>"; };
@@ -1884,6 +1888,8 @@
 				DAA1B2D02F8C100000112233 /* RageClickDetectorTest.swift */,
 				DAA1B2D22F8C100000112233 /* PostHogRageClickIntegrationTest.swift */,
 				690FF0E82AEFD3BD00A0B06B /* PostHogQueueTest.swift */,
+				A1C0DE0000000000000000F1 /* PostHogCaptureV1Test.swift */,
+				A1C0DE00000000000000FAB1 /* PostHogWrapperEventTest.swift */,
 				A1C081010000000000000002 /* PostHogReplayBatchBoundaryTest.swift */,
 				690FF0F42AF0F06100A0B06B /* PostHogSDKTest.swift */,
 				5CA51F0E2B5C9A0100000002 /* PostHogScreenNameTest.swift */,
@@ -3786,6 +3792,8 @@
 				AE3C6A5B6DAB01EF554A0270 /* PostHogPushNotificationTest.swift in Sources */,
 				D36F92424A13D7CE61B6E348 /* PostHogSwizzlerTest.swift in Sources */,
 				690FF0E92AEFD3BD00A0B06B /* PostHogQueueTest.swift in Sources */,
+				A1C0DE0000000000000000F2 /* PostHogCaptureV1Test.swift in Sources */,
+				A1C0DE00000000000000FAB2 /* PostHogWrapperEventTest.swift in Sources */,
 				A1C081010000000000000001 /* PostHogReplayBatchBoundaryTest.swift in Sources */,
 				3AE3FB4B2993A68500AFFC18 /* PostHogStorageTest.swift in Sources */,
 				DAD39DF62D56178D002A1A69 /* UtilsTest.swift in Sources */,

PostHog/Models/PostHogEvent.swift

@@ -22,23 +22,63 @@ import Foundation
     /// Event properties that will be serialized with the event.
     @objc public var properties: [String: Any]
 
+    /// Options that tell PostHog how to process this event, separate from its properties.
+    ///
+    /// Holds the options passed to `capture(..., options:)`. Known keys are `process_person_profile`,
+    /// `cookieless_mode`, `disable_skew_correction` and `product_tour_id`; unknown keys are sent
+    /// unchanged and ignored by PostHog. When the event is sent, the legacy `$process_person_profile`, `$cookieless_mode`,
+    /// `$ignore_sent_at` and `$product_tour_id` properties are removed from `properties` and used
+    /// for their options, unless that option is set here.
+    @objc public var options: [String: Any]
+
     /// Event timestamp. The absolute instant is serialized in UTC, regardless of the calendar or
     /// time zone used to create it.
     @objc public var timestamp: Date
 
     /// Unique event identifier generated by the SDK.
-    @objc public private(set) var uuid: UUID
+    @objc public internal(set) var uuid: UUID
     // Only used for Replay.
     // Serialized as api_key on the wire.
     var projectToken: String?
 
     /// Set by the SDK when this event took the throttled replay debug bundle, so it survives `beforeSend` renames or replacement.
     var carriesReplayDebugBundle = false
 
-    init(event: String, distinctId: String, properties: [String: Any]? = nil, timestamp: Date = Date(), uuid: UUID = UUID.v7(), projectToken: String? = nil) {
+    /// The caller's person properties, kept from build to send so feature flags see them once the event is accepted.
+    var flagUserProperties: [String: Any]?
+    var flagUserPropertiesSetOnce: [String: Any]?
+
+    /// Set when a wrapper build returns this event: true for the AI lane. Cleared once it's sent, so it's sent once.
+    var wrapperAiLane: Bool?
+    /// The SDK's distinct ID when a wrapper built this event, so a send after `reset()` or `identify()`
+    /// doesn't give the new user this event's person properties for feature flags.
+    var wrapperBuildDistinctId: String?
+    /// The SDK's reset count when a wrapper built this event, so a `reset()` that keeps the distinct ID
+    /// (`reuseAnonymousId`) still counts as a new identity at send.
+    var wrapperBuildResetGeneration: Int?
+    /// The SDK instance and setup generation that built this wrapper event, so a send after `close()`/`setup()`
+    /// or on another instance is dropped instead of sent with the new configuration.
+    var wrapperBuildSDK: ObjectIdentifier?
+    var wrapperBuildSetupGeneration: Int?
+    /// The optional replay debug values snapshotted when a wrapper built this event, set only when its built name
+    /// is eligible. Send adds them if it claims the throttled window.
+    var wrapperDeferredReplayDebug: [String: Any]?
+    /// True when a wrapper build passed person properties or groups. Person processing turns on at send.
+    var wrapperRequiresPersonProcessing = false
+
+    init(
+        event: String,
+        distinctId: String,
+        properties: [String: Any]? = nil,
+        options: [String: Any]? = nil,
+        timestamp: Date = Date(),
+        uuid: UUID = UUID.v7(),
+        projectToken: String? = nil
+    ) {
         self.event = event
         self.distinctId = distinctId
         self.properties = properties ?? [:]
+        self.options = options ?? [:]
         self.timestamp = timestamp
         self.uuid = uuid
         self.projectToken = projectToken
@@ -75,6 +115,8 @@ import Foundation
             event: event,
             distinctId: distinctId,
             properties: properties,
+            // Events queued by older versions have no options.
+            options: json["options"] as? [String: Any],
             timestamp: timestampDate,
             uuid: uuidObj,
             projectToken: projectToken
@@ -90,6 +132,11 @@ import Foundation
             "uuid": uuid.postHogUuidString,
         ]
 
+        // Stored for the queue only: each endpoint shapes its own wire format.
+        if !options.isEmpty {
+            json["options"] = options
+        }
+
         if let projectToken {
             // Wire field name remains api_key, but it carries the PostHog project token.
             json["api_key"] = projectToken