@tagadapay/plugin-sdk 1.0.3 → 1.0.4

package/README.md

@@ -1,461 +1,396 @@
 # TagadaPay Plugin SDK
 
-A modern, type-safe React SDK for building checkout plugins and integrations with the TagadaPay platform.
+A comprehensive SDK for building checkout plugins on the TagadaPay platform. Create custom checkout experiences with React components, payment processing, and advanced features.
 
-## Features
+## 📚 Documentation
 
-- 🚀 **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
+### Core APIs
 
-## Quick Start
+- **[useCheckout](./README-useCheckout.md)** - Checkout state management and flow control
+- **[setCheckoutInfo](./README-setCheckoutInfo.md)** - Customer information and validation
+- **[useOffers](./README-useOffers.md)** - Dynamic pricing and promotional offers
+- **[Money utilities](./README-money.md)** - Currency formatting and calculations
+- **[URL utilities](./README-urlUtils.md)** - Navigation and routing helpers
+
+### Examples
+
+- **[Vite Checkout Demo](../checkout-vite)** - Complete checkout implementation
+
+## 🚀 Quick Start
 
 ### Installation
 
 ```bash
 npm install @tagadapay/plugin-sdk
-# or
-pnpm add @tagadapay/plugin-sdk
-# or
-yarn add @tagadapay/plugin-sdk
 ```
 
-### Basic Setup
+### Basic Usage
 
-```tsx
-import React from 'react';
-import { TagadaProvider, useCheckout, useCustomer } from '@tagadapay/plugin-sdk';
+```typescript
+import { useCheckout, setCheckoutInfo } from '@tagadapay/plugin-sdk';
 
-function App() {
-  return (
-    <TagadaProvider storeId="your-store-id" accountId="your-account-id" environment="development">
-      <MyCheckoutPlugin />
-    </TagadaProvider>
-  );
-}
+function CheckoutPage() {
+  const { customer, cart, payment } = useCheckout();
 
-function MyCheckoutPlugin() {
-  const { customer, isAuthenticated } = useCustomer();
-  const { checkout, init, updateLineItems } = useCheckout();
+  const handleSubmit = async (data) => {
+    await setCheckoutInfo({
+      customer: data.customer,
+      payment: data.payment
+    });
+  };
 
   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>
-      )}
+      {/* Your checkout UI */}
     </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',
-      },
-    });
-  };
+## 🎯 Key Features
 
-  // Update items in cart
-  const updateCart = async () => {
-    await updateLineItems([{ variantId: 'variant-1', quantity: 3 }]);
-  };
+### Payment Processing
 
-  // Apply discount code
-  const applyDiscount = async () => {
-    await applyPromotionCode('SAVE20');
-  };
+- Secure tokenized payments
+- Multiple payment method support
+- Real-time validation
+- PCI compliance
 
-  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>
-  );
-}
-```
+### Customer Management
 
-### `useOrder`
+- Profile management
+- Address validation
+- Order history
+- Preferences
 
-Fetch and display order information for thankyou pages and order management.
+### Cart & Pricing
 
-```tsx
-import { useOrder, formatMoney } from '@tagadapay/plugin-sdk';
+- Dynamic pricing
+- Promotional offers
+- Tax calculations
+- Currency conversion
 
-function ThankYouPage({ orderId }: { orderId: string }) {
-  const { order, isLoading, error, refetch } = useOrder({
-    orderId,
-    autoFetch: true,
-  });
+### UI Components
 
-  if (isLoading) return <div>Loading order...</div>;
-  if (error) return <div>Error: {error.message}</div>;
-  if (!order) return <div>Order not found</div>;
+- Pre-built checkout components
+- Customizable themes
+- Mobile-optimized
+- Accessibility features
 
-  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>
-  );
-}
-```
+## 📖 API Reference
 
-### `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);
-    }
-  };
+### Core Hooks
 
-  return (
-    <form onSubmit={handlePayment}>
-      {/* Payment form fields */}
-      <button type="submit" disabled={isLoading}>
-        {isLoading ? 'Processing...' : 'Pay Now'}
-      </button>
-      {error && <div className="error">{error}</div>}
-    </form>
-  );
-}
+#### useCheckout()
+
+Primary hook for checkout state management.
+
+```typescript
+const {
+  customer, // Customer information
+  cart, // Shopping cart state
+  payment, // Payment details
+  shipping, // Shipping information
+  loading, // Loading states
+  errors, // Error handling
+} = useCheckout();
 ```
 
-### `useProducts`
+#### useOffers()
 
-Fetch product information, variants, and pricing.
+Hook for managing dynamic offers and pricing.
 
