feat(observability): route PostHog through magic-observability and unblock OTA sourcemaps

[GSTJ]

📝 DESCRIPTION:

Two things, both PostHog.

1. The three clients become one

apps/mobile and packages/api had each hand-rolled their own PostHog wiring and reached different answers to the same questions; apps/nextjs had nothing. magic-observability is pegada's own shape, generalised across the GSTJ repos, so all three now share one client surface, one captureError, and one error boundary that works on React and React Native.

apps/mobile (magic-observability/expo)

• services/posthog.ts → services/observability.ts, built with initExpo. Same standalone-instance-then-hand-it-to-the-provider shape as before, which is still the only way to get configured error tracking and PostHogProvider's screen tracking.
• environment and the OTA update group (release) are registered by initExpo itself, replacing the hand-rolled posthog.register({ code_bundle_id }) block in src/config.ts.
• NetworkBoundary swaps PostHogErrorBoundary for ObservabilityBoundary.
• PostHogProvider is now skipped entirely when there is no key, rather than being handed an uninitialised client.

packages/api (magic-observability/node)

• shared/posthog.ts → shared/observability.ts, runtime: "serverless" (the old flushAt: 1, flushInterval: 0 under a name).
• FlagService reads the raw posthog-node handle — feature flags are deliberately not wrapped — and a null client falls through to the caller's defaultValue, the same branch a PostHog outage takes.

apps/nextjs (magic-observability/web, /react, /next) — all new:

• src/instrumentation-client.ts (browser, pre-hydration), src/instrumentation.ts (onRequestError), src/app/providers.tsx (provider + top-level boundary).
• app/error.tsx now reports what it catches instead of only rendering; its 500 markup moved to components/something-went-wrong.tsx so both boundaries render the same screen.

No analytics events were removed. The Amplitude-era analytics.track({ event_type, event_properties }) call shape is untouched across its ~30 call sites — only the transport underneath moved. analytics.screenViewed still calls posthog.screen() on the raw SDK: $screen is a mobile-only event and the shared client surface deliberately stops short of methods four of the five platforms cannot implement.

2. EAS Publish goes green again

The workflow has been red on main since run 30316394285 — failing after the OTA it was publishing had already shipped:

400 release_id_mismatch   Symbol set 568c270f… already has a release ID
400 content_hash_mismatch Symbol set 568c270f… already exists with different content.
Oops! Content mismatch: use --skip-on-conflict or --force

The posthog-react-native Metro serializer's chunk id is stable per platform bundle rather than derived from the bundle's contents, so every OTA re-uploads the same two symbol sets with new content inside them. The upload now passes --force (the newest bundle is the one in users' hands, so its maps are the ones worth keeping — --skip-on-conflict would keep the previous bundle's maps and symbolicate every new stack trace against stale sources) and an explicit --release-version, which posthog-cli's docs call strongly recommended for release CD.

---

What is live today, and what activates when a key lands

Live now — mobile and the API already have their tokens, so this ships as a behaviour change there:

• Mobile gains uncaught exceptions, unhandled rejections and native crashes captured by default. Previously only explicit sendError calls were reported.
• Everything thrown is normalised into a real Error on the way in. throw "nope" used to reach PostHog with no stack and no message.
• Error context is flattened to dotted keys, so nested properties become filterable.
• EAS Publish stops failing.

Dormant until NEXT_PUBLIC_POSTHOG_KEY is set in Vercel — the whole apps/nextjs half. Pageviews, client exceptions, the top-level boundary and app/error.tsx all resolve to a no-op client that writes nothing and logs nothing. Setting the variable is the entire activation step; no code change follows it. The server half (onRequestError) already picks up the existing POSTHOG_API_KEY, so it is live wherever that is set.

Env variables

Documented in .env.example. Every one of them is optional — no key means a silent no-op client, which is why a clone with no .env now boots instead of throwing at import time.

Variable	Read by	Set today?
EXPO_PUBLIC_POSTHOG_KEY → falls back to EXPO_PUBLIC_POSTHOG_API_KEY	mobile	yes, under the old name
POSTHOG_KEY → falls back to POSTHOG_API_KEY	@pegada/api, Next server	yes, under the old name
NEXT_PUBLIC_POSTHOG_KEY	Next browser	no
*_POSTHOG_HOST	all	optional, defaults to https://us.i.posthog.com

Both names are read everywhere, newest first, because the old ones are what EAS and Vercel already store the token under and renaming them there is not something this repo can do.

One property rename to know about

Mobile's super properties were { environment, code_bundle_id }, set by a hand-rolled posthog.register(...). initExpo sets { environment, release } from the same values, so code_bundle_id becomes release and carries the identical OTA update group. environment is unchanged.

Any saved PostHog insight, filter or alert on code_bundle_id will need repointing at release. Nothing else moved, and no event name changed.

Notes

• magic-observability@1.0.0 published today; pnpm 11 blocks anything under 24h old, hence the version-pinned minimumReleaseAgeExclude entry.
• posthog-js is now in the site's client bundle even while it no-ops — initWebAnalytics imports it statically. First Load JS shared by all is 177 kB.
• packages/api and apps/nextjs each build their own posthog-node singleton, lazily. They capture different things (explicit sendError vs. Next's request errors) and the Next one is only constructed on the first server error.

💛 MY AMAZING PR CONTAINS:

Does this PR change only one thing (And only what is necessary for it)?

Two, and they are joined at the hip: the CI failure being fixed is in the same sourcemap pipeline the mobile client's release property feeds, and splitting them would leave one PR merging into a red main.

Verified locally: pnpm install clean, lint 0 (including magic/no-manual-classname), format clean, typecheck 5/5, test 73 passing, next build green, and expo export --platform ios bundles — Metro resolves the package's subpath exports.

pnpm build at the repo root fails on this machine for a missing local .env.dev; confirmed identical on a clean checkout of main, so it is not from this branch.