@propertysimple/client 0.1.0 → 0.2.0

package/contracts/src/search.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { ListingSchema } from './schemas.js';
+import { ListingSchema, Money } from './schemas.js';
 import { PropertyFeatureRegistrySchema } from './property-features.js';
 import { CatalogInventoryStatusSchema } from './catalog-inventory.js';
 const Id = z.string().min(1).max(256);
@@ -18,6 +18,11 @@ const Decimal = z
     .string()
     .regex(/^\d+(?:\.\d{1,2})?$/)
     .max(20);
+const WholeRange = (max) => z.strictObject({
+    min: z.number().int().min(0).max(max).optional(),
+    max: z.number().int().min(0).max(max).optional(),
+});
+const PropertyTypes = z.array(z.string().min(1).max(100)).min(1).max(20);
 export const SearchBounds = z
     .tuple([
     z.number().min(-180).max(180),
@@ -42,6 +47,24 @@ export const SearchFilters = z.strictObject({
     region: z.string().min(1).max(100).optional(),
     postal_code: z.string().min(1).max(30).optional(),
     property_type: z.string().min(1).max(100).optional(),
+    /** Any of these property types. */
+    property_types: PropertyTypes.optional(),
+    /** None of these property types; a listing without a type stays eligible. */
+    exclude_property_types: PropertyTypes.optional(),
+    /** CountyOrParish without a trailing " County" or " Parish". Names repeat across
+     * states, so pair it with `region`. */
+    county: z.string().min(1).max(200).optional(),
+    /** Whole days since the source listing date (listing contract date, else on-market
+     * date) at request time. ListHub sends no DaysOnMarket of its own. */
+    days_on_market: WholeRange(36500).optional(),
+    year_built: WholeRange(3000).optional(),
+    /** Lot area, compared in `lot_size_unit`. */
+    lot_size: Range.optional(),
+    lot_size_unit: z.enum(['acres', 'sqft']).optional(),
+    has_photos: z.boolean().optional(),
+    /** A branded or unbranded virtual tour URL. false matches listings whose source
+     * explicitly has none. */
+    has_virtual_tour: z.boolean().optional(),
     must: z.array(SearchFeaturePredicate).max(30).default([]),
     any: z.array(SearchFeaturePredicate).max(30).default([]),
     /** Exclude known matches. Unknown evidence stays eligible; use must eq:false for confirmed absence. */
@@ -61,6 +84,17 @@ export const SearchRequest = z
         km: z.number().positive().max(20000),
     })
         .optional(),
+    /** A neighbourhood or drawn area: vertices in order, closed or not. Edges are
+     * straight lines on the latitude/longitude plane, as in GeoJSON and PostGIS
+     * geometry; edges cannot cross and the polygon cannot cross the antimeridian. */
+    polygon: z
+        .array(z.strictObject({
+        latitude: z.number().min(-90).max(90),
+        longitude: z.number().min(-180).max(180),
+    }))
+        .min(3)
+        .max(500)
+        .optional(),
     sort: z.enum(['relevance', 'price_asc', 'price_desc', 'newest']).default('relevance'),
     limit: z.number().int().min(1).max(100).default(24),
     cursor: z.string().min(1).max(4096).optional(),
@@ -69,6 +103,7 @@ export const SearchRequest = z
     facet_limit: z.number().int().min(1).max(100).optional(),
 })
     .refine((v) => !(v.bbox && v.radius), 'Choose bbox or radius, not both.')
