@revova/hydrogen 1.0.0 → 1.0.2

package/README.md

@@ -11,42 +11,128 @@ npm install @revova/hydrogen
 ## Requirements
 
 - React 18+
-- Shopify Hydrogen storefront with the Revova app installed
+- Shopify Hydrogen storefront with the Revova app installed on the store
 
 ---
 
-## Quick Start
+## How it works
+
+Components and hooks call your Revova backend directly over HTTPS with a `shop` query parameter and a `Bearer` token:
 
-The `proxyUrl` is always `/apps/revova` — Shopify's App Proxy routes requests to your Revova backend automatically. No API keys needed in the storefront.
+```
+GET https://yourapp.trycloudflare.com/api/reviews?shop=yourstore.myshopify.com&...
+Authorization: Bearer <apiToken>
+```
+
+No Shopify App Proxy. No CORS issues. No API keys exposed beyond what you pass in.
 
 ---
 
-## Components
+## Setup (Hydrogen)
 
-### `<ReviewWidget>`
+### 1 — Add your credentials to the environment
 
-Full review list with pagination, sorting, and an inline submission form.
+```env
+# .env
+PUBLIC_REVOVA_API_URL=https://yourapp.trycloudflare.com
+PUBLIC_STORE_DOMAIN=yourstore.myshopify.com
+PUBLIC_REVOVA_API_TOKEN=your_token_here
+```
+
+Expose them through your Hydrogen loader:
+
+```ts
+// app/root.tsx or any route loader
+export async function loader({ context }: LoaderArgs) {
+  return {
+    apiUrl:   context.env.PUBLIC_REVOVA_API_URL,
+    shop:     context.env.PUBLIC_STORE_DOMAIN,
+    apiToken: context.env.PUBLIC_REVOVA_API_TOKEN,
+  };
+}
+```
+
+### 2 — Spread credentials into any component
+
+Every component accepts `apiUrl`, `shop`, and `apiToken`. The easiest pattern is to spread a single `creds` object:
 
 ```tsx
-import { ReviewWidget } from '@revova/hydrogen';
+const creds = {
+  apiUrl:   env.PUBLIC_REVOVA_API_URL,
+  shop:     env.PUBLIC_STORE_DOMAIN,
+  apiToken: env.PUBLIC_REVOVA_API_TOKEN,
+};
+
+<ReviewWidget {...creds} productId={product.id} />
+```
+
+---
+
+## Quick Start
+
+```tsx
+// app/routes/products.$handle.tsx
+import { ReviewWidget, FloatingReviewButton } from '@revova/hydrogen';
+
+export async function loader({ context, params }: LoaderArgs) {
+  const product = await getProduct(params.handle);
+  return {
+    product,
+    apiUrl:   context.env.PUBLIC_REVOVA_API_URL,
+    shop:     context.env.PUBLIC_STORE_DOMAIN,
+    apiToken: context.env.PUBLIC_REVOVA_API_TOKEN,
+  };
+}
 
 export default function ProductPage() {
-  const { product } = useLoaderData<typeof loader>();
+  const { product, apiUrl, shop, apiToken } = useLoaderData<typeof loader>();
+  const creds = { apiUrl, shop, apiToken };
 
   return (
-    <ReviewWidget
-      proxyUrl="/apps/revova"
-      productId={product.id}
-    />
+    <>
+      <h1>{product.title}</h1>
+      <ReviewWidget {...creds} productId={product.id} />
+      <FloatingReviewButton {...creds} productId={product.id} />
+    </>
   );
 }
 ```
 
