@diffsome/react 1.1.0

package/README.md

@@ -0,0 +1,353 @@
+# @diffsome/react
+
+Headless React hooks and providers for Diffsome SDK. Build any e-commerce or CMS frontend with your own UI components.
+
+## Installation
+
+```bash
+npm install @diffsome/react @diffsome/sdk
+# or
+yarn add @diffsome/react @diffsome/sdk
+```
+
+## Quick Start
+
+```tsx
+import { DiffsomeProvider, useAuth, useCart, useProducts } from '@diffsome/react';
+
+function App() {
+  return (
+    <DiffsomeProvider
+      config={{
+        tenantId: 'my-store',
+        apiKey: 'pky_your_api_key',
+      }}
+    >
+      <Shop />
+    </DiffsomeProvider>
+  );
+}
+
+function Shop() {
+  const { user, login, logout } = useAuth();
+  const { items, addToCart, total } = useCart();
+  const { products, loading } = useProducts();
+
+  if (loading) return <div>Loading...</div>;
+
+  return (
+    <div>
+      {user ? (
+        <p>Welcome, {user.name}! <button onClick={logout}>Logout</button></p>
+      ) : (
+        <button onClick={() => login({ email: '...', password: '...' })}>Login</button>
+      )}
+
+      <h2>Products</h2>
+      {products.map(product => (
+        <div key={product.id}>
+          <h3>{product.name}</h3>
+          <p>${product.sale_price}</p>
+          <button onClick={() => addToCart(product.id)}>Add to Cart</button>
+        </div>
+      ))}
+
+      <h2>Cart ({items.length} items)</h2>
+      <p>Total: ${total}</p>
+    </div>
+  );
+}
+```
+
+## Available Hooks
+
+### Authentication
+- `useAuth()` - Login, register, logout, profile management
+- `useSocialAuth()` - Social login (Google, Kakao, Naver, etc.)
+
+### E-commerce
+- `useCart()` - Cart management (add, update, remove items)
+- `useWishlist()` - Wishlist management
+- `useProducts()` - Product listing with pagination
+- `useProduct(slug)` - Single product details
+- `useCategories()` - Product categories
+- `useFeaturedProducts()` - Featured products
+- `useOrders()` - Order history
+- `useOrder(id)` - Single order details
+- `useCreateOrder()` - Create new order
+
+### Payment
+- `usePaymentStatus()` - Check available payment methods (Toss, Stripe)
+- `useTossPayment()` - Toss Payments (Korea)
+- `useStripePayment()` - Stripe Payments (Global)
+- `useCoupons()` - User's available coupons
+- `useValidateCoupon()` - Validate coupon code
+
+### Subscriptions
+- `useSubscriptions()` - User's subscriptions
+- `useSubscription(id)` - Single subscription with cancel/pause/resume
+- `useCreateSubscription()` - Create subscription via Stripe
+
+### Digital Downloads
+- `useDownloads()` - User's digital download links
+- `useOrderDownloads(orderNumber)` - Downloads for specific order
+
+### Reviews
+- `useProductReviews(slug)` - Product reviews
+- `useMyReviews()` - User's reviews
+- `useCanReview(slug)` - Check review eligibility
+- `useCreateReview()` - Create product review
+
+### Content
+- `useBlog()` - Blog posts with pagination
+- `useBlogPost(slug)` - Single blog post
+- `useBlogCategories()` - Blog categories
+- `useBoards()` - Board listing
+- `useBoard(slug)` - Single board
+- `useBoardPosts(slug)` - Board posts
+- `useBoardPost(id)` - Single board post
+- `useCreateBoardPost()` - Create board post
+- `useComments({ type, target })` - Comments for board/blog/standalone
+- `useForm(slug)` - Form with submission
+
+### Reservations
+- `useReservationServices()` - Available services
+- `useReservationStaffs()` - Staff members
+- `useAvailableSlots(serviceId, date)` - Time slots
+- `useMyReservations()` - User's reservations
+- `useCreateReservation()` - Create reservation
+- `useReservationSettings()` - Reservation settings
+
+### Media
+- `useMedia()` - File upload and management
+
+### Custom Entities (Dynamic Data)
+- `useEntities()` - List all entity definitions
+- `useEntity(slug)` - Single entity with schema
+- `useEntityRecords(slug)` - CRUD for entity records
+- `useEntityRecord(slug, id)` - Single record
+- `useTypedEntity<T>(slug)` - Typed entity accessor
+
+## Hook Examples
+
+### useAuth
+
+```tsx
+function LoginForm() {
+  const { user, login, logout, loading, error } = useAuth();
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+
+  const handleSubmit = async (e) => {
+    e.preventDefault();
+    await login({ email, password });
+  };
+
+  if (user) {
+    return (
+      <div>
+        <p>Welcome, {user.name}</p>
+        <button onClick={logout}>Logout</button>
+      </div>
+    );
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input value={email} onChange={(e) => setEmail(e.target.value)} />
+      <input type="password" value={password} onChange={(e) => setPassword(e.target.value)} />
+      <button disabled={loading}>Login</button>
+      {error && <p>{error.message}</p>}
+    </form>
+  );
+}
+```
+
+### useCart
+
+```tsx
+function Cart() {
+  const { items, total, updateItem, removeItem, clearCart } = useCart();
+
+  return (
+    <div>
+      {items.map(item => (
+        <div key={item.id}>
+          <span>{item.product_name}</span>
+          <input
+            type="number"
+            value={item.quantity}
+            onChange={(e) => updateItem(item.id, parseInt(e.target.value))}
+          />
+          <button onClick={() => removeItem(item.id)}>Remove</button>
+        </div>
+      ))}
+      <p>Total: ${total}</p>
+      <button onClick={clearCart}>Clear Cart</button>
+    </div>
+  );
+}
+```
+
+### useWishlist
+
+```tsx
+function WishlistButton({ productId }) {
+  const { isInWishlist, toggleWishlist } = useWishlist();
+  const inWishlist = isInWishlist(productId);
+
+  return (
+    <button onClick={() => toggleWishlist(productId)}>
+      {inWishlist ? '❤️' : '🤍'}
+    </button>
+  );
+}
+```
+
+### useStripePayment
+
+```tsx
+function CheckoutButton({ orderNumber }) {
+  const { createCheckout, loading } = useStripePayment();
+
+  const handleCheckout = async () => {
+    const { checkout_url } = await createCheckout(
+      orderNumber,
+      `${window.location.origin}/checkout/success`,
+      `${window.location.origin}/checkout/cancel`
+    );
+    window.location.href = checkout_url;
+  };
+
+  return (
+    <button onClick={handleCheckout} disabled={loading}>
+      Pay with Stripe
+    </button>
+  );
+}
+```
+
+### useComments
+
+```tsx
+function Comments({ postId }) {
+  const { comments, createComment, likeComment, loading } = useComments({
+    type: 'board',
+    target: postId,
+  });
+
+  const handleSubmit = async (content) => {
+    await createComment({ content });
+  };
+
+  return (
+    <div>
+      {comments.map(comment => (
+        <div key={comment.id}>
+          <p>{comment.content}</p>
+          <button onClick={() => likeComment(comment.id)}>
+            Like ({comment.likes})
+          </button>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+### useEntityRecords (Custom Entities)
+
+```tsx
+// Dynamic CRM example
+function CustomerList() {
+  const { records, createRecord, deleteRecord, loading } = useEntityRecords('customers');
+
+  const addCustomer = async () => {
+    await createRecord({
+      company: 'ACME Corp',
+      email: 'contact@acme.com',
+      tier: 'vip',
+    });
+  };
+
+  return (
+    <div>
+      {records.map(customer => (
+        <div key={customer.id}>
+          <span>{customer.data.company}</span>
+          <button onClick={() => deleteRecord(customer.id)}>Delete</button>
+        </div>
+      ))}
+      <button onClick={addCustomer}>Add Customer</button>
+    </div>
+  );
+}
+
+// With TypeScript
+interface Customer {
+  company: string;
+  email: string;
+  tier: 'standard' | 'vip';
+}
+
+function TypedCustomerList() {
+  const customers = useTypedEntity<Customer>('customers');
+  // customers.useRecords() returns typed records
+  // customers.create({ company: '...' }) has type checking
+}
+```
+
+### useMedia
+
+```tsx
+function FileUploader() {
+  const { upload, uploading, uploadProgress } = useMedia();
+
+  const handleFileChange = async (e) => {
+    const file = e.target.files[0];
+    if (file) {
+      const media = await upload(file);
+      console.log('Uploaded:', media.url);
+    }
+  };
+
+  return (
+    <div>
+      <input type="file" onChange={handleFileChange} disabled={uploading} />
+      {uploading && <progress value={uploadProgress} max={100} />}
+    </div>
+  );
+}
+```
+
+## Low-level Access
+
+Use `useClient()` to access the SDK directly:
+
+```tsx
+import { useClient } from '@diffsome/react';
+
+function CustomComponent() {
+  const client = useClient();
+
+  const handleCustomAction = async () => {
+    // Direct SDK access
+    const result = await client.shop.validateCoupon('SAVE10', 5000);
+    console.log(result);
+  };
+
+  return <button onClick={handleCustomAction}>Validate Coupon</button>;
+}
+```
+
+## TypeScript
+
+All types are re-exported from `@diffsome/sdk`:
+
+```tsx
+import type { Product, Cart, Order, Member, CustomEntity, EntityRecord } from '@diffsome/react';
+```
+
+## License
+
+MIT