Search API: Add Package Data Fields

Document Version: 1.1 Created: 2025-11-24 Updated: 2025-11-24 Status: ✅ Implemented - Pending Deployment Related Frontend Work: PartSpecs component for part cards

Overview

This document specifies a simple enhancement to include package dimension fields in the search API response. Currently, this data is only available in the detail API's specifications field. Adding it to search results enables the frontend to display package specs on catalog cards without requiring additional API calls.

Current State

Search API Response

Endpoint: GET/POST /api/search

The search API already returns weight for each part:

interface Part {
  // ... existing fields
  weight: number | null;  // Already present
}

Detail API Response

Endpoint: GET /api/parts/:id

Package dimensions are available in the specifications object:

{
  "specifications": {
    "Package Weight": "0.199",
    "Package Length": "63",
    "Package Width": "34",
    "Package Height": "63"
    // ... other specs
  }
}

Requirements

Problem Statement

The frontend displays part cards in catalog views (grid and list). We want to show key specs (weight, dimensions, package quantity) on these cards for quick scannability. Currently:

• weight is available in search results (can display)
• Package dimensions are only in detail API (cannot display without N+1 queries)
• Package quantity is not exposed anywhere

Use Cases

1. User browses catalog → sees weight and dimensions on each card
2. User compares parts → dimensions help assess physical compatibility
3. User estimates shipping → dimensions give rough idea of package size

API Specification

Request

No changes to request parameters.

Response Enhancement

Add packaging object to each Part in search results:

interface Part {
  // Existing fields...
  weight: number | null;           // Legacy field (deprecated)

  // New packaging object
  packaging: {
    quantity?: number;             // Items per package
    length?: number;               // Package length in mm
    width?: number;                // Package width in mm
    height?: number;               // Package height in mm
    weight?: number;               // Package weight
    lengthUnit?: 'mm' | 'cm' | 'in';  // Length unit (default: mm)
    weightUnit?: 'kg' | 'lb';      // Weight unit (default: kg)
  } | null;
}

Example Response

{
  "results": [
    {
      "id": "nhl-84356153",
      "partNumber": "84356153",
      "packaging": {
        "length": 63,
        "width": 34,
        "height": 63,
        "weight": 0.199,
        "quantity": 1,
        "lengthUnit": "mm",
        "weightUnit": "lb"
      }
      // ... other fields
    }
  ]
}

Data Source

The data should come from the same source as the specifications field in the detail API:

Data Transformation

• Parse string values to numbers (e.g., "63" → 63)
• Return null for missing or invalid values
• Normalize units to mm (if data is stored in different units)

Priority Classification

P0 (Must Have) - MVP

• packageLength field
• packageWidth field
• packageHeight field

P1 (Should Have) - Post-MVP

• packageQuantity field (if data available)

Implementation Notes

Performance Considerations

1. Index optimization: Ensure package fields are stored in the search index (not fetched from source)
2. Minimal overhead: These are simple numeric fields, minimal impact on response size

Backward Compatibility

This is an additive change - existing clients will ignore new fields. No breaking changes.

Frontend Integration

TypeScript Type Update

✅ Implemented in /lib/db/parts-types.ts:

/**
 * Package dimensions and weight from search API.
 */
export interface PartPackaging {
  quantity?: number;
  length?: number;
  width?: number;
  height?: number;
  weight?: number;
  lengthUnit?: "mm" | "cm" | "in";
  weightUnit?: "kg" | "lb";
}

interface UnifiedCatalogPart {
  // Existing fields...
  /** @deprecated Use packaging.weight instead */
  weight?: number;
  /** Package dimensions and weight */
  packaging?: PartPackaging;
}

UI Display

✅ Implemented in PartSpecs component. Displays in format:

⚖️ 0.2 kg · 📐 63×34×63 mm · 📦 2 pc

Component features:

• Fallback to legacy weight field for backwards compatibility
• Automatic unit handling (kg/lb, mm/cm/in)
• Package quantity only shown when > 1
• Returns null if no specs available (clean DOM)

Timeline Estimate

Total: 2-4 days

Questions for Backend Team

1. Data availability: What percentage of parts have package dimension data?
2. Data source: Are dimensions stored in the same index as other part data, or do they need to be joined?
3. Units: Are dimensions consistently in mm, or do we need unit conversion?
4. Package quantity: Is this data available? What field name is it stored under?

Success Metrics

• Response size impact: < 5% increase in response payload
• Query latency: No measurable increase in search latency
• Frontend display rate: Track % of cards that show dimensions (indicates data coverage)

Implementation Status

Backend ✅

• Types added to src/types/part.ts
• Zod validation in src/schemas/parts.ts
• Elasticsearch mapping updated
• Transformer logic in src/sync/transformers.ts
• Index migration (pending)
• Re-index data (pending)
• Deploy to production (pending)

Frontend ✅

• PartPackaging interface in /lib/db/parts-types.ts
• UnifiedCatalogPart updated with packaging field
• PartSpecs component with full packaging support
• Integrated into grid and list card variants
• Visual testing after backend deploy

Document Status: Implementation complete, pending deployment Priority: Medium (enhances UX but not blocking) Contact: Frontend team for questions