-**Props**
+---
+
+## API Credentials (`ApiProps`)
+
+All components and hooks require these three props. Spread them as a group for convenience.
+
+| Prop | Type | Description |
+|---|---|---|
+| `apiUrl` | `string` | Revova backend base URL (e.g. `https://yourapp.trycloudflare.com`) |
+| `shop` | `string` | Store myshopify.com domain (e.g. `yourstore.myshopify.com`) |
+| `apiToken` | `string` | Bearer token for authorization |
+
+---
+
+## Components
+
+### `<ReviewWidget>`
+
+Full review list with pagination, sorting, and an inline submission form.
+
+```tsx
+import { ReviewWidget } from '@revova/hydrogen';
+
+<ReviewWidget
+  {...creds}
+  productId={product.id}
+  pageSize={10}
+  showForm
+  locale="fr"
+/>
+```
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `proxyUrl` | `string` | — | App proxy base URL (`/apps/revova`) |
+| `...creds` | `ApiProps` | — | `apiUrl`, `shop`, `apiToken` |
 | `productId` | `string` | — | Shopify product GID |
 | `locale` | `string` | — | Locale code for translated reviews (e.g. `fr`) |
 | `pageSize` | `number` | `10` | Reviews per page |
@@ -65,14 +151,14 @@ import { ReviewForm } from '@revova/hydrogen';
 
 // `form` comes from the ReviewsResponse returned by useReviews
 <ReviewForm
-  proxyUrl="/apps/revova"
+  {...creds}
   productId={product.id}
   form={data.form}
   onSuccess={() => console.log('submitted')}
 />
 ```
 
-**Props:** `proxyUrl`, `productId`, `form` (required — `ResolvedForm` from loader), `onSuccess?`, `className?`
+**Props:** `...creds`, `productId`, `form` (required — `ResolvedForm`), `onSuccess?`, `className?`
 
 ---
 
@@ -92,16 +178,15 @@ import { StarRating } from '@revova/hydrogen';
 
 ### `<ReviewCount>`
 
-Aggregate rating + review count badge. Fetches from `widget-globals`.
+Aggregate rating + review count badge. Great for product cards and PDP headers.
 
 ```tsx
 import { ReviewCount } from '@revova/hydrogen';
 
-// On a product card or PDP header
-<ReviewCount proxyUrl="/apps/revova" starSize={14} />
+<ReviewCount {...creds} starSize={14} />
 ```
 
-**Props:** `proxyUrl`, `starColor?`, `starSize?`, `className?`
+**Props:** `...creds`, `starColor?`, `starSize?`, `className?`
 
 ---
 
@@ -112,15 +197,10 @@ Auto-advancing carousel of recent reviews. Includes previous/next arrows and dot
 ```tsx
 import { ReviewCarousel } from '@revova/hydrogen';
 
-<ReviewCarousel
-  proxyUrl="/apps/revova"
-  limit={10}
-  autoPlay
-  intervalMs={4000}
-/>
+<ReviewCarousel {...creds} limit={10} autoPlay intervalMs={4000} />
 ```
 
-**Props:** `proxyUrl`, `limit?` (default 10), `autoPlay?` (default `true`), `intervalMs?` (default 4000), `starColor?`, `className?`
+**Props:** `...creds`, `limit?` (default 10), `autoPlay?` (default `true`), `intervalMs?` (default 4000), `starColor?`, `className?`
 
 ---
 
@@ -131,14 +211,10 @@ Masonry photo grid of reviews that have images. Clicking any photo opens a light
 ```tsx
 import { ReviewGallery } from '@revova/hydrogen';
 
-<ReviewGallery
-  proxyUrl="/apps/revova"
-  columns={3}
-  limit={20}
-/>
+<ReviewGallery {...creds} columns={3} limit={20} />
 ```
 
-**Props:** `proxyUrl`, `limit?` (default 20), `columns?` (default 3), `starColor?`, `className?`
+**Props:** `...creds`, `limit?` (default 20), `columns?` (default 3), `starColor?`, `className?`
 
 ---
 
@@ -149,13 +225,10 @@ Product Q&A — lists questions with answers and includes an ask-a-question form
 ```tsx
 import { QnAWidget } from '@revova/hydrogen';
 
