Search Module

Authorization: Bearer <session-token>

{
  "data": <payload>,
  "message": "Success",
  "statusCode": 200,
  "metadata": { /* search pagination block */ }
}

{
  "data": null,
  "message": "Human-readable summary",
  "statusCode": 400,
  "errorCode": "BAD_REQUEST",
  "errors": [ /* zod issues, when validation fails */ ],
  "debug": { /* dev-only */ }
}

type ProductSearchVariant = {
  id: string;
  sku: string | null;
  // Raw, indexed fields.
  price: number | null;                    // integer minor unit
  specialPrice: number | null;
  specialPriceStartDate: string | null;    // ISO
  specialPriceEndDate: string | null;
  inventoryQuantity: number;               // quantityOnHand - reservedQuantity (>= 0)
  minQuantityPerCart: number | null;
  maxQuantityPerCart: number | null;
  thumbnail: string | null;
  images: string[];
  // Computed at response time so values stay correct between
  // special-price reroll cron ticks.
  originalPrice: number | null;            // = price
  currentPrice: number | null;             // = specialPriceActive ?? price
  specialPriceActive: number | null;       // null if no special is currently in effect
};

type ProductSearchProduct = {
  id: string;
  title: string;
  subtitle: string | null;
  description: string | null;
  slug: string;                            // we return `slug`, not `handle`
  thumbnail: string | null;
  images: string[];
  priceStart: number | null;               // min(currentPrice) across variants
  priceEnd: number | null;                 // max(currentPrice) across variants
  brand: { id: string; slug: string; name: string } | null;
  inStock: boolean;
  hasActiveSpecial: boolean;
  variants: ProductSearchVariant[];
};

type ProductSearchBrandFacet = {
  id: string;
  slug: string;
  name: string;
  productCount: number;
};

type ProductSearchAttributeFacet = {
  code: string;                            // productAttribute.code
  title: string;                           // productAttribute.title (display)
  values: Array<{ value: string; productCount: number }>;
};

type ProductSearchMetadata = {
  total: number;       // products matching the current filter combo (across all pages)
  items: number;       // hits returned in this page
  perPage: number;     // = limit
  currentPage: number; // 1-indexed
  lastPage: number;    // ceil(total / perPage)
};

type SuggestionsPayload = {
  suggestions: string[];                   // distinct titles + brand names
  products: ProductSearchProduct[];        // top N matching products
};

curl -G https://api.example/store/product-search \
  --data-urlencode 'q=lipstick' \
  --data-urlencode 'brands=mac,nars' \
  --data-urlencode 'categories=makeup' \
  --data-urlencode 'attributes={"shade":["red","ruby"]}' \
  --data-urlencode 'inStock=true' \
  --data-urlencode 'sortBy=price-asc' \
  --data-urlencode 'page=1' \
  --data-urlencode 'limit=20'

{
  "data": {
    "products": [
      {
        "id": "01J9...",
        "title": "Velvet Matte Lipstick",
        "subtitle": "Long-wear",
        "description": "...",
        "slug": "velvet-matte-lipstick",
        "thumbnail": "https://cdn.example/p/01J9....jpg",
        "images": ["https://cdn.example/p/01J9....jpg"],
        "priceStart": 129900,
        "priceEnd": 149900,
        "brand": { "id": "01J9...", "slug": "mac", "name": "MAC" },
        "inStock": true,
        "hasActiveSpecial": false,
        "variants": [
          {
            "id": "01J9...",
            "sku": "MAC-VML-RED-3G",
            "price": 149900,
            "specialPrice": null,
            "specialPriceStartDate": null,
            "specialPriceEndDate": null,
            "inventoryQuantity": 12,
            "minQuantityPerCart": null,
            "maxQuantityPerCart": null,
            "thumbnail": "https://cdn.example/v/01J9....jpg",
            "images": [],
            "originalPrice": 149900,
            "currentPrice": 149900,
            "specialPriceActive": null
          }
        ]
      }
    ],
    "brands": [
      { "id": "01J9...", "slug": "mac",  "name": "MAC",  "productCount": 24 },
      { "id": "01J9...", "slug": "nars", "name": "NARS", "productCount": 11 }
    ],
    "attributes": [
      {
        "code": "shade",
        "title": "Shade",
        "values": [
          { "value": "red",  "productCount": 18 },
          { "value": "ruby", "productCount":  6 }
        ]
      }
    ]
  },
  "message": "Success",
  "statusCode": 200,
  "metadata": {
    "total": 35,
    "items": 20,
    "perPage": 20,
    "currentPage": 1,
    "lastPage": 2
  }
}

