@lime-bundles/react 0.1.1 → 1.0.0

package/README.md

@@ -0,0 +1,132 @@
+# @lime-bundles/react
+
+React components and hooks for Lime Bundles on Hydrogen, Next.js, Vite, Remix, or any React renderer. BYO-cart: you pass an `onAddToCart` callback; Lime Bundles renders the UI and fires analytics.
+
+## Install
+
+```bash
+npm install @lime-bundles/react @lime-bundles/core
+```
+
+Peer dependencies: `react >=18`, `react-dom >=18`.
+
+## Components
+
+```tsx
+import { FixedBundle, VolumeBundle, MixMatchBundle } from "@lime-bundles/react";
+
+<FixedBundle
+  shopDomain="my-shop.myshopify.com"
+  storefrontAccessToken={process.env.NEXT_PUBLIC_LIME_BUNDLES_TOKEN!}
+  bundleGid="gid://shopify/Metaobject/42"
+  onAddToCart={async (lines) => {
+    await fetch("/api/cart/add", { method: "POST", body: JSON.stringify(lines) });
+  }}
+  onError={(err) => console.error(err)}
+/>
+```
+
+All three components share the same `BundleComponentProps` shape:
+
+| Prop | Type | Required | Notes |
+|---|---|:-:|---|
+| `shopDomain` | `string` | ✓ | Your shop domain. |
+| `storefrontAccessToken` | `string` | ✓ | Public Storefront Access Token. |
+| `bundleGid` | `string` | ✓ | Bundle metaobject GID. |
+| `onAddToCart` | `(lines: CartLineInput[]) => Promise<void>` | ✓ | Must return a Promise. Components `await` it for loading states. |
+| `appUrl` | `string` |  | Required only if `analyticsEnabled !== false`. |
+| `analyticsEnabled` | `boolean` |  | Default `true`. Set `false` to disable impression / add-to-cart POSTs. |
+| `onError` | `(error: Error) => void` |  | Fires on `StorefrontApiError`, `BundleParseError`, or errors thrown from `onAddToCart`. |
+| `locale` | `string` |  | BCP-47 locale tag. |
+| `className` | `string` |  | Applied to the outer wrapper. |
+
+The `CartLineInput` shape matches Shopify Hydrogen's. A structural-compat type test guards this across versions.
+
+## Hooks
+
+### `useBundleData`
+
+Client-side hook. Returns a discriminated union locked at v1.0.0:
+
+```tsx
+import { useBundleData } from "@lime-bundles/react";
+
+function MyBundle({ bundleGid }: { bundleGid: string }) {
+  const result = useBundleData({
+    shopDomain: "my-shop.myshopify.com",
+    storefrontAccessToken: TOKEN,
+    bundleGid,
+  });
+
+  if (result.status === "loading") return <Skeleton />;
+  if (result.status === "error") return <Error message={result.error.message} />;
+
+  // result.status === "success": result.bundle is a ParsedBundle
+  return <pre>{JSON.stringify(result.bundle, null, 2)}</pre>;
+}
+```
+
+Fetches custom CSS in parallel and injects a scoped `<style>` tag on success. No action needed from you.
+
+Unmounting or changing the bundle GID cancels the in-flight request via `AbortController`.
+
+## Async fetcher for RSC / SSR
+
+Use `fetchBundleData` in a server component, Next.js `getServerSideProps`, or any non-React async context:
+
+```ts
+import { fetchBundleData } from "@lime-bundles/react";
+
+const bundle = await fetchBundleData({
+  shopDomain: "my-shop.myshopify.com",
+  storefrontAccessToken: process.env.LIME_BUNDLES_TOKEN!,
+  bundleGid: "gid://shopify/Metaobject/42",
+  buyerIp: request.headers.get("x-forwarded-for")?.split(",")[0].trim() ?? undefined,
+});
+```
+
+`buyerIp` is required on SSR. Shopify may return `430 Security Rejection` for server-originated traffic on a private token without it. Pull the real client IP from whichever header your host sets (`x-forwarded-for` on Oxygen/Vercel/most hosts, `cf-connecting-ip` on Cloudflare, etc).
+
+Throws:
+- `StorefrontApiError`: network, HTTP, or GraphQL errors.
+- `BundleParseError`: metaobject missing, invalid type, inactive, not started, or expired. `error.reason` is a typed literal.
+
+## The cart contract
+
+`onAddToCart` receives Hydrogen-compatible cart lines:
+
+```ts
+type CartLineInput = {
+  merchandiseId: string;       // variant GID
+  quantity: number;
+  attributes: Array<{ key: string; value: string }>;
+};
+```
+
+Always preserve `attributes[].{key: "_lime_bundle_gid"}` on its way to Shopify. The `orders/create` webhook uses it for purchase attribution.
+
+## Styling
+
+Override CSS custom properties on any wrapping element:
+
+```tsx
+<div style={{ "--lb-primary-color": "#e91e63" } as React.CSSProperties}>
+  <FixedBundle ... />
+</div>
+```
+
+Full reference: [css-variables.md](https://github.com/lime-app-dev/lime-bundles-app/blob/main/docs/headless/css-variables.md).
+
+## Versioning
+
+Major versions bump together across `core`, `react`, and `widget`. The hook's `UseBundleDataResult` type and `BundleComponentProps` are locked at v1.0.0.
+
+## License
+
+MIT. See repo root.
+
+## Links
+
+- [Hydrogen guide](https://github.com/lime-app-dev/lime-bundles-app/blob/main/docs/headless/hydrogen.md)
+- [React / Next.js guide](https://github.com/lime-app-dev/lime-bundles-app/blob/main/docs/headless/react-nextjs.md)
+- [Report issues](https://github.com/lime-app-dev/lime-bundles-app/issues)