-<QnAWidget
-  proxyUrl="/apps/revova"
-  productId={product.id}
-/>
+<QnAWidget {...creds} productId={product.id} />
 ```
 
-**Props:** `proxyUrl`, `productId`, `className?`
+**Props:** `...creds`, `productId`, `className?`
 
 ---
 
@@ -166,17 +239,12 @@ Aggregate rating badge in three styles: `pill` (default), `inline`, or `card`.
 ```tsx
 import { TrustBadge } from '@revova/hydrogen';
 
-// Pill — great for footers, headers
-<TrustBadge proxyUrl="/apps/revova" style="pill" />
-
-// Card — great for landing pages
-<TrustBadge proxyUrl="/apps/revova" style="card" />
-
-// Inline — great inside sentences or product specs
-<TrustBadge proxyUrl="/apps/revova" style="inline" />
+<TrustBadge {...creds} style="pill" />
+<TrustBadge {...creds} style="card" />
+<TrustBadge {...creds} style="inline" />
 ```
 
-**Props:** `proxyUrl`, `style?` (`'pill' | 'inline' | 'card'`, default `'pill'`), `starColor?`, `className?`
+**Props:** `...creds`, `style?` (`'pill' | 'inline' | 'card'`, default `'pill'`), `starColor?`, `className?`
 
 ---
 
@@ -187,34 +255,29 @@ A continuously scrolling marquee of recent review snippets — ideal for homepag
 ```tsx
 import { ReviewTicker } from '@revova/hydrogen';
 
-<ReviewTicker
-  proxyUrl="/apps/revova"
-  limit={20}
-  speedSeconds={30}
-/>
+<ReviewTicker {...creds} limit={20} speedSeconds={30} />
 ```
 
-**Props:** `proxyUrl`, `limit?` (default 20), `speedSeconds?` (default 30), `starColor?`, `className?`
+**Props:** `...creds`, `limit?` (default 20), `speedSeconds?` (default 30), `starColor?`, `className?`
 
 ---
 
 ### `<SocialProofPopup>`
 
-A timed floating popup showing recent reviews one at a time. Appears after a short delay and cycles automatically.
+A timed floating popup showing recent reviews one at a time. Add once to your root layout.
 
 ```tsx
 import { SocialProofPopup } from '@revova/hydrogen';
 
-// Add once to your root layout
 <SocialProofPopup
-  proxyUrl="/apps/revova"
+  {...creds}
   position="bottom-left"
   intervalMs={8000}
   displayMs={5000}
 />
 ```
 
-**Props:** `proxyUrl`, `position?` (`'bottom-left' | 'bottom-right'`, default `'bottom-left'`), `intervalMs?` (default 8000), `displayMs?` (default 5000), `starColor?`, `className?`
+**Props:** `...creds`, `position?` (`'bottom-left' | 'bottom-right'`, default `'bottom-left'`), `intervalMs?` (default 8000), `displayMs?` (default 5000), `starColor?`, `className?`
 
 ---
 
@@ -225,15 +288,10 @@ A sticky tab fixed to the left or right edge of the viewport. Clicking it slides
 ```tsx
 import { FloatingReviewsTab } from '@revova/hydrogen';
 
-<FloatingReviewsTab
-  proxyUrl="/apps/revova"
-  label="Reviews"
-  position="right"
-  color="#111827"
-/>
+<FloatingReviewsTab {...creds} label="Reviews" position="right" />
 ```
 
-**Props:** `proxyUrl`, `label?` (default `'Reviews'`), `position?` (`'left' | 'right'`, default `'right'`), `color?`, `limit?` (default 5), `starColor?`, `className?`
+**Props:** `...creds`, `label?` (default `'Reviews'`), `position?` (`'left' | 'right'`, default `'right'`), `color?`, `limit?` (default 5), `starColor?`, `className?`
 
 ---
 
@@ -245,15 +303,14 @@ A fixed "Write a Review" button that opens a modal with the submission form.
 import { FloatingReviewButton } from '@revova/hydrogen';
 
 <FloatingReviewButton
-  proxyUrl="/apps/revova"
+  {...creds}
   productId={product.id}
   text="Write a Review"
   position="bottom-right"
-  color="#111827"
 />
 ```
 
