@eetech-commerce/cart-react 0.4.1

package/README.md

@@ -0,0 +1,356 @@
+# @eetech-commerce/cart-react
+
+React hooks and provider for interacting with the EETech Commerce Cart API.
+
+## Installation
+
+```bash
+npm install @eetech-commerce/cart-react
+# or
+yarn add @eetech-commerce/cart-react
+# or
+pnpm add @eetech-commerce/cart-react
+# or
+bun add @eetech-commerce/cart-react
+```
+
+For payment features (optional):
+
+```bash
+npm install @stripe/stripe-js
+```
+
+## Quick Start
+
+```tsx
+import {
+  CartProvider,
+  useCart,
+  useAddToCart,
+} from '@eetech-commerce/cart-react';
+
+function App() {
+  return (
+    <CartProvider
+      tenantSlug="my-store"
+      cartApiUrl="https://cart.api.com"
+    >
+      <Shop />
+    </CartProvider>
+  );
+}
+
+function Shop() {
+  const { data: cart, isLoading } = useCart();
+  const { addToCart, isPending } = useAddToCart();
+
+  if (isLoading) return <div>Loading cart...</div>;
+
+  return (
+    <div>
+      <h2>Cart ({cart?.items.length ?? 0} items)</h2>
+      <button
+        onClick={() => addToCart({ offerId: 'offer-123', quantity: 1 })}
+        disabled={isPending}
+      >
+        Add Item
+      </button>
+    </div>
+  );
+}
+```
+
+## CartProvider Configuration
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `tenantSlug` | `string` | Yes | - | Your tenant identifier |
+| `cartApiUrl` | `string` | Yes | - | Base URL of the cart API |
+| `storageAdapter` | `StorageAdapter` | No | `localStorage` | Custom storage implementation |
+| `autoInitialize` | `boolean` | No | `true` | Auto-create cart on mount |
+| `queryClient` | `QueryClient` | No | - | Custom TanStack Query client instance |
+
+## Hooks Reference
+
+### Cart Hooks
+
+| Hook | Description |
+|------|-------------|
+| `useCart()` | Fetch the current cart |
+| `useCreateCart()` | Create a new cart |
+| `useAddToCart()` | Add an item to the cart |
+| `useUpdateItemQty()` | Update item quantity |
+| `useRemoveItem()` | Remove an item from cart |
+| `useClearCart()` | Clear all items from cart |
+| `useInitializeCart()` | Manually initialize cart (for `autoInitialize={false}`) |
+
+### Checkout Hooks
+
+| Hook | Description |
+|------|-------------|
+| `useVerifyCart()` | Verify cart items before checkout |
+| `useCreateCheckoutSession()` | Create a checkout session |
+| `useShippingOptions(cartSessionId)` | Fetch available shipping options |
+| `useUpdateShippingSelections()` | Update selected shipping options |
+
+### Payment Hooks
+
+| Hook | Description |
+|------|-------------|
+| `useStripePromise()` | Get the Stripe.js instance |
+| `useCreateEmbeddedCheckoutSession()` | Create an embedded payment session |
+| `usePaymentSession(sessionId)` | Fetch payment session details |
+
+### Context Hook
+
+| Hook | Description |
+|------|-------------|
+| `useCartContext()` | Access cart context (tenantSlug, cartSessionId, etc.) |
+
+## Mutation Callbacks
+
+All mutation hooks support optional callbacks for success and error handling:
+
+```tsx
+const { addToCart } = useAddToCart();
+
+addToCart(
+  { offerId: 'offer-123', quantity: 1 },
+  {
+    onSuccess: (cart) => {
+      toast('Added to cart!');
+    },
+    onError: (error) => {
+      toast.error(error.message);
+    },
+  }
+);
+```
+
+## Custom Storage Adapter
+
+By default, the cart session ID is stored in `localStorage`. You can provide a custom storage adapter for different storage mechanisms:
+
+### Interface
+
+```typescript
+interface StorageAdapter {
+  get(key: string): string | null;
+  set(key: string, value: string): void;
+  remove(key: string): void;
+}
+```
+
+### Example: Cookie Adapter
+
+```tsx
+import { CartProvider, type StorageAdapter } from '@eetech-commerce/cart-react';
+import Cookies from 'js-cookie';
+
+const cookieAdapter: StorageAdapter = {
+  get: (key) => Cookies.get(key) ?? null,
+  set: (key, value) => Cookies.set(key, value, { expires: 7 }),
+  remove: (key) => Cookies.remove(key),
+};
+
+function App() {
+  return (
+    <CartProvider
+      tenantSlug="my-store"
+      cartApiUrl="https://cart.api.com"
+      storageAdapter={cookieAdapter}
+    >
+      <Shop />
+    </CartProvider>
+  );
+}
+```
+
+## Manual Cart Initialization
+
+By default, `CartProvider` automatically creates a cart on mount. If you need more control over when the cart is created, set `autoInitialize={false}`:
+
+```tsx
+import {
+  CartProvider,
+  useInitializeCart,
+  useCartContext,
+} from '@eetech-commerce/cart-react';
+
+function App() {
+  return (
+    <CartProvider
+      tenantSlug="my-store"
+      cartApiUrl="https://cart.api.com"
+      autoInitialize={false}
+    >
+      <CartInitializer />
+      <Shop />
+    </CartProvider>
+  );
+}
+
+function CartInitializer() {
+  const { isInitializing } = useInitializeCart();
+  const { cartSessionId } = useCartContext();
+
+  if (isInitializing) {
+    return <div>Initializing cart...</div>;
+  }
+
+  return null;
+}
+```
+
+This is useful when you want to:
+- Delay cart creation until user interaction
+- Initialize the cart conditionally based on route or user state
+- Handle initialization loading states explicitly
+
+## Using with Existing QueryClient
+
+If your application already uses TanStack Query, you can pass your existing `QueryClient` to share the cache:
+
+```tsx
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { CartProvider } from '@eetech-commerce/cart-react';
+
+const queryClient = new QueryClient();
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <CartProvider
+        tenantSlug="my-store"
+        cartApiUrl="https://cart.api.com"
+        queryClient={queryClient}
+      >
+        <Shop />
+      </CartProvider>
+    </QueryClientProvider>
+  );
+}
+```
+
+Benefits of sharing the QueryClient:
+- Unified cache management across your application
+- Shared devtools integration
+- Consistent query/mutation defaults
+
+## Payment Hooks (Stripe)
+
+To use payment features, install `@stripe/stripe-js`:
+
+```bash
+npm install @stripe/stripe-js
+```
+
+### Using useStripePromise
+
+The `useStripePromise` hook automatically fetches your tenant's Stripe publishable key and initializes Stripe.js:
+
+```tsx
+import { useStripePromise } from '@eetech-commerce/cart-react';
+import { Elements } from '@stripe/react-stripe-js';
+
+function CheckoutPage() {
+  const stripePromise = useStripePromise();
+
+  if (!stripePromise) {
+    return <div>Loading payment provider...</div>;
+  }
+
+  return (
+    <Elements stripe={stripePromise}>
+      <PaymentForm />
+    </Elements>
+  );
+}
+```
+
+### Creating an Embedded Checkout Session
+
+```tsx
+import {
+  useCreateEmbeddedCheckoutSession,
+  useCartContext,
+} from '@eetech-commerce/cart-react';
+
+function CheckoutButton() {
+  const { cartSessionId } = useCartContext();
+  const { createEmbeddedCheckoutSession, isPending, data } =
+    useCreateEmbeddedCheckoutSession();
+
+  const handleCheckout = () => {
+    createEmbeddedCheckoutSession(
+      {
+        cartSessionId: cartSessionId!,
+        returnUrl: 'https://my-store.com/checkout/complete',
+      },
+      {
+        onSuccess: (session) => {
+          // Use session.clientSecret with Stripe Embedded Checkout
+          console.log('Session created:', session.id);
+        },
+        onError: (error) => {
+          console.error('Failed to create session:', error);
+        },
+      }
+    );
+  };
+
+  return (
+    <button onClick={handleCheckout} disabled={isPending}>
+      {isPending ? 'Creating session...' : 'Checkout'}
+    </button>
+  );
+}
+```
+
+## TypeScript
+
+This package is fully typed. All hooks, providers, and utilities include TypeScript definitions.
+
+### Exported Types
+
+```typescript
+import type {
+  // Provider
+  CartProviderProps,
+  CartContextValue,
+
+  // Storage
+  StorageAdapter,
+
+  // Mutation callbacks
+  MutationCallbacks,
+
+  // API types
+  CartResponseDto,
+  LineItemResponseDto,
+  CreateCheckoutDto,
+  VerificationResultDto,
+  ShippingOptionDto,
+  ShippingSelectionDto,
+  CreateEmbeddedPaymentSessionDto,
+  EmbeddedPaymentSessionResponseDto,
+} from '@eetech-commerce/cart-react';
+```
+
+## Advanced: Query Keys
+
+For advanced cache control, query key factories are exported:
+
+```typescript
+import { cartKeys, shippingKeys, paymentKeys } from '@eetech-commerce/cart-react';
+
+// Invalidate all cart queries
+queryClient.invalidateQueries({ queryKey: cartKeys.all() });
+
+// Invalidate shipping options
+queryClient.invalidateQueries({ queryKey: shippingKeys.all() });
+```
+
+## License
+
+MIT