Developer Docs

Product Feature Enhancements

This document outlines the enhancements made to the Product management features, including backend schema updates, frontend management forms, and public display on item detail pages.

Overview

We have expanded the capabilities of Products to support more complex e-commerce scenarios. This includes support for product variants, inventory tracking, and shipping specifications.

Key Features

1. Variants

  • Description: Products can now have multiple variants (e.g., Size, Color).
  • Schema: Variant type added with id, name, sku, price, compareAtPrice, inventory, and options (key-value pairs).
  • Management: A new ProductVariantsManager component allows Malet Owners to define options and generate variants.
  • Display: The Item Detail page allows Visitors to select variants, dynamically updating the displayed price and stock status.

Automated Variant Generation (Backend API)

The products subgraph features a Cartesian matrix generation utility via the generateProductVariants mutation. Providing a tree of theoretical options (e.g. Size: [Small, Large], Color: [Red, Blue]) automatically yields the complete spectrum of SKUs.

  • Smart Retention: Existing variants that precisely match the generated matrix parameters are preserved, preventing accidental overrides of custom variant prices or inventory numbers during batch regenerations.

1b. Product Scaffolding (Duplicate API)

For rapidly creating deeply configured catalogs, Malet Owners can securely duplicate entire product configurations seamlessly using the duplicateProduct GraphQL mutation.

  • Transposes attributes (Images, Options, SKUs boundaries).
  • Scrubs protected system states (_id, internal variant ids, createdAt, etc).
  • Automatically initializes the replicated clone directly into an ItemStatus.DRAFT state for safety.

2. Inventory Tracking

  • Description: Detailed control over inventory levels.
  • Fields:
    • trackInventory: Boolean to enable/disable tracking.
    • totalInventory: Aggregate stock count.
    • sku: Stock Keeping Unit identifier.
  • Management: Integrated into the product create/edit forms.
  • Display: "In Stock" or "Out of Stock" badges are displayed based on current inventory levels.

3. Pricing

  • Compare-at Price: Added compareAtPrice to show original prices alongside sale prices, enabling "strikethrough" pricing displays.
  • Display: If compareAtPrice is greater than the current price, it is shown on the item page to indicate a discount.

4. Shipping Specifications

  • Description: Physical attributes for shipping calculations.
  • Fields:
    • weight: Product weight in grams.
    • dimensions: Object containing length, width, height, and unit.
  • Management: A ShippingManager component handles these inputs.
  • Display: Displayed in a "Specifications" section on the item page.

Technical Implementation

Components

New reusable Svelte components were created:

  • ProductVariantsManager.svelte: Handles variant generation and editing.
  • ShippingManager.svelte: Manages weight and dimension inputs.
  • MediaUploader.svelte: Handles image upload with drag-and-drop, preview, and reordering.
  • TagInput.svelte: Generic tag management.

GraphQL Updates

  • Queries: GET_ITEM_DETAILS was updated to fetch all new nested fields for products.
  • Mutations: UPDATE_PRODUCT accepts the full range of input fields matching the new logical capabilities.
  • Interfaces: TypeScript interfaces (ProductNode) updated to reflect the schema changes.