@betterreviews/react-native 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,581 @@
+import React from 'react';
+import * as v from 'valibot';
+import { WebView } from 'react-native-webview';
+
+/**
+ * `betterreviews_reactiv.config` (v1)
+ *
+ * Per-product render config. Signals "merchant has configured this
+ * product" so the RN package can fall back gracefully when no
+ * ProductContentBlock data exists.
+ *
+ * Schema SHAPE-OF-TRUTH: matches `PPO.Reactiv.ContentResolver.resolve_for_store/2`
+ * config emit shape today. The proposal doc mentions `bridge` and
+ * `min_sdk_version` as future fields; the resolver does not emit them
+ * yet. Both are forward-compat OPTIONAL so the schema accepts future
+ * resolver versions without a schema bump.
+ *
+ * See `docs/proposals/reactiv-schema-2026-05-20.md` § 10 for the
+ * future-state shape (bridge / min_sdk_version land in Card C.14 +
+ * post-soft-launch RN work).
+ */
+
+declare const configSchema: v.ObjectSchema<{
+    readonly v: v.LiteralSchema<1, undefined>;
+    readonly updated_at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, undefined>]>;
+    readonly product_content_block_enabled: v.BooleanSchema<undefined>;
+    readonly min_sdk_version: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "min_sdk_version must be valid semver">]>, undefined>;
+    readonly bridge: v.OptionalSchema<v.PicklistSchema<["auto", "required", "off"], undefined>, undefined>;
+}, undefined>;
+type Config = v.InferOutput<typeof configSchema>;
+
+/**
+ * `betterreviews_reactiv.theme` (v1)
+ *
+ * Theme inherited from the merchant's `review_settings.conversation_theme`.
+ * Colors are passed through `PPO.Reactiv.Color.normalize/1` on the
+ * Elixir side (rgb/rgba/hsl/hex input → canonical hex output) before
+ * being emitted by the resolver.
+ *
+ * Schema SHAPE-OF-TRUTH: matches `PPO.Reactiv.ContentResolver.build_theme/1`
+ * + `PPOWeb.Live.ThemeHelpers.@font_map`/@corner_map. The
+ * `docs/proposals/reactiv-schema-2026-05-20.md` § 10 sketch proposed a
+ * richer nested `palette`/`typography`/`corners` structure; the
+ * implemented resolver emits the flatter shape below. Proposal-vs-impl
+ * drift documented in `schemas/betterreviews-reactiv/DESIGN.md`.
+ *
+ * All theme fields except `v` are OPTIONAL — the resolver emits a
+ * field only when the corresponding store-level theme value is set
+ * (`maybe_put_color`/`maybe_put` semantics).
+ */
+
+declare const themeSchema: v.ObjectSchema<{
+    readonly v: v.LiteralSchema<1, undefined>;
+    readonly primary_color: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "Color must be hex #RRGGBB (case-insensitive)">]>, undefined>;
+    readonly background_color: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "Color must be hex #RRGGBB (case-insensitive)">]>, undefined>;
+    readonly text_color: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "Color must be hex #RRGGBB (case-insensitive)">]>, undefined>;
+    readonly accent_color: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "Color must be hex #RRGGBB (case-insensitive)">]>, undefined>;
+    readonly corner_style: v.OptionalSchema<v.PicklistSchema<["sharp", "slightly-rounded", "rounded", "extra-rounded"], undefined>, undefined>;
+    readonly font_family: v.OptionalSchema<v.PicklistSchema<["system", "serif", "sans-serif", "mono"], undefined>, undefined>;
+}, undefined>;
+type Theme = v.InferOutput<typeof themeSchema>;
+
+/**
+ * Telemetry event types emitted by the package. Per SECURITY.md, all
+ * events are pre-redacted — no customer email, name, IP, transcript,
+ * or review content appears in any payload.
+ *
+ * Consumers (partner host apps) wire `onTelemetryEvent` on the
+ * `<BetterReviewsProvider>` to forward events to their own
+ * observability stack.
+ */
+type TelemetryEvent = {
+    type: 'betterreviews.fetch.success';
+    block_id?: string;
+    latency_ms?: number;
+    cache_hit?: boolean;
+} | {
+    type: 'betterreviews.fetch.failure';
+    block_id?: string;
+    error_code: string;
+    retry_attempt?: number;
+} | {
+    type: 'betterreviews.signature.invalid';
+    endpoint?: string;
+    source_ip_hash?: string;
+} | {
+    type: 'betterreviews.schema.violation';
+    schema_version: number;
+    violation_path?: string;
+    dropped_count?: number;
+} | {
+    type: 'betterreviews.webview.error';
+    error_code: string;
+    url_origin?: string;
+};
+type TelemetryHandler = (event: TelemetryEvent) => void;
+/**
+ * Returns a handler that swallows all events. Used as the default
+ * when the partner host app doesn't supply `onTelemetryEvent`.
+ */
+declare function noopTelemetry(): TelemetryHandler;
+/**
+ * Wraps a handler so synchronous exceptions in the partner's
+ * implementation can't crash the renderer. Partner-side bugs become
+ * silent failures rather than UI outages.
+ */
+declare function safeTelemetry(handler: TelemetryHandler | undefined): TelemetryHandler;
+
+/**
+ * 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").
+ */
+
+interface BetterReviewsContextValue {
+    theme: Theme | null;
+    config: Config | null;
+    emit: TelemetryHandler;
+}
+interface BetterReviewsProviderProps {
+    theme?: Theme | null;
+    config?: Config | null;
+    onTelemetryEvent?: TelemetryHandler;
+    children: React.ReactNode;
+}
+declare function BetterReviewsProvider({ theme, config, onTelemetryEvent, children, }: BetterReviewsProviderProps): React.ReactElement;
+declare function useBetterReviews(): BetterReviewsContextValue;
+
+/**
+ * `betterreviews_reactiv.product_content_block` (v1)
+ *
+ * Merchant-curated mobile PDP content. Resolved server-side by
+ * `PPO.Reactiv.ContentResolver`; RN reads exactly what merchant intent
+ * resolved to, no client-side fallback.
+ *
+ * Schema SHAPE-OF-TRUTH: this file matches what
+ * `lib/ppo/reactiv/content_resolver.ex` emits today. The
+ * `docs/proposals/reactiv-schema-2026-05-20.md` § 10 sketch used
+ * `kind` + a `show` boolean for `reviews_summary`; the implemented
+ * resolver uses `type` + presence-as-toggle. The implemented form is
+ * the production contract (PR #88 has been on `dev` since 2026-05-22)
+ * — proposal-vs-impl drift documented in
+ * `schemas/betterreviews-reactiv/DESIGN.md` § "Schema vs proposal doc".
+ */
+
+declare const productContentBlockSchema: v.ObjectSchema<{
+    readonly v: v.LiteralSchema<1, undefined>;
+    readonly updated_at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, undefined>]>;
+    readonly sections: v.ArraySchema<v.VariantSchema<"type", [v.ObjectSchema<{
+        readonly type: v.LiteralSchema<"features", undefined>;
+        readonly bullets: v.SchemaWithPipe<readonly [v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 80, undefined>]>, undefined>, v.MaxLengthAction<string[], 6, undefined>]>;
+    }, undefined>, v.ObjectSchema<{
+        readonly type: v.LiteralSchema<"reviews_summary", undefined>;
+    }, undefined>], undefined>, undefined>;
+}, undefined>;
+type ProductContentBlock$1 = v.InferOutput<typeof productContentBlockSchema>;
+
+/**
+ * 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."
+ */
+
+interface ProductContentBlockProps {
+    /** Parsed metafield body from `betterreviews_reactiv.product_content_block`. */
+    block: ProductContentBlock$1 | null | undefined;
+}
+declare function ProductContentBlock({ block }: ProductContentBlockProps): React.ReactElement | null;
+
+/**
+ * Renders the `features` section — a bullet list capped by the schema
+ * at 6 bullets / 80 chars each. The schema's strict-overlay validator
+ * on the Elixir side has already enforced those caps; this component
+ * renders defensively in case a partial fallback path slips through.
+ */
+
+interface FeaturesSectionProps {
+    bullets: string[];
+}
+declare function FeaturesSection({ bullets }: FeaturesSectionProps): React.ReactElement;
+
+/**
+ * Renders the `reviews_summary` section. v1 displays a placeholder
+ * — the partner host app is expected to supply the live aggregate
+ * (star rating, count, top quote) by mounting its own review-summary
+ * component as a child or sibling.
+ *
+ * The presence of this section in the metafield blob is the merchant's
+ * "show me the reviews summary on this product" toggle. Absence means
+ * "don't render this section." A future PR may expand this to render
+ * `betterreviews.summary` data directly when supplied via
+ * `BetterReviewsProvider`'s `summary` prop.
+ */
+
+declare function ReviewsSummarySection(): React.ReactElement;
+
+/**
+ * `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.
+ */
+
+type WebViewProps = React.ComponentProps<typeof WebView>;
+type OnMessageHandler = NonNullable<WebViewProps['onMessage']>;
+type OnErrorHandler = NonNullable<WebViewProps['onError']>;
+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;
+}
+declare function WebViewHost({ url, onMessage, onError, onClose }: WebViewHostProps): React.ReactElement | null;
+
+/**
+ * `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.
+ */
+
+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;
+}
+declare function StarRating({ average, total, size, starColor, onPress, hideWhenEmpty, }: StarRatingProps): React.ReactElement | null;
+
+/**
+ * Public widget API responses — review list / detail / vote.
+ *
+ * Schema SHAPE-OF-TRUTH: matches `PPO.Reviews.Widget.to_widget_json/2`
+ * + `paginate_meta/3` in `elixir/lib/ppo/reviews/widget.ex` (the
+ * `/api/widget/{store}/...` endpoints served by `WidgetController`).
+ *
+ * UNLIKE the `betterreviews_reactiv.*` metafield schemas in this package,
+ * these describe LIVE API responses, not merchant-curated metafields — so
+ * there is NO `v: 1` / `updated_at` envelope, and they are deliberately
+ * EXCLUDED from `scripts/generate.ts` (the JSON-Schema drift gate is for the
+ * server-side metafield pre-write validator; the widget API contract is
+ * owned by the Elixir controller, not validated from a generated schema).
+ *
+ * Tolerant reader: plain `v.object` ignores unknown keys (the server emits
+ * extra fields like `date_iso`/`display_product_*` that older SDK builds
+ * simply skip). Nullable where the server can emit `nil`.
+ */
+
+declare const widgetMediaItemSchema: v.ObjectSchema<{
+    readonly type: v.StringSchema<undefined>;
+    readonly thumbnail: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly full: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly alt: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>;
+declare const widgetMerchantReplySchema: v.ObjectSchema<{
+    readonly body: v.StringSchema<undefined>;
+    readonly author_name: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly date: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>;
+declare const widgetReviewSchema: v.ObjectSchema<{
+    readonly id: v.NumberSchema<undefined>;
+    readonly author: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly rating: v.NumberSchema<undefined>;
+    readonly title: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly body: v.StringSchema<undefined>;
+    readonly body_truncated: v.BooleanSchema<undefined>;
+    readonly verified: v.BooleanSchema<undefined>;
+    readonly date: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly date_iso: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly helpful_count: v.NumberSchema<undefined>;
+    readonly unhelpful_count: v.NumberSchema<undefined>;
+    readonly media: v.ArraySchema<v.ObjectSchema<{
+        readonly type: v.StringSchema<undefined>;
+        readonly thumbnail: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly full: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly alt: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, undefined>;
+    readonly tags: v.ArraySchema<v.StringSchema<undefined>, undefined>;
+    readonly merchant_reply: v.NullableSchema<v.ObjectSchema<{
+        readonly body: v.StringSchema<undefined>;
+        readonly author_name: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly date: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, undefined>;
+    readonly display_product_id: v.StringSchema<undefined>;
+    readonly display_product_title: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>;
+declare const widgetPaginationSchema: v.ObjectSchema<{
+    readonly page: v.NumberSchema<undefined>;
+    readonly per_page: v.NumberSchema<undefined>;
+    readonly total: v.NumberSchema<undefined>;
+    readonly total_pages: v.NumberSchema<undefined>;
+    readonly has_next: v.BooleanSchema<undefined>;
+}, undefined>;
+declare const widgetVoteCountsSchema: v.ObjectSchema<{
+    readonly helpful_count: v.NumberSchema<undefined>;
+    readonly unhelpful_count: v.NumberSchema<undefined>;
+}, undefined>;
+declare const widgetSortValueSchema: v.PicklistSchema<["most_relevant", "most_helpful", "newest", "highest", "lowest"], undefined>;
+type WidgetMediaItem = v.InferOutput<typeof widgetMediaItemSchema>;
+type WidgetMerchantReply = v.InferOutput<typeof widgetMerchantReplySchema>;
+type WidgetReview = v.InferOutput<typeof widgetReviewSchema>;
+type WidgetPagination = v.InferOutput<typeof widgetPaginationSchema>;
+type WidgetVoteCounts = v.InferOutput<typeof widgetVoteCountsSchema>;
+type WidgetSortValue = v.InferOutput<typeof widgetSortValueSchema>;
+
+/**
+ * Synthesized review summary — NOT a server response.
+ *
+ * There is no summary endpoint on the widget API. The client computes this
+ * from 7 list calls (5 single-rating totals for the distribution, 1
+ * `media_only=true` for the photo count, 1 plain page for the verified
+ * count) — see `createBetterReviewsClient.fetchSummary`. This schema exists
+ * so the type re-exports symmetrically with the other widget types; it is
+ * NOT fed to `scripts/generate.ts`.
+ */
+
+declare const widgetSummarySchema: v.ObjectSchema<{
+    readonly total: v.NumberSchema<undefined>;
+    readonly average: v.NumberSchema<undefined>;
+    readonly breakdown: v.ArraySchema<v.NumberSchema<undefined>, undefined>;
+    readonly positivePct: v.NumberSchema<undefined>;
+    readonly photoCount: v.NumberSchema<undefined>;
+    readonly verifiedCount: v.NumberSchema<undefined>;
+}, undefined>;
+type WidgetSummary = v.InferOutput<typeof widgetSummarySchema>;
+
+/**
+ * Client types for the public widget API.
+ *
+ * The package owns the UI + pagination/sort/filter state and assembles the
+ * logical requests; the HOST owns transport — it implements the `Fetcher`,
+ * which prepends the API base URL and injects the auth `token`. No token
+ * ever lives in this package or the RN binary.
+ */
+
+/**
+ * A logical request the host fetcher fulfils. The host MUST prepend the API
+ * base URL, inject the `token`, perform the request, throw on a non-2xx
+ * status, and resolve with the parsed JSON body. The host MUST NOT put the
+ * resolved URL or the token into any error it throws (the token rides in the
+ * query string — a logged URL/error leaks it).
+ */
+interface FetcherRequest {
+    /** Path relative to the API base, e.g. `/api/widget/{store}/products/{product}/reviews`. */
+    path: string;
+    /** Non-secret query params. The token is added by the host, never here. */
+    query?: Record<string, string | number | boolean | undefined>;
+    method?: 'GET' | 'POST';
+    /** JSON-serializable body (vote only). */
+    body?: unknown;
+    signal?: AbortSignal;
+}
+type Fetcher = (req: FetcherRequest) => Promise<unknown>;
+type VoteType = 'helpful' | 'unhelpful';
+/**
+ * Host-provided persistence for "has this user voted on this review".
+ * Stores only review id → vote direction (no PII, no token, no review
+ * content) — safe for unencrypted storage like AsyncStorage. Do NOT widen
+ * it to cache review payloads.
+ */
+interface VoteStateStore {
+    get(reviewId: number): VoteType | null | undefined;
+    set(reviewId: number, vote: VoteType | null): void;
+}
+interface ListParams {
+    page?: number;
+    perPage?: number;
+    sort?: WidgetSortValue;
+    rating?: 1 | 2 | 3 | 4 | 5 | null;
+    mediaOnly?: boolean;
+    search?: string;
+}
+interface ReviewListResult {
+    reviews: WidgetReview[];
+    pagination: WidgetPagination;
+}
+/**
+ * Reported once per list response when one or more rows fail schema
+ * validation. Carries paths + a count ONLY — never row contents (untrusted
+ * customer-authored review text must not reach telemetry).
+ */
+interface SchemaViolationInfo {
+    droppedCount: number;
+    firstBadPath: string;
+}
+interface BetterReviewsClientConfig {
+    fetcher: Fetcher;
+    storeId: string;
+    productId: string;
+    onSchemaViolation?: (info: SchemaViolationInfo) => void;
+}
+interface BetterReviewsClient {
+    listReviews(params?: ListParams, signal?: AbortSignal): Promise<ReviewListResult>;
+    /** Detail is scoped to the configured product (`product_id` is always sent — the A4 IDOR fix). */
+    getReviewDetail(reviewId: number, signal?: AbortSignal): Promise<WidgetReview>;
+    /** Returns updated counts, or `null` if the POST succeeded but the body was unparseable. Rejects on HTTP/network error. */
+    voteReview(reviewId: number, type: VoteType, undo: boolean, signal?: AbortSignal): Promise<WidgetVoteCounts | null>;
+    fetchSummary(signal?: AbortSignal): Promise<WidgetSummary>;
+}
+
+/**
+ * `<ReviewWidget>` — the public, stateful review-browsing surface.
+ *
+ * Renders INLINE — it owns no scroll container, so it drops into a host's
+ * product-page `ScrollView` as one section (below the product info /
+ * `ProductContentBlock`) and scrolls with the page. Paging is a "Load more"
+ * button, so no virtualization is needed.
+ *
+ * Theme + telemetry flow from `<BetterReviewsProvider>` context (same
+ * convention as `ProductContentBlock`); transport/auth flow from the host via
+ * the injected `client` (or `fetcher` + ids). Schema violations are emitted as
+ * telemetry from the client's async callback (post-render, so the b9357c30
+ * "no emit during render" rule holds).
+ */
+
+interface ReviewWidgetProps {
+    /** Primary: a client built via `createBetterReviewsClient`. */
+    client?: BetterReviewsClient;
+    /** Convenience: supply transport + ids and the widget builds the client. */
+    fetcher?: Fetcher;
+    storeId?: string;
+    productId?: string;
+    /** Persist "already voted" across launches; defaults to in-memory. */
+    voteStateStore?: VoteStateStore;
+    /** Host-owned write-review action; the CTA hides if omitted. */
+    onWriteReview?: () => void;
+    initialSort?: WidgetSortValue;
+}
+declare function ReviewWidget(props: ReviewWidgetProps): React.ReactElement;
+
+declare function createBetterReviewsClient(config: BetterReviewsClientConfig): BetterReviewsClient;
+/**
+ * Default in-memory `VoteStateStore`. Survives only for the component's
+ * lifetime; hosts wanting "already voted" to persist across launches pass an
+ * AsyncStorage-backed implementation instead.
+ */
+declare function createMemoryVoteStore(): VoteStateStore;
+
+/**
+ * Maps a `betterreviews_reactiv.theme` JSON blob to a flat StyleSheet
+ * record consumed by the section renderers. All fields are optional —
+ * absent fields fall back to RN's platform defaults.
+ *
+ * The shape matches `PPO.Reactiv.ContentResolver.build_theme/1` —
+ * flat color keys + corner_style enum + font_family enum.
+ */
+
+interface ResolvedTheme {
+    primaryColor?: string;
+    backgroundColor?: string;
+    textColor?: string;
+    accentColor?: string;
+    borderRadius?: number;
+    fontFamily?: string;
+}
+/**
+ * Pure function — no React, no platform calls. Maps a Theme blob to a
+ * ResolvedTheme suitable for spreading into style props.
+ *
+ * Unknown enum values for `corner_style` / `font_family` resolve to
+ * `undefined` (the schema validator at the write boundary already
+ * rejects unknown values, but defensive in case of a malformed
+ * payload landing in the read path).
+ */
+declare function applyTheme(theme: Theme | null | undefined): ResolvedTheme;
+
+/**
+ * Semver floor compare. The metafield's optional `config.min_sdk_version`
+ * declares the minimum SDK version the merchant expects. The RN
+ * package compares against its own version on mount; if below the
+ * floor, ProductContentBlock renders nothing (degrade-gracefully).
+ *
+ * v1 of the resolver does NOT emit `min_sdk_version` — this is
+ * forward-compat plumbing.
+ */
+declare const SDK_VERSION: string;
+/**
+ * Returns true if the SDK's current version meets the configured
+ * floor, false otherwise. A null/undefined floor always passes (no
+ * floor declared). Malformed floor strings are treated as "no floor"
+ * — the package errs on the side of rendering rather than refusing.
+ */
+declare function meetsFloor(floor: string | undefined): boolean;
+
+/**
+ * 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.
+ */
+
+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.
+ */
+declare function resolveBridge(config: Config | null | undefined, emit: TelemetryHandler): ResolvedBridge;
+
+export { type BetterReviewsClient, type BetterReviewsClientConfig, type BetterReviewsContextValue, BetterReviewsProvider, type BetterReviewsProviderProps, type Config, FeaturesSection, type FeaturesSectionProps, type Fetcher, type FetcherRequest, type ListParams, ProductContentBlock, type ProductContentBlockProps, type ProductContentBlock$1 as ProductContentBlockSchema, type ResolvedBridge, type ResolvedTheme, type ReviewListResult, ReviewWidget, type ReviewWidgetProps, ReviewsSummarySection, SDK_VERSION, type SchemaViolationInfo, StarRating, type StarRatingProps, type TelemetryEvent, type TelemetryHandler, type Theme, type VoteStateStore, type VoteType, WebViewHost, type WebViewHostProps, type WidgetMediaItem, type WidgetMerchantReply, type WidgetPagination, type WidgetReview, type WidgetSortValue, type WidgetSummary, type WidgetVoteCounts, applyTheme, createBetterReviewsClient, createMemoryVoteStore, meetsFloor, noopTelemetry, resolveBridge, safeTelemetry, useBetterReviews };