🛍️ X10Minds Shop

Build beautiful e-commerce websites with just a few lines of code!

A powerful, user-friendly e-commerce solution that makes building online shops fun and easy. Whether you're creating your first store or scaling to thousands of products, X10Minds Shop has you covered.

📦 Installation

Install via npm

npm install x10minds-shop
npm run setup

Install via yarn

yarn add x10minds-shop
yarn setup

🚀 Quick Start

Create your first shop in under 5 minutes:

import { X10Shop } from "x10minds-shop";

// Initialize your shop
const shop = new X10Shop({
  name: "My Awesome Store",
  currency: "USD",
  theme: "modern",
});

// Add your first product
shop.addProduct({
  id: "prod_001",
  name: "Premium Widget",
  price: 99.99,
  description: "The best widget you'll ever buy",
  images: ["widget-1.jpg", "widget-2.jpg"],
});

// Start the shop
shop.start();

That's it! Your shop is now running at http://localhost:3000 🎉

📚 Table of Contents

• Product Management
• Order Processing
• Payment Integration
• User Management
• Customization
• Performance Optimization
• Security
• API Reference
• Examples

🏷️ Product Management

Manage your product catalog with powerful tools and features.

Adding Products

Add products to your shop with rich metadata and variants:

shop.addProduct({
  id: "prod_002",
  name: "Smart Watch Pro",
  price: 299.99,
  category: "Electronics",
  tags: ["smart", "watch", "fitness"],
  variants: [
    { color: "Black", size: "42mm", stock: 50 },
    { color: "Silver", size: "46mm", stock: 30 },
  ],
  images: ["watch-black.jpg", "watch-silver.jpg"],
  description: "Advanced smartwatch with health tracking",
});

Updating Products

shop.updateProduct("prod_002", {
  price: 279.99,
  stock: 100,
});

Removing Products

shop.removeProduct("prod_002");

Getting Products

// Get all products
const allProducts = shop.getProducts();

// Get specific product
const product = shop.getProduct("prod_002");

// Search products
const results = shop.searchProducts("smart watch");

// Filter by category
const electronics = shop.getProductsByCategory("Electronics");

Product Categories

Organize products into categories for better navigation:

• Electronics - Gadgets, devices, and tech products
• Fashion - Clothing, accessories, and footwear
• Home & Living - Furniture, decor, and essentials
• Sports & Outdoors - Fitness and outdoor gear
• Books & Media - Books, music, and entertainment
• Beauty & Health - Cosmetics, skincare, and wellness

📦 Order Processing

Handle customer orders efficiently with our order management system.

Order Lifecycle

Every order goes through these stages:

1. Pending - Order placed, awaiting payment
2. Processing - Payment confirmed, preparing shipment
3. Shipped - Order dispatched to customer
4. Delivered - Order received by customer
5. Completed - Transaction finalized

Managing Orders

// Get all orders
const orders = shop.getOrders();

// Get specific order
const order = shop.getOrder("order_123");

// Update order status
shop.updateOrderStatus("order_123", "shipped", {
  trackingNumber: "TRACK123456",
  carrier: "FedEx",
  estimatedDelivery: "2024-12-05",
});

// Cancel order
shop.cancelOrder("order_123", "Customer requested cancellation");

// Get orders by status
const pendingOrders = shop.getOrdersByStatus("pending");

Order Events

Listen to order events for custom logic:

shop.on("order:created", (order) => {
  console.log("New order received:", order.id);
  // Send confirmation email
});

shop.on("order:shipped", (order) => {
  console.log("Order shipped:", order.id);
  // Send tracking email
});

shop.on("order:delivered", (order) => {
  console.log("Order delivered:", order.id);
  // Request review
});

💳 Payment Integration

Accept payments securely with multiple payment providers.

Supported Payment Methods

• 💳 Credit/Debit Cards (Visa, Mastercard, Amex)
• 🏦 Bank Transfers
• 📱 Digital Wallets (Apple Pay, Google Pay)
• 💰 PayPal
• 🔗 Cryptocurrency (Bitcoin, Ethereum)

Configure Payment Gateway

shop.configurePayments({
  provider: "stripe",
  apiKey: process.env.STRIPE_API_KEY,
  currency: "USD",
  methods: ["card", "apple_pay", "google_pay"],
  webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
});

Multiple Payment Providers

// Add PayPal
shop.addPaymentProvider({
  name: "paypal",
  clientId: process.env.PAYPAL_CLIENT_ID,
  clientSecret: process.env.PAYPAL_CLIENT_SECRET,
  mode: "production",
});

// Add Cryptocurrency
shop.addPaymentProvider({
  name: "crypto",
  wallets: {
    bitcoin: "your-btc-address",
    ethereum: "your-eth-address",
  },
});

Payment Webhooks

Handle payment events:

shop.on("payment:success", (payment) => {
  console.log("Payment received:", payment.amount);
  // Update order status
  shop.updateOrderStatus(payment.orderId, "processing");
});

