vetir-style-this-piece 1.0.0

package/README.md

@@ -0,0 +1,568 @@
+# vetir-style-this-piece
+
+A React component that adds **AI outfit suggestions** to any product page. The shopper sees a "Style this Piece" button, clicks it, and gets a carousel of complete outfits built around that product.
+
+Works with **Vite**, **Create React App**, **Next.js**, or any React 16.8+ app.
+
+## Preview
+
+![Style This Piece demo — click to stream outfits and browse results](https://unpkg.com/vetir-style-this-piece/docs/style-this-piece-demo-flow.gif)
+
+_Live demo showing multiple banner configurations (custom CTA, brand colours, compact button) and AI outfit results._
+
+---
+
+## What it does
+
+1. You place the component on a product page.
+2. The shopper clicks the banner button.
+3. The library calls your AI stylist API and **streams outfit results** in real time.
+4. Outfits appear as cards below the banner (or on a page you build yourself).
+
+You do **not** need to write the API call, loading states, or carousel — the default component handles all of that.
+
+---
+
+## Before you start
+
+Make sure you have these ready:
+
+| You need              | What it is                                                               |
+| --------------------- | ------------------------------------------------------------------------ |
+| **Partner API token** | A key from your API provider. The library sends this with every request. |
+| **API base URL**      | Your stylist API root URL (e.g. `https://api.example.com/s1/`).          |
+| **Product ID**        | The ID of the product on the page (from your product data).              |
+| **User ID**           | A user ID or guest ID string. Required for the API to work.              |
+| **React app**         | React 16.8 or newer (`react` and `react-dom` installed in your project). |
+
+> Pass `productId`, `userId`, `token`, and `apiBaseUrl`. If any are missing, the banner shows a clear error message. The library does not ship a default API URL.
+
+---
+
+## Step-by-step setup
+
+### Step 1 — Install the package
+
+```bash
+npm install vetir-style-this-piece
+```
+
+Run this in your project folder (the same place as your `package.json`). After installing, you should see it inside `node_modules/vetir-style-this-piece/`.
+
+### Step 2 — Import the CSS (once)
+
+Add this **one line** to your app entry file. If you skip this, the banner and cards will look unstyled.
+
+**Vite / Create React App** — `src/main.jsx` or `src/index.js`:
+
+```js
+import "vetir-style-this-piece/style.css";
+```
+
+**Next.js** — `pages/_app.js` or `app/layout.js`:
+
+```js
+import "vetir-style-this-piece/style.css";
+```
+
+### Step 3 — Add the component to your product page
+
+```jsx
+import StyleThisPiece from "vetir-style-this-piece";
+
+function ProductPage({ product }) {
+  const userId = getLoggedInUserId() || getGuestUserId();
+  const apiToken = import.meta.env.VITE_STP_API_KEY;
+  const apiBaseUrl = import.meta.env.VITE_STP_API_BASE_URL;
+
+  return (
+    <div>
+      {/* your existing product details */}
+      <h1>{product.name}</h1>
+
+      <StyleThisPiece
+        productId={product.id}
+        userId={userId}
+        token={apiToken}
+        apiBaseUrl={apiBaseUrl}
+      />
+    </div>
+  );
+}
+```
+
+That is the **minimum** working setup. The banner appears, outfits stream in below it when clicked.
+
+### Step 4 — Add a "Shop the look" button (optional)
+
+By default, outfit cards have no button. Pass `onCardCta` to handle clicks:
+
+```jsx
+<StyleThisPiece
+  productId={product.id}
+  userId={userId}
+  token={apiToken}
+  apiBaseUrl={apiBaseUrl}
+  cardCtaText="Shop The Look"
+  onCardCta={(outfit) => {
+    // outfit is an array of products (top, bottom, shoes, bag, etc.)
+    openOutfitModal(outfit);
+  }}
+/>
+```
+
+### Step 5 — Match your brand (optional)
+
+Override text and colours with props — no CSS file edits needed:
+
+```jsx
+<StyleThisPiece
+  productId={product.id}
+  userId={userId}
+  token={apiToken}
+  apiBaseUrl={apiBaseUrl}
+  bannerText="See how to wear this piece."
+  ctaText="Get Outfit Ideas"
+  ctaStyle={{ background: "#000", color: "#fff" }}
+/>
+```
+
+---
+
+## Understanding the required props
+
+| Prop        | In plain English                                                                                                                                          |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `productId` | Which product to build outfits around. Use the same ID your catalogue uses.                                                                               |
+| `userId`    | Who is asking for outfits. Use a real user ID or a guest ID. If empty, the banner shows **"User ID is required"**.                                        |
+| `token`       | Your partner API key. If empty, the banner shows **"API token is required"**. |
+| `apiBaseUrl`  | Your stylist API base URL. If empty, the banner shows **"API base URL is required"**. Not hardcoded in the library — you must pass it. |
+
+**Guest users:** Most apps pass `authUserId || guestUserId`. As long as `userId` is a non-empty string, the API is called.
+
+**Token security:** Load the token from your server or a build-time env var (e.g. `import.meta.env.VITE_STP_TOKEN`). The token is sent from the browser to the stylist API.
+
+---
+
+## What happens when the user clicks
+
+```
+User clicks "Style this Piece"
+        ↓
+Is productId set? ──no──→  Banner shows "Product ID is required"
+        │
+       yes
+        ↓
+Is userId set?    ──no──→  Banner shows "User ID is required"
+        │
+       yes
+        ↓
+Is token set?     ──no──→  Banner shows "API token is required"
+        │
+       yes
+        ↓
+Is apiBaseUrl set? ──no──→  Banner shows "API base URL is required"
+        │
+       yes
+        ↓
+Library calls the streaming API with productId + userId + token + apiBaseUrl
+        ↓
+Outfits arrive one by one (loading spinner while waiting)
+        ↓
+Cards appear in a horizontal carousel below the banner
+        ↓
+User clicks a card CTA (if you provided onCardCta)
+        ↓
+Your onCardCta(outfit) runs with the full outfit array
+```
+
+---
+
+## Choose your integration style
+
+| Approach                 | Best for                                             | What you use                                                       |
+| ------------------------ | ---------------------------------------------------- | ------------------------------------------------------------------ |
+| **All-in-one** (easiest) | Most product pages                                   | `<StyleThisPiece />` — banner, API, and results included           |
+| **Hook + banner**        | Custom results UI (new page, modal, your own layout) | `useStyleThisPieceOutfits` + `StyleThisPieceBanner`                |
+| **Full control**         | Completely custom flow                               | Hook + `StyleThisPieceBanner` + `StyleThisPieceResults` separately |
+
+**Start with the all-in-one component.** Only switch to the hook if you need to render results somewhere else.
+
+---
+
+## Examples
+
+### Example 1 — Custom results page (hook + banner)
+
+**When to use:** You want outfits on a separate page or in your own design — not the built-in carousel.
+
+The hook fetches outfits. The banner is just the trigger button. You decide where results go.
+
+**Trigger (product page):**
+
+```jsx
+import {
+  StyleThisPieceBanner,
+  useStyleThisPieceOutfits,
+} from "vetir-style-this-piece";
+
+function StyleTrigger({ productId, userId, token, apiBaseUrl, onSeeResults }) {
+  const { outfits, isLoading, error, generateOutfits } =
+    useStyleThisPieceOutfits({
+      productId,
+      userId,
+      token,
+      baseUrl: apiBaseUrl,
+    });
+
+  const hasResults = outfits.length > 0;
+
+  return (
+    <>
+      <StyleThisPieceBanner
+        isLoading={isLoading}
+        error={hasResults ? null : error}
+        onGenerate={generateOutfits}
+        showCtaIcon={false}
+      />
+      {hasResults && (
+        <button type="button" onClick={() => onSeeResults(outfits)}>
+          See Results
+        </button>
+      )}
+    </>
+  );
+}
+```
+
+**Results page (your own UI):**
+
+```jsx
+function OutfitResultsPage({ outfits }) {
+  return (
+    <ul>
+      {outfits.map((outfit, i) => (
+        <li key={i}>
+          <h2>Look {i + 1}</h2>
+          <ul>
+            {outfit.map((product) => (
+              <li key={product.id}>
+                <img src={product.imageUrls?.[0]} alt={product.productName} />
+                <span>
+                  {product.brandName} — {product.productName}
+                </span>
+                <span>${product.productPrice?.toLocaleString()}</span>
+                {product.productButtonLink && (
+                  <a
+                    href={product.productButtonLink}
+                    target="_blank"
+                    rel="noreferrer"
+                  >
+                    View
+                  </a>
+                )}
+              </li>
+            ))}
+          </ul>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+**Wire with your router:**
+
+```jsx
+<StyleTrigger
+  productId={productId}
+  userId={userId}
+  token={token}
+  apiBaseUrl={apiBaseUrl}
+  onSeeResults={(outfits) => navigate("/outfits", { state: { outfits } })}
+/>
+```
+
+---
+
+### Example 2 — Custom card CTA text
+
+Change the button label on each outfit card:
+
+```jsx
+<StyleThisPiece
+  productId={productId}
+  userId={userId}
+  token={token}
+  apiBaseUrl={apiBaseUrl}
+  cardCtaText="Explore This Look"
+  onCardCta={(outfit) => openOutfitModal(outfit)}
+/>
+```
+
+---
+
+### Example 3 — Brand colours and copy override
+
+Change all visible text and colours without touching CSS files:
+
+```jsx
+<StyleThisPiece
+  productId={productId}
+  userId={userId}
+  token={token}
+  apiBaseUrl={apiBaseUrl}
+  bannerText="Discover complete looks featuring this item."
+  ctaText="Get Styled"
+  resultsTitle="Complete The Look"
+  resultsDescription="AI-curated outfits built around your selection."
+  bannerStyle={{ background: "white", borderColor: "#444" }}
+  ctaStyle={{ background: "#d4af37", color: "#000" }}
+/>
+```
+
+---
+
+### Example 4 — Compact round CTA + card extras
+
+A small round icon button and extra info under each card (item count, total price):
+
+```jsx
+<StyleThisPiece
+  productId={productId}
+  userId={userId}
+  token={token}
+  apiBaseUrl={apiBaseUrl}
+  bannerText=""
+  ctaText=""
+  bannerStyle={{ borderRadius: 60, padding: "8px", width: 120, height: 120 }}
+  ctaStyle={{
+    width: 60,
+    padding: 0,
+    justifyContent: "center",
+    height: 60,
+    borderRadius: 60,
+  }}
+  renderCardExtra={(outfit) => (
+    <div style={{ padding: "8px 12px", fontSize: 12, color: "#555" }}>
+      {outfit.length} items · Est. $
+      {outfit.reduce((s, p) => s + (p.productPrice || 0), 0).toLocaleString()}
+    </div>
+  )}
+/>
+```
+
+---
+
+### Example 5 — Custom label above the carousel
+
+Add a branded strip above the outfit cards:
+
+```jsx
+<StyleThisPiece
+  productId={productId}
+  userId={userId}
+  token={token}
+  apiBaseUrl={apiBaseUrl}
+  renderResultsHeader={() => (
+    <div
+      style={{
+        padding: "8px 16px",
+        background: "#222",
+        color: "#fff",
+        fontSize: 12,
+        letterSpacing: 2,
+        textTransform: "uppercase",
+        textAlign: "center",
+      }}
+    >
+      ✦ Styled by AI · Personalised for you
+    </div>
+  )}
+/>
+```
+
+---
+
+### Full production integration
+
+Everything together: custom API URL, results in a specific page section, card CTA, header, and styling:
+
+```jsx
+const resultsRef = useRef(null);
+
+<StyleThisPiece
+  productId={productId}
+  userId={userId}
+  token={token}
+  apiBaseUrl={apiBaseUrl}
+  gender="female"
+  resultsContainerRef={resultsRef}
+  cardCtaText="Shop The Look"
+  onCardCta={(outfit) => openOutfitModal(outfit)}
+  renderResultsHeader={() => (
+    <div
+      style={{
+        padding: "8px 16px",
+        background: "#222",
+        color: "#fff",
+        fontSize: 12,
+      }}
+    >
+      ✦ AI Stylist Picks
+    </div>
+  )}
+  renderCardExtra={(outfit) => (
+    <div style={{ padding: "8px 12px", fontSize: 12, color: "#555" }}>
+      {outfit.length} items
+    </div>
+  )}
+  resultsTitle="Styled For You"
+  resultsDescription="AI-curated outfits built around this piece."
+  bannerStyle={{ borderColor: "#333" }}
+  ctaStyle={{ background: "#c9a96e" }}
+/>;
+
+{
+  /* Results render inside this div instead of below the banner */
+}
+<div ref={resultsRef} />;
+```
+
+`resultsContainerRef` lets you control **where** on the page the carousel appears — useful if your layout has a sidebar or a dedicated "stylist" section.
+
+---
+
+## Props reference
+
+### `StyleThisPiece` (default export — recommended)
+
+| Prop                              | Required | Description                                                            |
+| --------------------------------- | -------- | ---------------------------------------------------------------------- |
+| `productId`                       | ✅       | Product to style                                                       |
+| `userId`                          | ✅       | User or guest ID. Empty → banner shows "User ID is required"           |
+| `token`                           | ✅       | Partner API key                                                        |
+| `apiBaseUrl`                      | ✅       | Stylist API base URL. Empty → banner shows "API base URL is required"  |
+| `gender`                          | —        | `female` (default) or `male`                                           |
+| `country`                         | —        | Region for pricing. Default: from cookie or `United States of America` |
+| `hideBannerOnResults`             | —        | Hide banner once results show. Default `false`                         |
+| `resultsContainerRef`             | —        | Render results inside this DOM element instead of inline               |
+| `onCardCta`                       | —        | Called when card button clicked. Button only shows if this is set      |
+| `cardCtaText`                     | —        | Card button label (e.g. `"Shop The Look"`)                             |
+| `renderResultsHeader`             | —        | Custom JSX above the carousel                                          |
+| `renderCardExtra`                 | —        | Custom JSX inside each outfit card                                     |
+| `bannerText`                      | —        | Text next to the CTA button                                            |
+| `ctaText`                         | —        | CTA button label                                                       |
+| `showCtaIcon`                     | —        | Show sparkle icon. Default `true`                                      |
+| `ctaIcon`                         | —        | Replace sparkle with your own image URL                                |
+| `resultsTitle`                    | —        | Heading above the carousel                                             |
+| `resultsDescription`              | —        | Subheading above the carousel                                          |
+| `bannerStyle` / `ctaStyle` / etc. | —        | Inline styles to match your brand                                      |
+
+### Named exports (advanced)
+
+```jsx
+import {
+  StyleThisPieceBanner,
+  StyleThisPieceResults,
+  StyleThisPieceOutfitCard,
+  useStyleThisPieceOutfits,
+} from "vetir-style-this-piece";
+```
+
+#### `useStyleThisPieceOutfits`
+
+```ts
+const {
+  outfits,         // array of outfits; each outfit is an array of products
+  isLoading,       // true until the first outfit arrives
+  isStreaming,     // true while more outfits are still coming in
+  hasStarted,      // true after the user clicked generate
+  error,           // error message string, or null
+  generateOutfits, // call this to start (wired to banner button)
+  reset,           // go back to the initial banner state
+} = useStyleThisPieceOutfits({
+  productId,
+  userId,
+  token,
+  baseUrl,         // required — same as apiBaseUrl on the main component
+  gender?,
+  country?,
+});
+```
+
+---
+
+## What you get back from the API
+
+Each **outfit** is an array of **products** (typically top, bottom, shoes, bag, jewelry):
+
+```ts
+interface OutfitProduct {
+  id: string;
+  productId: string;
+  brandName: string;
+  productName: string;
+  productPrice: number;
+  imageUrls: string[]; // use imageUrls[0] for the card image
+  productColor: string;
+  categoryName: string;
+  aiCategoryName: "top" | "bottom" | "footwear" | "bag" | "jewelry";
+  productSizes: string[];
+  productButtonLink: string; // link to buy this item
+  returnObject: { url: string; text: string };
+  gender: string;
+  country: string[];
+}
+```
+
+When `onCardCta` or `renderCardExtra` fires, you receive one full outfit array — loop over it to show each item.
+
+---
+
+## Troubleshooting
+
+| Problem                                                 | Likely cause             | Fix                                                          |
+| ------------------------------------------------------- | ------------------------ | ------------------------------------------------------------ |
+| `Failed to resolve import "vetir-style-this-piece"`           | Package not installed    | Run `npm install` in your project                            |
+| `Failed to resolve import "vetir-style-this-piece/style.css"` | Same as above            | Run `npm install`, then restart dev server                   |
+| Banner looks broken / no styles                         | CSS not imported         | Add `import 'vetir-style-this-piece/style.css'` to your entry file |
+| Banner says "Product ID is required"                    | `productId` is empty     | Pass the product ID from your product data                   |
+| Banner says "User ID is required"                       | `userId` is empty        | Pass `authUserId \|\| guestUserId`                           |
+| Banner says "API token is required"                     | `token` prop missing     | Pass your partner API key                                    |
+| Banner says "API base URL is required"                  | `apiBaseUrl` missing     | Pass your stylist API base URL                               |
+| Stream fails / Retry shown                              | Bad token or API error   | Check token value and API base URL                           |
+| Card has no button                                      | `onCardCta` not provided | Add `onCardCta` and `cardCtaText` together                   |
+| Results in wrong place                                  | Layout issue             | Use `resultsContainerRef` to target a specific `<div>`       |
+
+---
+
+## Peer dependencies
+
+Your app must already have React installed:
+
+```json
+"react": ">=16.8.0",
+"react-dom": ">=16.8.0"
+```
+
+The library does not bundle React — it uses yours.
+
+---
+
+## Local development (yalc)
+
+For testing unreleased changes in another project:
+
+```bash
+# In this repo — after every change:
+npm run push
+
+# In consumer — one-time setup:
+yalc add vetir-style-this-piece
+yarn install
+```
+
+---
+
+More examples: [USAGE.md](./USAGE.md)