{
  "data": {
    "suggestions": [
      "Velvet Matte Lipstick",
      "MAC",
      "Velvet Matte Liner"
    ],
    "products": [
      { "id": "01J9...", "title": "Velvet Matte Lipstick", /* ...full product shape... */ }
    ]
  },
  "message": "Success",
  "statusCode": 200
}

{
  "vendorId": "01J9...",   // optional — scope the run to one vendor
  "batchSize": 500          // optional — default 500, max 2000
}

{
  "data": {
    "runId": "01J9...",
    "jobId": "backfill-01J9...-start",
    "vendorId": null,
    "batchSize": 500
  },
  "message": "Success",
  "statusCode": 202
}

ProductService writes  ──►  EventEmitter2  ──►  ProductEventListener
                                                  │
                                                  ▼
                                       BullMQ "search" queue
                                       (jobId-coalesced per product)
                                                  │
                                                  ▼
                                        SearchProcessor.indexOne
                                                  │
                                ┌─────────────────┼──────────────────┐
                                ▼                 ▼                  ▼
                  ProductProjectionService   SEARCH_PORT.indexOne   search_index_state
                  (Drizzle joins → doc)      (Typesense upsert)     (watermark row)

CREATE TABLE "search_index_state" (
  "product_id" text PRIMARY KEY REFERENCES "product"("id") ON DELETE CASCADE,
  "indexed_at" timestamp NOT NULL,
  "last_error" text,
  "attempts" integer DEFAULT 0 NOT NULL,
  "updated_at" timestamp DEFAULT now() NOT NULL
);
CREATE INDEX "search_index_state_indexed_at_idx" ON "search_index_state" ("indexed_at");

filter_by:  status:=active && visibility:=public && publishedAtTs:>0
            [ && brandSlug:=[`...`] ]
            [ && categorySlugs:=[`...`] ]
            [ && tagSlugs:=[`...`] ]
            [ && attr_<code>:=[`...`] ... ]
            [ && priceMin:>=N && priceMin:<=M ]
            [ && inStock:=true|false ]
            [ && hasActiveSpecial:=true|false ]

sort_by:    inStock:desc,priceMin:asc          (etc, depending on sortBy)

facet_by:   brandSlug, categorySlugs, tagSlugs, inStock, hasActiveSpecial,
            attr_<code> for every productAttribute (so filter chips paint
            on the first request, not only after the user filters)

query_by:   title, subtitle, description, brandName, categoryNames

num_typos:  2

export interface SearchPort {
  ensureCollection(): Promise<void>;
  dropCollection(): Promise<void>;
  indexOne(doc: IndexableProduct): Promise<void>;
  indexBulk(docs: IndexableProduct[]): Promise<BulkIndexResult>;
  deindex(productId: string): Promise<void>;
  search(query: SearchQuery): Promise<SearchResult>;
  suggest(q: string, limit: number): Promise<SuggestionResult>;
}

# 1. Boot Typesense (and the rest of the stack)
docker compose up typesense postgres redis -d

# 2. Apply the search_index_state migration
bun run db:migrate

# 3. Start the API — SearchBootstrapper will create the products collection
bun --filter api start:dev

# 4. (Optional) Trigger an initial backfill instead of waiting for the
#    5-min reconcile cron to drip in batches of 100.
curl -X POST http://localhost:3000/admin/search/reindex \
  -H "Authorization: Bearer $ADMIN_SESSION" \
  -H "Content-Type: application/json" \
  -d '{}'

# 5. Hit the storefront search.
curl 'http://localhost:3000/store/product-search?q=lipstick&page=1&limit=10'