@mrrocket/sdk 0.2.0 → 0.4.0

package/dist/react-native/index.d.cts

@@ -0,0 +1,259 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+/**
+ * The part of the SDK that runs anywhere: experiment config, variant assignment, preview links and event shapes.
+ * No React, no browser APIs, so the server helper, the proxy helper and the client share it.
+ */
+type VariantId = string;
+/** This build of the SDK. Sent with the config request so MRRocket knows what the site runs (error tracking, flags). */
+declare const SDK_VERSION = "0.4.0";
+/** One variant of an experiment. `changes` replaces texts that the page marks with `<Text id>`. */
+interface VariantConfig {
+    id: VariantId;
+    /** Share of traffic, 0 to 1. The weights of an experiment add up to 1. */
+    weight: number;
+    changes?: Record<string, string>;
+}
+interface ExperimentConfig {
+    /** The experiment's key, the same as in Cockpit. */
+    key: string;
+    status: "running" | "draft" | "stopped";
+    /** Control first. */
+    variants: VariantConfig[];
+    /** A winner that shipped: everyone gets it, and nobody is assigned anymore. */
+    winner?: VariantId;
+}
+interface CockpitConfig {
+    /** The product the public key belongs to. */
+    project: string;
+    experiments: ExperimentConfig[];
+    /** The product's affiliate program: how many days a partner's referral is kept. Missing without a program. */
+    referral?: {
+        cookieDays: number;
+    };
+    /** Session recordings: present only while the product records (Cockpit › Sessions). See `ReplayConfig`. */
+    replay?: ReplayConfig;
+    /** Feature flags of the product in Production (MRRocket › Build › Feature flags), evaluated by `useFlag` and `getFlag`. */
+    flags?: FlagConfig[];
+}
+/** One condition of a flag's audience, on a property of the person (`identify(id, props)`), the id or the page. */
+interface FlagCondition {
+    /** "Email", "Plan", "Country", "id", "path" … Matched against the person's properties without regard to case. */
+    property: string;
+    op: "is" | "is not" | "in" | "not in" | "≥" | "in cohort";
+    values: string[];
+}
+/** Users who match every condition, of whom `rollout` percent get the flag. No conditions: everyone. */
+interface FlagConditionSet {
+    conditions: FlagCondition[];
+    /** 0 to 100. */
+    rollout: number;
+}
+interface FlagConfig {
+    key: string;
+    /** Off: everyone gets the off side. */
+    on: boolean;
+    /** The first set a person matches decides; none matched: off. */
+    sets: FlagConditionSet[];
+    /** Multivariate flags: the variants and their split in percent (control included). Missing for an on/off flag. */
+    variants?: {
+        key: string;
+        split: number;
+        payload?: string;
+    }[];
+}
+/**
+ * Session recordings of a product, from the config. Recording also needs the visitor's own replay consent
+ * (`<CockpitProvider replay>` or `setConsent({ replay: true })`); without it nothing is recorded or buffered.
+ */
+interface ReplayConfig {
+    /**
+     * Share of sessions uploaded from their start, 0 to 1 (default 0.1). The others keep only the last minute in
+     * memory and upload it when something goes wrong: a JS error, a rage click, a `purchase…` or `checkout…` event.
+     */
+    sampleRate: number;
+}
+/** One event as it goes over the wire to `POST /api/sdk/events`. */
+interface CockpitEvent {
+    event: string;
+    /** The visitor. Missing in "cookieless" mode until identify(): the server then uses its daily visitor hash. */
+    distinctId?: string;
+    /** Ends after 30 minutes without an event. */
+    sessionId?: string;
+    props?: Record<string, unknown>;
+    /** Milliseconds since the epoch. */
+    ts: number;
+    url?: string;
+    /** `document.referrer` on the first page of a page load, the previous in-app URL after client-side navigation. */
+    referrer?: string;
+    utm_source?: string;
+    utm_medium?: string;
+    utm_campaign?: string;
+    utm_term?: string;
+    utm_content?: string;
+    /** The screen size in CSS pixels (points on a phone). */
+    screen?: {
+        w: number;
+        h: number;
+    };
+    /** The app that sent it (React Native only): MRRocket stores it with the event and fills OS and device from it. */
+    app?: AppContext;
+}
+/** Where a React Native event comes from. Every field is optional except the platform; nothing identifies the person. */
+interface AppContext {
+    /** "ios" or "android" (React Native's `Platform.OS`). */
+    platform: string;
+    /** The app's version, like "1.4.0" (`expo-application`'s `nativeApplicationVersion`). */
+    appVersion?: string;
+    /** The build number, like "42". */
+    build?: string;
+    /** The OS version, like "17.4". */
+    osVersion?: string;
+    /** The device model, like "iPhone 15 Pro" (`expo-device`). */
+    deviceModel?: string;
+    /** "phone", "tablet", "desktop" or "tv" when `expo-device` knows it. */
+    deviceType?: string;
+    /** The first preferred locale, like "de-DE". */
+    locale?: string;
+}
+
+/**
+ * What the app may send and store.
+ * - "anonymous" (default): no id is stored on the device. Events go without a person id until `identify()` (MRRocket
+ *   counts visitors by its daily hash); flags and experiments use a random id that lives until the app is closed.
+ * - "persistent": a random install id is stored on the device (removed with the app) and sent with every event.
+ * - "off": nothing is sent, and what the SDK stored is deleted.
+ */
+type NativeConsent = "anonymous" | "persistent" | "off";
+interface MRRocketOptions {
+    /** The product's public key (MRRocket › Settings › Products), the same as on the website. */
+    apiKey: string;
+    /** Where MRRocket runs. Default `https://app.mrrocket.dev`. */
+    host?: string;
+    /** Default "anonymous". The SDK does not remember it: pass it on every start (from your consent screen's stored answer). */
+    consent?: NativeConsent;
+    /** Uncaught JavaScript errors and `captureError` go to Build › Errors (default true). */
+    errors?: boolean;
+    /** Your release, for Build › Errors. Default: the app version and build, like "1.4.0 (42)". */
+    release?: string;
+    /** `$app_open` and `$app_background` events (default true). */
+    lifecycle?: boolean;
+    /** Read UTM and referral parameters of the deep link that opened the app the first time, sent with `$install` (default true). */
+    attribution?: boolean;
+    /** How often the queue is sent while the app is open, in ms (default 10 000). It is also sent when the app goes to the background. */
+    flushIntervalMs?: number;
+    /** At most this many events wait on the device; the oldest go first (default 1,000). */
+    maxQueue?: number;
+    /** Log what the SDK does to the console. */
+    debug?: boolean;
+}
+/** AsyncStorage's shape. */
+interface KeyValueStorage {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+/** What the app (and the React hooks) use. */
+interface MRRocketClient {
+    track(event: string, props?: Record<string, unknown>): void;
+    /** A screen view: a route name ("Settings") or an Expo Router path ("/settings"). */
+    screen(name: string, props?: Record<string, unknown>): void;
+    identify(id: string, props?: Record<string, unknown>): void;
+    /** Forgets the signed-in person (sign-out): a new anonymous id and a new session. */
+    reset(): void;
+    setConsent(consent: NativeConsent): void;
+    captureError(error: unknown): void;
+    getFlag(key: string): boolean;
+    getFlagVariant(key: string): string | null;
+    /** The variant of an experiment ("control" until the config is known); records the exposure once per screen. */
+    getVariant(key: string): VariantId;
+    /** The variant without recording anything (render code); pair it with `expose`. */
+    peekVariant(key: string): VariantId;
+    /** Records that the person saw `variant` of `key`, once per screen. */
+    expose(key: string, variant: VariantId): void;
+    /** Sends what is queued now. */
+    flush(): Promise<void>;
+    /** Resolves once stored state and the config (cached or fetched) are known. */
+    ready: Promise<void>;
+    isReady(): boolean;
+    getDistinctId(): string;
+    getConsent(): NativeConsent;
+    getConfig(): CockpitConfig | null;
+    /** For React: called after every change flags, variants or the consent depend on. Returns the unsubscribe. */
+    subscribe(listener: () => void): () => void;
+    /** Grows with every such change (useSyncExternalStore's snapshot). */
+    getVersion(): number;
+    /** Stops timers and listeners and sends what is queued (tests, or an app that tears the SDK down). */
+    close(): Promise<void>;
+    /** For tests: what waits to be sent. */
+    queued(): readonly CockpitEvent[];
+}
+/** The name of the screen a React Navigation state shows: the focused route, followed into nested navigators. */
+declare const activeRouteName: (state: unknown) => string | undefined;
+
+/**
+ * The SDK's client outside React (a background task, a store, an API layer): the one the provider made, or a new one.
+ * One client per app; a second call returns the first.
+ */
+declare const createMRRocket: (options: MRRocketOptions & {
+    storage?: KeyValueStorage | null;
+}) => MRRocketClient;
+/** The running client, or null before the provider (or createMRRocket) started it. */
+declare const getMRRocket: () => MRRocketClient | null;
+interface MRRocketProviderProps extends Partial<MRRocketOptions> {
+    /** The product's public key (MRRocket › Settings › Products), the same as on the website. */
+    apiKey: string;
+    /** A storage with AsyncStorage's shape instead of AsyncStorage (MMKV, SecureStore); null keeps everything in memory. */
+    storage?: KeyValueStorage | null;
+    /** A client you made with createMRRocket; the other props are then ignored. */
+    client?: MRRocketClient;
+    children?: ReactNode;
+}
+/**
+ * Put it once around your app (Expo Router: app/_layout.tsx; React Navigation: around the NavigationContainer). It
+ * starts the SDK: lifecycle events, the event queue, flags and experiments, error capture. Changing `consent` later
+ * calls setConsent.
+ */
+declare const MRRocketProvider: ({ client: given, children, consent, ...options }: MRRocketProviderProps) => react.FunctionComponentElement<react.ProviderProps<MRRocketClient | null>>;
+/**
+ * `track`, `screen`, `identify`, `reset`, `setConsent`, `captureError`, `flush`, the visitor id, the consent and whether
+ * flags and experiments have loaded.
+ */
+declare const useMRRocket: () => {
+    track: (event: string, props?: Record<string, unknown>) => void;
+    screen: (name: string, props?: Record<string, unknown>) => void;
+    identify: (id: string, props?: Record<string, unknown>) => void;
+    reset: () => void;
+    setConsent: (consent: NativeConsent) => void;
+    captureError: (error: unknown) => void;
+    flush: () => Promise<void>;
+    distinctId: string;
+    consent: NativeConsent;
+    ready: boolean;
+};
+/** A feature flag from MRRocket › Build › Feature flags: true while it is on for this person; false while off, unknown or loading. */
+declare const useFlag: (key: string) => boolean;
+/** The variant of a multivariate flag ("control", "test" …), or null while it is off. */
+declare const useFlagVariant: (key: string) => string | null;
+/**
+ * The variant of an experiment this person sees ("control" until the config is known; the cached config is used on a
+ * cold start, so the first screen is already stable). Records the exposure once per screen.
+ */
+declare const useVariant: (key: string) => VariantId;
+/**
+ * Screen views for Expo Router: one `$screen` per path ("/settings", "/product/[id]" as its real path). Call it in a
+ * component inside both the router and MRRocketProvider, for example the root layout's child.
+ */
+declare const useExpoRouterTracking: () => void;
+/**
+ * Screen views for React Navigation: pass the result to the container's `onStateChange`, and call it once in `onReady`
+ * with the root state, so the first screen counts too.
+ *
+ *     const ref = useNavigationContainerRef();
+ *     const onStateChange = useNavigationTracking();
+ *     <NavigationContainer ref={ref} onReady={() => onStateChange(ref.getRootState())} onStateChange={onStateChange}>
+ */
+declare const useNavigationTracking: () => (state: unknown) => void;
+
+export { type AppContext, type CockpitConfig, type FlagConfig, type KeyValueStorage, type MRRocketClient, type MRRocketOptions, MRRocketProvider, type MRRocketProviderProps, type NativeConsent, SDK_VERSION, type VariantId, activeRouteName, createMRRocket, getMRRocket, useExpoRouterTracking, useFlag, useFlagVariant, useMRRocket, useNavigationTracking, useVariant };

package/dist/react-native/index.d.ts

@@ -0,0 +1,259 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+/**
+ * The part of the SDK that runs anywhere: experiment config, variant assignment, preview links and event shapes.
+ * No React, no browser APIs, so the server helper, the proxy helper and the client share it.
+ */
+type VariantId = string;
+/** This build of the SDK. Sent with the config request so MRRocket knows what the site runs (error tracking, flags). */
+declare const SDK_VERSION = "0.4.0";
+/** One variant of an experiment. `changes` replaces texts that the page marks with `<Text id>`. */
+interface VariantConfig {
+    id: VariantId;
+    /** Share of traffic, 0 to 1. The weights of an experiment add up to 1. */
+    weight: number;
+    changes?: Record<string, string>;
+}
+interface ExperimentConfig {
+    /** The experiment's key, the same as in Cockpit. */
+    key: string;
+    status: "running" | "draft" | "stopped";
+    /** Control first. */
+    variants: VariantConfig[];
+    /** A winner that shipped: everyone gets it, and nobody is assigned anymore. */
+    winner?: VariantId;
+}
+interface CockpitConfig {
+    /** The product the public key belongs to. */
+    project: string;
+    experiments: ExperimentConfig[];
+    /** The product's affiliate program: how many days a partner's referral is kept. Missing without a program. */
+    referral?: {
+        cookieDays: number;
+    };
+    /** Session recordings: present only while the product records (Cockpit › Sessions). See `ReplayConfig`. */
+    replay?: ReplayConfig;
+    /** Feature flags of the product in Production (MRRocket › Build › Feature flags), evaluated by `useFlag` and `getFlag`. */
+    flags?: FlagConfig[];
+}
+/** One condition of a flag's audience, on a property of the person (`identify(id, props)`), the id or the page. */
+interface FlagCondition {
+    /** "Email", "Plan", "Country", "id", "path" … Matched against the person's properties without regard to case. */
+    property: string;
+    op: "is" | "is not" | "in" | "not in" | "≥" | "in cohort";
+    values: string[];
+}
+/** Users who match every condition, of whom `rollout` percent get the flag. No conditions: everyone. */
+interface FlagConditionSet {
+    conditions: FlagCondition[];
+    /** 0 to 100. */
+    rollout: number;
+}
+interface FlagConfig {
+    key: string;
+    /** Off: everyone gets the off side. */
+    on: boolean;
+    /** The first set a person matches decides; none matched: off. */
+    sets: FlagConditionSet[];
+    /** Multivariate flags: the variants and their split in percent (control included). Missing for an on/off flag. */
+    variants?: {
+        key: string;
+        split: number;
+        payload?: string;
+    }[];
+}
+/**
+ * Session recordings of a product, from the config. Recording also needs the visitor's own replay consent
+ * (`<CockpitProvider replay>` or `setConsent({ replay: true })`); without it nothing is recorded or buffered.
+ */
+interface ReplayConfig {
+    /**
+     * Share of sessions uploaded from their start, 0 to 1 (default 0.1). The others keep only the last minute in
+     * memory and upload it when something goes wrong: a JS error, a rage click, a `purchase…` or `checkout…` event.
+     */
+    sampleRate: number;
+}
+/** One event as it goes over the wire to `POST /api/sdk/events`. */
+interface CockpitEvent {
+    event: string;
+    /** The visitor. Missing in "cookieless" mode until identify(): the server then uses its daily visitor hash. */
+    distinctId?: string;
+    /** Ends after 30 minutes without an event. */
+    sessionId?: string;
+    props?: Record<string, unknown>;
+    /** Milliseconds since the epoch. */
+    ts: number;
+    url?: string;
+    /** `document.referrer` on the first page of a page load, the previous in-app URL after client-side navigation. */
+    referrer?: string;
+    utm_source?: string;
+    utm_medium?: string;
+    utm_campaign?: string;
+    utm_term?: string;
+    utm_content?: string;
+    /** The screen size in CSS pixels (points on a phone). */
+    screen?: {
+        w: number;
+        h: number;
+    };
+    /** The app that sent it (React Native only): MRRocket stores it with the event and fills OS and device from it. */
+    app?: AppContext;
+}
+/** Where a React Native event comes from. Every field is optional except the platform; nothing identifies the person. */
+interface AppContext {
+    /** "ios" or "android" (React Native's `Platform.OS`). */
+    platform: string;
+    /** The app's version, like "1.4.0" (`expo-application`'s `nativeApplicationVersion`). */
+    appVersion?: string;
+    /** The build number, like "42". */
+    build?: string;
+    /** The OS version, like "17.4". */
+    osVersion?: string;
+    /** The device model, like "iPhone 15 Pro" (`expo-device`). */
+    deviceModel?: string;
+    /** "phone", "tablet", "desktop" or "tv" when `expo-device` knows it. */
+    deviceType?: string;
+    /** The first preferred locale, like "de-DE". */
+    locale?: string;
+}
+
+/**
+ * What the app may send and store.
+ * - "anonymous" (default): no id is stored on the device. Events go without a person id until `identify()` (MRRocket
+ *   counts visitors by its daily hash); flags and experiments use a random id that lives until the app is closed.
+ * - "persistent": a random install id is stored on the device (removed with the app) and sent with every event.
+ * - "off": nothing is sent, and what the SDK stored is deleted.
+ */
+type NativeConsent = "anonymous" | "persistent" | "off";
+interface MRRocketOptions {
+    /** The product's public key (MRRocket › Settings › Products), the same as on the website. */
+    apiKey: string;
+    /** Where MRRocket runs. Default `https://app.mrrocket.dev`. */
+    host?: string;
+    /** Default "anonymous". The SDK does not remember it: pass it on every start (from your consent screen's stored answer). */
+    consent?: NativeConsent;
+    /** Uncaught JavaScript errors and `captureError` go to Build › Errors (default true). */
+    errors?: boolean;
+    /** Your release, for Build › Errors. Default: the app version and build, like "1.4.0 (42)". */
+    release?: string;
+    /** `$app_open` and `$app_background` events (default true). */
+    lifecycle?: boolean;
+    /** Read UTM and referral parameters of the deep link that opened the app the first time, sent with `$install` (default true). */
+    attribution?: boolean;
+    /** How often the queue is sent while the app is open, in ms (default 10 000). It is also sent when the app goes to the background. */
+    flushIntervalMs?: number;
+    /** At most this many events wait on the device; the oldest go first (default 1,000). */
+    maxQueue?: number;
+    /** Log what the SDK does to the console. */
+    debug?: boolean;
+}
+/** AsyncStorage's shape. */
+interface KeyValueStorage {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+/** What the app (and the React hooks) use. */
+interface MRRocketClient {
+    track(event: string, props?: Record<string, unknown>): void;
+    /** A screen view: a route name ("Settings") or an Expo Router path ("/settings"). */
+    screen(name: string, props?: Record<string, unknown>): void;
+    identify(id: string, props?: Record<string, unknown>): void;
+    /** Forgets the signed-in person (sign-out): a new anonymous id and a new session. */
+    reset(): void;
+    setConsent(consent: NativeConsent): void;
+    captureError(error: unknown): void;
+    getFlag(key: string): boolean;
+    getFlagVariant(key: string): string | null;
+    /** The variant of an experiment ("control" until the config is known); records the exposure once per screen. */
+    getVariant(key: string): VariantId;
+    /** The variant without recording anything (render code); pair it with `expose`. */
+    peekVariant(key: string): VariantId;
+    /** Records that the person saw `variant` of `key`, once per screen. */
+    expose(key: string, variant: VariantId): void;
+    /** Sends what is queued now. */
+    flush(): Promise<void>;
+    /** Resolves once stored state and the config (cached or fetched) are known. */
+    ready: Promise<void>;
+    isReady(): boolean;
+    getDistinctId(): string;
+    getConsent(): NativeConsent;
+    getConfig(): CockpitConfig | null;
+    /** For React: called after every change flags, variants or the consent depend on. Returns the unsubscribe. */
+    subscribe(listener: () => void): () => void;
+    /** Grows with every such change (useSyncExternalStore's snapshot). */
+    getVersion(): number;
+    /** Stops timers and listeners and sends what is queued (tests, or an app that tears the SDK down). */
+    close(): Promise<void>;
+    /** For tests: what waits to be sent. */
+    queued(): readonly CockpitEvent[];
+}
+/** The name of the screen a React Navigation state shows: the focused route, followed into nested navigators. */
+declare const activeRouteName: (state: unknown) => string | undefined;
+
+/**
+ * The SDK's client outside React (a background task, a store, an API layer): the one the provider made, or a new one.
+ * One client per app; a second call returns the first.
+ */
+declare const createMRRocket: (options: MRRocketOptions & {
+    storage?: KeyValueStorage | null;
+}) => MRRocketClient;
+/** The running client, or null before the provider (or createMRRocket) started it. */
+declare const getMRRocket: () => MRRocketClient | null;
+interface MRRocketProviderProps extends Partial<MRRocketOptions> {
+    /** The product's public key (MRRocket › Settings › Products), the same as on the website. */
+    apiKey: string;
+    /** A storage with AsyncStorage's shape instead of AsyncStorage (MMKV, SecureStore); null keeps everything in memory. */
+    storage?: KeyValueStorage | null;
+    /** A client you made with createMRRocket; the other props are then ignored. */
+    client?: MRRocketClient;
+    children?: ReactNode;
+}
+/**
+ * Put it once around your app (Expo Router: app/_layout.tsx; React Navigation: around the NavigationContainer). It
+ * starts the SDK: lifecycle events, the event queue, flags and experiments, error capture. Changing `consent` later
+ * calls setConsent.
+ */
+declare const MRRocketProvider: ({ client: given, children, consent, ...options }: MRRocketProviderProps) => react.FunctionComponentElement<react.ProviderProps<MRRocketClient | null>>;
+/**
+ * `track`, `screen`, `identify`, `reset`, `setConsent`, `captureError`, `flush`, the visitor id, the consent and whether
+ * flags and experiments have loaded.
+ */
+declare const useMRRocket: () => {
+    track: (event: string, props?: Record<string, unknown>) => void;
+    screen: (name: string, props?: Record<string, unknown>) => void;
+    identify: (id: string, props?: Record<string, unknown>) => void;
+    reset: () => void;
+    setConsent: (consent: NativeConsent) => void;
+    captureError: (error: unknown) => void;
+    flush: () => Promise<void>;
+    distinctId: string;
+    consent: NativeConsent;
+    ready: boolean;
+};
+/** A feature flag from MRRocket › Build › Feature flags: true while it is on for this person; false while off, unknown or loading. */
+declare const useFlag: (key: string) => boolean;
+/** The variant of a multivariate flag ("control", "test" …), or null while it is off. */
+declare const useFlagVariant: (key: string) => string | null;
+/**
+ * The variant of an experiment this person sees ("control" until the config is known; the cached config is used on a
+ * cold start, so the first screen is already stable). Records the exposure once per screen.
+ */
+declare const useVariant: (key: string) => VariantId;
+/**
+ * Screen views for Expo Router: one `$screen` per path ("/settings", "/product/[id]" as its real path). Call it in a
+ * component inside both the router and MRRocketProvider, for example the root layout's child.
+ */
+declare const useExpoRouterTracking: () => void;
+/**
+ * Screen views for React Navigation: pass the result to the container's `onStateChange`, and call it once in `onReady`
+ * with the root state, so the first screen counts too.
+ *
+ *     const ref = useNavigationContainerRef();
+ *     const onStateChange = useNavigationTracking();
+ *     <NavigationContainer ref={ref} onReady={() => onStateChange(ref.getRootState())} onStateChange={onStateChange}>
+ */
+declare const useNavigationTracking: () => (state: unknown) => void;
+
+export { type AppContext, type CockpitConfig, type FlagConfig, type KeyValueStorage, type MRRocketClient, type MRRocketOptions, MRRocketProvider, type MRRocketProviderProps, type NativeConsent, SDK_VERSION, type VariantId, activeRouteName, createMRRocket, getMRRocket, useExpoRouterTracking, useFlag, useFlagVariant, useMRRocket, useNavigationTracking, useVariant };