/**
 * Creates a new product with the provided data
 * 
 * @param productData - The product information to create
 * @returns Promise resolving to the created product
 * @throws {ValidationError} When product data is invalid
 * @throws {DatabaseError} When database operation fails
 * 
 * @example
 * ```typescript
 * const product = await createProduct({
 *   name: 'New Product',
 *   sku: 'NP-001',
 *   price: 29.99
 * })
 * ```
 */
export async function createProduct(
  productData: CreateProductRequest
): Promise<Product> {
  // Implementation
}

/**
 * Product filtering options for search and listing
 */
interface ProductFilters {
  /** Filter by product category */
  category?: string
  /** Search term for product name or SKU */
  search?: string
  /** Page number for pagination (1-based) */
  page: number
  /** Number of items per page (max 100) */
  limit: number
  /** Include inactive products in results */
  includeInactive?: boolean
}

/**
 * Order status enumeration
 * 
 * @enum {string}
 */
enum OrderStatus {
  /** Order is in draft state, not yet sent */
  DRAFT = 'draft',
  /** Order has been sent to supplier */
  SENT = 'sent',
  /** Order confirmed by supplier */
  CONFIRMED = 'confirmed',
  /** Order has been received */
  RECEIVED = 'received',
  /** Order is closed and complete */
  CLOSED = 'closed'
}

/**
 * Product card component for displaying product information
 * 
 * @component
 * @example
 * ```tsx
 * <ProductCard
 *   product={product}
 *   onEdit={handleEdit}
 *   onDelete={handleDelete}
 * />
 * ```
 */
interface ProductCardProps {
  /** Product data to display */
  product: Product
  /** Callback when edit button is clicked */
  onEdit?: (product: Product) => void
  /** Callback when delete button is clicked */
  onDelete?: (productId: string) => void
  /** Additional CSS classes */
  className?: string
}

export const ProductCard = ({ product, onEdit, onDelete, className }: ProductCardProps) => {
  // Implementation
}

## Features

- ✅ Product Management
- ✅ Inventory Tracking
- ✅ Order Management
- ✅ Barcode Scanning (New!)
- ✅ Bulk Operations (New!)
- 🔄 Analytics Dashboard (In Progress)

## Usage Examples

### Barcode Scanning

```typescript
import { scanBarcode } from '@/lib/barcode'

const product = await scanBarcode(barcodeData)
if (product) {
  console.log('Product found:', product.name)
}

import { bulkUpdateInventory } from '@/lib/inventory'

await bulkUpdateInventory([
  { productId: '123', quantity: 100 },
  { productId: '456', quantity: 50 }
])

### Configuration Options

Document new configuration options:

```markdown
## Configuration

### Environment Variables

| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `DATABASE_URL` | PostgreSQL connection string | - | Yes |
| `NEXTAUTH_SECRET` | NextAuth.js secret key | - | Yes |
| `BARCODE_API_KEY` | Barcode scanning API key | - | No |

# Changelog

All notable changes to this project will be documented in this file.

## [Unreleased]

### Added
- Barcode scanning functionality for product lookup
- Bulk inventory adjustment feature
- Export functionality for inventory reports

### Changed
- Improved dashboard loading performance by 40%
- Updated user interface for better accessibility
- Enhanced search functionality with fuzzy matching

### Fixed
- Fixed authentication redirect loop issue
- Resolved inventory calculation errors for allocated stock
- Fixed responsive layout issues on mobile devices

### Security
- Updated dependencies with security patches
- Implemented rate limiting for API endpoints
- Enhanced input validation and sanitization

### Deprecated
- Legacy inventory import format (will be removed in v2.0)

### Removed
- Unused product category migration scripts

## [1.2.0] - 2024-01-15

### Added
- Advanced filtering options for product search
- Email notifications for low stock alerts

## Products API

### Create Product

```http
POST /api/products

{
  "name": "Product Name",
  "sku": "PROD-001",
  "price": 29.99,
  "cost_price": 15.00,
  "category_id": "cat-123"
}

{
  "success": true,
  "data": {
    "id": "prod-456",
    "name": "Product Name",
    "sku": "PROD-001",
    "price": 29.99,
    "created_at": "2024-01-01T00:00:00Z"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid product data",
    "details": {
      "name": "Name is required",
      "price": "Price must be positive"
    }
  }
}

## Documentation Tools

### Generated Documentation

Use TypeDoc for generating API documentation:

```bash
# Generate API documentation
pnpm docs:generate

# Serve documentation locally
pnpm docs:serve

# Test all code examples
pnpm docs:test

# Test specific documentation file
pnpm docs:test api.md