shop.on("payment:failed", (payment) => {
  console.log("Payment failed:", payment.error);
  // Notify customer
});

👥 User Management

Manage customer accounts and authentication.

User Registration

shop.registerUser({
  email: "[email protected]",
  password: "securePassword123",
  name: "John Doe",
  phone: "+1234567890",
  address: {
    street: "123 Main St",
    city: "New York",
    state: "NY",
    zip: "10001",
    country: "USA",
  },
});

User Authentication

// Login
const user = await shop.login("[email protected]", "securePassword123");

// Logout
shop.logout(user.id);

// Password reset
shop.requestPasswordReset("[email protected]");

User Roles

• Customer - Can browse and purchase products
• Vendor - Can manage their own products
• Admin - Full access to shop management
• Support - Can view orders and assist customers

Managing User Roles

// Assign role
shop.assignRole(userId, "vendor");

// Check permissions
if (shop.hasPermission(userId, "manage_products")) {
  // Allow product management
}

🎨 Customization

Customize your shop's appearance and behavior to match your brand.

Theme Configuration

shop.setTheme({
  primaryColor: "#ff6600",
  secondaryColor: "#ffd700",
  fontFamily: "Inter, sans-serif",
  borderRadius: "12px",
  layout: "grid", // or 'list'
  darkMode: true,
});

Pre-built Themes

Choose from beautiful pre-built themes:

// Modern minimalist theme
shop.useTheme("modern");

// Classic e-commerce theme
shop.useTheme("classic");

// Luxury brand theme
shop.useTheme("luxury");

// Tech/gadget theme
shop.useTheme("tech");

Custom Components

Add custom components to enhance functionality:

shop.addComponent("ProductReviews", {
  position: "product-detail",
  enabled: true,
  allowImages: true,
  requirePurchase: true,
  moderationEnabled: true,
});

shop.addComponent("WishList", {
  position: "header",
  enabled: true,
  shareEnabled: true,
});

shop.addComponent("LiveChat", {
  position: "bottom-right",
  enabled: true,
  provider: "intercom",
  apiKey: process.env.INTERCOM_KEY,
});

Custom Pages

Create custom pages for your shop:

shop.addPage({
  path: "/about",
  title: "About Us",
  content: "<h1>Our Story</h1><p>We started in 2024...</p>",
});

shop.addPage({
  path: "/faq",
  title: "FAQ",
  template: "faq",
  data: {
    questions: [
      { q: "How do I track my order?", a: "Visit the order tracking page..." },
      {
        q: "What is your return policy?",
        a: "We accept returns within 30 days...",
      },
    ],
  },
});

⚡ Performance Optimization

Optimize your shop for speed and efficiency.

Best Practices

✅ Enable image lazy loading
✅ Use CDN for static assets
✅ Implement caching strategies
✅ Minimize bundle size
✅ Optimize database queries
✅ Enable compression
✅ Use pagination for large catalogs

Performance Configuration

shop.optimize({
  lazyLoading: true,
  imageCompression: "auto",
  caching: {
    products: 3600, // Cache products for 1 hour
    categories: 7200, // Cache categories for 2 hours
    static: 86400, // Cache static assets for 24 hours
  },
  cdn: "https://cdn.x10minds.com",
  compression: true,
  minification: true,
  pagination: {
    productsPerPage: 24,
    ordersPerPage: 50,
  },
});

Database Optimization

shop.configureDatabase({
  indexing: true,
  poolSize: 10,
  caching: true,
  queryOptimization: true,
});

Monitoring

// Enable performance monitoring
shop.enableMonitoring({
  provider: "newrelic",
  apiKey: process.env.NEWRELIC_KEY,
  metrics: ["response_time", "throughput", "error_rate"],
});

// Get performance metrics
const metrics = shop.getMetrics();
console.log("Average response time:", metrics.avgResponseTime);

🔒 Security

Keep your shop and customer data secure.

Security Features

• 🔒 SSL/TLS encryption
• 🛡️ CSRF protection
• 🔐 Secure password hashing (bcrypt)
• 👁️ Rate limiting
• 📝 Audit logging
• 🚫 XSS protection
• 🔑 JWT authentication
• 🌐 CORS configuration

Security Configuration

shop.configureSecurity({
  ssl: true,
  csrfProtection: true,
  rateLimit: {
    windowMs: 15 * 60 * 1000, // 15 minutes
    max: 100, // Limit each IP to 100 requests per window
  },
  passwordPolicy: {
    minLength: 8,
    requireNumbers: true,
    requireSpecialChars: true,
    requireUppercase: true,
    requireLowercase: true,
  },
  sessionTimeout: 3600, // 1 hour
  maxLoginAttempts: 5,
  lockoutDuration: 900, // 15 minutes
});

Data Encryption

