digital-tools 2.0.2 → 2.1.1

package/src/entities/ecommerce.js

@@ -0,0 +1,1429 @@
+/**
+ * E-Commerce Entity Types (Nouns)
+ *
+ * Semantic type definitions for e-commerce digital tools that can be used by
+ * both remote human workers AND AI agents. Each entity defines:
+ * - Properties: The data fields
+ * - Actions: Operations that can be performed (Verbs)
+ * - Events: State changes that occur
+ *
+ * @packageDocumentation
+ */
+// =============================================================================
+// Product
+// =============================================================================
+/**
+ * Product entity
+ *
+ * Represents a product that can be sold in an e-commerce store
+ */
+export const Product = {
+    singular: 'product',
+    plural: 'products',
+    description: 'A product that can be sold in an e-commerce store',
+    properties: {
+        // Identity
+        sku: {
+            type: 'string',
+            description: 'Stock Keeping Unit - unique product identifier',
+        },
+        name: {
+            type: 'string',
+            description: 'Product name',
+        },
+        slug: {
+            type: 'string',
+            optional: true,
+            description: 'URL-friendly version of the product name',
+        },
+        // Content
+        description: {
+            type: 'string',
+            optional: true,
+            description: 'Product description',
+        },
+        shortDescription: {
+            type: 'string',
+            optional: true,
+            description: 'Brief product summary',
+        },
+        features: {
+            type: 'string',
+            array: true,
+            optional: true,
+            description: 'List of product features',
+        },
+        specifications: {
+            type: 'json',
+            optional: true,
+            description: 'Technical specifications and attributes',
+        },
+        // Pricing
+        price: {
+            type: 'number',
+            description: 'Base price of the product',
+        },
+        compareAtPrice: {
+            type: 'number',
+            optional: true,
+            description: 'Original price for comparison (for showing discounts)',
+        },
+        cost: {
+            type: 'number',
+            optional: true,
+            description: 'Cost of goods (for internal use)',
+        },
+        currency: {
+            type: 'string',
+            description: 'Currency code (USD, EUR, etc.)',
+            examples: ['USD', 'EUR', 'GBP', 'CAD'],
+        },
+        // Media
+        images: {
+            type: 'url',
+            array: true,
+            optional: true,
+            description: 'Product image URLs',
+        },
+        featuredImage: {
+            type: 'url',
+            optional: true,
+            description: 'Primary product image URL',
+        },
+        videos: {
+            type: 'url',
+            array: true,
+            optional: true,
+            description: 'Product video URLs',
+        },
+        // Categorization
+        category: {
+            type: 'string',
+            optional: true,
+            description: 'Product category',
+        },
+        tags: {
+            type: 'string',
+            array: true,
+            optional: true,
+            description: 'Tags for organization and search',
+        },
+        brand: {
+            type: 'string',
+            optional: true,
+            description: 'Product brand or manufacturer',
+        },
+        // Inventory
+        trackInventory: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether to track inventory for this product',
+        },
+        inventoryQuantity: {
+            type: 'number',
+            optional: true,
+            description: 'Available inventory quantity',
+        },
+        lowStockThreshold: {
+            type: 'number',
+            optional: true,
+            description: 'Quantity at which low stock warning triggers',
+        },
+        // Variants
+        hasVariants: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether product has variants (size, color, etc.)',
+        },
+        variantOptions: {
+            type: 'json',
+            optional: true,
+            description: 'Available variant options (e.g., sizes, colors)',
+        },
+        // Status
+        status: {
+            type: 'string',
+            description: 'Product status: draft, active, archived',
+            examples: ['draft', 'active', 'archived'],
+        },
+        published: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether the product is publicly visible',
+        },
+        publishedAt: {
+            type: 'datetime',
+            optional: true,
+            description: 'When the product was published',
+        },
+        // Shipping
+        weight: {
+            type: 'number',
+            optional: true,
+            description: 'Product weight for shipping',
+        },
+        weightUnit: {
+            type: 'string',
+            optional: true,
+            description: 'Weight unit: lb, kg, oz, g',
+            examples: ['lb', 'kg', 'oz', 'g'],
+        },
+        dimensions: {
+            type: 'json',
+            optional: true,
+            description: 'Product dimensions (length, width, height)',
+        },
+        requiresShipping: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether product requires physical shipping',
+        },
+        // SEO
+        metaTitle: {
+            type: 'string',
+            optional: true,
+            description: 'SEO meta title',
+        },
+        metaDescription: {
+            type: 'string',
+            optional: true,
+            description: 'SEO meta description',
+        },
+        // Metrics
+        viewCount: {
+            type: 'number',
+            optional: true,
+            description: 'Number of times product has been viewed',
+        },
+        salesCount: {
+            type: 'number',
+            optional: true,
+            description: 'Total number of units sold',
+        },
+        averageRating: {
+            type: 'number',
+            optional: true,
+            description: 'Average customer rating (e.g., 4.5)',
+        },
+        reviewCount: {
+            type: 'number',
+            optional: true,
+            description: 'Number of customer reviews',
+        },
+    },
+    relationships: {
+        variants: {
+            type: 'ProductVariant[]',
+            backref: 'product',
+            description: 'Product variants (different sizes, colors, etc.)',
+        },
+        reviews: {
+            type: 'Review[]',
+            backref: 'product',
+            description: 'Customer reviews for this product',
+        },
+        inventory: {
+            type: 'Inventory',
+            backref: 'product',
+            description: 'Inventory tracking information',
+        },
+        orderItems: {
+            type: 'OrderItem[]',
+            backref: 'product',
+            description: 'Order items containing this product',
+        },
+    },
+    actions: [
+        'create',
+        'update',
+        'publish',
+        'unpublish',
+        'archive',
+        'delete',
+        'duplicate',
+        'addVariant',
+        'removeVariant',
+        'updatePrice',
+        'updateInventory',
+        'addImage',
+        'removeImage',
+        'addToCart',
+        'addToWishlist',
+        'view',
+        'review',
+    ],
+    events: [
+        'created',
+        'updated',
+        'published',
+        'unpublished',
+        'archived',
+        'deleted',
+        'duplicated',
+        'variantAdded',
+        'variantRemoved',
+        'priceChanged',
+        'inventoryUpdated',
+        'imageAdded',
+        'imageRemoved',
+        'viewed',
+        'addedToCart',
+        'addedToWishlist',
+        'purchased',
+        'reviewed',
+        'outOfStock',
+        'lowStock',
+    ],
+};
+/**
+ * Product variant entity
+ *
+ * Represents a variant of a product (e.g., size, color)
+ */
+export const ProductVariant = {
+    singular: 'product variant',
+    plural: 'product variants',
+    description: 'A variant of a product with different options (size, color, etc.)',
+    properties: {
+        // Identity
+        sku: {
+            type: 'string',
+            description: 'Unique SKU for this variant',
+        },
+        title: {
+            type: 'string',
+            description: 'Variant title (e.g., "Large / Blue")',
+        },
+        // Options
+        option1: {
+            type: 'string',
+            optional: true,
+            description: 'First option value (e.g., "Large")',
+        },
+        option2: {
+            type: 'string',
+            optional: true,
+            description: 'Second option value (e.g., "Blue")',
+        },
+        option3: {
+            type: 'string',
+            optional: true,
+            description: 'Third option value',
+        },
+        // Pricing
+        price: {
+            type: 'number',
+            description: 'Variant price (overrides product price)',
+        },
+        compareAtPrice: {
+            type: 'number',
+            optional: true,
+            description: 'Original price for comparison',
+        },
+        cost: {
+            type: 'number',
+            optional: true,
+            description: 'Cost of goods for this variant',
+        },
+        // Inventory
+        inventoryQuantity: {
+            type: 'number',
+            description: 'Available inventory quantity',
+        },
+        inventoryPolicy: {
+            type: 'string',
+            optional: true,
+            description: 'How to handle out-of-stock: deny, continue',
+            examples: ['deny', 'continue'],
+        },
+        // Media
+        image: {
+            type: 'url',
+            optional: true,
+            description: 'Variant-specific image URL',
+        },
+        position: {
+            type: 'number',
+            optional: true,
+            description: 'Display position/order',
+        },
+        // Physical
+        weight: {
+            type: 'number',
+            optional: true,
+            description: 'Variant weight (overrides product weight)',
+        },
+        barcode: {
+            type: 'string',
+            optional: true,
+            description: 'Barcode/UPC for this variant',
+        },
+        // Status
+        available: {
+            type: 'boolean',
+            description: 'Whether variant is available for purchase',
+        },
+    },
+    relationships: {
+        product: {
+            type: 'Product',
+            backref: 'variants',
+            description: 'Parent product',
+        },
+        inventory: {
+            type: 'Inventory',
+            backref: 'variant',
+            description: 'Inventory tracking for this variant',
+        },
+        orderItems: {
+            type: 'OrderItem[]',
+            backref: 'variant',
+            description: 'Order items for this variant',
+        },
+    },
+    actions: [
+        'create',
+        'update',
+        'delete',
+        'updatePrice',
+        'updateInventory',
+        'enable',
+        'disable',
+        'addToCart',
+    ],
+    events: [
+        'created',
+        'updated',
+        'deleted',
+        'priceChanged',
+        'inventoryUpdated',
+        'enabled',
+        'disabled',
+        'purchased',
+        'outOfStock',
+        'restocked',
+    ],
+};
+// =============================================================================
+// Order
+// =============================================================================
+/**
+ * Order entity
+ *
+ * Represents a customer order
+ */
+export const Order = {
+    singular: 'order',
+    plural: 'orders',
+    description: 'A customer order containing one or more products',
+    properties: {
+        // Identity
+        orderNumber: {
+            type: 'string',
+            description: 'Unique order number (human-readable)',
+        },
+        // Status
+        status: {
+            type: 'string',
+            description: 'Order status: pending, confirmed, processing, shipped, delivered, cancelled, refunded',
+            examples: ['pending', 'confirmed', 'processing', 'shipped', 'delivered', 'cancelled', 'refunded'],
+        },
+        fulfillmentStatus: {
+            type: 'string',
+            optional: true,
+            description: 'Fulfillment status: unfulfilled, partial, fulfilled',
+            examples: ['unfulfilled', 'partial', 'fulfilled'],
+        },
+        paymentStatus: {
+            type: 'string',
+            description: 'Payment status: pending, paid, partial, refunded, failed',
+            examples: ['pending', 'paid', 'partial', 'refunded', 'failed'],
+        },
+        // Amounts
+        subtotal: {
+            type: 'number',
+            description: 'Subtotal before tax and shipping',
+        },
+        shippingCost: {
+            type: 'number',
+            optional: true,
+            description: 'Shipping cost',
+        },
+        taxAmount: {
+            type: 'number',
+            optional: true,
+            description: 'Total tax amount',
+        },
+        discountAmount: {
+            type: 'number',
+            optional: true,
+            description: 'Total discount amount applied',
+        },
+        total: {
+            type: 'number',
+            description: 'Total amount charged',
+        },
+        currency: {
+            type: 'string',
+            description: 'Currency code',
+            examples: ['USD', 'EUR', 'GBP', 'CAD'],
+        },
+        // Shipping
+        shippingMethod: {
+            type: 'string',
+            optional: true,
+            description: 'Selected shipping method',
+        },
+        shippingAddress: {
+            type: 'json',
+            description: 'Shipping address details',
+        },
+        billingAddress: {
+            type: 'json',
+            optional: true,
+            description: 'Billing address details',
+        },
+        trackingNumber: {
+            type: 'string',
+            optional: true,
+            description: 'Shipping tracking number',
+        },
+        trackingUrl: {
+            type: 'url',
+            optional: true,
+            description: 'URL to track shipment',
+        },
+        // Payment
+        paymentMethod: {
+            type: 'string',
+            optional: true,
+            description: 'Payment method used: card, paypal, bank_transfer, etc.',
+            examples: ['card', 'paypal', 'bank_transfer', 'apple_pay', 'google_pay'],
+        },
+        paymentReference: {
+            type: 'string',
+            optional: true,
+            description: 'Payment gateway transaction reference',
+        },
+        // Customer
+        customerEmail: {
+            type: 'string',
+            description: 'Customer email address',
+        },
+        customerPhone: {
+            type: 'string',
+            optional: true,
+            description: 'Customer phone number',
+        },
+        // Discounts
+        couponCode: {
+            type: 'string',
+            optional: true,
+            description: 'Applied coupon code',
+        },
+        // Metadata
+        notes: {
+            type: 'string',
+            optional: true,
+            description: 'Order notes or special instructions',
+        },
+        tags: {
+            type: 'string',
+            array: true,
+            optional: true,
+            description: 'Tags for organization',
+        },
+        source: {
+            type: 'string',
+            optional: true,
+            description: 'Order source: web, mobile, phone, pos',
+            examples: ['web', 'mobile', 'phone', 'pos'],
+        },
+        // Timestamps
+        placedAt: {
+            type: 'datetime',
+            optional: true,
+            description: 'When the order was placed',
+        },
+        confirmedAt: {
+            type: 'datetime',
+            optional: true,
+            description: 'When the order was confirmed',
+        },
+        shippedAt: {
+            type: 'datetime',
+            optional: true,
+            description: 'When the order was shipped',
+        },
+        deliveredAt: {
+            type: 'datetime',
+            optional: true,
+            description: 'When the order was delivered',
+        },
+        cancelledAt: {
+            type: 'datetime',
+            optional: true,
+            description: 'When the order was cancelled',
+        },
+    },
+    relationships: {
+        customer: {
+            type: 'Customer',
+            backref: 'orders',
+            description: 'Customer who placed the order',
+        },
+        items: {
+            type: 'OrderItem[]',
+            backref: 'order',
+            description: 'Line items in this order',
+        },
+        discount: {
+            type: 'Discount',
+            required: false,
+            description: 'Applied discount/coupon',
+        },
+    },
+    actions: [
+        'create',
+        'update',
+        'confirm',
+        'process',
+        'fulfill',
+        'ship',
+        'deliver',
+        'cancel',
+        'refund',
+        'addItem',
+        'removeItem',
+        'updateAddress',
+        'applyDiscount',
+        'removeDiscount',
+        'sendNotification',
+        'print',
+        'export',
+    ],
+    events: [
+        'created',
+        'updated',
+        'confirmed',
+        'processing',
+        'fulfilled',
+        'shipped',
+        'delivered',
+        'cancelled',
+        'refunded',
+        'itemAdded',
+        'itemRemoved',
+        'addressUpdated',
+        'discountApplied',
+        'discountRemoved',
+        'notificationSent',
+        'printed',
+        'exported',
+    ],
+};
+/**
+ * Order item entity
+ *
+ * Represents a line item in an order
+ */
+export const OrderItem = {
+    singular: 'order item',
+    plural: 'order items',
+    description: 'A line item in an order',
+    properties: {
+        // Product Info
+        productName: {
+            type: 'string',
+            description: 'Product name (snapshot at time of order)',
+        },
+        variantTitle: {
+            type: 'string',
+            optional: true,
+            description: 'Variant title if applicable',
+        },
+        sku: {
+            type: 'string',
+            optional: true,
+            description: 'Product or variant SKU',
+        },
+        // Quantity & Price
+        quantity: {
+            type: 'number',
+            description: 'Quantity ordered',
+        },
+        price: {
+            type: 'number',
+            description: 'Unit price at time of order',
+        },
+        subtotal: {
+            type: 'number',
+            description: 'Line item subtotal (price × quantity)',
+        },
+        discountAmount: {
+            type: 'number',
+            optional: true,
+            description: 'Discount applied to this line item',
+        },
+        taxAmount: {
+            type: 'number',
+            optional: true,
+            description: 'Tax for this line item',
+        },
+        total: {
+            type: 'number',
+            description: 'Line item total',
+        },
+        // Fulfillment
+        fulfillmentStatus: {
+            type: 'string',
+            optional: true,
+            description: 'Fulfillment status: unfulfilled, fulfilled, returned',
+            examples: ['unfulfilled', 'fulfilled', 'returned'],
+        },
+        quantityFulfilled: {
+            type: 'number',
+            optional: true,
+            description: 'Quantity that has been fulfilled',
+        },
+        // Metadata
+        image: {
+            type: 'url',
+            optional: true,
+            description: 'Product image URL',
+        },
+        requiresShipping: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether this item requires shipping',
+        },
+    },
+    relationships: {
+        order: {
+            type: 'Order',
+            backref: 'items',
+            description: 'Parent order',
+        },
+        product: {
+            type: 'Product',
+            backref: 'orderItems',
+            description: 'The product ordered',
+        },
+        variant: {
+            type: 'ProductVariant',
+            required: false,
+            backref: 'orderItems',
+            description: 'The variant ordered if applicable',
+        },
+    },
+    actions: [
+        'add',
+        'update',
+        'remove',
+        'fulfill',
+        'unfulfill',
+        'return',
+        'refund',
+    ],
+    events: [
+        'added',
+        'updated',
+        'removed',
+        'fulfilled',
+        'unfulfilled',
+        'returned',
+        'refunded',
+    ],
+};
+// =============================================================================
+// Cart
+// =============================================================================
+/**
+ * Shopping cart entity
+ *
+ * Represents a customer's shopping cart
+ */
+export const Cart = {
+    singular: 'cart',
+    plural: 'carts',
+    description: 'A shopping cart containing products to be purchased',
+    properties: {
+        // Status
+        status: {
+            type: 'string',
+            description: 'Cart status: active, abandoned, completed',
+            examples: ['active', 'abandoned', 'completed'],
+        },
+        // Amounts
+        subtotal: {
+            type: 'number',
+            optional: true,
+            description: 'Subtotal of all items',
+        },
+        discountAmount: {
+            type: 'number',
+            optional: true,
+            description: 'Total discount amount',
+        },
+        total: {
+            type: 'number',
+            optional: true,
+            description: 'Total cart value',
+        },
+        currency: {
+            type: 'string',
+            description: 'Currency code',
+            examples: ['USD', 'EUR', 'GBP', 'CAD'],
+        },
+        // Item Count
+        itemCount: {
+            type: 'number',
+            optional: true,
+            description: 'Total number of items in cart',
+        },
+        uniqueItemCount: {
+            type: 'number',
+            optional: true,
+            description: 'Number of unique products in cart',
+        },
+        // Discounts
+        couponCode: {
+            type: 'string',
+            optional: true,
+            description: 'Applied coupon code',
+        },
+        // Session
+        token: {
+            type: 'string',
+            optional: true,
+            description: 'Cart token for anonymous users',
+        },
+        expiresAt: {
+            type: 'datetime',
+            optional: true,
+            description: 'When the cart expires',
+        },
+        // Metadata
+        notes: {
+            type: 'string',
+            optional: true,
+            description: 'Customer notes or special instructions',
+        },
+        lastActivityAt: {
+            type: 'datetime',
+            optional: true,
+            description: 'Last time cart was modified',
+        },
+    },
+    relationships: {
+        customer: {
+            type: 'Customer',
+            required: false,
+            backref: 'carts',
+            description: 'Customer who owns this cart (if logged in)',
+        },
+        items: {
+            type: 'OrderItem[]',
+            description: 'Items in the cart',
+        },
+        discount: {
+            type: 'Discount',
+            required: false,
+            description: 'Applied discount/coupon',
+        },
+    },
+    actions: [
+        'create',
+        'addItem',
+        'removeItem',
+        'updateItem',
+        'clear',
+        'applyCoupon',
+        'removeCoupon',
+        'checkout',
+        'abandon',
+        'recover',
+        'merge',
+    ],
+    events: [
+        'created',
+        'itemAdded',
+        'itemRemoved',
+        'itemUpdated',
+        'cleared',
+        'couponApplied',
+        'couponRemoved',
+        'checkedOut',
+        'abandoned',
+        'recovered',
+        'merged',
+    ],
+};
+// =============================================================================
+// Customer
+// =============================================================================
+/**
+ * Customer entity
+ *
+ * Represents an e-commerce customer
+ */
+export const Customer = {
+    singular: 'customer',
+    plural: 'customers',
+    description: 'An e-commerce customer',
+    properties: {
+        // Identity
+        email: {
+            type: 'string',
+            description: 'Customer email address',
+        },
+        firstName: {
+            type: 'string',
+            optional: true,
+            description: 'First name',
+        },
+        lastName: {
+            type: 'string',
+            optional: true,
+            description: 'Last name',
+        },
+        phone: {
+            type: 'string',
+            optional: true,
+            description: 'Phone number',
+        },
+        // Account
+        acceptsMarketing: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether customer accepts marketing emails',
+        },
+        emailVerified: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether email has been verified',
+        },
+        // Status
+        status: {
+            type: 'string',
+            optional: true,
+            description: 'Customer status: active, disabled, invited',
+            examples: ['active', 'disabled', 'invited'],
+        },
+        // Addresses
+        defaultAddress: {
+            type: 'json',
+            optional: true,
+            description: 'Default shipping address',
+        },
+        addresses: {
+            type: 'json',
+            array: true,
+            optional: true,
+            description: 'Saved addresses',
+        },
+        // Metadata
+        notes: {
+            type: 'string',
+            optional: true,
+            description: 'Internal notes about the customer',
+        },
+        tags: {
+            type: 'string',
+            array: true,
+            optional: true,
+            description: 'Customer tags for segmentation',
+        },
+        // Statistics
+        orderCount: {
+            type: 'number',
+            optional: true,
+            description: 'Total number of orders',
+        },
+        totalSpent: {
+            type: 'number',
+            optional: true,
+            description: 'Total amount spent',
+        },
+        averageOrderValue: {
+            type: 'number',
+            optional: true,
+            description: 'Average order value',
+        },
+        // Timestamps
+        lastOrderAt: {
+            type: 'datetime',
+            optional: true,
+            description: 'Date of last order',
+        },
+        firstOrderAt: {
+            type: 'datetime',
+            optional: true,
+            description: 'Date of first order',
+        },
+    },
+    relationships: {
+        orders: {
+            type: 'Order[]',
+            backref: 'customer',
+            description: 'Customer orders',
+        },
+        carts: {
+            type: 'Cart[]',
+            backref: 'customer',
+            description: 'Customer shopping carts',
+        },
+        reviews: {
+            type: 'Review[]',
+            backref: 'customer',
+            description: 'Product reviews written by this customer',
+        },
+    },
+    actions: [
+        'create',
+        'update',
+        'delete',
+        'enable',
+        'disable',
+        'invite',
+        'addAddress',
+        'updateAddress',
+        'removeAddress',
+        'setDefaultAddress',
+        'sendEmail',
+        'addNote',
+        'tag',
+        'untag',
+        'merge',
+        'export',
+    ],
+    events: [
+        'created',
+        'updated',
+        'deleted',
+        'enabled',
+        'disabled',
+        'invited',
+        'addressAdded',
+        'addressUpdated',
+        'addressRemoved',
+        'defaultAddressSet',
+        'emailSent',
+        'noteAdded',
+        'tagged',
+        'untagged',
+        'merged',
+        'exported',
+        'orderPlaced',
+        'emailVerified',
+    ],
+};
+// =============================================================================
+// Inventory
+// =============================================================================
+/**
+ * Inventory entity
+ *
+ * Tracks inventory for products and variants
+ */
+export const Inventory = {
+    singular: 'inventory',
+    plural: 'inventories',
+    description: 'Inventory tracking for a product or variant',
+    properties: {
+        // Quantity
+        quantity: {
+            type: 'number',
+            description: 'Available quantity',
+        },
+        reservedQuantity: {
+            type: 'number',
+            optional: true,
+            description: 'Quantity reserved for pending orders',
+        },
+        availableQuantity: {
+            type: 'number',
+            optional: true,
+            description: 'Quantity available for new orders',
+        },
+        // Thresholds
+        lowStockThreshold: {
+            type: 'number',
+            optional: true,
+            description: 'Threshold for low stock warning',
+        },
+        isLowStock: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether inventory is below threshold',
+        },
+        isOutOfStock: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether inventory is out of stock',
+        },
+        // Policy
+        allowBackorder: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether to allow backorders when out of stock',
+        },
+        trackInventory: {
+            type: 'boolean',
+            description: 'Whether to track inventory for this item',
+        },
+        // Location
+        location: {
+            type: 'string',
+            optional: true,
+            description: 'Warehouse or location name',
+        },
+        bin: {
+            type: 'string',
+            optional: true,
+            description: 'Bin or shelf location',
+        },
+        // Metadata
+        lastRestockedAt: {
+            type: 'datetime',
+            optional: true,
+            description: 'Last time inventory was restocked',
+        },
+        lastCountedAt: {
+            type: 'datetime',
+            optional: true,
+            description: 'Last physical inventory count',
+        },
+    },
+    relationships: {
+        product: {
+            type: 'Product',
+            required: false,
+            backref: 'inventory',
+            description: 'Product being tracked',
+        },
+        variant: {
+            type: 'ProductVariant',
+            required: false,
+            backref: 'inventory',
+            description: 'Variant being tracked',
+        },
+    },
+    actions: [
+        'create',
+        'update',
+        'adjust',
+        'reserve',
+        'release',
+        'restock',
+        'count',
+        'transfer',
+        'setThreshold',
+    ],
+    events: [
+        'created',
+        'updated',
+        'adjusted',
+        'reserved',
+        'released',
+        'restocked',
+        'counted',
+        'transferred',
+        'thresholdSet',
+        'lowStock',
+        'outOfStock',
+        'backInStock',
+    ],
+};
+// =============================================================================
+// Discount
+// =============================================================================
+/**
+ * Discount entity
+ *
+ * Represents a discount code or coupon
+ */
+export const Discount = {
+    singular: 'discount',
+    plural: 'discounts',
+    description: 'A discount code or coupon',
+    properties: {
+        // Identity
+        code: {
+            type: 'string',
+            description: 'Discount code (e.g., "SAVE20")',
+        },
+        name: {
+            type: 'string',
+            optional: true,
+            description: 'Internal name for the discount',
+        },
+        // Type
+        type: {
+            type: 'string',
+            description: 'Discount type: percentage, fixed_amount, free_shipping',
+            examples: ['percentage', 'fixed_amount', 'free_shipping'],
+        },
+        value: {
+            type: 'number',
+            description: 'Discount value (percentage or amount)',
+        },
+        // Conditions
+        minimumPurchase: {
+            type: 'number',
+            optional: true,
+            description: 'Minimum purchase amount required',
+        },
+        minimumQuantity: {
+            type: 'number',
+            optional: true,
+            description: 'Minimum quantity of items required',
+        },
+        appliesToProducts: {
+            type: 'string',
+            array: true,
+            optional: true,
+            description: 'Product IDs this discount applies to',
+        },
+        appliesToCategories: {
+            type: 'string',
+            array: true,
+            optional: true,
+            description: 'Categories this discount applies to',
+        },
+        excludedProducts: {
+            type: 'string',
+            array: true,
+            optional: true,
+            description: 'Product IDs excluded from discount',
+        },
+        // Usage
+        usageLimit: {
+            type: 'number',
+            optional: true,
+            description: 'Maximum number of times code can be used',
+        },
+        usageCount: {
+            type: 'number',
+            optional: true,
+            description: 'Number of times code has been used',
+        },
+        usageLimitPerCustomer: {
+            type: 'number',
+            optional: true,
+            description: 'Max uses per customer',
+        },
+        oneTimeUse: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether code can only be used once',
+        },
+        // Validity
+        startsAt: {
+            type: 'datetime',
+            optional: true,
+            description: 'When discount becomes active',
+        },
+        endsAt: {
+            type: 'datetime',
+            optional: true,
+            description: 'When discount expires',
+        },
+        active: {
+            type: 'boolean',
+            description: 'Whether discount is currently active',
+        },
+        // Metadata
+        description: {
+            type: 'string',
+            optional: true,
+            description: 'Description of the discount',
+        },
+    },
+    relationships: {
+        orders: {
+            type: 'Order[]',
+            description: 'Orders that used this discount',
+        },
+    },
+    actions: [
+        'create',
+        'update',
+        'activate',
+        'deactivate',
+        'delete',
+        'apply',
+        'remove',
+        'extend',
+        'duplicate',
+    ],
+    events: [
+        'created',
+        'updated',
+        'activated',
+        'deactivated',
+        'deleted',
+        'applied',
+        'removed',
+        'extended',
+        'duplicated',
+        'expired',
+        'limitReached',
+    ],
+};
+// =============================================================================
+// Review
+// =============================================================================
+/**
+ * Review entity
+ *
+ * Represents a product review
+ */
+export const Review = {
+    singular: 'review',
+    plural: 'reviews',
+    description: 'A customer review of a product',
+    properties: {
+        // Rating
+        rating: {
+            type: 'number',
+            description: 'Star rating (typically 1-5)',
+        },
+        // Content
+        title: {
+            type: 'string',
+            optional: true,
+            description: 'Review title or headline',
+        },
+        body: {
+            type: 'string',
+            description: 'Review text content',
+        },
+        // Author
+        authorName: {
+            type: 'string',
+            optional: true,
+            description: 'Name of reviewer',
+        },
+        authorEmail: {
+            type: 'string',
+            optional: true,
+            description: 'Email of reviewer',
+        },
+        verified: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether reviewer is a verified purchaser',
+        },
+        // Status
+        status: {
+            type: 'string',
+            description: 'Review status: pending, published, rejected',
+            examples: ['pending', 'published', 'rejected'],
+        },
+        publishedAt: {
+            type: 'datetime',
+            optional: true,
+            description: 'When review was published',
+        },
+        // Engagement
+        helpful: {
+            type: 'number',
+            optional: true,
+            description: 'Number of "helpful" votes',
+        },
+        notHelpful: {
+            type: 'number',
+            optional: true,
+            description: 'Number of "not helpful" votes',
+        },
+        // Media
+        images: {
+            type: 'url',
+            array: true,
+            optional: true,
+            description: 'Customer-submitted images',
+        },
+        videos: {
+            type: 'url',
+            array: true,
+            optional: true,
+            description: 'Customer-submitted videos',
+        },
+        // Metadata
+        source: {
+            type: 'string',
+            optional: true,
+            description: 'Review source: website, email, imported',
+            examples: ['website', 'email', 'imported'],
+        },
+    },
+    relationships: {
+        product: {
+            type: 'Product',
+            backref: 'reviews',
+            description: 'Product being reviewed',
+        },
+        customer: {
+            type: 'Customer',
+            required: false,
+            backref: 'reviews',
+            description: 'Customer who wrote the review',
+        },
+    },
+    actions: [
+        'create',
+        'update',
+        'publish',
+        'unpublish',
+        'approve',
+        'reject',
+        'delete',
+        'markHelpful',
+        'markNotHelpful',
+        'reply',
+        'flag',
+    ],
+    events: [
+        'created',
+        'updated',
+        'published',
+        'unpublished',
+        'approved',
+        'rejected',
+        'deleted',
+        'markedHelpful',
+        'markedNotHelpful',
+        'replied',
+        'flagged',
+    ],
+};
+// =============================================================================
+// Export all entities as a schema
+// =============================================================================
+/**
+ * All e-commerce entity types
+ */
+export const EcommerceEntities = {
+    Product,
+    ProductVariant,
+    Order,
+    OrderItem,
+    Cart,
+    Customer,
+    Inventory,
+    Discount,
+    Review,
+};
+/**
+ * Entity categories for organization
+ */
+export const EcommerceCategories = {
+    products: ['Product', 'ProductVariant'],
+    orders: ['Order', 'OrderItem'],
+    cart: ['Cart'],
+    customers: ['Customer'],
+    inventory: ['Inventory'],
+    marketing: ['Discount'],
+    reviews: ['Review'],
+};