@betterreviews/react-native 1.0.0

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@betterreviews/react-native",
+  "version": "1.0.0",
+  "description": "React Native renderer for BetterReviews mobile PDP content. Consumes the betterreviews_reactiv.* Shopify metafields and renders product content blocks (features, reviews_summary) themed to the merchant.",
+  "license": "SEE LICENSE IN LICENSE",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Product-Page-Optimizer/ppo.git",
+    "directory": "react-native/packages/react-native"
+  },
+  "bugs": {
+    "url": "https://github.com/Product-Page-Optimizer/ppo/issues",
+    "email": "security@betterreviews.app"
+  },
+  "homepage": "https://betterreviews.app",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "prepublishOnly": "yarn typecheck && yarn test && yarn build",
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean --external react --external react-native --external react-native-webview --external react-native-svg --external react-native-gesture-handler",
+    "test": "vitest run",
+    "test:rn": "jest",
+    "typecheck": "tsc --noEmit",
+    "smoke": "bash scripts/smoke-from-pack.sh"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-native": ">=0.74.0",
+    "react-native-gesture-handler": ">=2.16.0",
+    "react-native-svg": ">=15.0.0",
+    "react-native-webview": ">=13.0.0"
+  },
+  "dependencies": {
+    "valibot": "^1.0.0"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.25.0",
+    "@babel/plugin-syntax-import-attributes": "^7.29.7",
+    "@react-native/babel-preset": "0.74.89",
+    "@testing-library/react-native": "^12.5.0",
+    "@types/jest": "^29.5.0",
+    "@types/node": "^22.0.0",
+    "@types/react": "^18.0.0",
+    "babel-jest": "^29.7.0",
+    "jest": "^29.7.0",
+    "react": "^18.0.0",
+    "react-native": "^0.74.0",
+    "react-native-gesture-handler": "^2.28.0",
+    "react-native-svg": "^15.12.0",
+    "react-native-webview": "^13.0.0",
+    "react-test-renderer": "18.2.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}

package/src/BetterReviewsProvider.tsx

@@ -0,0 +1,62 @@
+/**
+ * Context provider for the BetterReviews RN package. Partner host
+ * apps wrap their navigation tree with `<BetterReviewsProvider>` and
+ * supply the merchant-resolved `theme` + `config` + an optional
+ * `onTelemetryEvent` callback.
+ *
+ * The provider is intentionally thin — no fetching, no state. The
+ * partner is responsible for fetching the metafield bodies from
+ * Shopify and passing them in. Decoupling fetch from render lets the
+ * partner cache however they want (subject to the 1h TTL ceiling per
+ * SECURITY.md § "Cache TTL contract").
+ */
+
+import React, { createContext, useContext, useMemo } from 'react';
+import type { Config } from '../../schemas/src/config.js';
+import type { Theme } from '../../schemas/src/theme.js';
+import { safeTelemetry, type TelemetryHandler } from './telemetry.js';
+
+export interface BetterReviewsContextValue {
+  theme: Theme | null;
+  config: Config | null;
+  emit: TelemetryHandler;
+}
+
+const defaultValue: BetterReviewsContextValue = {
+  theme: null,
+  config: null,
+  emit: () => {},
+};
+
+const BetterReviewsContext = createContext<BetterReviewsContextValue>(defaultValue);
+
+export interface BetterReviewsProviderProps {
+  theme?: Theme | null;
+  config?: Config | null;
+  onTelemetryEvent?: TelemetryHandler;
+  children: React.ReactNode;
+}
+
+export function BetterReviewsProvider({
+  theme = null,
+  config = null,
+  onTelemetryEvent,
+  children,
+}: BetterReviewsProviderProps): React.ReactElement {
+  const emit = useMemo(() => safeTelemetry(onTelemetryEvent), [onTelemetryEvent]);
+
+  const value = useMemo<BetterReviewsContextValue>(
+    () => ({ theme, config, emit }),
+    [theme, config, emit],
+  );
+
+  return (
+    <BetterReviewsContext.Provider value={value}>
+      {children}
+    </BetterReviewsContext.Provider>
+  );
+}
+
+export function useBetterReviews(): BetterReviewsContextValue {
+  return useContext(BetterReviewsContext);
+}

package/src/ProductContentBlock.tsx

@@ -0,0 +1,143 @@
+/**
+ * Top-level renderer for `betterreviews_reactiv.product_content_block`.
+ * Iterates the merchant's section list and dispatches each to its
+ * type-specific renderer. Unknown section types are silently dropped
+ * (tolerant-reader contract) with a `schema.violation` telemetry
+ * event.
+ *
+ * Mount-time gates:
+ *   1. `config.product_content_block_enabled === false` — render nothing.
+ *   2. `config.min_sdk_version` declared and current SDK is below
+ *      floor — render nothing + emit `fetch.failure` with
+ *      `error_code: "sdk_below_floor"`.
+ *
+ * Per-section validation uses valibot's `safeParse` so a single
+ * malformed section doesn't crash the whole block — bad sections
+ * are dropped, known-good ones render.
+ *
+ * Telemetry discipline: parsing + section building happen purely during
+ * render (no side effects); every telemetry event is emitted from a
+ * `useEffect`. Emitting during render would invoke the host app's
+ * `onTelemetryEvent` (commonly a `setState`) mid-render and crash React
+ * with "Cannot update a component while rendering a different component."
+ */
+
+import React, { useEffect, useMemo } from 'react';
+import { View } from 'react-native';
+import * as v from 'valibot';
+import { sectionSchema } from '../../schemas/src/product_content_block.js';
+import type { ProductContentBlock as ProductContentBlockData } from '../../schemas/src/product_content_block.js';
+import { useBetterReviews } from './BetterReviewsProvider.js';
+
+// Tolerant READ envelope: validate the wrapper shape but treat `sections` as
+// `unknown[]` so a single unknown/bad section drops ITSELF (in renderSection),
+// not the whole block. The strict `productContentBlockSchema` remains the
+// WRITE-side contract (server pre-write validation); the reader must be lenient
+// — that is the whole point of the tolerant-reader pattern.
+const readEnvelopeSchema = v.object({
+  v: v.literal(1),
+  sections: v.array(v.unknown()),
+});
+import { meetsFloor } from './minSdkVersion.js';
+import { FeaturesSection } from './sections/FeaturesSection.js';
+import { ReviewsSummarySection } from './sections/ReviewsSummarySection.js';
+
+export interface ProductContentBlockProps {
+  /** Parsed metafield body from `betterreviews_reactiv.product_content_block`. */
+  block: ProductContentBlockData | null | undefined;
+}
+
+export function ProductContentBlock({ block }: ProductContentBlockProps): React.ReactElement | null {
+  const { config, emit } = useBetterReviews();
+
+  // Mount-time gate 1: merchant explicitly disabled this product.
+  const disabled = config?.product_content_block_enabled === false;
+
+  // Mount-time gate 2: SDK version floor.
+  const sdkOk = meetsFloor(config?.min_sdk_version);
+
+  // Pure render-time computation: parse the envelope, build renderable
+  // section nodes, and COLLECT schema-violation paths. No telemetry is
+  // emitted here — see "Telemetry discipline" above.
+  const { nodes, violations } = useMemo<{
+    nodes: React.ReactElement[] | null;
+    violations: (string | undefined)[];
+  }>(() => {
+    if (disabled || !sdkOk || !block) {
+      return { nodes: null, violations: [] };
+    }
+
+    // Validate only the ENVELOPE shape (wrong `v`, missing/!array `sections`).
+    // Sections are parsed individually below so one bad section drops itself.
+    const envelope = v.safeParse(readEnvelopeSchema, block);
+    if (!envelope.success) {
+      return {
+        nodes: null,
+        violations: [envelope.issues?.[0]?.path?.[0]?.key as string | undefined],
+      };
+    }
+
+    const violations: (string | undefined)[] = [];
+    const nodes = envelope.output.sections
+      .map((section, index) => renderSection(section, index, violations))
+      .filter((node): node is React.ReactElement => node !== null);
+
+    return { nodes, violations };
+  }, [disabled, sdkOk, block]);
+
+  // Gate 2 telemetry: SDK below floor.
+  useEffect(() => {
+    if (!sdkOk) {
+      emit({
+        type: 'betterreviews.fetch.failure',
+        error_code: 'sdk_below_floor',
+      });
+    }
+  }, [sdkOk, emit]);
+
+  // Schema-violation telemetry — emitted from an effect, never during render.
+  useEffect(() => {
+    for (const violation_path of violations) {
+      emit({
+        type: 'betterreviews.schema.violation',
+        schema_version: 1,
+        violation_path,
+      });
+    }
+  }, [violations, emit]);
+
+  if (disabled || !sdkOk || !block) return null;
+  if (nodes === null) return null;
+
+  return <View>{nodes}</View>;
+}
+
+// Pure: returns the section's rendered node, or null while pushing the
+// offending path onto `violations` for the caller to emit from an effect.
+function renderSection(
+  section: unknown,
+  index: number,
+  violations: (string | undefined)[],
+): React.ReactElement | null {
+  // Per-section validation — a single bad section drops itself, not
+  // the rest. valibot's variant is strict; unknown types fail here.
+  const result = v.safeParse(sectionSchema, section);
+  if (!result.success) {
+    violations.push(`sections[${index}]`);
+    return null;
+  }
+
+  switch (result.output.type) {
+    case 'features':
+      return <FeaturesSection key={index} bullets={result.output.bullets} />;
+    case 'reviews_summary':
+      return <ReviewsSummarySection key={index} />;
+    default:
+      // Exhaustiveness: TypeScript narrows `result.output.type` to `never`
+      // here. If a new section type is added to the schema without a
+      // renderer case, this branch + telemetry surfaces it at runtime
+      // (defense-in-depth on top of the compile-time narrowing).
+      violations.push(`sections[${index}].type`);
+      return null;
+  }
+}

package/src/StarRating.tsx

@@ -0,0 +1,85 @@
+/**
+ * `StarRating` — compact aggregate rating badge (stars + score + review
+ * count), the RN equivalent of the storefront `br-star-rating` block. It sits
+ * near the product title; tap it (via `onPress`) to jump to the reviews.
+ *
+ * The host supplies the aggregate (`average` + `total`) — typically from the
+ * `betterreviews.summary` metafield it already fetches. A badge must NOT
+ * trigger `ReviewWidget`'s multi-call summary synthesis.
+ *
+ * Theme (star color) comes from `<BetterReviewsProvider>` context, with a fixed
+ * gold fallback when used outside a provider.
+ */
+import React, { useId } from 'react';
+import { Pressable, Text, View } from 'react-native';
+import { useBetterReviews } from './BetterReviewsProvider.js';
+import { IconStar } from './icons/BRIcons.js';
+import { resolveWidgetTheme } from './theme/widgetTheme.js';
+
+export interface StarRatingProps {
+  /** Aggregate average rating, e.g. 4.5. */
+  average: number;
+  /** Total review count. */
+  total: number;
+  /** Star pixel size (default 16). */
+  size?: number;
+  /** Override the star fill color (defaults to the theme's star color). */
+  starColor?: string;
+  /** Tap handler — e.g. scroll to the ReviewWidget. Renders as a button when set. */
+  onPress?: () => void;
+  /** Render nothing when there are no reviews (default true). */
+  hideWhenEmpty?: boolean;
+}
+
+export function StarRating({
+  average,
+  total,
+  size = 16,
+  starColor,
+  onPress,
+  hideWhenEmpty = true,
+}: StarRatingProps): React.ReactElement | null {
+  const { theme } = useBetterReviews();
+  const t = resolveWidgetTheme(theme);
+  // Unique per-instance gradient seed — two badges with half-stars on screen
+  // must not share a react-native-svg gradient id.
+  const uid = useId();
+
+  if (hideWhenEmpty && total <= 0) return null;
+  const fill = starColor ?? t.star;
+
+  const content = (
+    <View
+      style={{ flexDirection: 'row', alignItems: 'center' }}
+      accessibilityRole="image"
+      accessibilityLabel={`${average.toFixed(1)} out of 5 stars, ${total} ${total === 1 ? 'review' : 'reviews'}`}
+    >
+      {[1, 2, 3, 4, 5].map((i) => {
+        const diff = average - (i - 1);
+        const p = diff >= 0.75 ? 100 : diff >= 0.25 ? 50 : 0;
+        return (
+          <View key={i} style={{ marginRight: 1 }}>
+            <IconStar size={size} fillPercentage={p} fillColor={fill} emptyColor={t.muted} uid={`${uid}-${i}`} />
+          </View>
+        );
+      })}
+      <Text style={{ marginLeft: 6, fontSize: size * 0.85, fontWeight: '600', color: t.text }}>
+        {average.toFixed(1)}
+      </Text>
+      <Text style={{ marginLeft: 5, fontSize: size * 0.8, color: t.mutedFg }}>
+        · {total} {total === 1 ? 'review' : 'reviews'}
+      </Text>
+    </View>
+  );
+
+  if (!onPress) return content;
+  return (
+    <Pressable
+      onPress={onPress}
+      accessibilityRole="button"
+      style={({ pressed }: { pressed: boolean }) => (pressed ? { opacity: 0.6 } : null)}
+    >
+      {content}
+    </Pressable>
+  );
+}

package/src/WebViewHost.tsx

@@ -0,0 +1,164 @@
+/**
+ * `WebViewHost` — the ONLY place `react-native-webview` is consumed.
+ *
+ * Critical seam discipline: this wrapper hides all underlying
+ * `WebView` props from callers. Public API is `{ url, onMessage,
+ * onError }` only. Recovery patches (e.g. adding
+ * `onContentProcessDidTerminate` if the Tier 2 WebView test surfaces
+ * a WebSocket-survival failure) are single-file, single-line changes
+ * INSIDE this file — zero changes at any caller. See
+ * `docs/proposals/reactiv-webview-tier2-test-2026-05-18.md` § "Known
+ * traps" for the documented recovery paths.
+ *
+ * Default `WebView` props match the Tier 2 test's chosen baseline:
+ *   - sharedCookiesEnabled=false (worst-case isolation; Reactiv may
+ *     flip later)
+ *   - automaticallyAdjustContentInsets=false
+ *   - contentInsetAdjustmentBehavior="never"
+ *   - keyboardDisplayRequiresUserAction=false
+ *   - allowsInlineMediaPlayback
+ *   - mediaPlaybackRequiresUserAction=false
+ *
+ * The baseline matches what the Tier 2 test validates — keeps any
+ * future test pass/fail directly applicable.
+ */
+
+import React, { useEffect } from 'react';
+import { WebView } from 'react-native-webview';
+import { useBetterReviews } from './BetterReviewsProvider.js';
+import { isCloseSignal } from './webviewMessage.js';
+
+// Derive the event types from the WebView component's own props. Avoids
+// importing from a deep path (`react-native-webview/lib/WebViewTypes`)
+// + insulates us if the library's type-export surface shifts between
+// versions.
+type WebViewProps = React.ComponentProps<typeof WebView>;
+type OnMessageHandler = NonNullable<WebViewProps['onMessage']>;
+type OnErrorHandler = NonNullable<WebViewProps['onError']>;
+type ShouldStartLoadHandler = NonNullable<
+  WebViewProps['onShouldStartLoadWithRequest']
+>;
+
+// Allowed origin suffixes for navigations inside the WebView. SECURITY.md
+// commits to pinning to BetterReviews-controlled hosts; this list is the
+// implementation of that commitment.
+//
+// Includes the dev-only `*.betterreviews.ngrok-free.dev` reserved domain
+// so the Tier 2 WebView test + local-dev integration with Reactiv can run
+// without an SDK build tweak. Production builds reach `api.betterreviews.app`
+// — the ngrok entry is a no-op for partner apps in stores.
+const ALLOWED_ORIGIN_SUFFIXES = [
+  '.betterreviews.app',
+  '.betterreviews.ngrok-free.dev',
+];
+
+function originAllowed(rawUrl: string): boolean {
+  // `javascript:` / `data:` / `file:` / opaque URLs lack a parseable
+  // host and must be rejected.
+  let parsed: URL;
+  try {
+    parsed = new URL(rawUrl);
+  } catch {
+    return false;
+  }
+
+  if (parsed.protocol !== 'https:') return false;
+
+  const host = parsed.hostname.toLowerCase();
+  return ALLOWED_ORIGIN_SUFFIXES.some(
+    (suffix) => host === suffix.slice(1) || host.endsWith(suffix),
+  );
+}
+
+export interface WebViewHostProps {
+  /** Chat surface URL (e.g. `https://api.betterreviews.app/review/chat?...`). */
+  url: string;
+  /** Fires on every `postMessage` from inside the WebView (except the close signal — see `onClose`). */
+  onMessage?: OnMessageHandler;
+  /** Fires on navigation / load error. */
+  onError?: OnErrorHandler;
+  /**
+   * Fires when the embedded page asks the host to dismiss it by posting
+   * `{ "type": "close" }` (e.g. the chat's "Back to store" / done button).
+   * Wire this to close the modal/screen the WebView is in. Other messages
+   * still flow to `onMessage`.
+   */
+  onClose?: () => void;
+}
+
+export function WebViewHost({ url, onMessage, onError, onClose }: WebViewHostProps): React.ReactElement | null {
+  const { emit } = useBetterReviews();
+
+  // Refuse to mount with a non-https / non-betterreviews URL. Mirrors
+  // SECURITY.md § "What BetterReviews commits to (the wire)" —
+  // "WKWebView origin pinning. The package's WebView host for
+  // `/review/chat` pins the origin to `*.betterreviews.app` and
+  // `*.betterreviews.ngrok-free.dev` (development only). Cross-origin
+  // navigations are blocked."
+  const allowed = originAllowed(url);
+
+  // Emit the origin-rejection from an effect, NEVER during render — a host
+  // telemetry handler that calls setState would otherwise crash render
+  // ("Cannot update a component while rendering a different component").
+  useEffect(() => {
+    if (!allowed) {
+      emit({
+        type: 'betterreviews.webview.error',
+        error_code: 'origin_not_allowed',
+        url_origin: safeOrigin(url),
+      });
+    }
+  }, [allowed, url, emit]);
+
+  if (!allowed) return null;
+
+  // Intercept the `{type:'close'}` signal for `onClose`; forward everything
+  // else to `onMessage`. The page sends close instead of navigating away when
+  // it detects a native host (so "Back to store" dismisses the WebView rather
+  // than loading the storefront inside it).
+  const handleMessage: OnMessageHandler = (event) => {
+    if (onClose && isCloseSignal(event.nativeEvent.data)) {
+      onClose();
+      return;
+    }
+    onMessage?.(event);
+  };
+
+  const handleShouldStartLoad: ShouldStartLoadHandler = (request) => {
+    if (originAllowed(request.url)) return true;
+
+    emit({
+      type: 'betterreviews.webview.error',
+      error_code: 'cross_origin_blocked',
+      url_origin: safeOrigin(request.url),
+    });
+
+    return false;
+  };
+
+  return (
+    <WebView
+      source={{ uri: url }}
+      sharedCookiesEnabled={false}
+      automaticallyAdjustContentInsets={false}
+      contentInsetAdjustmentBehavior="never"
+      keyboardDisplayRequiresUserAction={false}
+      allowsInlineMediaPlayback
+      mediaPlaybackRequiresUserAction={false}
+      onShouldStartLoadWithRequest={handleShouldStartLoad}
+      onMessage={onMessage || onClose ? handleMessage : undefined /* either prop → wire handler */}
+      onError={onError}
+    />
+  );
+}
+
+// Returns just the origin (scheme + host) for telemetry — never the
+// path/query, which could include tokens.
+function safeOrigin(rawUrl: string): string {
+  try {
+    const parsed = new URL(rawUrl);
+    return `${parsed.protocol}//${parsed.hostname}`;
+  } catch {
+    return 'invalid';
+  }
+}

package/src/bridge.ts

@@ -0,0 +1,48 @@
+/**
+ * Bridge config resolution (Card C.14).
+ *
+ * `config.bridge` declares the merchant's preference for native bridge
+ * surfaces (sort drawer, photo viewer):
+ *   - `"off"` (default): everything renders in-WebView.
+ *   - `"auto"`: use native if available, fall back to in-WebView.
+ *   - `"required"`: use native; if not available, render nothing.
+ *
+ * Schema spec § 11.5 — v1 of this RN package ships in-WebView fallback
+ * only. The native bridge is post-soft-launch. So all three values
+ * resolve to `"in_webview"` behaviour today; `"auto"` and `"required"`
+ * additionally emit a `bridge_not_implemented` telemetry hint so the
+ * future merchant who configures non-default can be notified that
+ * their intent is not yet honoured.
+ */
+
+import type { Config } from '../../schemas/src/config.js';
+import type { TelemetryHandler } from './telemetry.js';
+
+export type ResolvedBridge = 'in_webview' | 'native';
+
+/**
+ * Returns the bridge mode this package will actually use. v1 always
+ * returns `"in_webview"` regardless of the config preference, since the
+ * native bridge isn't implemented yet.
+ *
+ * Side-effect: if the config requested `"auto"` or `"required"`, emits
+ * a `betterreviews.fetch.failure` telemetry event with
+ * `error_code: "bridge_not_implemented"` so the partner observability
+ * stack can surface that the merchant's intent is not yet honoured.
+ */
+export function resolveBridge(
+  config: Config | null | undefined,
+  emit: TelemetryHandler,
+): ResolvedBridge {
+  const requested = config?.bridge;
+
+  if (requested && requested !== 'off') {
+    emit({
+      type: 'betterreviews.fetch.failure',
+      error_code: 'bridge_not_implemented',
+    });
+  }
+
+  // v1: always in-WebView. Native bridge lands post-soft-launch.
+  return 'in_webview';
+}