@marktiderman/genesis-native 0.2.0 → 0.4.0

package/src/observability/sentry.ts

@@ -0,0 +1,222 @@
+/**
+ * `sentrySink(Sentry, options)`: Sentry through the observability seam.
+ * `@sentry/react-native` is an optional peer, passed in rather than
+ * imported (`import * as Sentry from "@sentry/react-native"`), so an app
+ * without it never bundles it.
+ *
+ * Calling it runs `Sentry.init` at once, so call it at module scope (where
+ * `createObservability` is built, before the root layout renders): errors
+ * thrown while the app's modules load and the shell's first render are then
+ * caught. A second call in the same process (Fast Refresh) reuses the client.
+ *
+ * What it sets up, on Expo SDK 58 with @sentry/react-native 8:
+ * - `expoRouterIntegration` (navigation spans, time to initial display);
+ * - release `<applicationId>@<version>+<build>` and dist `<build>` from the
+ *   version signature (Sentry's own format, so release health lines up),
+ *   with the update id, channel, runtime version and launch as tags;
+ * - the PII scrubber on every event, transaction, span, breadcrumb and log
+ *   (`beforeSend`, `beforeSendTransaction`, `beforeSendSpan`,
+ *   `beforeBreadcrumb`, `beforeSendLog`), and the user as an id only;
+ * - no default PII, screenshots, view hierarchy or accessibility labels, and
+ *   touch breadcrumbs without the touched element's label (labels hold names);
+ * - fatal errors marked unhandled, so release health counts them as crashes.
+ *
+ * Native crashes (sentry-cocoa, sentry-android) are built on the device's
+ * native side and don't pass through these JavaScript hooks.
+ *
+ * Errors: the shell (`GenesisNativeApp`) reports every error it catches
+ * through `captureError`. Sentry's own global handler stays on for errors
+ * before the shell mounts; when both see one error object, Sentry's
+ * deduplication (`__sentry_captured__`) sends it once.
+ */
+import type { ComponentType } from "react";
+import type { VersionSignature } from "../updates/signature";
+import { scrubEvent, scrubRecord, scrubString } from "./scrub";
+import type { ObservabilitySink } from "./sink";
+
+type Options = Record<string, unknown>;
+type Hook<T> = (value: T, hint?: unknown) => T | null | PromiseLike<T | null>;
+
+/**
+ * `@sentry/react-native`'s namespace: the calls this sink makes. Method
+ * syntax on purpose, so the real namespace (with wider option types) fits.
+ */
+export interface SentryLike {
+  init(options: Options): unknown;
+  getClient(): unknown;
+  wrap<P extends Record<string, unknown>>(root: ComponentType<P>): ComponentType<P>;
+  captureException(error: unknown, context?: Options): string;
+  addBreadcrumb(breadcrumb: Options): void;
+  setUser(user: { id: string } | null): void;
+  setTag(key: string, value: string): void;
+  expoRouterIntegration?(options?: { enableTimeToInitialDisplay?: boolean }): unknown;
+  metrics?: {
+    distribution(name: string, value: number, options?: Options): void;
+    count(name: string, value?: number, options?: Options): void;
+  };
+}
+
+export interface SentrySinkOptions {
+  /** `process.env.EXPO_PUBLIC_SENTRY_DSN`. Empty or missing: Sentry is not started and the sink does nothing. */
+  dsn: string | undefined | null;
+  /** Default `development` in `__DEV__`, else from the signature's channel: `production`, `preview` (`preview` and `pr-*`), `development`, else `production`. */
+  environment?: string;
+  /** The version signature (`versionSignature(…)` from `/updates`, or the updates block's `signature`): release, dist and update tags. */
+  signature?: VersionSignature;
+  /** `Application.applicationId` (expo-application): the release's prefix. */
+  applicationId?: string | null;
+  /** Default 0.2 in production and 1 elsewhere. */
+  tracesSampleRate?: number;
+  /** Navigation spans and time to initial display through Expo Router. Default true. */
+  expoRouter?: boolean | { enableTimeToInitialDisplay?: boolean };
+  /** More integrations (replay, profiling). Masking is yours to set on them. */
+  integrations?: readonly unknown[];
+  /**
+   * Other `Sentry.init` options. The scrubbing hooks run first and yours
+   * after, on the scrubbed value; `sendDefaultPii` and the screenshot,
+   * view-hierarchy and accessibility options can be set here on purpose.
+   */
+  init?: Options;
+  /** False turns the scrubber off (not recommended; it is also the only thing reducing the user to an id). Default true. */
+  scrub?: boolean;
+  /** Called instead of `console.warn` when the DSN is missing outside development. */
+  onMissingDsn?: () => void;
+}
+
+declare const __DEV__: boolean | undefined;
+const isDev = () => typeof __DEV__ !== "undefined" && __DEV__;
+
+/** Sentry's release format: `<applicationId>@<version>+<build>`, with `dist` the build; `undefined` parts when unknown. */
+export function sentryRelease(signature: VersionSignature | undefined, applicationId?: string | null): { release?: string; dist?: string } {
+  const version = signature?.version;
+  const build = signature?.build;
+  if (!version || !build || !applicationId) return {};
+  return { release: `${applicationId}@${version}+${build}`, dist: build };
+}
+
+/** The tags each event carries from the signature. Unknown values are written `unknown`, never left out. */
+export function signatureTags(signature: VersionSignature | undefined): Record<string, string> {
+  if (!signature) return {};
+  return {
+    "update.launch": signature.launch,
+    "update.id": signature.launch === "update" ? (signature.updateId ?? "unknown") : signature.launch,
+    "update.channel": signature.requestedChannel ?? signature.channel ?? (signature.launch === "off" ? "none" : "unknown"),
+    "update.runtime": signature.runtimeVersion ?? "unknown",
+    ...(signature.emergency ? { "update.emergency": "true" } : {}),
+  };
+}
+
+/** One Sentry environment per kind of build, not one per channel (`pr-42` is `preview`). */
+export function sentryEnvironment(channel: string | null | undefined): string {
+  if (!channel || channel === "production") return "production";
+  if (channel === "development") return "development";
+  if (channel === "preview" || /^pr-\d+$/.test(channel)) return "preview";
+  return "production";
+}
+
+/** A touch breadcrumb with the touched elements' names only: their labels (accessibility labels, test ids) can hold names. */
+export function withoutTouchLabels<T extends { category?: unknown; message?: unknown; data?: unknown }>(crumb: T): T {
+  if (crumb.category !== "touch" || !crumb.data || typeof crumb.data !== "object") return crumb;
+  const data = crumb.data as { path?: unknown };
+  const path = Array.isArray(data.path) ? data.path.map((p) => (p && typeof p === "object" ? { name: (p as { name?: unknown }).name } : p)) : undefined;
+  const first = path?.[0] as { name?: unknown } | undefined;
+  return { ...crumb, message: `Touch event within element: ${typeof first?.name === "string" ? first.name : "unknown"}`, data: { ...data, ...(path ? { path } : {}) } };
+}
+
+function chain<T>(ours: (value: T) => T | null, theirs: unknown): Hook<T> {
+  return (value, hint) => {
+    const scrubbed = ours(value);
+    if (scrubbed === null) return null;
+    return typeof theirs === "function" ? (theirs as Hook<T>)(scrubbed, hint) : scrubbed;
+  };
+}
+
+/**
+ * Start Sentry and return a sink for it. Without a DSN it starts nothing and
+ * returns a sink that does nothing (a warning outside development says so).
+ *
+ * @stability Beta
+ */
+export function sentrySink(sentry: SentryLike, options: SentrySinkOptions): ObservabilitySink {
+  const { dsn, signature, applicationId, scrub = true } = options;
+  if (!dsn) {
+    if (!isDev()) (options.onMissingDsn ?? (() => console.warn("[observability] EXPO_PUBLIC_SENTRY_DSN is not set: errors are not reported to Sentry.")))();
+    return { name: "sentry (no DSN)" };
+  }
+  const environment = options.environment ?? (isDev() ? "development" : sentryEnvironment(signature?.requestedChannel ?? signature?.channel));
+  // Fast Refresh runs this module again: a second init would stack integrations on the live client.
+  if (!sentry.getClient()) {
+    const extra = options.init ?? {};
+    const router = options.expoRouter ?? true;
+    const integrations = [
+      ...(router && sentry.expoRouterIntegration
+        ? [sentry.expoRouterIntegration({ enableTimeToInitialDisplay: typeof router === "object" ? router.enableTimeToInitialDisplay : true })]
+        : []),
+      ...(options.integrations ?? []),
+      ...(Array.isArray(extra.integrations) ? extra.integrations : []),
+    ];
+    const keep = <T>(value: T) => value;
+    const span = (value: Options): Options => {
+      const scrubbed = scrubRecord(value);
+      // A span can't be dropped here: fail closed by sending it without its description and data.
+      return scrubbed ?? { ...value, description: undefined, data: {} };
+    };
+    sentry.init({
+      sendDefaultPii: false,
+      attachScreenshot: false,
+      attachViewHierarchy: false,
+      reportAccessibilityIdentifier: false,
+      tracesSampleRate: options.tracesSampleRate ?? (environment === "production" ? 0.2 : 1),
+      ...extra,
+      dsn,
+      environment,
+      ...sentryRelease(signature, applicationId),
+      integrations,
+      beforeSend: chain(scrub ? scrubEvent : keep, extra.beforeSend),
+      beforeSendTransaction: chain(scrub ? scrubEvent : keep, extra.beforeSendTransaction),
+      beforeBreadcrumb: chain<Options>((crumb) => (scrub ? scrubRecord(withoutTouchLabels(crumb)) : crumb), extra.beforeBreadcrumb),
+      beforeSendLog: chain(scrub ? scrubRecord : keep, extra.beforeSendLog),
+      beforeSendMetric: chain(scrub ? scrubRecord : keep, extra.beforeSendMetric),
+      beforeSendSpan: (value: Options) => {
+        const scrubbed = scrub ? span(value) : value;
+        return typeof extra.beforeSendSpan === "function" ? (extra.beforeSendSpan as (s: Options) => Options)(scrubbed) : scrubbed;
+      },
+    });
+    for (const [key, value] of Object.entries(signatureTags(signature))) sentry.setTag(key, value);
+  }
+
+  return {
+    name: "sentry",
+    // Sentry deduplicates by error object, and `beforeSend` scrubs: it always gets the original.
+    scrubsErrors: true,
+    captureError(error, context) {
+      sentry.captureException(error, {
+        // Unhandled when the app could not go on, so release health counts it as a crash.
+        mechanism: { handled: !context.fatal, type: `genesis.${context.source}` },
+        captureContext: {
+          level: context.fatal ? "fatal" : "error",
+          tags: { "genesis.source": context.source, ...(context.route ? { route: context.route } : {}) },
+          ...(context.componentStack ? { contexts: { react: { componentStack: scrub ? scrubString(context.componentStack) : context.componentStack } } } : {}),
+        },
+      });
+    },
+    breadcrumb(crumb) {
+      // Sentry's Expo Router integration records navigation itself.
+      if (crumb.category === "navigation" && (options.expoRouter ?? true)) return;
+      sentry.addBreadcrumb({
+        category: crumb.category,
+        message: crumb.message,
+        level: crumb.level ?? "info",
+        data: crumb.data,
+        ...(crumb.timestamp ? { timestamp: crumb.timestamp / 1000 } : {}),
+      });
+    },
+    setUser: (id) => sentry.setUser(id ? { id } : null),
+    event(name, props) {
+      sentry.addBreadcrumb({ category: "event", message: name, level: "info", data: props });
+      sentry.metrics?.count(name, 1, { attributes: props });
+    },
+    timing: (name, ms, tags) => sentry.metrics?.distribution(name, ms, { unit: "millisecond", attributes: tags }),
+    wrap: (root) => sentry.wrap(root),
+  };
+}

