docs(config): clarify maxRetries scope

[dustinbyrne]

💡 Motivation and Context

Stacked on #788; companion clarification: PostHog/posthog-android#776.

Clarify that PostHogConfig.maxRetries controls push-subscription registration retries, with a default of 3. It does not limit event, replay, or log ingestion retries. Retryable ingestion failures retain queued records for later flush triggers, subject to backoff; capacity is controlled by maxQueueSize for events/replay and logs.maxBufferSize for logs.

The stack base already implements this behavior and includes its release notes. This PR clarifies the API documentation.

💚 How did you test it?

• make test — 172 XCTest/Quick tests and 769 Swift Testing tests passed, including configuration, queue retention, and push retry coverage.
• make format and make lint — passed.
• Checked that the net stack diff contains only API documentation.

Local tests ran on macOS; cross-platform validation is left to CI.

📝 Checklist

• Reviewed the submitted code.
• Updated API documentation.
• Preserved public declarations, defaults, and runtime behavior from the stack base.

🤖 Agent context

Autonomy: Human-driven (agent-assisted).

Implemented with Pi and reviewed by a fresh read-only Pi reviewer. Tooling: Git, GitHub CLI, and repository Makefile validation commands.

[greptile-apps]

Prompt To Fix All With AI

### Issue 1
PostHog/PostHogConfig.swift:97
**Push retries lack replacement**

`maxRetries` remains the only public control for push-subscription registration retries, but this change deprecates it without adding a push-specific replacement. Applications that need a non-default retry count—and the repository's compliance adapter—must accept a permanent compiler warning to preserve their existing push behavior. Please introduce a non-deprecated push retry setting before deprecating this shared property and include it in the migration guidance.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "chore(config): deprecate maxRetries" | Re-trigger Greptile}

[github-actions]

posthog-ios Compliance Report

Date: 2026-09-10 22:49:34 UTC
Duration: 227431ms

⚠️ Some Tests Failed

44/45 tests passed, 1 failed

---

Capture Tests

⚠️ 28/29 tests passed, 1 failed

View Details

Test	Status	Duration
Format Validation.Event Has Required Fields	✅	2931ms
Format Validation.Event Has Uuid	✅	2699ms
Format Validation.Event Has Lib Properties	✅	2799ms
Format Validation.Distinct Id Is String	✅	2688ms
Format Validation.Token Is Present	✅	2826ms
Format Validation.Custom Properties Preserved	✅	2684ms
Format Validation.Event Has Timestamp	✅	2848ms
Retry Behavior.Retries On 503	✅	11749ms
Retry Behavior.Does Not Retry On 400	✅	4808ms
Retry Behavior.Does Not Retry On 401	✅	4683ms
Retry Behavior.Respects Retry After Header	✅	7820ms
Retry Behavior.Implements Backoff	✅	15511ms
Retry Behavior.Retries On 500	✅	9373ms
Retry Behavior.Retries On 502	✅	9281ms
Retry Behavior.Retries On 504	✅	9237ms
Retry Behavior.Max Retries Respected	❌	21205ms
Deduplication.Generates Unique Uuids	✅	2917ms
Deduplication.Preserves Uuid On Retry	✅	9499ms
Deduplication.Preserves Uuid And Timestamp On Retry	✅	16674ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry	✅	7932ms
Deduplication.No Duplicate Events In Batch	✅	2884ms
Deduplication.Different Events Have Different Uuids	✅	2871ms
Compression.Sends Gzip When Enabled	✅	2695ms
Batch Format.Uses Proper Batch Structure	✅	2903ms
Batch Format.Flush With No Events Sends Nothing	✅	340ms
Batch Format.Multiple Events Batched Together	✅	2869ms
Error Handling.Does Not Retry On 403	✅	2432ms
Error Handling.Does Not Retry On 413	✅	4650ms
Error Handling.Retries On 408	✅	9332ms

Failures

retry_behavior.max_retries_respected

Expected 4 requests, got 6

Feature_Flags Tests

✅ 16/16 tests passed

View Details

Test	Status	Duration
Request Payload.Request With Person Properties Device Id	✅	2786ms
Request Payload.Flags Request Uses V2 Query Param	✅	2708ms
Request Payload.Flags Request Hits Flags Path Not Decide	✅	2845ms
Request Payload.Flags Request Omits Authorization Header	✅	2892ms
Request Payload.Token In Flags Body Matches Init	✅	2967ms
Request Payload.Groups Round Trip	✅	2849ms
Request Payload.Groups Default To Empty Object	✅	2758ms
Request Payload.Person Properties Distinct Id Auto Populated When Caller Omits It	✅	2848ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False	✅	2864ms
Request Payload.Disable Geoip Omitted Defaults To False	✅	2790ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key	✅	2767ms
Request Lifecycle.No Flags Request On Init Alone	✅	75ms
Request Lifecycle.No Flags Request On Normal Capture	✅	2822ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests	✅	5590ms
Request Lifecycle.Mock Response Value Is Returned To Caller	✅	2788ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event	✅	2838ms