@revova/hydrogen 1.0.1 → 1.1.0

package/README.md

@@ -17,55 +17,53 @@ npm install @revova/hydrogen
 
 ## How it works
 
-Revova uses Shopify's built-in **App Proxy**. When the Revova app is installed on a store, Shopify automatically registers the route `/apps/revova` on the `myshopify.com` domain.
-
-In Hydrogen, your storefront runs on its own domain (Oxygen, Vercel, etc.), so you must pass the **absolute** proxy URL — not a relative path.
+Components and hooks call your Revova backend directly over HTTPS with a `shop` query parameter and a `Bearer` token:
 
 ```
-https://yourstore.myshopify.com/apps/revova
+GET https://yourapp.trycloudflare.com/api/reviews?shop=yourstore.myshopify.com&...
+Authorization: Bearer <apiToken>
 ```
 
-No API keys. No CORS config. Shopify handles all of it.
+No Shopify App Proxy. No CORS issues. No API keys exposed beyond what you pass in.
 
 ---
 
 ## Setup (Hydrogen)
 
-### 1 — Install the Revova app on your Shopify store
-
-Same as any merchant. The App Proxy is registered automatically on install.
-
-### 2 — Expose your store domain in the Hydrogen environment
+### 1 — Add your credentials to the environment
 
 ```env
 # .env
+PUBLIC_REVOVA_API_URL=https://yourapp.trycloudflare.com
 PUBLIC_STORE_DOMAIN=yourstore.myshopify.com
+PUBLIC_REVOVA_API_TOKEN=your_token_here
 ```
 
-Hydrogen exposes this through `context.env` in loaders:
+Expose them through your Hydrogen loader:
 
 ```ts
 // app/root.tsx or any route loader
 export async function loader({ context }: LoaderArgs) {
   return {
-    storeDomain: context.env.PUBLIC_STORE_DOMAIN,
+    apiUrl:   context.env.PUBLIC_REVOVA_API_URL,
+    shop:     context.env.PUBLIC_STORE_DOMAIN,
+    apiToken: context.env.PUBLIC_REVOVA_API_TOKEN,
   };
 }
 ```
 
-### 3 — Pass `storeDomain` (or `proxyUrl`) to any component
+### 2 — Spread credentials into any component
 
-Every component accepts either prop — use whichever is more convenient:
+Every component accepts `apiUrl`, `shop`, and `apiToken`. The easiest pattern is to spread a single `creds` object:
 
 ```tsx
-// Recommended — convenience shorthand
-<ReviewWidget storeDomain={storeDomain} productId={product.id} />
+const creds = {
+  apiUrl:   env.PUBLIC_REVOVA_API_URL,
+  shop:     env.PUBLIC_STORE_DOMAIN,
+  apiToken: env.PUBLIC_REVOVA_API_TOKEN,
+};
 
-// Explicit — same result
-<ReviewWidget
-  proxyUrl={`https://${storeDomain}/apps/revova`}
-  productId={product.id}
-/>
+<ReviewWidget {...creds} productId={product.id} />
 ```
 
 ---
@@ -74,32 +72,28 @@ Every component accepts either prop — use whichever is more convenient:
 
 ```tsx
 // app/routes/products.$handle.tsx
+import '@revova/hydrogen/styles.css'; // import once in app/root.tsx instead
 import { ReviewWidget, FloatingReviewButton } from '@revova/hydrogen';
 
 export async function loader({ context, params }: LoaderArgs) {
   const product = await getProduct(params.handle);
   return {
     product,
-    storeDomain: context.env.PUBLIC_STORE_DOMAIN,
+    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, storeDomain } = useLoaderData<typeof loader>();
+  const { product, apiUrl, shop, apiToken } = useLoaderData<typeof loader>();
+  const creds = { apiUrl, shop, apiToken };
 
   return (
     <>
       <h1>{product.title}</h1>
-
-      <ReviewWidget
-        storeDomain={storeDomain}
-        productId={product.id}
-      />
-
-      <FloatingReviewButton
-        storeDomain={storeDomain}
-        productId={product.id}
-      />
+      <ReviewWidget {...creds} productId={product.id} />
+      <FloatingReviewButton {...creds} productId={product.id} />
     </>
   );
 }
