feat!: remove the /batch fallback from capture V1

[turnipdabeets]

💡 Motivation and Context

Stacked on #939 (captureAi) and #938. Removes the iOS-only /batch fallback so analytics events only go to capture V1 (/i/v1/analytics/events), matching posthog-python 8.0, posthog-go 2.0 and posthog-rs 1.0. #938 kept the fallback as a removable piece so we can decide separately whether 4.0 keeps it: merge this PR to drop it, or close it to keep it.

• A V1 404 is now terminal like any other non-retriable status: the batch is dropped, not resent to /batch.
• Removes PostHogApi.batch(events:), the per-session "V1 unavailable" flag, the /batch retry policy for events and the options-to-legacy-properties fold-back.
• /snapshot keeps its own retry policy, unchanged.
• The changeset bullet about reverse proxies now says self-hosted instances must serve /i/v1/analytics/events.

Trade-off: a self-hosted instance or reverse proxy that doesn't serve the V1 route drops events until it serves that route, with no client-side fallback for apps already installed.

💚 How did you test it?

• Replaced the fallback tests with one that checks a 404 is terminal and every later batch still goes to V1.
• Moved the /batch endpoint-path, gzip and custom-header tests in PostHogApiTest to capture V1.
• After rebasing onto captureAi: make lint passes; make test ran 1155 tests and only the 13 known group-container PostHogStorageTest failures ("Operation not permitted" locally) failed.
• sendSendsNewTokenAfterDelivery failed once in an earlier full run but passed 8/8 alone on this branch and 5/5 on the base; it polls with timeouts and doesn't touch capture.
• Not run locally: make buildSdk (xcpretty missing).

📝 Checklist

• I reviewed the submitted code.
• I added tests to verify the changes.
• I updated the docs if needed.
• No breaking change or entry added to the changelog.

If releasing new changes

• Ran pnpm changeset to generate a changeset file (updated .changeset/v4-capture-v1.md)

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Built with Claude Code as a stacked follow-up to #938.

🤖 Generated with Claude Code

[github-actions]

posthog-ios Compliance Report

Date: 2026-10-10 17:36:46 UTC
Duration: 464175ms

⚠️ Some Tests Failed

107/110 tests passed, 3 failed

---

Capture_V1 Tests

⚠️ 91/94 tests passed, 3 failed

View Details