// Encrypt sensitive data
shop.enableEncryption({
  algorithm: "aes-256-gcm",
  key: process.env.ENCRYPTION_KEY,
  fields: ["creditCard", "ssn", "bankAccount"],
});

Audit Logging

// Enable audit logs
shop.enableAuditLog({
  events: ["login", "logout", "purchase", "admin_action"],
  retention: 90, // Keep logs for 90 days
});

// Query audit logs
const logs = shop.getAuditLogs({
  userId: "user_123",
  startDate: "2024-01-01",
  endDate: "2024-12-31",
});

📖 API Reference

X10Shop Class

Constructor

new X10Shop(options);

Options:

• name (string) - Shop name
• currency (string) - Default currency (ISO 4217)
• theme (string|object) - Theme name or custom theme object
• port (number) - Server port (default: 3000)
• database (object) - Database configuration

Methods

Product Management

• addProduct(product) - Add a new product
• updateProduct(id, updates) - Update product details
• removeProduct(id) - Remove a product
• getProduct(id) - Get product by ID
• getProducts(filters) - Get all products with optional filters
• searchProducts(query) - Search products
• getProductsByCategory(category) - Get products by category

Order Management

• createOrder(orderData) - Create a new order
• getOrder(id) - Get order by ID
• getOrders(filters) - Get all orders with optional filters
• updateOrderStatus(id, status, metadata) - Update order status
• cancelOrder(id, reason) - Cancel an order
• getOrdersByStatus(status) - Get orders by status

Payment

• configurePayments(config) - Configure payment provider
• addPaymentProvider(provider) - Add additional payment provider
• processPayment(paymentData) - Process a payment
• refundPayment(paymentId, amount) - Refund a payment

User Management

• registerUser(userData) - Register a new user
• login(email, password) - Authenticate user
• logout(userId) - Log out user
• assignRole(userId, role) - Assign role to user
• hasPermission(userId, permission) - Check user permission

Customization

• setTheme(theme) - Set custom theme
• useTheme(themeName) - Use pre-built theme
• addComponent(name, config) - Add custom component
• addPage(pageConfig) - Add custom page

Configuration

• optimize(config) - Configure performance optimizations
• configureSecurity(config) - Configure security settings
• configureDatabase(config) - Configure database settings
• enableMonitoring(config) - Enable performance monitoring

Server

• start(port) - Start the shop server
• stop() - Stop the shop server

💡 Examples

Complete E-commerce Setup

import { X10Shop } from "x10minds-shop";

const shop = new X10Shop({
  name: "TechGadgets Pro",
  currency: "USD",
  theme: "tech",
  port: 3000,
});

// Configure payments
shop.configurePayments({
  provider: "stripe",
  apiKey: process.env.STRIPE_API_KEY,
  methods: ["card", "apple_pay", "google_pay"],
});

// Add products
const products = [
  {
    id: "laptop_001",
    name: "UltraBook Pro 15",
    price: 1299.99,
    category: "Electronics",
    tags: ["laptop", "computer", "portable"],
    stock: 50,
    images: ["laptop-1.jpg", "laptop-2.jpg"],
    description: "Powerful laptop for professionals",
  },
  {
    id: "phone_001",
    name: "SmartPhone X",
    price: 899.99,
    category: "Electronics",
    tags: ["phone", "mobile", "5G"],
    stock: 100,
    images: ["phone-1.jpg", "phone-2.jpg"],
    description: "Latest smartphone with 5G",
  },
];

products.forEach((product) => shop.addProduct(product));

// Configure security
shop.configureSecurity({
  ssl: true,
  csrfProtection: true,
  rateLimit: { windowMs: 900000, max: 100 },
});

// Add custom components
shop.addComponent("ProductReviews", {
  position: "product-detail",
  enabled: true,
});

// Start the shop
shop.start();
console.log("🛍️ Shop is running at http://localhost:3000");

Multi-vendor Marketplace

import { X10Shop } from "x10minds-shop";

const marketplace = new X10Shop({
  name: "Global Marketplace",
  currency: "USD",
  theme: "modern",
  multiVendor: true,
});

// Register vendors
marketplace.registerUser({
  email: "[email protected]",
  password: "secure123",
  name: "Vendor One",
  role: "vendor",
});

// Vendors can add their products
marketplace.addProduct({
  id: "v1_prod_001",
  vendorId: "vendor_001",
  name: "Handmade Jewelry",
  price: 49.99,
  commission: 15, // 15% commission to marketplace
});

// Configure vendor payouts
marketplace.configurePayouts({
  schedule: "weekly",
  method: "bank_transfer",
  minimumAmount: 100,
});

marketplace.start();

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

MIT © X10Minds

🆘 Support

• 📧 Email: [email protected]
• 💬 Discord: Join our community
• 📚 Documentation: docs.x10minds.com
• 🐛 Issues: GitHub Issues

🌟 Show Your Support

Give a ⭐️ if this project helped you!

Made with ❤️ by X10Minds