hey-pharmacist-ecommerce 1.0.5 → 1.0.7

package/README.md

@@ -1,16 +1,17 @@
-# Hey Pharmacist E-commerce Package
+# Hey Pharmacist E‑commerce
 
-A multi-tenant e-commerce package for Next.js applications with stunning design and full functionality.
+Production‑ready, multi‑tenant e‑commerce UI + API adapter for Next.js. It ships with end‑to‑end flows (browse, cart, checkout, orders), robust authentication, typed SDKs, and a polished pharmacist‑grade UX. Drop it into a Next.js app, point it at your API, and ship a beautiful store in hours—not weeks.
 
-## Features
+## Highlights
 
-- 🛒 **Complete E-commerce Flow**: Shop, cart, checkout, orders
-- 🎨 **Stunning Design**: Modern UI with smooth animations
-- 🔐 **Authentication**: Login, register, profile management
-- 💳 **Stripe Integration**: Secure payment processing
-- 🏪 **Multi-tenant**: Single package, multiple stores
-- 📱 **Responsive**: Works on all devices
-- ⚡ **Fast**: Optimized for performance
+- 🛒 **Complete flows**: Shop, product details, wishlist, cart, checkout, orders (history + current)
+- 🔐 **Auth built‑in**: Sign up/in, profile, token persistence, background rehydration
+- 💳 **Payments**: Card/Cash/Credit modes; Stripe‑ready checkout handoff
+- 🧩 **Typed API adapters**: Generated axios SDK under `src/lib/Apis` with bearer + store key headers
+- 🎨 **Themeable**: Brand colors + configurable header gradient via `EcommerceConfig`
+- 🧠 **Smart UX**: Skeletons, optimistic UI, searchable overflow filters, and mobile‑first layouts
+- 🧱 **Composable**: Use our screens, or import atomic components and hooks
+- ⚡ **Production‑grade**: Tree‑shakable build, types, sourcemaps, React 18, Next 14
 
 ## Installation
 
@@ -20,7 +21,7 @@ npm install hey-pharmacist-ecommerce react-hook-form @hookform/resolvers
 
 ## Quick Start
 
-### 1. Configure Your Store
+### 1) Configure your store
 
 Create a config file for your store:
 
@@ -40,7 +41,7 @@ export const ecommerceConfig = {
 };
 ```
 
-### 2. Wrap Your App
+### 2) Wrap your app
 
 ```tsx
 // app/layout.tsx
@@ -64,7 +65,7 @@ export default function RootLayout({
 }
 ```
 
-### 3. Use the Screens
+### 3) Use the screens
 
 ```tsx
 // app/shop/page.tsx
@@ -75,7 +76,7 @@ export default function ShopPage() {
 }
 ```
 
-## Available Screens
+## Available screens
 
 - `<ShopScreen />` - Product listing with filters
 - `<ProductDetailScreen />` - Individual product page
@@ -87,9 +88,26 @@ export default function ShopPage() {
 - `<OrdersScreen />` - Order history
 - `<CurrentOrdersScreen />` - Active orders
 
-## Customization
+## Theming and customization
 
-The package uses CSS variables for theming. Your colors are automatically applied throughout the interface.
+The package exposes CSS variables for theme colors and a dynamic header gradient. Update via `EcommerceConfig`:
+
+```ts
+headerGradient?: { from: string; via: string; to: string } // hex colors
+```
+
+Under the hood, `ThemeProvider` sets `--color-<brand>-<shade>` and:
+
+```css
+from: rgb(var(--header-from));
+via:  rgb(var(--header-via));
+to:   rgb(var(--header-to));
+```
+
+Update colors/gradient at runtime and the UI updates automatically.
+
+### Using individual components
+You can import components like `Header`, `Footer`, `ProductCard`, `OrderCard`, and UI primitives (`Button`, `Input`, `Modal`, etc.) for bespoke pages.
 
 ## Requirements
 
@@ -97,6 +115,128 @@ The package uses CSS variables for theming. Your colors are automatically applie
 - Next.js 14+
 - react-hook-form 7+
 
+## Architecture
+
+- Screens (page‑level flows) under `src/screens`
+- Providers for Auth, Cart, Wishlist, Theme under `src/providers`
+- Hooks for products, orders, wishlist, addresses under `src/hooks`
+- Generated API SDK under `src/lib/Apis` (axios + typed models)
+- API adapter bridge under `src/lib/api-adapter`
+
+Auth persists access token using `localStorage` and rehydrates on load. Requests attach `x-store-key` and `Authorization: Bearer` automatically.
+
+## Local development & testing
+
+### Testing locally before publishing
+
+You can test the package locally in your frontend project using npm link:
+
+#### Step 1: Build and Link the Package
+
+In this package directory:
+
+```bash
+# Build the package
+npm run build
+
+# Create a global symlink
+npm link
+```
+
+For active development with auto-rebuild:
+
+```bash
+# Watch mode - rebuilds on file changes
+npm run build:watch
+```
+
+#### Step 2: Link in Your Frontend Project
+
+In your frontend project directory:
+
+```bash
+# Link to the local package
+npm link hey-pharmacist-ecommerce
+
+# Install peer dependencies if not already installed
+npm install react react-dom next react-hook-form @hookform/resolvers
+```
+
+#### Step 3: Use the Package
+
+Now you can use the package in your frontend as if it were installed from npm:
+
+```typescript
+// app/ecommerce.config.ts
+import { EcommerceConfig } from 'hey-pharmacist-ecommerce';
+
+export const config: EcommerceConfig = {
+  storeId: '68e3b34ca07948e882f9418f',
+  storeName: 'Briarmill Pharmacy',
+  logo: '/logo.png',
+  colors: {
+    primary: '#EF821F',
+    secondary: '#8B5CF6',
+    accent: '#10B981',
+  },
+  apiBaseUrl: 'https://api.heypharmacist.com',
+  stripePublicKey: 'pk_test_...',
+};
+```
+
+```tsx
+// app/layout.tsx
+import { EcommerceProvider } from 'hey-pharmacist-ecommerce';
+import { config } from './ecommerce.config';
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en">
+      <body>
+        <EcommerceProvider config={config}>
+          {children}
+        </EcommerceProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+#### Step 4: Test Your Changes
+
+Make changes to the package source code, and:
+- If using `npm run build:watch`, changes rebuild automatically
+- If not, run `npm run build` after each change
+- Refresh your frontend to see the changes
+
+#### Step 5: Unlink When Done
+
+When you're ready to use the published version:
+
+```bash
+# In your frontend project
+npm unlink hey-pharmacist-ecommerce
+npm install hey-pharmacist-ecommerce@latest
+```
+
+### Publishing to npm
+
+When everything works as expected:
+
+```bash
+# Update version (will auto-build before publish)
+npm version patch  # or minor, or major
+
+# Publish to npm
+npm publish
+```
+
+## Troubleshooting
+
+- Types not emitted: ensure `tsup` dts is enabled and `tsconfig` does not use incremental for dts build.
+- 401 after refresh: confirm `AuthProvider` calls `setAuthToken` on login/register and that `initializeApiAdapter` runs at app boot.
+- Filters not working server‑side: pass `orderStatus` and `paymentStatus` to `useOrders` to forward to `getAllOrders`.
+
 ## License
 
-MIT
+MIT