@propertysimple/client 0.1.0

package/contracts/src/search.js

@@ -0,0 +1,223 @@
+import { z } from 'zod';
+import { ListingSchema } from './schemas.js';
+import { PropertyFeatureRegistrySchema } from './property-features.js';
+import { CatalogInventoryStatusSchema } from './catalog-inventory.js';
+const Id = z.string().min(1).max(256);
+const FeatureId = z.string().regex(/^[a-z][a-z0-9_]{0,79}$/);
+const Scalar = z.union([z.boolean(), z.string().max(200), z.number().finite()]);
+export const SearchFeaturePredicate = z.strictObject({
+    feature: FeatureId,
+    operator: z.enum(['eq', 'neq', 'in', 'not_in', 'gt', 'gte', 'lt', 'lte']).default('eq'),
+    value: z.union([Scalar, z.array(Scalar).min(1).max(20)]),
+});
+const Range = z.strictObject({
+    min: z.number().nonnegative().optional(),
+    max: z.number().nonnegative().optional(),
+});
+const Decimal = z
+    .string()
+    .regex(/^\d+(?:\.\d{1,2})?$/)
+    .max(20);
+export const SearchBounds = z
+    .tuple([
+    z.number().min(-180).max(180),
+    z.number().min(-90).max(90),
+    z.number().min(-180).max(180),
+    z.number().min(-90).max(90),
+])
+    .refine(([w, s, e, n]) => w <= e && s <= n, 'Use west,south,east,north without crossing the antimeridian.');
+export const SearchFilters = z.strictObject({
+    transaction_type: z.enum(['for_sale', 'for_rent']).optional(),
+    currency: z
+        .string()
+        .regex(/^[A-Z]{3}$/)
+        .optional(),
+    price_period: z.string().min(1).max(40).optional(),
+    price: z.strictObject({ min: Decimal.optional(), max: Decimal.optional() }).optional(),
+    bedrooms: Range.optional(),
+    bathrooms: Range.optional(),
+    living_area: Range.optional(),
+    living_area_unit: z.enum(['sqft', 'sqm']).optional(),
+    city: z.string().min(1).max(200).optional(),
+    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(),
+    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. */
+    exclude: z.array(SearchFeaturePredicate).max(30).default([]),
+    prefer: z.array(SearchFeaturePredicate).max(10).default([]),
+});
+export const SearchRequest = z
+    .strictObject({
+    dataset_id: Id.optional(),
+    q: z.string().max(500).default(''),
+    filters: SearchFilters.prefault({}),
+    bbox: SearchBounds.optional(),
+    radius: z
+        .strictObject({
+        latitude: z.number().min(-90).max(90),
+        longitude: z.number().min(-180).max(180),
+        km: z.number().positive().max(20000),
+    })
+        .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(),
+    /** Optional refinements computed with the same authorized hits and checkpoint. */
+    facet_fields: z.array(z.string().min(1).max(80)).min(1).max(12).optional(),
+    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.facet_limit === undefined || v.facet_fields !== undefined, 'Facet limit requires facet fields.');
+export const SearchMeta = z.strictObject({
+    backend: z.enum(['typesense', 'postgres']),
+    consistency: z.enum(['current_index', 'completed_snapshot', 'degraded']),
+    generation: z.string(),
+    checkpoint: z.string(),
+    query_hash: z.string(),
+    checked_at: z.iso.datetime({ offset: true }),
+    inventory: CatalogInventoryStatusSchema.optional(),
+    snapshot: z
+        .strictObject({
+        published_through_at: z.iso.datetime({ offset: true }),
+        max_lag_seconds: z.number().int().min(60).max(3600),
+        updates_pending: z.boolean(),
+        excluded_count: z.number().int().min(0).max(1000),
+    })
+        .optional(),
+    total: z.number().int().nonnegative().nullable(),
+    total_relation: z.enum(['exact', 'unavailable']),
+    search_time_ms: z.number().nonnegative(),
+    timings: z
+        .strictObject({
+        authorization_ms: z.number().nonnegative(),
+        provider_ms: z.number().nonnegative(),
+        hydration_ms: z.number().nonnegative(),
+        total_ms: z.number().nonnegative(),
+    })
+        .optional(),
+    warnings: z.array(z.string()),
+});
+export const SearchMatch = z.strictObject({
+    feature: FeatureId,
+    value: Scalar,
+    origin: z.enum(['source_structured', 'source_text_interpreted']),
+    evidence_refs: z.array(z.string()),
+});
+const SearchFacetValues = z.array(z.strictObject({
+    field: z.string(),
+    values: z.array(z.strictObject({ value: Scalar, count: z.number().int().nonnegative() })),
+    assessed: z.number().int().nonnegative().nullable(),
+    conflicting: z.number().int().nonnegative().nullable(),
+    not_assessed: z.number().int().nonnegative().nullable(),
+    unknown: z.number().int().nonnegative().nullable(),
+    truncated: z.boolean(),
+}));
+export const SearchResponse = z.strictObject({
+    facets: SearchFacetValues.optional(),
+    data: z.array(z.strictObject({ listing: z.lazy(() => ListingSchema), matched_because: z.array(SearchMatch) })),
+    next_cursor: z.string().nullable(),
+    has_more: z.boolean(),
+    meta: SearchMeta,
+});
+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),
+});
+export const SearchFacetResponse = z.strictObject({
+    facets: SearchFacetValues,
+    meta: SearchMeta,
+});
+export const SearchMapRequest = z.strictObject({
+    query: SearchRequest,
+    // Camera bounds intersect, never replace, the applied bbox/radius and filters.
+    viewport: SearchBounds.optional(),
+    zoom: z.number().int().min(0).max(22).default(10),
+    limit: z.number().int().min(1).max(1000).default(500),
+});
+export const SearchMapResponse = z.strictObject({
+    points: z.array(z.strictObject({
+        id: Id,
+        latitude: z.number().min(-90).max(90),
+        longitude: z.number().min(-180).max(180),
+        price: Decimal.nullable(),
+        // Optional for older search producers; current responses preserve the
+        // canonical currency and source-established payment period together.
+        currency: z
+            .string()
+            .regex(/^[A-Z]{3}$/)
+            .nullable()
+            .optional(),
+        price_period: z.string().nullable().optional(),
+    })),
+    clusters: z.array(z.strictObject({
+        id: z.string(),
+        latitude: z.number().min(-90).max(90),
+        longitude: z.number().min(-180).max(180),
+        count: z.number().int().positive(),
+        bounds: SearchBounds,
+    })),
+    truncated: z.boolean(),
+    unmappable: z.number().int().nonnegative().nullable(),
+    mode: z.enum(['points', 'cells']),
+    coverage: z.enum(['complete', 'bounded']),
+    counts: z.strictObject({
+        matching: z.number().int().nonnegative(),
+        mappable: z.number().int().nonnegative(),
+        viewport: z.number().int().nonnegative(),
+        returned: z.number().int().nonnegative(),
+        represented: z.number().int().nonnegative(),
+    }),
+    valid_until: z.iso.datetime({ offset: true }),
+    meta: SearchMeta,
+});
+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),
+});
+export const SearchSuggestResponse = z.strictObject({
+    suggestions: z.array(z.strictObject({
+        kind: z.enum(['feature', 'place', 'listing']),
+        label: z.string(),
+        value: z.string(),
+        feature: FeatureId.optional(),
+        // Consumers apply these exact filters instead of reparsing a display label
+        // as a full-text query (which could match another listing's description).
+        place: z
+            .strictObject({
+            city: z.string().min(1).max(256).optional(),
+            region: z.string().min(1).max(256).optional(),
+            postal_code: z.string().min(1).max(64).optional(),
+        })
+            .refine((place) => Object.keys(place).length > 0)
+            .optional(),
+    })),
+    meta: SearchMeta,
+});
+export const SearchInterpretRequest = z.strictObject({
+    dataset_id: Id.optional(),
+    text: z.string().min(1).max(500),
+});
+export const SearchInterpretResponse = z.strictObject({
+    query: SearchRequest,
+    chips: z.array(z.strictObject({
+        label: z.string(),
+        field: z.string(),
+        value: z.union([Scalar, z.array(Scalar)]),
+    })),
+    unresolved: z.array(z.string()),
+    requires_confirmation: z.boolean(),
+    method: z.literal('bounded_rules'),
+});
+export const SearchFeaturesResponse = PropertyFeatureRegistrySchema;
+export const searchOperations = {
+    searchFeatures: { input: z.strictObject({}), output: SearchFeaturesResponse },
+    searchListings: { input: SearchRequest, output: SearchResponse },
+    searchFacets: { input: SearchFacetRequest, output: SearchFacetResponse },
+    searchMap: { input: SearchMapRequest, output: SearchMapResponse },
+    searchSuggest: { input: SearchSuggestRequest, output: SearchSuggestResponse },
+    searchInterpret: { input: SearchInterpretRequest, output: SearchInterpretResponse },
+};