Test	Status	Duration
Endpoint And Method.Targets V1 Endpoint	✅	2698ms
Endpoint And Method.Does Not Use Legacy Endpoints	✅	2690ms
Required Headers.Has Authorization Bearer Header	✅	2766ms
Required Headers.Has Content Type Json	✅	367ms
Required Headers.Has Posthog Sdk Info Format	✅	2741ms
Required Headers.Has Posthog Attempt Header	✅	2752ms
Required Headers.Has Posthog Request Id	✅	2778ms
Required Headers.Has Posthog Request Timestamp	✅	2762ms
Required Headers.Has User Agent	✅	2766ms
Body Format.Body Has Created At And Batch	✅	2770ms
Body Format.No Api Key In Body	✅	2672ms
Body Format.No Sent At In Body	✅	2657ms
Event Format.Event Has Required Root Fields	✅	2729ms
Event Format.Event Uuid Is Valid	✅	2707ms
Event Format.Event Timestamp Is Rfc3339	✅	2704ms
Event Format.Distinct Id Is String	✅	2758ms
Event Format.Distinct Id At Root Not Properties	✅	336ms
Event Format.Custom Properties Preserved	✅	2759ms
Event Format.Set Properties Preserved	✅	2748ms
Event Format.Set Once Properties Preserved	✅	2660ms
Event Format.Groups Properties Preserved	✅	2718ms
Event Format.Sdk Generates Uuid If Not Provided	✅	2725ms
Event Format.Event Has Required Root Fields Batch	✅	314ms
Event Format.Event Uuid Is Valid Batch	✅	2809ms
Event Format.Event Timestamp Is Rfc3339 Batch	✅	2791ms
Event Format.Distinct Id Is String Batch	✅	2709ms
Event Format.Distinct Id At Root Not Properties Batch	✅	2751ms
Event Format.Custom Properties Preserved Batch	✅	415ms
Event Format.Set Properties Preserved Batch	✅	2760ms
Event Format.Set Once Properties Preserved Batch	✅	2686ms
Event Format.Groups Properties Preserved Batch	✅	2800ms
Event Format.Sdk Generates Uuid If Not Provided Batch	✅	2742ms
Batch Behavior.Multiple Events In Single Batch	✅	2712ms
Batch Behavior.Batch Envelope Smoke	✅	2767ms
Batch Behavior.Flush With No Events Sends Nothing	✅	212ms
Batch Behavior.Flush At Triggers Batch	✅	1133ms
Batch Behavior.Created At Reflects Batch Creation Time	✅	2770ms
Deduplication.Generates Unique Uuids	✅	2876ms
Deduplication.Different Events Same Content Different Uuids	✅	2754ms
Deduplication.Preserves Uuid On Retry	✅	8868ms
Deduplication.Preserves Timestamp On Retry	✅	8812ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry	✅	7688ms
Deduplication.No Duplicate Events In Batch	✅	2859ms
Header Behavior On Retry.Attempt Header Starts At One	✅	266ms
Header Behavior On Retry.Attempt Header Increments On Retry	✅	16764ms
Header Behavior On Retry.Request Id Preserved On Retry	✅	5236ms
Header Behavior On Retry.Different Requests Have Different Request Ids	✅	5028ms
Header Behavior On Retry.Request Timestamp Changes On Retry	✅	9276ms
Response Format Validation.Success Response Has Uuid Keyed Results	✅	2661ms
Response Format Validation.Success Response Has Ok For Each Event	✅	2660ms
Response Format Validation.Success No Retry After When All Ok	✅	2739ms
Response Format Validation.Success Retry After Present When Retry Events	✅	2800ms
Response Format Validation.Success No Retry After When Drop Only	✅	2744ms
Response Format Validation.Response Echoes Request Id	✅	2700ms
Retry Behavior.Retries On 408	✅	8771ms
Retry Behavior.Retries On 500	✅	8749ms
Retry Behavior.Retries On 503	✅	11628ms
Retry Behavior.Retries On 504	✅	8856ms
Retry Behavior.Retryable Errors Have Retry After	✅	2268ms
Retry Behavior.Respects Retry After On Retryable Error	✅	10740ms
Retry Behavior.Does Not Retry On 400	✅	4721ms
Retry Behavior.Does Not Retry On 401	✅	4772ms
Retry Behavior.Does Not Retry On 402	✅	4668ms
Retry Behavior.Does Not Retry On 413	✅	4768ms
Retry Behavior.Does Not Retry On 415	✅	4630ms
Retry Behavior.Non Retryable Errors Have No Retry After	✅	2370ms
Retry Behavior.Implements Backoff	✅	21636ms
Retry Behavior.Max Retries Respected	❌	21308ms
Partial Batch Handling.Handles 200 Full Success	✅	4634ms
Partial Batch Handling.Handles 200 With All Ok	✅	5683ms
Partial Batch Handling.Does Not Retry Dropped Events	✅	5849ms
Partial Batch Handling.Does Not Retry Limited Events	✅	5753ms
Partial Batch Handling.Prunes Ok Events On Partial Retry	✅	7644ms
Partial Batch Handling.Prunes Dropped Events On Partial Retry	✅	7753ms
Partial Batch Handling.Retries Only Retry Events From Partial	✅	7832ms
Partial Batch Handling.Partial Retry Preserves Uuids	✅	7808ms
Partial Batch Handling.Partial Retry Attempt Header Increments	✅	7682ms
Partial Batch Handling.Partial Retry Request Id Preserved	✅	7748ms
Partial Batch Handling.Respects Retry After On Partial	✅	7846ms
Partial Batch Handling.Unknown Result Treated As Terminal	✅	5794ms
Partial Batch Handling.Mixed Ok Drop Limited No Retry	✅	5733ms
Compression.Sends Gzip Content Encoding	✅	2742ms
Compression.No Content Encoding When Disabled	✅	2762ms
Compression.Compressed Body Is Decompressible	✅	2799ms
Error Handling.Does Not Retry On Unknown 4Xx	✅	4755ms
Event Options.Cookieless Mode Override	✅	2685ms
Event Options.Disable Skew Correction Override	✅	2754ms
Event Options.Process Person Profile Override	✅	2764ms
Event Options.Product Tour Id Override	✅	2758ms
Event Options.Unset Options Omitted	❌	2742ms
Event Options.Options Override In Batch	✅	2804ms
Geoip And Historical Migration.Geoip Disable Injected Into Properties	✅	2696ms
Geoip And Historical Migration.Historical Migration Set In Body	❌	2657ms
Geoip And Historical Migration.Historical Migration Absent By Default	✅	2697ms

Failures

retry_behavior.max_retries_respected

Expected 4 requests, got 6

event_options.unset_options_omitted

Event option 'process_person_profile' should be absent, but options={'process_person_profile': False}

geoip_and_historical_migration.historical_migration_set_in_body

Body missing 'historical_migration' field. Body keys: ['batch', 'created_at']

Feature_Flags Tests

✅ 16/16 tests passed

View Details

Test	Status	Duration
Request Payload.Request With Person Properties Device Id	✅	2768ms
Request Payload.Flags Request Uses V2 Query Param	✅	2705ms
Request Payload.Flags Request Hits Flags Path Not Decide	✅	2644ms
Request Payload.Flags Request Omits Authorization Header	✅	2819ms
Request Payload.Token In Flags Body Matches Init	✅	2779ms
Request Payload.Groups Round Trip	✅	2687ms
Request Payload.Groups Default To Empty Object	✅	2758ms
Request Payload.Person Properties Distinct Id Auto Populated When Caller Omits It	✅	2808ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False	✅	2738ms
Request Payload.Disable Geoip Omitted Defaults To False	✅	2762ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key	✅	2635ms
Request Lifecycle.No Flags Request On Init Alone	✅	65ms
Request Lifecycle.No Flags Request On Normal Capture	✅	2774ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests	✅	5290ms
Request Lifecycle.Mock Response Value Is Returned To Caller	✅	2735ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event	✅	2933ms