-```tsx
-import { useProducts } from '@tagadapay/plugin-sdk';
+```typescript
+const {
+  offers, // Available offers
+  applyOffer, // Apply offer function
+  removeOffer, // Remove offer function
+  total, // Calculated total
+} = useOffers();
+```
 
-function ProductSelector() {
-  const { products, isLoading, getVariant, filterVariants } = useProducts({
-    includeVariants: true,
-    includePrices: true,
-  });
+### Utility Functions
 
-  const featuredVariants = filterVariants((variant, product) => product.metadata?.featured === true);
+#### setCheckoutInfo()
 
-  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>
-  );
-}
+Update checkout information with validation.
+
+```typescript
+await setCheckoutInfo({
+  customer: {
+    email: 'user@example.com',
+    firstName: 'John',
+    lastName: 'Doe',
+  },
+  payment: {
+    method: 'card',
+    token: 'pm_token_123',
+  },
+});
 ```
 
-### `useOffers`
+#### Money utilities
 
-Handle special offers and promotional content.
+Format and calculate monetary values.
 
-```tsx
-import { useOffers } from '@tagadapay/plugin-sdk';
+```typescript
+import { formatMoney, convertCurrency } from '@tagadapay/plugin-sdk';
 
-function OffersDisplay() {
-  const { offers, isLoading, createCheckoutSession, getTotalSavings } = useOffers({
-    offerIds: ['offer-1', 'offer-2'],
-    returnUrl: window.location.origin + '/thankyou',
-  });
+const formatted = formatMoney(2999, 'USD'); // "$29.99"
+const converted = convertCurrency(2999, 'USD', 'EUR'); // 2699
+```
 
-  const handleOfferClick = async (offerId: string) => {
-    const { checkoutUrl } = await createCheckoutSession(offerId);
-    window.location.href = checkoutUrl;
-  };
+## 🛠️ Development
 
-  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>
-  );
-}
+### Local Development
+
+```bash
+# Install dependencies
+npm install
+
+# Start development server
+npm run dev
+
+# Build for production
+npm run build
 ```
 
-## Utility Functions
+### Testing
 
-### `formatMoney`
+```bash
+# Run tests
+npm test
 
-Format monetary amounts with proper currency symbols.
+# Run tests with coverage
+npm run test:coverage
+```
 
-```tsx
-import { formatMoney } from '@tagadapay/plugin-sdk';
+### Linting
 
-// Format different currencies
-formatMoney(2999, 'USD'); // "$29.99"
-formatMoney(2999, 'EUR'); // "€29.99"
-formatMoney(2999, 'GBP'); // "£29.99"
+```bash
+# Check code style
+npm run lint
 
-// With custom options
-formatMoney(2999, 'USD', {
-  showDecimals: false,
-}); // "$30"
+# Fix linting issues
+npm run lint:fix
 ```
 
-## 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>
+## 📦 Build & Deploy
+
+### Building Your Plugin
+
+```bash
+# Build optimized bundle
+npm run build
+
+# Analyze bundle size
+npm run analyze
 ```
 
-## TypeScript Support
+### Deployment
 
-The SDK is fully typed with comprehensive TypeScript definitions:
+```bash
+# Deploy using TagadaPay CLI
+npx @tagadapay/plugin-cli deploy
 
-```tsx
-import type {
-  Order,
-  OrderItem,
-  CheckoutSession,
-  Customer,
-  UseCheckoutResult,
-  UseOrderResult,
-} from '@tagadapay/plugin-sdk';
+# Deploy specific environment
+npx @tagadapay/plugin-cli deploy --env production
+```
 
