feat: deferred tracker install — queue events until trackers finish async init

[alirezat66]

You can copy each block below into a separate GitHub issue (title on the first line, body from the line after ---).

Issue 1 — copy from here
Title: feat: offline queue — persist & flush events when connectivity returns

Summary

Add an offline-capable event path: when the device has no network (or delivery to trackers is impossible), store events safely and send them when connectivity and policy allow.

Problem

• Events can be lost during offline / flaky networks if trackers fail synchronously or the pipeline does not buffer.
• Teams need predictable semantics for ordering, caps, and consent while queued.

Goals

• Durable best-effort delivery for eligible events (policy-driven).
• Bounded memory/disk usage with explicit overflow behavior.
• Clear interaction with consent, routing, and sampling on flush.

Non-goals (MVP)

• Full “analytics database” product; start with a small, auditable queue.

Acceptance criteria

• Offline capture: when offline (or “cannot reach trackers”), eligible track calls are queued instead of dropped (per documented policy).
• Online flush: when connectivity returns, queued items are processed in a documented order without deadlocks.
• Backpressure: max queue size / storage cap; overflow behavior is documented and tested (drop oldest / drop newest / sample / stop queueing — pick one and justify).
• Consent: behavior defined + tested when consent changes while events are queued (e.g. drop now-disallowed events).
• PII safety: events flagged as PII are handled per policy (e.g. never persisted unencrypted / never queued without consent — document).
• Tests: unit tests for queue + flush; at least one integration-style test with simulated connectivity.
• Docs: README section + CHANGELOG note (limits, platform caveats, storage expectations).

Notes / links

• Likely overlaps with deferred tracker initialization queueing — consider a shared internal “outbox” design.

---

Implementation hints (optional)

- Consider a pluggable **OutboxStore** (memory + optional persistent impl). - Consider reusing / aligning with any future “pre-init queue” from deferred setup.

Issue 2 — copy from here Title: feat: deferred tracker init — fast setup + queue until trackers are ready

Summary

Make initialization non-blocking for app startup: setup / FlexTrackClient.create returns quickly while trackers finish async installation in the background. Events emitted early are queued and delivered once trackers become ready (per policy).

Problem

• Heavy SDK initialization (Firebase, etc.) can block cold start and first-frame work.
• Early lifecycle events (first open, splash) are valuable and should not be dropped.

Goals

• Fast return from setup APIs by default (opt-in “await all inits” if needed).
• Ordered / deterministic delivery after readiness (document global vs per-tracker ordering).
• Failure handling for tracker init timeouts and partial readiness.

Non-goals (MVP)

• Parallel init micro-optimization beyond “don’t block the UI isolate unnecessarily”.

Acceptance criteria

• Non-blocking default: FlexTrack.setup / FlexTrackClient.create completes without awaiting all tracker initialize work unless an explicit flag/mode requests it.
• Early events retained: track calls before readiness are queued and later delivered to the correct trackers.
• Per-tracker failures: if one tracker fails init, behavior is defined (skip that tracker only vs fail all — document).
• Timeouts: init timeouts do not hang the queue forever; behavior is tested.
• Bounded queue: prevents unbounded growth if init never completes.
• Tests: slow mock init proves early track eventually reaches MockTracker.
• Docs: migration notes for code assuming “init finished before first track”.

Notes / links

• Likely shares design with offline queue — link issues and plan one outbox if possible.

---

API ideas (optional)

- `FlexTrackClient.whenReady` / readiness `Stream` - debug/inspector signal: “pending queue depth”