package/src/observability/sink.ts

@@ -0,0 +1,147 @@
+/**
+ * The vendor-neutral seam: a sink is where errors, breadcrumbs, the user id,
+ * analytics events and timings go. `createObservability` fans every call out
+ * to its sinks, scrubbed first; a sink that throws is reported to
+ * `onSinkError` and never takes the others (or the app) down with it.
+ *
+ * Shipped sinks: `sentrySink` (Sentry), `observeSink` (EAS Observe) and
+ * `consoleSink` (development). A vendor adapter (PostHog, Datadog…) is one
+ * object with the methods it supports.
+ */
+import type { ComponentType } from "react";
+import { scrubString, scrubValue } from "./scrub";
+import type { EventValues } from "./events";
+
+/** Where a caught error came from and whether the app could go on. */
+export interface ErrorContext {
+  /** True when the app could not go on (a render error, a failed boot, a fatal global error). */
+  fatal: boolean;
+  /** `boundary`, `global`, `boot`, `rejection` (the shell's), or the app's own (`updates:policy`, `sync`). */
+  source: string;
+  componentStack?: string;
+  /** The route pattern on screen (`/(app)/settings`), when known. */
+  route?: string | null;
+}
+
+export type BreadcrumbLevel = "debug" | "info" | "warning" | "error";
+
+/** One step that led up to an error: a navigation, a tap, a request. */
+export interface Breadcrumb {
+  /** `navigation`, `ui`, `http`, `event`, or the app's own. */
+  category: string;
+  message?: string;
+  level?: BreadcrumbLevel;
+  data?: Readonly<Record<string, unknown>>;
+  /** Milliseconds since the epoch. Default now. */
+  timestamp?: number;
+}
+
+/** Low-cardinality labels on a timing (`route`, `step`), never ids or text someone typed. */
+export type TimingTags = Readonly<Record<string, string>>;
+
+/**
+ * One destination. Every method is optional: a sink takes what its vendor
+ * supports. Errors arrive as an `Error` whose message is already scrubbed,
+ * unless the sink sets `scrubsErrors` (it scrubs the whole event itself and
+ * needs the original object, as Sentry does to deduplicate).
+ *
+ * @stability Beta
+ */
+export interface ObservabilitySink {
+  readonly name: string;
+  /** The sink scrubs error events itself; give it the original `Error`. */
+  readonly scrubsErrors?: boolean;
+  captureError?(error: Error, context: ErrorContext): void;
+  breadcrumb?(crumb: Breadcrumb): void;
+  /** The signed-in login's id, or `null` when signed out. Never an email or a name. */
+  setUser?(id: string | null): void;
+  /** An analytics event, its props checked against the schema. */
+  event?(name: string, props: EventValues): void;
+  timing?(name: string, ms: number, tags?: TimingTags): void;
+  /** Wraps the root layout (Sentry's `wrap`, EAS Observe's `ObserveRoot.wrap`). */
+  wrap?<P extends Record<string, unknown>>(root: ComponentType<P>): ComponentType<P>;
+}
+
+/** A copy of `error` whose message and stack have been scrubbed (for sinks that don't scrub themselves). */
+export function scrubbedError(error: Error): Error {
+  const copy = new Error(scrubString(error.message));
+  copy.name = error.name;
+  if (error.stack) copy.stack = scrubString(error.stack);
+  return copy;
+}
+
+export interface ConsoleSinkOptions {
+  /** Default `console`. */
+  console?: Pick<Console, "log" | "warn" | "error">;
+  /** Also log breadcrumbs (noisy). Default false. */
+  breadcrumbs?: boolean;
+}
+
+/**
+ * Logs what would be sent, for development: fatal errors with `console.error`, others with `console.warn`,
+ * events and timings with `console.log`. Already scrubbed, so what you read
+ * is what a vendor sink would get.
+ *
+ * @stability Beta
+ */
+export function consoleSink(options: ConsoleSinkOptions = {}): ObservabilitySink {
+  const out = options.console ?? console;
+  return {
+    name: "console",
+    // `warn` for what the app survives: `console.error` would raise a LogBox error for every one in development.
+    captureError: (error, context) => {
+      const line = `[observability] ${context.fatal ? "fatal " : ""}${context.source}: ${error.message}`;
+      if (context.fatal) out.error(line);
+      else out.warn(line);
+    },
+    breadcrumb: options.breadcrumbs ? (crumb) => out.log(`[observability] · ${crumb.category} ${crumb.message ?? ""}`) : undefined,
+    setUser: (id) => out.log(`[observability] user ${id ?? "(signed out)"}`),
+    event: (name, props) => out.log(`[observability] event ${name}`, props),
+    timing: (name, ms, tags) => out.log(`[observability] timing ${name} ${Math.round(ms)}ms`, tags ?? {}),
+  };
+}
+
+/**
+ * `expo-observe`'s `Observe` (SDK 56+), or a stand-in: the calls `observeSink`
+ * uses. Pass `import { Observe } from "expo-observe"`.
+ */
+export interface ObserveLike {
+  logEvent(name: string, options?: { severity?: "debug" | "info" | "warn" | "error"; body?: string; attributes?: Record<string, unknown> }): void;
+  /** Error reporting, in preview on SDK 57+. */
+  reportError?(error: unknown): void;
+}
+
+export interface ObserveSinkOptions {
+  /** Report caught errors with `Observe.reportError` (in preview). Default false: Sentry is the error tracker. */
+  errors?: boolean;
+}
+
+/**
+ * EAS Observe. It measures launch (cold, warm, bundle load, first render),
+ * time to interactive and, with its Expo Router integration, per-route
+ * render times on its own; it has no API for a custom timing metric, so
+ * `timing` is logged as an event (`timing.<name>` with `duration_ms`) and
+ * shows on the Events page, not as a metric. Analytics events go to
+ * `Observe.logEvent` as they are.
+ *
+ * @stability Beta
+ */
+export function observeSink(observe: ObserveLike, options: ObserveSinkOptions = {}): ObservabilitySink {
+  return {
+    name: "eas-observe",
+    event: (name, props) => observe.logEvent(name, { attributes: { ...props } }),
+    timing: (name, ms, tags) => observe.logEvent(`timing.${name}`, { severity: "info", attributes: { duration_ms: Math.round(ms), ...(tags ?? {}) } }),
+    captureError: options.errors && observe.reportError ? (error) => observe.reportError?.(error) : undefined,
+  };
+}
+
+/** Breadcrumb data scrubbed and made plain (for sinks and the devtools overlay). */
+export function scrubBreadcrumb(crumb: Breadcrumb): Breadcrumb {
+  return {
+    category: scrubString(crumb.category),
+    level: crumb.level,
+    timestamp: crumb.timestamp,
+    ...(crumb.message !== undefined ? { message: scrubString(crumb.message) } : {}),
+    ...(crumb.data ? { data: scrubValue(crumb.data) as Record<string, unknown> } : {}),
+  };
+}

