@marktiderman/genesis-native 0.2.0 → 0.4.0

package/dist/block-Onqx7NiK.d.ts

@@ -0,0 +1,223 @@
+import * as react from 'react';
+import { ComponentType, ReactNode } from 'react';
+import { N as NativeBlock, n as ErrorReport, x as NativeBlockRootProps } from './blocks-C2RDpvaN.js';
+
+/**
+ * Typed analytics events: the app lists every event and the props each may
+ * carry once, and `track(name, props)` accepts nothing else. A prop is a
+ * closed list of strings, a number or a boolean, never free text, so an
+ * event can't carry a name, an email or a message someone typed.
+ *
+ * ```ts
+ * export const events = defineEvents({
+ *   "auth.signed_in": { method: ["email", "apple"] },
+ *   "settings.opened": {},
+ *   "checkin.saved": { mood: "number", first: "boolean" },
+ * });
+ * ```
+ *
+ * At run time an unknown event, an unknown prop or a value outside its list
+ * is dropped and reported (a `console.warn` in development, `onInvalid`
+ * always), so a bad call is loud and still sends nothing.
+ */
+/** A closed list of strings, `"number"` (finite) or `"boolean"`. */
+type EventPropSpec = readonly string[] | "number" | "boolean";
+/** Every event, by name, with the props it may carry. */
+type EventSchema = Readonly<Record<string, Readonly<Record<string, EventPropSpec>>>>;
+type PropValue<S> = S extends readonly (infer L)[] ? L : S extends "number" ? number : S extends "boolean" ? boolean : never;
+/** The props of one event: every prop optional, each its spec's type. */
+type EventProps<S extends Readonly<Record<string, EventPropSpec>>> = {
+    readonly [K in keyof S]?: PropValue<S[K]>;
+};
+/** What a sink receives: the checked props. */
+type EventValues = Readonly<Record<string, string | number | boolean>>;
+/**
+ * Declare the app's events. Checks names (lower-case, dot-separated), prop
+ * names, and that each list has at least one short value, and throws listing
+ * every problem, so a bad schema fails where it is written.
+ *
+ * @stability Beta
+ */
+declare function defineEvents<const E extends EventSchema>(schema: E): E;
+type EventCheck = {
+    ok: true;
+    props: EventValues;
+} | {
+    ok: false;
+    problem: string;
+};
+/** Check one call against the schema: the props to send, or why nothing is sent. */
+declare function checkEvent(schema: EventSchema, name: string, props: Readonly<Record<string, unknown>> | undefined): EventCheck;
+
+/**
+ * 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.
+ */
+
+/** Where a caught error came from and whether the app could go on. */
+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;
+}
+type BreadcrumbLevel = "debug" | "info" | "warning" | "error";
+/** One step that led up to an error: a navigation, a tap, a request. */
+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. */
+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
+ */
+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). */
+declare function scrubbedError(error: Error): Error;
+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
+ */
+declare function consoleSink(options?: ConsoleSinkOptions): ObservabilitySink;
+/**
+ * `expo-observe`'s `Observe` (SDK 56+), or a stand-in: the calls `observeSink`
+ * uses. Pass `import { Observe } from "expo-observe"`.
+ */
+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;
+}
+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
+ */
+declare function observeSink(observe: ObserveLike, options?: ObserveSinkOptions): ObservabilitySink;
+/** Breadcrumb data scrubbed and made plain (for sinks and the devtools overlay). */
+declare function scrubBreadcrumb(crumb: Breadcrumb): Breadcrumb;
+
+/** The FeatureId of the observability block. */
+declare const OBSERVABILITY_BLOCK_ID = "observability";
+/** A caught error as the devtools overlay shows it (scrubbed). */
+interface RecentError {
+    at: number;
+    name: string;
+    message: string;
+    source: string;
+    fatal: boolean;
+}
+interface RecentActivity {
+    /** Oldest first. Navigation, events and the app's breadcrumbs. */
+    breadcrumbs: readonly Breadcrumb[];
+    /** Oldest first. */
+    errors: readonly RecentError[];
+}
+interface RecentStore {
+    getState(): RecentActivity;
+    subscribe(listener: () => void): () => void;
+    clear(): void;
+}
+interface ObservabilityOptions<E extends EventSchema = EventSchema> {
+    /** Where everything goes: `sentrySink(Sentry, …)`, `consoleSink()` in development, `observeSink(Observe)`. */
+    sinks: readonly (ObservabilitySink | null | undefined | false)[];
+    /** The app's analytics events (`defineEvents`). Without it, `track` accepts nothing. */
+    events?: E;
+    /** `useSegments` from expo-router: route breadcrumbs and `route.time_on_screen` timings. */
+    useSegments?: () => readonly string[];
+    /** How many breadcrumbs and errors `recent` keeps. Default 50 and 20. */
+    recent?: {
+        breadcrumbs?: number;
+        errors?: number;
+    };
+    /** A sink threw, or `track` was called with something the schema doesn't allow. Default `console.warn` in development. */
+    onProblem?: (problem: string, error?: unknown) => void;
+    now?: () => number;
+}
+interface ObservabilityBlock<E extends EventSchema = EventSchema> extends NativeBlock<typeof OBSERVABILITY_BLOCK_ID> {
+    readonly sinks: readonly ObservabilitySink[];
+    readonly events: E | undefined;
+    /** Report an error. The shell calls it for every error it catches. */
+    captureError(error: unknown, context?: Partial<ErrorContext>): void;
+    breadcrumb(crumb: Breadcrumb): void;
+    /** The login's id only. The block's root sets it from the session. */
+    setUser(id: string | null): void;
+    /** An analytics event from the schema. Anything else is dropped and reported. */
+    track<N extends keyof E & string>(name: N, props?: EventProps<E[N]>): void;
+    timing(name: string, ms: number, tags?: TimingTags): void;
+    /** The root layout wrapped by each sink that wraps (Sentry's `wrap`). Use once: `export default observability.wrap(RootLayout)`. */
+    wrap<P extends Record<string, unknown>>(root: ComponentType<P>): ComponentType<P>;
+    /** The last breadcrumbs and errors, scrubbed, for the devtools overlay. */
+    readonly recent: RecentStore;
+    /** For the shell: every error it catches. */
+    readonly onError: (error: Error, report: ErrorReport) => void;
+    readonly Root: ComponentType<NativeBlockRootProps>;
+}
+/** Build the block once, at module scope, before the root layout renders. @stability Beta */
+declare function createObservability<const E extends EventSchema = EventSchema>(options: ObservabilityOptions<E>): ObservabilityBlock<E>;
+/** Provides a block to the hooks without its root (rung 4). @stability Beta */
+declare function ObservabilityProvider({ block, children }: {
+    block: ObservabilityBlock;
+    children?: ReactNode;
+}): react.JSX.Element;
+/** The block, or `null` when it is off (so a screen can call it whether or not the block is on). @stability Beta */
+declare function useObservability(): ObservabilityBlock | null;
+/** The last breadcrumbs and errors, scrubbed; empty when the block is off. @stability Beta */
+declare function useRecentActivity(block?: ObservabilityBlock | null): RecentActivity;
+
+export { type Breadcrumb as B, type ConsoleSinkOptions as C, type ErrorContext as E, type ObservabilityBlock as O, type RecentActivity as R, type TimingTags as T, type ObservabilitySink as a, type BreadcrumbLevel as b, type EventCheck as c, type EventPropSpec as d, type EventProps as e, type EventSchema as f, type EventValues as g, OBSERVABILITY_BLOCK_ID as h, type ObservabilityOptions as i, ObservabilityProvider as j, type ObserveLike as k, type ObserveSinkOptions as l, type RecentError as m, type RecentStore as n, checkEvent as o, consoleSink as p, createObservability as q, defineEvents as r, observeSink as s, scrubBreadcrumb as t, scrubbedError as u, useObservability as v, useRecentActivity as w };