@@ -107,9 +101,19 @@ export default function ProductPage() {
 
 ---
 
-## Components
+## 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 |
+
+---
 
-All components accept either `storeDomain` **or** `proxyUrl` — never both.
+## Components
 
 ### `<ReviewWidget>`
 
@@ -119,7 +123,7 @@ Full review list with pagination, sorting, and an inline submission form.
 import { ReviewWidget } from '@revova/hydrogen';
 
 <ReviewWidget
-  storeDomain={storeDomain}
+  {...creds}
   productId={product.id}
   pageSize={10}
   showForm
@@ -129,8 +133,7 @@ import { ReviewWidget } from '@revova/hydrogen';
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `storeDomain` | `string` | — | Your `myshopify.com` domain (e.g. `yourstore.myshopify.com`) |
-| `proxyUrl` | `string` | — | Explicit proxy URL — use instead of `storeDomain` if preferred |
+| `...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 |
@@ -149,14 +152,14 @@ import { ReviewForm } from '@revova/hydrogen';
 
 // `form` comes from the ReviewsResponse returned by useReviews
 <ReviewForm
-  storeDomain={storeDomain}
+  {...creds}
   productId={product.id}
   form={data.form}
   onSuccess={() => console.log('submitted')}
 />
 ```
 
-**Props:** `storeDomain` or `proxyUrl`, `productId`, `form` (required — `ResolvedForm` from loader), `onSuccess?`, `className?`
+**Props:** `...creds`, `productId`, `form` (required — `ResolvedForm`), `onSuccess?`, `className?`
 
 ---
 
@@ -181,10 +184,10 @@ Aggregate rating + review count badge. Great for product cards and PDP headers.
 ```tsx
 import { ReviewCount } from '@revova/hydrogen';
 
-<ReviewCount storeDomain={storeDomain} starSize={14} />
+<ReviewCount {...creds} starSize={14} />
 ```
 
-**Props:** `storeDomain` or `proxyUrl`, `starColor?`, `starSize?`, `className?`
+**Props:** `...creds`, `starColor?`, `starSize?`, `className?`
 
 ---
 
@@ -195,15 +198,10 @@ Auto-advancing carousel of recent reviews. Includes previous/next arrows and dot
 ```tsx
 import { ReviewCarousel } from '@revova/hydrogen';
 
-<ReviewCarousel
-  storeDomain={storeDomain}
-  limit={10}
-  autoPlay
-  intervalMs={4000}
-/>
+<ReviewCarousel {...creds} limit={10} autoPlay intervalMs={4000} />
 ```
 
-**Props:** `storeDomain` or `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?`
 
 ---
 
@@ -214,14 +212,10 @@ Masonry photo grid of reviews that have images. Clicking any photo opens a light
 ```tsx
 import { ReviewGallery } from '@revova/hydrogen';
 
-<ReviewGallery
-  storeDomain={storeDomain}
-  columns={3}
-  limit={20}
-/>
+<ReviewGallery {...creds} columns={3} limit={20} />
 ```
 
-**Props:** `storeDomain` or `proxyUrl`, `limit?` (default 20), `columns?` (default 3), `starColor?`, `className?`
+**Props:** `...creds`, `limit?` (default 20), `columns?` (default 3), `starColor?`, `className?`
 
 ---
 
@@ -232,13 +226,10 @@ Product Q&A — lists questions with answers and includes an ask-a-question form
 ```tsx
 import { QnAWidget } from '@revova/hydrogen';
 
-<QnAWidget
-  storeDomain={storeDomain}
-  productId={product.id}
-/>
+<QnAWidget {...creds} productId={product.id} />
 ```
 
-**Props:** `storeDomain` or `proxyUrl`, `productId`, `className?`
+**Props:** `...creds`, `productId`, `className?`
 
 ---
 
@@ -249,17 +240,12 @@ Aggregate rating badge in three styles: `pill` (default), `inline`, or `card`.
 ```tsx
 import { TrustBadge } from '@revova/hydrogen';
 
-// Pill — great for footers, headers
-<TrustBadge storeDomain={storeDomain} style="pill" />
-
-// Card — great for landing pages
-<TrustBadge storeDomain={storeDomain} style="card" />
-
-// Inline — great inside sentences or product specs
-<TrustBadge storeDomain={storeDomain} style="inline" />
+<TrustBadge {...creds} style="pill" />
+<TrustBadge {...creds} style="card" />
+<TrustBadge {...creds} style="inline" />
 ```
 
-**Props:** `storeDomain` or `proxyUrl`, `style?` (`'pill' | 'inline' | 'card'`, default `'pill'`), `starColor?`, `className?`
+**Props:** `...creds`, `style?` (`'pill' | 'inline' | 'card'`, default `'pill'`), `starColor?`, `className?`
 
 ---
 
@@ -270,14 +256,10 @@ A continuously scrolling marquee of recent review snippets — ideal for homepag
 ```tsx
 import { ReviewTicker } from '@revova/hydrogen';
 
-<ReviewTicker
-  storeDomain={storeDomain}
-  limit={20}
-  speedSeconds={30}
-/>
+<ReviewTicker {...creds} limit={20} speedSeconds={30} />
 ```
 
-**Props:** `storeDomain` or `proxyUrl`, `limit?` (default 20), `speedSeconds?` (default 30), `starColor?`, `className?`
+**Props:** `...creds`, `limit?` (default 20), `speedSeconds?` (default 30), `starColor?`, `className?`
 
 ---
 
@@ -289,14 +271,14 @@ A timed floating popup showing recent reviews one at a time. Add once to your ro
 import { SocialProofPopup } from '@revova/hydrogen';
 
 <SocialProofPopup
-  storeDomain={storeDomain}
+  {...creds}
   position="bottom-left"
   intervalMs={8000}
   displayMs={5000}
 />
 ```
 
-**Props:** `storeDomain` or `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?`
 
 ---
 
@@ -307,15 +289,10 @@ A sticky tab fixed to the left or right edge of the viewport. Clicking it slides
 ```tsx
 import { FloatingReviewsTab } from '@revova/hydrogen';
 
-<FloatingReviewsTab
-  storeDomain={storeDomain}
-  label="Reviews"
-  position="right"
-  color="#111827"
-/>
+<FloatingReviewsTab {...creds} label="Reviews" position="right" />
 ```
 
-**Props:** `storeDomain` or `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?`
 
 ---
 
@@ -327,37 +304,30 @@ A fixed "Write a Review" button that opens a modal with the submission form.
 import { FloatingReviewButton } from '@revova/hydrogen';
 
 <FloatingReviewButton
-  storeDomain={storeDomain}
+  {...creds}
   productId={product.id}
   text="Write a Review"
   position="bottom-right"
-  color="#111827"
 />
 ```
 
-**Props:** `storeDomain` or `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?`
 
 ---
 
 ## Hooks
 
-Use hooks to build fully custom UIs while Revova handles data fetching. Hooks take `proxyUrl` as a plain string — use the exported `resolveProxyUrl` helper to build it from `storeDomain`.
-
-```ts
-import { resolveProxyUrl } from '@revova/hydrogen';
-
-const proxyUrl = resolveProxyUrl({ storeDomain }); // or { proxyUrl }
-```
+Use hooks to build fully custom UIs while Revova handles data fetching.
 
 ### `useReviews(options)`
 
 Paginated reviews for a product with sorting controls.
 
 ```tsx
-import { useReviews, resolveProxyUrl } from '@revova/hydrogen';
+import { useReviews } from '@revova/hydrogen';
 
 const { data, loading, error, setPage, setSort, currentPage, currentSort, refetch } = useReviews({
-  proxyUrl: resolveProxyUrl({ storeDomain }),
+  ...creds,
   productId: product.id,
   limit: 5,
   sort: 'helpful',   // 'recent' | 'helpful' | 'rating_high' | 'rating_low'
@@ -367,15 +337,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, resolveProxyUrl } from '@revova/hydrogen';
+import { useWidgetGlobals } from '@revova/hydrogen';
 
-const { data, loading, error } = useWidgetGlobals({
-  proxyUrl: resolveProxyUrl({ storeDomain }),
-  limit: 20,
-});
+const { data, loading, error } = useWidgetGlobals({ ...creds, limit: 20 });
 
 // data.stats.averageRating  — "4.8"
 // data.stats.totalReviews   — 142
@@ -383,16 +350,14 @@ const { data, loading, error } = useWidgetGlobals({
 // data.config               — merchant widget settings
 ```
 
-### `useSubmitReview(proxyUrl)`
+### `useSubmitReview(creds)`
 
 Submit a new review programmatically.
 
 ```tsx
-import { useSubmitReview, resolveProxyUrl } from '@revova/hydrogen';
+import { useSubmitReview } from '@revova/hydrogen';
 
-const { submit, submitting, success, error, result, reset } = useSubmitReview(
-  resolveProxyUrl({ storeDomain })
-);
+const { submit, submitting, success, error, result, reset } = useSubmitReview(creds);
 
 await submit({
   productId: 'gid://shopify/Product/123',
@@ -411,18 +376,10 @@ await submit({
 Fetch and submit Q&A for a product.
 
 ```tsx
-import { useQnA, resolveProxyUrl } from '@revova/hydrogen';
-
-const {
-  data,
-  loading,
-  setPage,
-  submitQuestion,
-  submitAnswer,
-  submitState,
-  resetSubmit,
-} = useQnA({
-  proxyUrl: resolveProxyUrl({ storeDomain }),
+import { useQnA } from '@revova/hydrogen';
+
+const { data, loading, setPage, submitQuestion, submitAnswer, submitState, resetSubmit } = useQnA({
+  ...creds,
   productId: product.id,
 });
 
@@ -434,14 +391,14 @@ await submitQuestion({
 });
 ```
 
-### `useHelpfulVote(proxyUrl)`
+### `useHelpfulVote(creds)`
 
 Cast a helpful / not-helpful vote on a review.
 
 ```tsx
-import { useHelpfulVote, resolveProxyUrl } from '@revova/hydrogen';
+import { useHelpfulVote } from '@revova/hydrogen';
 
-const { vote, loading, voted } = useHelpfulVote(resolveProxyUrl({ storeDomain }));
+const { vote, loading, voted } = useHelpfulVote(creds);
 
 <button onClick={() => vote({ reviewId: review.id, vote: 'helpful' })} disabled={voted}>
   Helpful ({review.helpfulCount})
@@ -452,9 +409,15 @@ const { vote, loading, voted } = useHelpfulVote(resolveProxyUrl({ storeDomain })
 
 ## Styling
 
-All components are **unstyled by default** — they render semantic HTML with inline structural styles only (layout, positioning). Pass a `className` prop and override with Tailwind, CSS Modules, or any CSS-in-JS solution.
+The package ships a bundled CSS file. Import it **once** in your app root (e.g. `app/root.tsx`):
+
+```ts
+import '@revova/hydrogen/styles.css';
+```
+
+This applies the full `rv-*` design system — cards, stars, modal, form, ticker animation, popup, gallery lightbox, and all widget layouts. All class names are prefixed `rv-` so they won't conflict with your theme styles.
 
-The `starColor` prop is available on every component that displays stars and defaults to `#f59e0b` (amber).
+To customise, pass a `className` prop on any component and override the relevant `rv-*` classes in your own CSS. The `starColor` prop (default `#f59e0b`) is available on every component that renders stars.
 
 ---