package/src/persist.ts

@@ -0,0 +1,83 @@
+/**
+ * `@marktiderman/genesis-native/persist`: save chosen queries to async storage
+ * (AsyncStorage, MMKV, …) with TanStack's own persister, so restore,
+ * throttling and max age are theirs.
+ *
+ * Install `@tanstack/query-persist-client-core` and
+ * `@tanstack/query-async-storage-persister` at the same version as your
+ * `@tanstack/react-query`: they pin `@tanstack/query-core` exactly, and two
+ * copies of it would not share a cache.
+ *
+ *   <GenesisNativeApp persist={persistQueries({ storage: AsyncStorage, keys: ["clients"], buster: version })} … />
+ *
+ * @stability Beta
+ */
+import { defaultShouldDehydrateQuery, type QueryClient } from "@tanstack/react-query";
+import { persistQueryClientRestore, persistQueryClientSubscribe } from "@tanstack/query-persist-client-core";
+import { createAsyncStoragePersister } from "@tanstack/query-async-storage-persister";
+import { DAY_MS, type AsyncStorageLike, type QueryPersistence } from "./query";
+
+export interface PersistQueriesOptions {
+  storage: AsyncStorageLike;
+  /**
+   * The query-key roots to persist: a query is saved when its key's first
+   * element is listed (`["clients", id]` is saved under `"clients"`). Nothing
+   * else is written to the phone.
+   */
+  keys: readonly string[];
+  /** Your app's version: a different value discards the saved cache. */
+  buster: string;
+  /** How old a saved cache may be when restored. Default 24 hours. */
+  maxAge?: number;
+  /** Storage key. Default `"genesis-query-cache"`. */
+  storageKey?: string;
+  /** Write at most this often. Default 1000 ms. */
+  throttleMs?: number;
+}
+
+export interface QueryPersistenceOptions extends PersistQueriesOptions {
+  queryClient: QueryClient;
+}
+
+/** Save the allowlisted queries to async storage and restore them, with a max age, an app-version buster and a user scope. */
+export function createQueryPersistence({
+  queryClient,
+  storage,
+  keys,
+  buster,
+  maxAge = DAY_MS,
+  storageKey = "genesis-query-cache",
+  throttleMs = 1000,
+}: QueryPersistenceOptions): QueryPersistence {
+  const persister = createAsyncStoragePersister({ storage, key: storageKey, throttleTime: throttleMs });
+  const allowed = new Set(keys);
+  const dehydrateOptions = {
+    shouldDehydrateQuery: (query: Parameters<typeof defaultShouldDehydrateQuery>[0]) =>
+      allowed.has(String(query.queryKey[0])) && defaultShouldDehydrateQuery(query),
+    // Mutations stay in memory: replaying a saved write is an outbox's job.
+    shouldDehydrateMutation: () => false,
+  };
+  // The scope rides in the buster: TanStack discards (and deletes) a saved
+  // cache whose buster differs, so another user's cache is never restored.
+  const scoped = (scope: string) => `${buster}|user:${scope}`;
+  return {
+    restore: async (scope) => {
+      try {
+        await persistQueryClientRestore({ queryClient, persister, buster: scoped(scope), maxAge });
+      } catch {
+        // An unreadable cache has already been deleted; start without it rather than fail the boot.
+      }
+    },
+    subscribe: (scope) => persistQueryClientSubscribe({ queryClient, persister, buster: scoped(scope), dehydrateOptions }),
+    clear: async () => {
+      await persister.removeClient();
+    },
+  };
+}
+
+/** `createQueryPersistence` for `GenesisNativeApp`'s `persist` prop, which supplies the client. */
+export function persistQueries(options: PersistQueriesOptions): (queryClient: QueryClient) => QueryPersistence {
+  return (queryClient) => createQueryPersistence({ ...options, queryClient });
+}
+
+export type { QueryPersistence } from "./query";