storenest-commerce/README.md

Complete e-commerce SDK for Storenest platform with React components, multi-language support, secure checkout, and enterprise-grade security

# Storenest Commerce SDK

A complete e-commerce SDK for the Storenest platform with React components, multi-language support, and secure checkout functionality.

## 🌟 Features

- **🛒 Complete Checkout Components** - Ready-to-use React and vanilla JavaScript checkout components
- **🌍 Multi-Language Support** - Croatian, English, and German translations
- **🔒 Secure Architecture** - Hybrid approach with client-side UI and server-side sensitive operations
- **⚡ TypeScript Support** - Full type safety and IntelliSense
- **🎨 Modern Design** - Beautiful, responsive checkout interface matching Storenest branding
- **📱 SSR Safe** - Works with Next.js and other React frameworks
- **🔧 Flexible Configuration** - Customizable themes, currencies, and locales

## 📦 Installation

```bash
npm install storenest-commerce
```

## 🚀 Quick Start

### React Component (Recommended)

```typescript
import { CheckoutBox } from 'storenest-commerce';

function MyCheckoutPage() {
  const handleSuccess = (orderId: string) => {
    console.log('Order placed successfully:', orderId);
  };

  const handleError = (error: string) => {
    console.error('Checkout error:', error);
  };

  return (
    <CheckoutBox
      config={{
        locale: 'hr', // Croatian
        currency: 'EUR',
        theme: 'modern',
        showOrderSummary: true
      }}
      onSuccess={handleSuccess}
      onError={handleError}
    />
  );
}
```

### Vanilla JavaScript Component

```typescript
import { SimpleCheckoutBox } from 'storenest-commerce';

const checkout = new SimpleCheckoutBox({
  locale: 'de', // German
  currency: 'EUR',
  theme: 'modern'
}, {
  onSuccess: (orderId) => console.log('Order placed:', orderId),
  onError: (error) => console.error('Error:', error)
});

checkout.render('checkout-container');
```

## 🌍 Supported Languages

- **🇭🇷 Croatian (Hrvatski)** - `locale: 'hr'`
- **🇺🇸 English** - `locale: 'en'` (default)
- **🇩🇪 German (Deutsch)** - `locale: 'de'`

## ⚙️ Configuration Options

### CheckoutBox Props

```typescript
interface CheckoutBoxProps {
  config?: {
    theme?: 'modern' | 'classic' | 'minimal';
    currency?: string;
    locale?: 'hr' | 'en' | 'de';
    showOrderSummary?: boolean;
    enableGuestCheckout?: boolean;
  };
  onSuccess?: (orderId: string) => void;
  onError?: (error: string) => void;
  onCancel?: () => void;
}
```

### SimpleCheckoutBox Config

```typescript
interface SimpleCheckoutConfig {
  theme?: 'modern' | 'classic' | 'minimal';
  currency?: string;
  locale?: 'hr' | 'en' | 'de';
  showOrderSummary?: boolean;
  enableGuestCheckout?: boolean;
}
```

## 🔒 Security Architecture

The SDK uses a **Hybrid Approach** for maximum security:

### Client-Side (Safe Operations)
- UI components and styling
- Form validation and user experience
- Session management
- Price formatting and display
- Multi-step checkout flow

### Server-Side (Secure Operations)
- Payment processing and card data
- Order calculations and pricing
- Fraud detection and validation
- Discount application and abuse prevention
- Address validation and verification

## 📚 API Reference

### Client-Side SDK (`storenest-commerce`)

```typescript
import { 
  CheckoutBox,
  SimpleCheckoutBox,
  StorenestCheckout,
  login,
  register,
  createOrGetGuestUser
} from 'storenest-commerce';
```

### Server-Side SDK (`storenest-commerce/server`)

```typescript
import { 
  StorenestServerCheckout,
  initializeStorenest,
  placeOrder,
  getOrder
} from 'storenest-commerce/server';
```

## 🎨 Themes

- **Modern** - Clean, gradient-based design (default)
- **Classic** - Traditional e-commerce styling
- **Minimal** - Simplified, focused interface

## 💰 Supported Currencies

- EUR (Euro)
- USD (US Dollar)
- And more...

## 🔧 Advanced Usage

### Custom Styling

The components use inline styles for maximum compatibility. You can override styles by wrapping the components:

```typescript
<div style={{ 
  '--storenest-primary': '#667eea',
  '--storenest-secondary': '#764ba2'
}}>
  <CheckoutBox config={{ theme: 'modern' }} />
</div>
```

### Server-Side Integration

```typescript
// pages/api/checkout.ts
import { initializeStorenest, placeOrder } from 'storenest-commerce/server';

initializeStorenest({
  apiBaseUrl: 'https://api.storenest.io',
  apiKey: process.env.STORENEST_API_KEY,
  secretKey: process.env.STORENEST_SECRET_KEY
});

export default async function handler(req, res) {
  const confirmation = await placeOrder({
    userId: 123,
    cartId: 'cart_123',
    deliveryMethodId: 1,
    paymentMethodId: 1,
    address: {
      firstName: 'John',
      lastName: 'Doe',
      email: 'john@example.com',
      address: '123 Main St',
      city: 'Zagreb',
      zipCode: '10000',
      country: 'HR'
    }
  });
  
  res.json(confirmation);
}
```

## 🛠️ Development

### Building the Package

```bash
npm run build
```

### Testing

```bash
# Run the demo shop
cd demo-shop
npm run dev
```

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🤝 Support

- **Website**: [storenest.hr](https://storenest.hr)
- **Admin Panel**: [app.storenest.io](https://app.storenest.io)
- **International**: [storenest.io](https://storenest.io)
- **Email**: developer-support@storenest.hr

## 🔗 Related

- [Storenest Platform](https://storenest.hr)
- [Admin Dashboard](https://app.storenest.io)
- [International Site](https://storenest.io)

---

Built with ❤️ by [Storenest](https://storenest.hr)