-interface MyComponentProps {
-  order: Order;
-  onOrderUpdate: (order: Order) => void;
+## 🔧 Configuration
+
+### Plugin Configuration
+
+```json
+{
+  "name": "My Checkout Plugin",
+  "version": "1.0.0",
+  "description": "Custom checkout experience",
+  "main": "dist/index.js",
+  "tagadapay": {
+    "type": "checkout",
+    "mode": "direct",
+    "framework": "react"
+  }
 }
+```
+
+### Environment Variables
+
+```env
+TAGADAPAY_API_KEY=your_api_key
+TAGADAPAY_ENVIRONMENT=sandbox
+TAGADAPAY_STORE_ID=your_store_id
+```
+
+## 🎨 Styling & Themes
 
-function MyComponent({ order, onOrderUpdate }: MyComponentProps) {
-  // Fully typed props and hooks
+### CSS Custom Properties
+
+```css
+:root {
+  --tagada-primary: #007bff;
+  --tagada-secondary: #6c757d;
+  --tagada-success: #28a745;
+  --tagada-danger: #dc3545;
+  --tagada-border-radius: 4px;
+  --tagada-font-family: -apple-system, BlinkMacSystemFont, sans-serif;
 }
 ```
 
-## Error Handling
+### Component Styling
+
+```typescript
+import { styled } from '@tagadapay/plugin-sdk';
+
+const StyledButton = styled.button`
+  background: var(--tagada-primary);
+  color: white;
+  border-radius: var(--tagada-border-radius);
+  padding: 12px 24px;
+  border: none;
+  cursor: pointer;
+
+  &:hover {
+    opacity: 0.9;
+  }
+`;
+```
+
+## 🔐 Security
+
+### Best Practices
+
+- Never store sensitive payment data
+- Always validate user inputs
+- Use HTTPS in production
+- Implement proper error handling
+- Follow PCI DSS guidelines
+
+### Token Management
+
+```typescript
+// ✅ Good: Use tokenized payments
+const paymentToken = await tokenizePayment(cardData);
+await processPayment({ token: paymentToken });
 
-All hooks provide comprehensive error handling:
+// ❌ Bad: Never store raw card data
+// const cardNumber = '4111111111111111'; // Don't do this
+```
+
+## 📱 Mobile Optimization
 
-```tsx
-function MyComponent() {
-  const { order, error, isLoading } = useOrder({ orderId: 'order-123' });
+### Responsive Design
 
-  if (isLoading) return <LoadingSpinner />;
+```css
+.checkout-container {
+  max-width: 600px;
+  margin: 0 auto;
+  padding: 16px;
+}
 
-  if (error) {
-    return (
-      <ErrorDisplay
-        title="Failed to load order"
-        message={error.message}
-        onRetry={() => window.location.reload()}
-      />
-    );
+@media (max-width: 768px) {
+  .checkout-container {
+    padding: 8px;
   }
 
-  return <OrderDisplay order={order} />;
+  .checkout-form {
+    font-size: 16px; /* Prevent zoom on iOS */
+  }
 }
 ```
 
-## Advanced Usage
+### Touch Interactions
 
-### Custom API Configuration
-
-```tsx
-const customConfig = {
-  baseUrl: 'https://api.your-domain.com',
-  endpoints: {
-    checkout: {
-      sessionInit: '/v2/checkout/init',
-      sessionStatus: '/v2/checkout/status',
-    },
-  },
+```typescript
+const handleTouchStart = (e) => {
+  // Optimize for touch devices
+  e.preventDefault();
+  // Handle touch interaction
 };
-
-<TagadaProvider customApiConfig={customConfig}>
-  <App />
-</TagadaProvider>;
 ```
 
-### Plugin Development
+## 🌐 Internationalization
 
-For building complete checkout plugins:
+### Multi-language Support
+
+```typescript
+import { useTranslation } from '@tagadapay/plugin-sdk';
+
+function CheckoutForm() {
+  const { t } = useTranslation();
 
-```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>
+    <form>
+      <label>{t('checkout.email')}</label>
+      <input type="email" placeholder={t('checkout.email_placeholder')} />
+    </form>
   );
 }
 ```
 
-## Examples
+### Currency Support
+
+```typescript
+import { useCurrency } from '@tagadapay/plugin-sdk';
+
+function PriceDisplay({ amount }) {
+  const { formatPrice, currency } = useCurrency();
+
+  return <span>{formatPrice(amount, currency)}</span>;
+}
+```
+
+## 📊 Analytics & Monitoring
 
-- **[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
+### Event Tracking
 
-## API Reference
+```typescript
+import { trackEvent } from '@tagadapay/plugin-sdk';
 
-### Hooks
+// Track user interactions
+trackEvent('checkout_started', {
+  product_id: 'prod_123',
+  value: 2999,
+  currency: 'USD',
+});
 
-- [`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
+// Track conversions
+trackEvent('purchase_completed', {
+  transaction_id: 'txn_456',
+  value: 2999,
+  currency: 'USD',
+});
+```
 
-### Utilities
+### Performance Monitoring
 
-- [`formatMoney`](./README-money.md) - Currency formatting
-- [`setCheckoutInfo`](./README-setCheckoutInfo.md) - Checkout information helpers
-- [`urlUtils`](./README-urlUtils.md) - URL manipulation utilities
+```typescript
+import { performance } from '@tagadapay/plugin-sdk';
 
-## Browser Support
+// Measure load times
+performance.mark('checkout-start');
+// ... checkout logic
+performance.mark('checkout-end');
+performance.measure('checkout-duration', 'checkout-start', 'checkout-end');
+```
+
+## 🤝 Contributing
 
-- Chrome 90+
-- Firefox 88+
-- Safari 14+
-- Edge 90+
+### Development Setup
 
-## Contributing
+```bash
+# Clone the repository
+git clone https://github.com/tagadapay/plugin-sdk.git
+
+# Install dependencies
+npm install
+
+# Start development
+npm run dev
+```
+
+### Submitting Changes
 
 1. Fork the repository
 2. Create a feature branch
@@ -463,13 +398,17 @@ export function MyCheckoutPlugin() {
 4. Add tests
 5. Submit a pull request
 
-## License
+## 📄 License
 
 MIT License - see [LICENSE](./LICENSE) for details.
 
-## Support
+## 🆘 Support
+
+- **Documentation**: [docs.tagadapay.com](https://docs.tagadapay.com)
+- **Discord**: [discord.gg/tagadapay](https://discord.gg/tagadapay)
+- **Email**: support@tagadapay.com
+- **GitHub Issues**: [github.com/tagadapay/plugin-sdk/issues](https://github.com/tagadapay/plugin-sdk/issues)
+
+---
 
-- 📖 [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)
+Built with ❤️ by the TagadaPay team

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tagadapay/plugin-sdk",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Modern React SDK for building Tagada Pay plugins",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",