-**Props:** `proxyUrl`, `productId`, `text?` (default `'Write a Review'`), `color?`, `position?` (`'bottom-left' | 'bottom-right'`, default `'bottom-right'`), `className?`
+**Props:** `...creds`, `productId`, `text?` (default `'Write a Review'`), `color?`, `position?` (`'bottom-left' | 'bottom-right'`, default `'bottom-right'`), `className?`
 
 ---
 
@@ -269,7 +326,7 @@ Paginated reviews for a product with sorting controls.
 import { useReviews } from '@revova/hydrogen';
 
 const { data, loading, error, setPage, setSort, currentPage, currentSort, refetch } = useReviews({
-  proxyUrl: '/apps/revova',
+  ...creds,
   productId: product.id,
   limit: 5,
   sort: 'helpful',   // 'recent' | 'helpful' | 'rating_high' | 'rating_low'
@@ -279,15 +336,12 @@ const { data, loading, error, setPage, setSort, currentPage, currentSort, refetc
 
 ### `useWidgetGlobals(options)`
 
-Shop-level stats and recent reviews. Used internally by `<ReviewCount>`, `<TrustBadge>`, `<ReviewCarousel>`, `<ReviewGallery>`, `<ReviewTicker>`, `<SocialProofPopup>`, and `<FloatingReviewsTab>`.
+Shop-level stats and recent reviews. Used internally by most global widgets.
 
 ```tsx
 import { useWidgetGlobals } from '@revova/hydrogen';
 
-const { data, loading, error } = useWidgetGlobals({
-  proxyUrl: '/apps/revova',
-  limit: 20,
-});
+const { data, loading, error } = useWidgetGlobals({ ...creds, limit: 20 });
 
 // data.stats.averageRating  — "4.8"
 // data.stats.totalReviews   — 142
@@ -295,14 +349,14 @@ const { data, loading, error } = useWidgetGlobals({
 // data.config               — merchant widget settings
 ```
 
-### `useSubmitReview(proxyUrl)`
+### `useSubmitReview(creds)`
 
 Submit a new review programmatically.
 
 ```tsx
 import { useSubmitReview } from '@revova/hydrogen';
 
-const { submit, submitting, success, error, result, reset } = useSubmitReview('/apps/revova');
+const { submit, submitting, success, error, result, reset } = useSubmitReview(creds);
 
 await submit({
   productId: 'gid://shopify/Product/123',
@@ -323,17 +377,11 @@ Fetch and submit Q&A for a product.
 ```tsx
 import { useQnA } from '@revova/hydrogen';
 
-const {
-  data,
-  loading,
-  setPage,
-  submitQuestion,
-  submitAnswer,
-  submitState,
-  resetSubmit,
-} = useQnA({ proxyUrl: '/apps/revova', productId: product.id });
-
-// Submit a question
+const { data, loading, setPage, submitQuestion, submitAnswer, submitState, resetSubmit } = useQnA({
+  ...creds,
+  productId: product.id,
+});
+
 await submitQuestion({
   intent: 'question',
   productId: product.id,
@@ -342,14 +390,14 @@ await submitQuestion({
 });
 ```
 
-### `useHelpfulVote(proxyUrl)`
+### `useHelpfulVote(creds)`
 
 Cast a helpful / not-helpful vote on a review.
 
 ```tsx
 import { useHelpfulVote } from '@revova/hydrogen';
 
-const { vote, loading, voted } = useHelpfulVote('/apps/revova');
+const { vote, loading, voted } = useHelpfulVote(creds);
 
 <button onClick={() => vote({ reviewId: review.id, vote: 'helpful' })} disabled={voted}>
   Helpful ({review.helpfulCount})