@tagadapay/plugin-sdk 1.0.2

package/README.md

@@ -0,0 +1,475 @@
+# TagadaPay Plugin SDK
+
+A modern, type-safe React SDK for building checkout plugins and integrations with the TagadaPay platform.
+
+## Features
+
+- 🚀 **Modern React Hooks** - Built with React 18+ hooks for optimal performance
+- 🔧 **TypeScript Support** - Full type safety with comprehensive TypeScript definitions
+- 🎯 **Checkout Management** - Complete checkout session lifecycle management
+- 💳 **Payment Processing** - Integrated payment processing with 3DS support
+- 📦 **Product Management** - Fetch and manage products, variants, and pricing
+- 🛒 **Order Management** - Comprehensive order data fetching and management
+- 🎁 **Offers & Promotions** - Handle special offers and promotional codes
+- 🌍 **Multi-Environment** - Support for development, staging, and production
+- 📱 **Responsive Design** - Mobile-first design patterns
+
+## Quick Start
+
+### Installation
+
+```bash
+npm install @tagadapay/plugin-sdk
+# or
+pnpm add @tagadapay/plugin-sdk
+# or
+yarn add @tagadapay/plugin-sdk
+```
+
+### Basic Setup
+
+```tsx
+import React from 'react';
+import { TagadaProvider, useCheckout, useCustomer } from '@tagadapay/plugin-sdk';
+
+function App() {
+  return (
+    <TagadaProvider storeId="your-store-id" accountId="your-account-id" environment="development">
+      <MyCheckoutPlugin />
+    </TagadaProvider>
+  );
+}
+
+function MyCheckoutPlugin() {
+  const { customer, isAuthenticated } = useCustomer();
+  const { checkout, init, updateLineItems } = useCheckout();
+
+  return (
+    <div>
+      {isAuthenticated ? <p>Welcome back, {customer?.firstName}!</p> : <p>Welcome, guest!</p>}
+
+      {checkout ? (
+        <CheckoutForm checkout={checkout} />
+      ) : (
+        <button
+          onClick={() =>
+            init({
+              lineItems: [{ variantId: 'variant-id', quantity: 1 }],
+            })
+          }
+        >
+          Start Checkout
+        </button>
+      )}
+    </div>
+  );
+}
+```
+
+## Core Hooks
+
+### `useCheckout`
+
+Manage checkout sessions, line items, and customer information.
+
+```tsx
+import { useCheckout } from '@tagadapay/plugin-sdk';
+
+function CheckoutComponent() {
+  const {
+    checkout,
+    isLoading,
+    error,
+    init,
+    updateLineItems,
+    updateCustomerAndSessionInfo,
+    applyPromotionCode,
+  } = useCheckout({
+    checkoutToken: 'optional-existing-token',
+    autoRefresh: true,
+  });
+
+  // Initialize new checkout
+  const startCheckout = async () => {
+    await init({
+      storeId: 'store-id',
+      lineItems: [
+        { variantId: 'variant-1', quantity: 2 },
+        { variantId: 'variant-2', quantity: 1 },
+      ],
+      customer: {
+        email: 'customer@example.com',
+        currency: 'USD',
+      },
+    });
+  };
+
+  // Update items in cart
+  const updateCart = async () => {
+    await updateLineItems([{ variantId: 'variant-1', quantity: 3 }]);
+  };
+
+  // Apply discount code
+  const applyDiscount = async () => {
+    await applyPromotionCode('SAVE20');
+  };
+
+  return (
+    <div>
+      {checkout && (
+        <div>
+          <h2>Total: {formatMoney(checkout.summary.totalAdjustedAmount, checkout.summary.currency)}</h2>
+          {checkout.summary.items.map((item) => (
+            <div key={item.id}>
+              {item.name} - Qty: {item.quantity} - {formatMoney(item.adjustedAmount, item.currency)}
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+### `useOrder`
+
+Fetch and display order information for thankyou pages and order management.
+
+```tsx
+import { useOrder, formatMoney } from '@tagadapay/plugin-sdk';
+
+function ThankYouPage({ orderId }: { orderId: string }) {
+  const { order, isLoading, error, refetch } = useOrder({
+    orderId,
+    autoFetch: true,
+  });
+
+  if (isLoading) return <div>Loading order...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+  if (!order) return <div>Order not found</div>;
+
+  return (
+    <div>
+      <h1>Order Confirmed!</h1>
+      <p>Order #{order.id}</p>
+      <p>Status: {order.status}</p>
+      <p>Total: {formatMoney(order.paidAmount, order.currency)}</p>
+
+      <h3>Items:</h3>
+      {order.items.map((item) => (
+        <div key={item.id}>
+          <h4>{item.orderLineItemProduct?.name}</h4>
+          <p>Quantity: {item.quantity}</p>
+          <p>Price: {formatMoney(item.adjustedAmount, item.currency)}</p>
+        </div>
+      ))}
+
+      {order.shippingAddress && (
+        <div>
+          <h3>Shipping Address:</h3>
+          <p>
+            {order.shippingAddress.firstName} {order.shippingAddress.lastName}
+          </p>
+          <p>{order.shippingAddress.address1}</p>
+          <p>
+            {order.shippingAddress.city}, {order.shippingAddress.state} {order.shippingAddress.postal}
+          </p>
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+### `usePayment`
+
+Process payments with support for credit cards, Apple Pay, and 3D Secure.
+
+```tsx
+import { usePayment, useCheckout } from '@tagadapay/plugin-sdk';
+
+function PaymentForm() {
+  const { checkout } = useCheckout();
+  const { processCardPayment, isLoading, error } = usePayment();
+
+  const handlePayment = async (formData: any) => {
+    if (!checkout?.checkoutSession?.id) return;
+
+    try {
+      const result = await processCardPayment(
+        checkout.checkoutSession.id,
+        {
+          cardNumber: formData.cardNumber,
+          expiryDate: formData.expiryDate,
+          cvc: formData.cvc,
+          cardholderName: formData.cardholderName,
+        },
+        {
+          enableThreeds: true,
+          onSuccess: (payment) => {
+            // Redirect to thank you page
+            window.location.href = `/thankyou/${payment.orderId}`;
+          },
+          onFailure: (error) => {
+            console.error('Payment failed:', error);
+          },
+        },
+      );
+    } catch (err) {
+      console.error('Payment error:', err);
+    }
+  };
+
+  return (
+    <form onSubmit={handlePayment}>
+      {/* Payment form fields */}
+      <button type="submit" disabled={isLoading}>
+        {isLoading ? 'Processing...' : 'Pay Now'}
+      </button>
+      {error && <div className="error">{error}</div>}
+    </form>
+  );
+}
+```
+
+### `useProducts`
+
+Fetch product information, variants, and pricing.
+
+```tsx
+import { useProducts } from '@tagadapay/plugin-sdk';
+
+function ProductSelector() {
+  const { products, isLoading, getVariant, filterVariants } = useProducts({
+    includeVariants: true,
+    includePrices: true,
+  });
+
+  const featuredVariants = filterVariants((variant, product) => product.metadata?.featured === true);
+
+  return (
+    <div>
+      {products.map((product) => (
+        <div key={product.id}>
+          <h3>{product.name}</h3>
+          <p>{product.description}</p>
+          {product.variants?.map((variant) => (
+            <div key={variant.id}>
+              <span>{variant.name}</span>
+              <span>{formatMoney(variant.price?.amount || 0, variant.price?.currency || 'USD')}</span>
+            </div>
+          ))}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+### `useOffers`
+
+Handle special offers and promotional content.
+
+```tsx
+import { useOffers } from '@tagadapay/plugin-sdk';
+
+function OffersDisplay() {
+  const { offers, isLoading, createCheckoutSession, getTotalSavings } = useOffers({
+    offerIds: ['offer-1', 'offer-2'],
+    returnUrl: window.location.origin + '/thankyou',
+  });
+
+  const handleOfferClick = async (offerId: string) => {
+    const { checkoutUrl } = await createCheckoutSession(offerId);
+    window.location.href = checkoutUrl;
+  };
+
+  return (
+    <div>
+      <p>Total Savings: {formatMoney(getTotalSavings(), 'USD')}</p>
+      {offers.map((offer) => (
+        <div key={offer.id}>
+          <h3>{offer.title}</h3>
+          <p>{offer.description}</p>
+          <button onClick={() => handleOfferClick(offer.id)}>Claim Offer</button>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+## Utility Functions
+
+### `formatMoney`
+
+Format monetary amounts with proper currency symbols.
+
+```tsx
+import { formatMoney } from '@tagadapay/plugin-sdk';
+
+// Format different currencies
+formatMoney(2999, 'USD'); // "$29.99"
+formatMoney(2999, 'EUR'); // "€29.99"
+formatMoney(2999, 'GBP'); // "£29.99"
+
+// With custom options
+formatMoney(2999, 'USD', {
+  showDecimals: false,
+}); // "$30"
+```
+
+## Environment Configuration
+
+```tsx
+<TagadaProvider
+  storeId="your-store-id"
+  accountId="your-account-id"
+  environment="development" // 'development' | 'production' | 'local'
+  customApiConfig={{
+    baseUrl: 'https://custom-api.example.com',
+  }}
+  debugMode={true}
+>
+  <App />
+</TagadaProvider>
+```
+
+## TypeScript Support
+
+The SDK is fully typed with comprehensive TypeScript definitions:
+
+```tsx
+import type {
+  Order,
+  OrderItem,
+  CheckoutSession,
+  Customer,
+  UseCheckoutResult,
+  UseOrderResult,
+} from '@tagadapay/plugin-sdk';
+
+interface MyComponentProps {
+  order: Order;
+  onOrderUpdate: (order: Order) => void;
+}
+
+function MyComponent({ order, onOrderUpdate }: MyComponentProps) {
+  // Fully typed props and hooks
+}
+```
+
+## Error Handling
+
+All hooks provide comprehensive error handling:
+
+```tsx
+function MyComponent() {
+  const { order, error, isLoading } = useOrder({ orderId: 'order-123' });
+
+  if (isLoading) return <LoadingSpinner />;
+
+  if (error) {
+    return (
+      <ErrorDisplay
+        title="Failed to load order"
+        message={error.message}
+        onRetry={() => window.location.reload()}
+      />
+    );
+  }
+
+  return <OrderDisplay order={order} />;
+}
+```
+
+## Advanced Usage
+
+### Custom API Configuration
+
+```tsx
+const customConfig = {
+  baseUrl: 'https://api.your-domain.com',
+  endpoints: {
+    checkout: {
+      sessionInit: '/v2/checkout/init',
+      sessionStatus: '/v2/checkout/status',
+    },
+  },
+};
+
+<TagadaProvider customApiConfig={customConfig}>
+  <App />
+</TagadaProvider>;
+```
+
+### Plugin Development
+
+For building complete checkout plugins:
+
+```tsx
+// Plugin entry point
+export function MyCheckoutPlugin() {
+  return (
+    <TagadaProvider storeId={STORE_ID}>
+      <Router>
+        <Routes>
+          <Route path="/checkout" element={<CheckoutPage />} />
+          <Route path="/thankyou/:orderId" element={<ThankYouPage />} />
+        </Routes>
+      </Router>
+    </TagadaProvider>
+  );
+}
+```
+
+## Examples
+
+- **[JointBoost Vite Demo](../jointboost-vite)** - Complete checkout implementation
+- **[Checkout Integration](./README-useCheckout.md)** - Detailed checkout examples
+- **[Payment Processing](./README-useOffers.md)** - Payment integration examples
+- **[Money Formatting](./README-money.md)** - Currency formatting utilities
+
+## API Reference
+
+### Hooks
+
+- [`useCheckout`](./README-useCheckout.md) - Checkout session management
+- [`useOrder`](#useorder) - Order data fetching
+- [`usePayment`](./README-useOffers.md) - Payment processing
+- [`useProducts`](#useproducts) - Product management
+- [`useOffers`](./README-useOffers.md) - Offers and promotions
+- [`useCustomer`](#usecustomer) - Customer information
+- [`useSession`](#usesession) - Session management
+
+### Utilities
+
+- [`formatMoney`](./README-money.md) - Currency formatting
+- [`setCheckoutInfo`](./README-setCheckoutInfo.md) - Checkout information helpers
+- [`urlUtils`](./README-urlUtils.md) - URL manipulation utilities
+
+## Browser Support
+
+- Chrome 90+
+- Firefox 88+
+- Safari 14+
+- Edge 90+
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests
+5. Submit a pull request
+
+## License
+
+MIT License - see [LICENSE](./LICENSE) for details.
+
+## Support
+
+- 📖 [Documentation](./README.md)
+- 🐛 [Issues](https://github.com/tagadapay/plugin-sdk/issues)
+- 💬 [Discussions](https://github.com/tagadapay/plugin-sdk/discussions)
+- 📧 [Support Email](mailto:support@tagadapay.com)