feat: Implement search and filtering system for listings

[cole-hackman]

Linked Issues

Closes #POLY-9
Linear: POLY-9

⚠️ Dependency: This PR depends on #POLY-7 (authentication). Please merge POLY-7 first.

Summary

Implements search and filtering system for listings so buyers can quickly find items by keywords, category, price range, and condition.

Changes Made

Shared Types (packages/shared/types/)

• NEW filters.ts - Filter types: ListingFilters, ListingSortOption, PaginatedResult<T>
• MODIFIED listing.ts - Added ListingCondition type and condition field to Listing

Backend (backend/convex/)

• MODIFIED schema.ts:
  • Added condition field (new, like_new, good, fair, poor)
  • Added compound indexes: by_status_category, by_status_createdAt
  • Enhanced search index with filter fields (status, category, condition, description)
• MODIFIED listings.ts:
  • Added searchAndFilterListings query with full-text search, filters, sorting, and pagination
  • Updated createListing to require condition field
• MODIFIED schema.test.ts - Updated tests for new fields and indexes

Features

• ✅ Full-text search by title (with description in index)
• ✅ Filter by category (textbooks, electronics, furniture, tickets, other)
• ✅ Filter by price range (min/max)
• ✅ Filter by condition (new, like_new, good, fair, poor)
• ✅ Sort options (newest, oldest, price_asc, price_desc)
• ✅ Cursor-based pagination (20 items per page)
• ✅ Performant queries with compound indexes

How to Test

npm install
npm run dev:backend

# Test queries via Convex CLI
cd backend
npx convex run listings:searchAndFilterListings '{}'
npx convex run listings:searchAndFilterListings '{"filters":{"category":"textbooks"}}'
npx convex run listings:searchAndFilterListings '{"filters":{"minPrice":10,"maxPrice":50}}'
npx convex run listings:searchAndFilterListings '{"filters":{"searchTerm":"calculus"}}'
npx convex run listings:searchAndFilterListings '{"filters":{"condition":"new","sortBy":"price_asc"}}'

Checklist
- [x] Tests added/updated (schema tests updated)
- [x] Lint/tests pass locally (`npm run lint`, `npm run test`)
- [x] Docs updated (README/ADR/changelog if needed)
- [x] Follows conventional commit format
- [ ] No merge conflicts with `dev` (depends on POLY-7)

<!-- This is an auto-generated comment: release notes by coderabbit.ai -->

## Summary by CodeRabbit

## Release Notes

* **New Features**
  * Advanced search and filtering: filter listings by category, price range, condition status (new/used/refurbished), and more.
  * Multiple sorting options: organize results by newest, oldest, price ascending, or price descending.
  * Enhanced listing information: listings now include condition status, images, seller information, and posting date.
  * Improved search performance and reliability.

<sub>✏️ Tip: You can customize this high-level summary in your review settings.</sub>

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

[evan-taylor]

@cole-hackman it looks like a few of your commits from the auth branch landed here, could you drop b0af9cf, ccf1f30, and 1be11b1 from this branch and push?

[coderabbitai]

📝 Walkthrough

Walkthrough

A new advanced search and filtering API is introduced for listings, supporting full-text search, multi-field filtering by category, price, condition, and status, with sorting and cursor-based pagination. Schema indices are updated to support efficient queries, type definitions are expanded with filter options and listing properties, and validators are extracted for reuse.

Changes

Cohort / File(s)	Summary
Convex API Implementation backend/convex/listings.ts	New searchAndFilterListings export with search, filtering, sorting, and pagination logic. Extracted categoryValidator and conditionValidator for reuse. Updated createListing and updateListing to use validators. Updated searchListings to use shared search_listings index.
Convex Schema & Indices backend/convex/schema.ts	Added two new composite indices: by_status_category on [status, category] and by_status_createdAt on [status, createdAt]. Renamed search index from search_title to search_listings with additional filterFields: status, category, condition, description.
Schema Validation Tests backend/convex/__tests__/schema.test.ts	Extended enum validation to include condition literals: ['new', 'used', 'refurbished']. Added assertions for new indices by_status_category and by_status_createdAt. Renamed search index test from search_title to search_listings and added filter field assertions.
Shared Type Definitions packages/shared/types/listing.ts	Added ListingCondition type ('new' | 'used' | 'refurbished'). Extended ListingStatus to include 'deleted'. Added properties to Listing: sellerId, images, condition, postedOn. Added properties to CreateListingInput: condition, images.
Shared Filter Types packages/shared/types/filters.ts	New module defining ListingSortOption, ListingFilters, and PaginatedResult<T> types for filtering and pagination support.
Shared Type Exports packages/shared/types/index.ts	Added re-export of all types from ./filters module to public API surface.

Sequence Diagram(s)

sequenceDiagram
    actor Client
    participant Convex as Convex Backend
    participant DB as Database
    
    Client->>Convex: searchAndFilterListings(searchTerm?, filters, cursor?)
    
    alt Has search term
        Convex->>DB: Query search_listings index with searchTerm
        DB-->>Convex: Matching documents
    else No search term
        Convex->>DB: Query by_status_category or by_status_createdAt
        DB-->>Convex: Documents by index
    end
    
    Convex->>Convex: Apply in-memory filters (condition, price)
    Convex->>Convex: Sort results (sortBy option)
    Convex->>Convex: Apply cursor-based pagination
    Convex-->>Client: { items[], nextCursor, hasMore }

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Poem

🐰 Whiskers twitching with delight,
Search indices gleaming bright,
Filters, sorts, and pagination flow,
Listings bounding to and fro!
Types expanded, schemas refined,
A faster search for listings we find! 🏃‍♂️✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title 'feat: Implement search and filtering system for listings' clearly and accurately summarizes the main change—adding a comprehensive search and filtering system for listings with keyword search, filters, sorting, and pagination.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

Warning

Tools execution failed with the following error:

Failed to run tools: 13 INTERNAL: Received RST_STREAM with code 2 (Internal server error)

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cole-hackman]

@evan-taylor I dropped the other commits so it should be good now. Let me know if there is still issues, thanks