+    .refine((v) => !(v.polygon && (v.bbox || v.radius)), 'Choose one of bbox, radius or polygon.')
     .refine((v) => v.facet_limit === undefined || v.facet_fields !== undefined, 'Facet limit requires facet fields.');
 export const SearchMeta = z.strictObject({
     backend: z.enum(['typesense', 'postgres']),
@@ -121,10 +156,13 @@ export const SearchResponse = z.strictObject({
     has_more: z.boolean(),
     meta: SearchMeta,
 });
+/** Values per field, at most 1,000: enough for every city, county or postal code of
+ * one state (a portal's place pages and sitemaps need all of them, not the top 100). */
+export const SEARCH_FACET_LIMIT = 1000;
 export const SearchFacetRequest = z.strictObject({
     query: SearchRequest,
     fields: z.array(z.string().min(1).max(80)).min(1).max(12),
-    limit: z.number().int().min(1).max(100).default(20),
+    limit: z.number().int().min(1).max(SEARCH_FACET_LIMIT).default(20),
 });
 export const SearchFacetResponse = z.strictObject({
     facets: SearchFacetValues,
@@ -177,6 +215,10 @@ export const SearchSuggestRequest = z.strictObject({
     dataset_id: Id.optional(),
     q: z.string().min(1).max(200),
     limit: z.coerce.number().int().min(1).max(20).default(8),
+    /** Also suggest listings by street address (`kind: listing`, `value` is the listing
+     * ID) when the text starts with a house number. Only listings whose address may be
+     * shown. Off by default: older consumers treat any non-place value as search text. */
+    include_listings: z.union([z.boolean(), z.enum(['true', 'false'])]).optional(),
 });
 export const SearchSuggestResponse = z.strictObject({
     suggestions: z.array(z.strictObject({
@@ -213,10 +255,83 @@ export const SearchInterpretResponse = z.strictObject({
     method: z.literal('bounded_rules'),
 });
 export const SearchFeaturesResponse = PropertyFeatureRegistrySchema;
+export const SearchStatsRequest = z.strictObject({ query: SearchRequest });
+/** A compact walk of every listing a query matches, for sitemaps and link indexes:
+ * `after` is the previous page's `next`. Ordered by listing position, never by the
+ * query's sort; the query's cursor, sort and limit do not apply. */
+export const SEARCH_INDEX_LIMIT = 5000;
+export const SearchIndexRequest = z.strictObject({
+    query: SearchRequest,
+    after: z
+        .string()
+        .regex(/^p1\.\d{1,20}$/)
+        .optional(),
+    limit: z.number().int().min(1).max(SEARCH_INDEX_LIMIT).default(1000),
+});
+export const SearchIndexEntry = z.strictObject({
+    id: Id,
+    /** Null where the source withholds the address, as listing-v1 withholds it. */
+    street: z.string().nullable(),
+    city: z.string().nullable(),
+    region: z.string().nullable(),
+    postal_code: z.string().nullable(),
+    price: Money.nullable(),
+    property_type: z.string().nullable(),
+    photo_count: z.number().int().nonnegative(),
+    /** The source listing date, as the days_on_market filter reads it. */
+    listed_at: z.iso.datetime({ offset: true }).nullable(),
+    /** The map pin, as searches place it: null where the address is withheld, the
+     * listing has no usable point, or a geocoded point has expired. */
+    latitude: z.number().min(-90).max(90).nullable(),
+    longitude: z.number().min(-180).max(180).nullable(),
+});
+export const SearchIndexResponse = z.strictObject({
+    data: z.array(SearchIndexEntry),
+    next: z.string().nullable(),
+    has_more: z.boolean(),
+    meta: SearchMeta,
+});
+const PriceStatistic = (unit) => z.strictObject({
+    currency: z.string().regex(/^[A-Z]{3}$/),
+    ...(unit === 'price'
+        ? { period: z.string().nullable() }
+        : { area_unit: z.enum(['sqft', 'sqm']) }),
+    /** Matching listings with a value; the statistics describe these. */
+    listings: z.number().int().positive(),
+    min: Decimal,
+    max: Decimal,
+    /** Mean, rounded to the cent. */
+    avg: Decimal,
+});
+export const SearchStatsResponse = z.strictObject({
+    stats: z.strictObject({
+        /** Matching listings, as meta.total. */
+        count: z.number().int().nonnegative(),
+        /** Null unless the query fixes currency and transaction_type (and price_period
+         * for rentals), or when no matching listing has a price. */
+        price: PriceStatistic('price').nullable(),
+        /** The mean of each listing's price / living area, not a ratio of averages. Also
+         * needs living_area_unit. */
+        price_per_area: PriceStatistic('area').nullable(),
+        /** Whole days since the listing date, as the days_on_market filter counts them.
+         * Listings dated in the future are left out. */
+        days_on_market: z
+            .strictObject({
+            listings: z.number().int().positive(),
+            min: z.number().int().nonnegative(),
+            max: z.number().int().nonnegative(),
+            avg: z.number().nonnegative(),
+        })
+            .nullable(),
+    }),
+    meta: SearchMeta,
+});
 export const searchOperations = {
     searchFeatures: { input: z.strictObject({}), output: SearchFeaturesResponse },
     searchListings: { input: SearchRequest, output: SearchResponse },
     searchFacets: { input: SearchFacetRequest, output: SearchFacetResponse },
+    searchStats: { input: SearchStatsRequest, output: SearchStatsResponse },
+    searchIndex: { input: SearchIndexRequest, output: SearchIndexResponse },
     searchMap: { input: SearchMapRequest, output: SearchMapResponse },
     searchSuggest: { input: SearchSuggestRequest, output: SearchSuggestResponse },
     searchInterpret: { input: SearchInterpretRequest, output: SearchInterpretResponse },