@propertysimple/client 0.1.0

package/contracts/src/property-features.js

@@ -0,0 +1,398 @@
+import { z } from 'zod';
+/** Stable product vocabulary. Availability describes an implemented inference path,
+ * not measured model accuracy or whether a particular feed supplies the field. */
+export const PROPERTY_DISCOVERY_REGISTRY_VERSION = 'property-discovery-v1';
+export const PropertyFeatureDefinitionSchema = z.strictObject({
+    id: z.string().regex(/^[a-z][a-z0-9_]{1,79}$/),
+    family: z.number().int().min(1).max(52),
+    label: z.string().min(1).max(160),
+    definition: z.string().min(1).max(1600),
+    type: z.enum(['boolean', 'string', 'number']),
+    values: z.record(z.string(), z.string()).optional(),
+    synonyms: z.array(z.string().min(1).max(100)).max(20),
+    applicability: z.enum(['any', 'dwelling', 'sale', 'rental']),
+    source_paths: z.array(z.string().min(1)).min(1),
+    operators: z.array(z.enum(['eq', 'neq', 'in', 'not_in', 'gt', 'gte', 'lt', 'lte'])),
+    availability: z.enum(['source_and_interpretation', 'source_only']),
+    consequence: z.enum(['ordinary', 'consequential']),
+    status: z.literal('experimental'),
+});
+export const PropertyFeatureRegistrySchema = z.strictObject({
+    version: z.literal(PROPERTY_DISCOVERY_REGISTRY_VERSION),
+    features: z.array(PropertyFeatureDefinitionSchema),
+});
+export const PROPERTY_FEATURE_FAMILIES = [
+    'Outdoor living',
+    'Laundry',
+    'Energy efficiency',
+    'Storage',
+    'Single-level living',
+    'Garage',
+    'Pools and spas',
+    'Water amenities',
+    'Accessory living spaces',
+    'Fenced yard',
+    'Fireplace and wood stove',
+    'Architecture',
+    'Land and farm facilities',
+    'Furnishing',
+    'Pet rules',
+    'Workspaces',
+    'Gardens',
+    'Solar',
+    'Architectural details',
+    'HVAC',
+    'Roof replacement',
+    'System replacement',
+    'Condition',
+    'Association',
+    'Outbuildings',
+    'RV and boat facilities',
+    'Basement',
+    'Views',
+    'Layout and daylight',
+    'Kitchen and bath',
+    'Access features',
+    'Security equipment',
+    'Outdoor cooking and gathering',
+    'EV charging',
+    'Backup power',
+    'Architect involvement',
+    'Seller financing',
+    'Seller incentives',
+    'Assumable mortgage',
+    'Lease purchase',
+    'Short-term rental claim',
+    'Occupancy claim',
+    'Off-grid operation',
+    'Water and sewer',
+    'Shelter',
+    'Historic status',
+    'Private wellness',
+    'Sports courts',
+    'Internet service',
+    'Landscaping',
+    'Resilience specifications',
+    'Land tenure',
+].map((label, index) => ({ id: index + 1, label }));
+const source = (fields) => [
+    ...fields.map((field) => `property_details.features.${field}`),
+    'description',
+];
+function feature(family, id, label, definition, fields, options = {}) {
+    return {
+        family,
+        id,
+        label,
+        definition,
+        type: options.values ? 'string' : 'boolean',
+        synonyms: [],
+        applicability: [
+            7, 8, 13, 17, 18, 21, 24, 25, 26, 28, 32, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46,
+            48, 49, 50, 51, 52,
+        ].includes(family)
+            ? 'any'
+            : 'dwelling',
+        source_paths: [`attributes.${id}`, ...source(fields)],
+        operators: options.values ? ['eq', 'neq', 'in', 'not_in'] : ['eq', 'neq'],
+        availability: 'source_and_interpretation',
+        consequence: 'ordinary',
+        status: 'experimental',
+        ...options,
+    };
+}
+const exact = (family, id, label, definition, type, paths) => ({
+    family,
+    id,
+    label,
+    definition,
+    type,
+    synonyms: [],
+    applicability: 'any',
+    source_paths: paths,
+    operators: type === 'number' ? ['eq', 'neq', 'gt', 'gte', 'lt', 'lte'] : ['eq', 'neq', 'in', 'not_in'],
+    availability: 'source_only',
+    consequence: 'ordinary',
+    status: 'experimental',
+});
+const consequential = { consequence: 'consequential', applicability: 'any' };
+const offered = {
+    offered: 'The source explicitly advertises this offer without a stated conditional qualifier.',
+    conditional: 'The source explicitly offers this only subject to approval, terms, qualification or another stated condition.',
+    not_offered: 'The source explicitly states this offer is not available.',
+};
+/** Never reuse an existing ID for a narrower claim: the legacy coarse pantry,
+ * laundry and style definitions remain alongside precise discovery attributes. */
+export const PROPERTY_FEATURE_REGISTRY = [
+    feature(1, 'private_yard', 'Private yard', 'An existing yard exclusively for this property; shared grounds or room for a yard is insufficient.', ['ExteriorFeatures', 'LotFeatures']),
+    feature(1, 'patio', 'Patio', 'An existing private patio serving this property; a shared patio is insufficient.', ['PatioAndPorchFeatures', 'ExteriorFeatures']),
+    feature(1, 'deck', 'Deck', 'An existing private deck serving this property.', [
+        'PatioAndPorchFeatures',
+    ]),
+    feature(1, 'covered_porch', 'Covered porch', 'An existing covered porch, not a merely covered patio or proposed porch.', ['PatioAndPorchFeatures']),
+    feature(1, 'outdoor_living', 'Outdoor living', 'An explicitly described patio, deck, terrace or outdoor entertaining space belonging to the property.', ['PatioAndPorchFeatures', 'ExteriorFeatures']),
+    feature(1, 'covered_outdoor_space', 'Covered outdoor space', 'An explicitly roofed or covered patio, porch, deck or terrace on this property.', ['PatioAndPorchFeatures']),
+    feature(1, 'balcony', 'Balcony', 'A balcony belonging to this property, explicitly stated.', [
+        'PatioAndPorchFeatures',
+        'ExteriorFeatures',
+    ]),
+    feature(2, 'laundry_room', 'Laundry room', 'A dedicated existing laundry room; a closet, shared facility or hookup alone does not establish a room.', ['LaundryFeatures', 'Rooms', 'RoomType', 'InteriorFeatures']),
+    feature(2, 'laundry_appliances_installed', 'Installed laundry appliances', 'Both a washer and dryer explicitly installed and included inside the dwelling; hookups, negotiable appliances and communal laundry are insufficient.', ['Appliances', 'LaundryFeatures']),
+    feature(2, 'laundry_hookups', 'Laundry hookups', 'Installed washer/dryer hookups in the dwelling; does not establish included appliances.', ['LaundryFeatures', 'InteriorFeatures']),
+    feature(2, 'laundry_in_unit', 'In-unit laundry facilities', 'Laundry appliances or hookups explicitly inside the dwelling or unit; shared laundry is insufficient.', ['LaundryFeatures', 'Appliances']),
+    feature(3, 'efficient_windows', 'Energy-efficient windows', 'Source explicitly specifies energy-efficient or ENERGY STAR windows; new or double-pane alone is not an efficiency certification.', ['WindowFeatures', 'GreenEnergyEfficient']),
+    feature(3, 'efficient_appliances', 'Energy-efficient appliances', 'Source explicitly specifies energy-efficient or ENERGY STAR appliances; no predicted savings.', ['Appliances', 'GreenEnergyEfficient']),
+    feature(3, 'insulation_upgrade', 'Insulation upgrade', 'An explicit installed insulation upgrade or named enhanced insulation specification; generic efficient home claims are insufficient.', ['GreenEnergyEfficient']),
+    feature(4, 'walk_in_pantry', 'Walk-in pantry', 'An explicitly walk-in pantry; a pantry without walk-in specification and ordinary cabinets are insufficient.', ['InteriorFeatures', 'Rooms']),
+    feature(4, 'pantry', 'Pantry', 'An explicitly described pantry; ordinary kitchen cabinets alone are insufficient.', ['InteriorFeatures', 'Rooms']),
+    feature(4, 'walk_in_closet', 'Walk-in closet', 'An explicitly described walk-in closet.', [
+        'InteriorFeatures',
+    ]),
+    feature(4, 'garage_storage', 'Garage storage', 'Dedicated installed shelving, cabinetry or storage space in a garage; garage presence alone is insufficient.', ['ParkingFeatures', 'InteriorFeatures']),
+    feature(4, 'built_in_storage', 'Built-in storage', 'Explicitly described built-in shelving, cabinetry or storage beyond ordinary kitchen cabinets.', ['InteriorFeatures']),
+    feature(5, 'single_level', 'Single-level dwelling', 'The entire dwelling is explicitly single-story or single-level; a single room on the ground floor is insufficient.', ['InteriorFeatures', 'Stories']),
+    feature(5, 'main_level_primary_bedroom', 'Main-level primary bedroom', 'An existing primary bedroom explicitly on the main or entry living level; does not establish step-free entry.', ['InteriorFeatures', 'Rooms', 'RoomType']),
+    feature(5, 'main_level_full_bath', 'Main-level full bathroom', 'An existing full bathroom explicitly on the main or entry living level; a powder room is insufficient.', ['InteriorFeatures', 'Rooms', 'RoomType']),
+    feature(6, 'garage', 'Garage', 'A garage explicitly included with this property; street parking or a carport is insufficient.', ['ParkingFeatures']),
+    feature(6, 'oversized_garage', 'Oversized garage', 'The source explicitly calls the garage oversized; do not infer this from vehicle capacity.', ['ParkingFeatures']),
+    exact(6, 'garage_capacity', 'Garage capacity', 'Explicit garage vehicle spaces; no capacity inferred from prose or area.', 'number', ['property_details.garage_spaces']),
+    feature(7, 'private_pool', 'Private pool', 'A swimming pool belonging exclusively to this property, not a shared community pool.', ['PoolFeatures']),
+    feature(7, 'community_pool', 'Community pool', 'A shared community swimming pool available to this property, not a private pool.', ['CommunityFeatures', 'AssociationAmenities']),
+    feature(7, 'private_spa', 'Private spa or hot tub', 'An installed private spa or hot tub included with the property; community spa access is insufficient.', ['SpaFeatures']),
+    feature(8, 'water_frontage', 'Water frontage', 'The property itself directly borders a body of water; a view or nearby access alone is insufficient.', ['WaterfrontFeatures']),
+    feature(8, 'water_view', 'Water view', 'A water view explicitly described from the property; nearby water alone is insufficient.', ['View']),
+    feature(8, 'water_access', 'Water access', 'Explicit access rights or direct access to water associated with the property; nearby water alone is insufficient and no ownership is implied.', ['WaterfrontFeatures', 'AssociationAmenities'], { ...consequential }),
+    feature(8, 'dock', 'Dock present', 'An existing dock reported for this property; private ownership and access rights are not implied.', ['Dock'], { applicability: 'any' }),
+    feature(8, 'private_dock', 'Private dock', 'An existing dock explicitly for exclusive property use; shared docks, availability and dock permits alone are insufficient.', ['Dock', 'ExteriorFeatures', 'WaterfrontFeatures']),
+    feature(9, 'accessory_dwelling', 'Accessory dwelling', 'An explicitly described separate accessory dwelling or guest house; this does not establish legal permit or rental status.', ['OtherStructures', 'InteriorFeatures']),
+    feature(9, 'detached_guest_house', 'Detached guest house', 'An existing detached guest dwelling, not a room, attached suite or future conversion; no permit claim.', ['OtherStructures']),
+    feature(9, 'guest_suite', 'Guest suite', 'An explicitly separate guest suite within the property; spare bedrooms alone are insufficient.', ['InteriorFeatures', 'Rooms']),
+    feature(9, 'in_law_suite', 'In-law suite', 'An existing suite explicitly described as an in-law or multigenerational suite; no legal separate-unit claim.', ['InteriorFeatures', 'Rooms']),
+    feature(9, 'separate_entrance', 'Separate entrance', 'An existing separate entrance to a described suite, living space or basement; not merely the dwelling front door.', ['InteriorFeatures', 'ExteriorFeatures', 'Basement']),
+    feature(10, 'fenced_yard', 'Fenced yard', 'An explicitly fenced private yard; a fence elsewhere or suggested fencing is insufficient.', ['Fencing', 'ExteriorFeatures']),
+    feature(10, 'fully_fenced_yard', 'Fully fenced yard', 'The private yard is explicitly fully fenced or enclosed on all sides; partial fencing or a gate alone is insufficient.', ['Fencing', 'ExteriorFeatures']),
+    feature(11, 'fireplace', 'Fireplace', 'An installed fireplace explicitly part of the property.', [
+        'FireplaceFeatures',
+    ]),
+    feature(11, 'wood_stove', 'Wood stove', 'An installed wood-burning stove; a fireplace or wood-stove-ready connection is insufficient.', ['Heating', 'FireplaceFeatures']),
+    feature(12, 'architectural_style', 'Architectural style', 'The architectural style explicitly named in the source; do not guess a style from location, age or price.', ['ArchitecturalStyle'], {
+        values: {
+            contemporary: 'Explicit contemporary or modern architectural design.',
+            craftsman: 'Explicit Craftsman architecture.',
+            colonial: 'Explicit Colonial architecture.',
+            mediterranean: 'Explicit Mediterranean or Spanish design.',
+            ranch: 'Explicit ranch architectural style, not ranch land.',
+            victorian: 'Explicit Victorian architecture.',
+            other: 'An explicitly named style outside the supplied values.',
+        },
+    }),
+    ...Object.entries({
+        midcentury: 'midcentury or mid-century modern',
+        tudor: 'Tudor',
+        a_frame: 'A-frame',
+        cottage: 'cottage',
+        loft: 'loft',
+        cabin: 'cabin',
+    }).map(([id, style]) => feature(12, `style_${id}`, `${style} style`, `The source explicitly describes the dwelling as ${style} architecture or form; do not guess from photographs, age or a nearby place name.`, ['ArchitecturalStyle', 'StructureType'])),
+    exact(13, 'lot_area_acres', 'Lot area in acres', 'Exact normalized source lot area with a known conversion unit; unknown units stay unavailable.', 'number', ['lot_size']),
+    feature(13, 'barn', 'Barn', 'An existing barn on this property; barn-style decoration and proposed barns are insufficient.', ['OtherStructures'], { applicability: 'any' }),
+    feature(13, 'horse_facilities', 'Horse facilities', 'Existing stalls, stables, paddocks or an equestrian arena; horse-friendly zoning or room for horses alone is insufficient.', ['OtherStructures', 'LotFeatures'], { applicability: 'any' }),
+    feature(13, 'farm_buildings', 'Farm buildings', 'Existing agricultural outbuildings explicitly on the property; acreage or farmland alone is insufficient.', ['OtherStructures'], { applicability: 'any' }),
+    feature(14, 'furnishing', 'Furnishing terms', 'The explicitly advertised furnishing arrangement for this property; staged photographs prove nothing.', [], {
+        values: {
+            furnished: 'Furniture explicitly included with the advertised transaction.',
+            partially_furnished: 'Only some furniture explicitly included.',
+            negotiable: 'Furniture explicitly negotiable or separately purchasable, not promised included.',
+            unfurnished: 'Explicitly unfurnished or furniture excluded.',
+        },
+    }),
+    feature(15, 'pet_policy', 'Pet policy', 'The advertised property pet rule; this is a source claim, not legal advice or an assistance-animal policy.', ['PetsAllowed'], {
+        ...consequential,
+        applicability: 'rental',
+        values: {
+            allowed: 'Pets explicitly allowed without stated restrictions.',
+            conditional: 'Pets require approval, conditions or restrictions.',
+            prohibited: 'Pets explicitly prohibited.',
+        },
+    }),
+    feature(15, 'cats_allowed', 'Cats allowed', 'Cats explicitly allowed for this rental; conditional approval or generic pets considered is not unconditional permission.', ['PetsAllowed'], { ...consequential, applicability: 'rental' }),
+    feature(15, 'dogs_allowed', 'Dogs allowed', 'Dogs explicitly allowed for this rental; conditional approval or generic pets considered is not unconditional permission.', ['PetsAllowed'], { ...consequential, applicability: 'rental' }),
+    feature(15, 'pet_restrictions_stated', 'Pet restrictions stated', 'The rental source explicitly states species, breed, size, number or approval restrictions; do not invent their exact terms.', ['PetsAllowed'], { ...consequential, applicability: 'rental' }),
+    feature(16, 'dedicated_workspace', 'Dedicated workspace', 'A dedicated office or workspace described as part of the property, rather than a suggested conversion.', ['Rooms', 'RoomType', 'InteriorFeatures', 'OtherStructures']),
+    feature(16, 'enclosed_study', 'Enclosed study', 'An existing enclosed study or office room; a desk nook or convertible bedroom is insufficient.', ['Rooms', 'InteriorFeatures']),
+    feature(16, 'detached_work_studio', 'Detached work studio', 'An existing detached workspace or studio; a shed suitable for conversion is insufficient.', ['OtherStructures']),
+    feature(17, 'garden', 'Garden', 'An existing planted garden belonging to the property; garden tub, garden-level unit and space for a garden are insufficient.', ['ExteriorFeatures', 'LotFeatures', 'Vegetation']),
+    feature(17, 'raised_garden_beds', 'Raised garden beds', 'Existing raised garden beds on the property; proposed beds are insufficient.', ['ExteriorFeatures', 'LotFeatures']),
+    feature(17, 'greenhouse', 'Greenhouse', 'An existing greenhouse on the property; green home or a proposed greenhouse is insufficient.', ['OtherStructures']),
+    feature(17, 'orchard', 'Orchard', 'An existing orchard on the property, not a subdivision or street name.', ['Vegetation', 'LotFeatures']),
+    feature(17, 'fruit_trees', 'Fruit trees', 'Existing fruit-bearing trees on the property; decorative trees or a fruit-themed street name are insufficient.', ['Vegetation', 'LotFeatures', 'ExteriorFeatures']),
+    feature(18, 'solar_panels', 'Solar panels', 'Installed solar panels explicitly serving the property; suitability or solar-ready wiring is insufficient.', ['GreenEnergyGeneration']),
+    feature(18, 'solar_ownership', 'Solar ownership', 'The explicitly stated tenure of the installed solar system; presence alone proves no ownership.', ['GreenEnergyGeneration'], {
+        ...consequential,
+        values: {
+            owned: 'Explicitly owned outright.',
+            leased: 'Explicitly leased system.',
+            financed: 'Explicitly financed system or outstanding solar loan.',
+        },
+    }),
+    feature(19, 'exposed_beams', 'Exposed beams', 'Explicitly described exposed ceiling or structural beams.', ['InteriorFeatures']),
+    feature(19, 'exposed_interior_brick', 'Exposed interior brick', 'Visible exposed brick explicitly inside the dwelling; brick exterior is insufficient.', ['InteriorFeatures']),
+    feature(19, 'interior_arches', 'Interior arches', 'Existing architectural arches explicitly inside the dwelling.', ['InteriorFeatures']),
+    feature(19, 'original_vintage_details', 'Original vintage details', 'Explicit original or retained historic interior details; generic charm, age or reproduction finishes are insufficient.', ['InteriorFeatures']),
+    feature(20, 'central_air_conditioning', 'Central air conditioning', 'Central air conditioning explicitly present; ceiling fans or an unspecified cooling system are insufficient.', ['Cooling']),
+    feature(20, 'heat_pump', 'Heat pump', 'An installed heat pump for space conditioning; a heat-pump-ready connection or water heater alone is insufficient.', ['Heating', 'Cooling']),
+    feature(20, 'zoned_hvac', 'Zoned HVAC', 'An explicitly zoned heating or cooling system; multiple units alone do not establish independent zones.', ['Heating', 'Cooling']),
+    feature(20, 'smart_thermostat', 'Smart thermostat', 'An installed smart or connected thermostat; programmable alone is insufficient.', ['InteriorFeatures', 'GreenEnergyEfficient']),
+    feature(21, 'roof_replaced', 'Roof replaced', 'A completed roof replacement explicitly stated; servicing, a warranty, material type or planned replacement is insufficient.', ['Roof']),
+    exact(21, 'roof_replacement_year', 'Roof replacement year', 'An explicitly normalized source year for completed roof replacement; never infer a year from relative recency.', 'number', ['attributes.roof_replacement_year']),
+    exact(21, 'roof_material', 'Roof material', 'Explicit normalized source roof material; does not establish replacement or condition.', 'string', ['property_details.features.Roof']),
+    ...[
+        ['hvac', 'HVAC'],
+        ['water_heater', 'Water heater'],
+        ['windows', 'Windows'],
+    ].flatMap(([id, label]) => [
+        feature(22, `${id}_replaced`, `${label} replaced`, `A completed ${label.toLowerCase()} replacement explicitly stated; servicing, a warranty and planned work are insufficient.`, id === 'windows' ? ['WindowFeatures'] : ['Heating', 'Cooling', 'Appliances']),
+        exact(22, `${id}_replacement_year`, `${label} replacement year`, `An explicitly normalized source year for completed ${label.toLowerCase()} replacement; no date extraction by Jev.`, 'number', [`attributes.${id}_replacement_year`]),
+    ]),
+    feature(23, 'described_condition', 'Described condition', 'The condition explicitly described in the source, not an inference from photographs, price or generic promotional adjectives.', ['PropertyCondition'], {
+        values: {
+            new_construction: 'Explicitly newly built or new construction, not merely new to market.',
+            renovated: 'Explicitly renovated or remodeled; cosmetic adjectives alone are insufficient.',
+            needs_renovation: 'Explicitly needs renovation, repair or substantial work.',
+        },
+    }),
+    feature(23, 'renovated_kitchen', 'Renovated kitchen', 'A completed kitchen renovation or remodel explicitly stated; generic updated finishes or planned work are insufficient.', ['InteriorFeatures', 'PropertyCondition']),
+    feature(23, 'renovated_bathroom', 'Renovated bathroom', 'A completed bathroom renovation or remodel explicitly stated; generic updated finishes or planned work are insufficient.', ['InteriorFeatures', 'PropertyCondition']),
+    feature(24, 'association_present', 'Association present', 'An owners association explicitly applies to the property; zero or missing fees do not establish no association.', ['AssociationAmenities', 'AssociationFeeIncludes'], { ...consequential }),
+    feature(24, 'special_assessment_mentioned', 'Special assessment mentioned', 'An association special assessment is explicitly mentioned; ordinary recurring fees and special listing conditions are insufficient.', ['AssociationFeeIncludes'], { ...consequential }),
+    exact(24, 'association_fee_amount', 'Association fee amount', 'Exact primary association amount, used with known currency and period; zero does not prove no association.', 'number', ['property_details.association_fees']),
+    exact(24, 'association_fee_currency', 'Association fee currency', 'Explicit supported currency for the primary association fee; never inferred from the listing price.', 'string', ['property_details.association_fees']),
+    exact(24, 'association_fee_period', 'Association fee period', 'Exact known primary association billing period; unspecified frequency is unknown.', 'string', ['property_details.association_fees']),
+    feature(25, 'workshop', 'Workshop', 'An existing workshop on the property; space suitable for a workshop is insufficient.', ['OtherStructures', 'Rooms']),
+    feature(25, 'powered_outbuilding', 'Powered outbuilding', 'An existing outbuilding explicitly supplied with electricity; electric service to the main property alone is insufficient.', ['OtherStructures', 'Utilities']),
+    feature(25, 'insulated_outbuilding', 'Insulated outbuilding', 'An existing outbuilding explicitly insulated; potential conversion is insufficient.', ['OtherStructures']),
+    feature(26, 'rv_parking', 'RV parking', 'Existing space explicitly designated for RV parking; does not establish hookup or legal permission.', ['ParkingFeatures', 'ExteriorFeatures'], { applicability: 'any' }),
+    feature(26, 'boat_parking', 'Boat parking', 'Existing space explicitly designated for boat parking; does not establish water access.', ['ParkingFeatures', 'ExteriorFeatures'], { applicability: 'any' }),
+    feature(26, 'covered_vehicle_storage', 'Covered vehicle storage', 'Existing covered RV or boat storage; ordinary garage or uncovered space alone is insufficient.', ['ParkingFeatures', 'OtherStructures'], { applicability: 'any' }),
+    feature(26, 'rv_hookup', 'RV hookup', 'An installed RV utility hookup; parking space or general utilities alone are insufficient.', ['ExteriorFeatures', 'Utilities'], { applicability: 'any' }),
+    feature(27, 'finished_basement', 'Finished basement', 'Basement explicitly finished in whole or part; no legal bedroom or rental-unit claim.', ['Basement']),
+    feature(27, 'walkout_basement', 'Walkout basement', 'Basement explicitly has a walkout to the exterior; an interior stair alone is insufficient.', ['Basement']),
+    feature(28, 'mountain_view', 'Mountain view', 'A mountain view explicitly described from the property; geographic proximity alone is insufficient.', ['View']),
+    feature(28, 'city_view', 'City view', 'A city or skyline view explicitly described from the property.', ['View']),
+    feature(28, 'golf_view', 'Golf view', 'A golf course view explicitly from the property; nearby golf is insufficient.', ['View']),
+    feature(28, 'ocean_view', 'Ocean view', 'An ocean view explicitly from the property; proximity or a generic water view is insufficient.', ['View']),
+    feature(29, 'open_layout', 'Open layout', 'An explicitly open-plan or open-concept living layout; an open house event is insufficient.', ['InteriorFeatures']),
+    feature(29, 'high_ceilings', 'High ceilings', 'Explicitly high, vaulted or cathedral ceilings; do not estimate ceiling height from photos.', ['InteriorFeatures']),
+    feature(29, 'skylights', 'Skylights', 'Installed skylights explicitly serving the dwelling; natural-light adjectives alone are insufficient.', ['WindowFeatures', 'InteriorFeatures']),
+    feature(30, 'kitchen_island', 'Kitchen island', 'An existing kitchen island; portable furniture or room for an island is insufficient.', ['InteriorFeatures']),
+    feature(30, 'eat_in_kitchen', 'Eat-in kitchen', 'An explicitly eat-in kitchen or dedicated dining area inside the kitchen.', ['InteriorFeatures', 'Rooms']),
+    feature(30, 'double_vanity', 'Double vanity', 'An installed double-sink bathroom vanity; two separate bathrooms are insufficient.', ['InteriorFeatures']),
+    feature(31, 'step_free_entry', 'Step-free entry', 'An explicitly step-free or zero-step entrance to the dwelling; do not infer legal accessibility compliance.', ['AccessibilityFeatures']),
+    feature(31, 'entrance_ramp', 'Entrance ramp', 'An existing ramp serving a dwelling entrance; no whole-home accessibility certification.', ['AccessibilityFeatures']),
+    feature(31, 'elevator_access', 'Elevator access', 'An elevator explicitly serves the unit or is installed inside the dwelling; do not infer accessibility certification.', ['AccessibilityFeatures', 'InteriorFeatures']),
+    feature(31, 'curbless_shower', 'Curbless shower', 'An explicitly curbless or roll-in shower; walk-in shower alone is insufficient.', ['AccessibilityFeatures', 'InteriorFeatures']),
+    feature(32, 'security_system', 'Security system', 'An installed security alarm system; monitoring subscription and neighborhood safety are not implied.', ['SecurityFeatures']),
+    feature(32, 'security_cameras', 'Security cameras', 'Installed security cameras included with the property; no operating or subscription guarantee.', ['SecurityFeatures']),
+    feature(32, 'gated_property', 'Gated property', 'A private gate controlling entry to this property; a gated community alone is insufficient.', ['SecurityFeatures', 'ExteriorFeatures']),
+    feature(32, 'community_security', 'Community access control', 'An explicitly described staffed, gated or access-controlled community; this is not a safety or crime claim.', ['SecurityFeatures', 'CommunityFeatures']),
+    feature(33, 'outdoor_kitchen', 'Outdoor kitchen', 'An existing private outdoor kitchen; a portable grill alone is insufficient.', ['ExteriorFeatures']),
+    feature(33, 'built_in_grill', 'Built-in grill', 'An existing installed private outdoor grill; portable or communal grills are insufficient.', ['ExteriorFeatures']),
+    feature(33, 'fire_pit', 'Fire pit', 'An existing private fire pit included with the property; communal access and proposed installation are insufficient.', ['ExteriorFeatures']),
+    feature(34, 'ev_charging', 'Installed EV charging', 'An installed electric vehicle charging facility explicitly available to this property; EV-ready wiring alone is insufficient.', ['ParkingFeatures', 'Electric']),
+    feature(34, 'ev_ready_wiring', 'EV-ready wiring', 'Installed dedicated EV-ready wiring or prewiring explicitly stated; no installed charger is implied.', ['Electric', 'ParkingFeatures']),
+    feature(35, 'generator', 'Generator', 'An installed generator included with the property; generator-ready hookup alone is insufficient.', ['Electric', 'OtherEquipment']),
+    feature(35, 'home_battery', 'Home battery', 'An installed home electrical battery storage system; solar alone is insufficient.', ['GreenEnergyGeneration', 'Electric']),
+    feature(35, 'backup_power_connection', 'Backup power connection', 'An installed generator inlet, transfer switch or dedicated backup-power connection; no generator is implied.', ['Electric']),
+    ...[
+        ['designed', 'designed'],
+        ['built', 'built'],
+        ['owned', 'owned'],
+    ].map(([id, verb]) => feature(36, `architect_${id}`, `Architect-${verb}`, `The source explicitly says an architect ${verb} this property; architectural style, architect-quality adjectives or builder name alone are insufficient.`, [], { consequence: 'consequential' })),
+    exact(36, 'architect_name', 'Architect name', 'An explicitly normalized public architect credit; names are not generated or guessed by Jev.', 'string', ['attributes.architect_name']),
+    feature(37, 'seller_financing', 'Seller financing', 'The seller explicitly offers owner carry or seller financing; buyer financing availability is insufficient.', ['ListingTerms'], {
+        ...consequential,
+        applicability: 'sale',
+        values: offered,
+        synonyms: ['owner carry', 'owner financing'],
+    }),
+    feature(38, 'seller_credit', 'Seller credit', 'An explicitly advertised seller credit or concession; asking-price reductions alone are insufficient.', ['ListingTerms'], { ...consequential, applicability: 'sale', values: offered }),
+    feature(38, 'closing_cost_contribution', 'Closing-cost contribution', 'Seller explicitly offers a contribution toward buyer closing costs.', ['ListingTerms'], { ...consequential, applicability: 'sale', values: offered }),
+    feature(38, 'rate_buydown', 'Rate buydown', 'An explicitly advertised seller or builder mortgage rate buydown; financing or low-rate adjectives alone are insufficient.', ['ListingTerms'], { ...consequential, applicability: 'sale', values: offered }),
+    feature(39, 'assumable_mortgage', 'Assumable mortgage claim', 'An assumable mortgage is explicitly advertised; no guarantee of approval, transferability or rate.', ['ListingTerms'], { ...consequential, applicability: 'sale', values: offered }),
+    feature(40, 'lease_purchase_type', 'Lease purchase proposal', 'An explicit rent-to-own arrangement; an ordinary rental does not qualify.', ['ListingTerms'], {
+        ...consequential,
+        values: {
+            lease_option: 'Explicit option to purchase under a lease.',
+            lease_purchase: 'Explicit lease-purchase agreement or obligation.',
+            rent_to_own: 'Explicit rent-to-own without sufficient subtype detail.',
+            not_offered: 'Explicitly no rent-to-own or lease purchase.',
+        },
+    }),
+    feature(41, 'short_term_rental_claim', 'Short-term rental source claim', 'Explicit advertised permission or restriction for short-term rentals; zoning, income potential and current operation do not establish legality.', ['ListingTerms'], {
+        ...consequential,
+        values: {
+            allowed: 'Explicit source claim that short-term rental use is allowed.',
+            conditional: 'Explicitly subject to approval, permit or stated conditions.',
+            prohibited: 'Explicit source claim that short-term rental use is prohibited.',
+        },
+        synonyms: ['STR', 'vacation rental'],
+    }),
+    feature(42, 'occupancy_claim', 'Occupancy source claim', 'Explicit current occupancy or delivery commitment; no exact future date or lease terms inferred.', [], {
+        ...consequential,
+        values: {
+            tenant_occupied: 'Explicitly occupied by a tenant now.',
+            lease_in_place: 'An existing lease explicitly remains in force.',
+            delivered_vacant: 'Explicit commitment to deliver vacant.',
+            vacant: 'Explicitly vacant now.',
+        },
+    }),
+    exact(42, 'vacancy_date', 'Vacancy date', 'An explicitly normalized source vacancy date; relative promises are not converted by Jev.', 'string', ['attributes.vacancy_date']),
+    feature(43, 'off_grid_status', 'Off-grid status', 'Explicit operation independent of utility grid service; solar, well and septic alone do not establish off-grid operation.', ['Utilities'], {
+        ...consequential,
+        values: {
+            operating_off_grid: 'The existing property explicitly operates off-grid.',
+            grid_optional: 'Existing off-grid operation with an optional grid connection explicitly available.',
+            potential: 'Only off-grid potential or proposed conversion is described.',
+        },
+    }),
+    feature(44, 'well', 'Well', 'An installed water well serving the property; does not establish potable water, yield or rights.', ['WaterSource'], { applicability: 'any' }),
+    feature(44, 'septic', 'Septic system', 'An installed septic system serving the property; a septic permit or soil suitability is insufficient.', ['Sewer'], { applicability: 'any' }),
+    feature(44, 'rainwater_collection', 'Rainwater collection', 'An installed rainwater collection system; no potable-water or capacity claim.', ['WaterSource', 'ExteriorFeatures'], { applicability: 'any' }),
+    feature(44, 'cistern', 'Cistern', 'An installed water cistern; no potable-water or capacity claim.', ['WaterSource'], { applicability: 'any' }),
+    feature(45, 'storm_shelter', 'Storm shelter', 'An existing space explicitly described as a storm shelter; basement alone is insufficient and no protection certification is implied.', ['OtherStructures', 'SecurityFeatures']),
+    feature(45, 'safe_room', 'Safe room', 'An existing room explicitly described as a safe room; generic security does not suffice and no certification is implied.', ['SecurityFeatures', 'Rooms']),
+    feature(45, 'underground_bunker', 'Underground bunker', 'An existing underground bunker explicitly stated; basement or shelter alone is insufficient.', ['OtherStructures']),
+    feature(46, 'historic_designation_claim', 'Historic designation claim', 'The source explicitly claims an official historic designation or register listing; age and historic character alone are insufficient.', ['SpecialListingConditions'], { consequence: 'consequential' }),
+    feature(46, 'historic_character', 'Historic character', 'Explicit historic or period architectural character; does not establish an official designation.', ['ArchitecturalStyle', 'InteriorFeatures']),
+    feature(47, 'private_sauna', 'Private sauna', 'An installed private sauna; community sauna access is insufficient.', ['InteriorFeatures', 'OtherStructures']),
+    feature(47, 'private_cold_plunge', 'Private cold plunge', 'An installed private cold plunge; pool or communal facility is insufficient.', ['InteriorFeatures', 'ExteriorFeatures']),
+    feature(47, 'home_gym', 'Home gym', 'An existing dedicated private gym space; suggested conversion and community fitness are insufficient.', ['Rooms', 'InteriorFeatures']),
+    feature(47, 'home_theater', 'Home theater', 'An existing dedicated home theater or media room; an ordinary living-room television is insufficient.', ['Rooms', 'InteriorFeatures']),
+    feature(47, 'community_fitness', 'Community fitness', 'An explicitly available shared community fitness center or gym, not a nearby commercial gym.', ['CommunityFeatures', 'AssociationAmenities']),
+    ...['tennis', 'pickleball', 'basketball'].flatMap((sport) => ['private', 'community'].map((scope) => feature(48, `${scope}_${sport}_court`, `${scope} ${sport} court`, `An existing ${sport} court ${scope === 'private' ? 'exclusively belonging to this property' : 'available as a shared community amenity'}; nearby facilities and room to build are insufficient.`, scope === 'private'
+        ? ['ExteriorFeatures', 'LotFeatures']
+        : ['AssociationAmenities', 'CommunityFeatures']))),
+    feature(49, 'fiber_internet_advertised', 'Fiber internet advertised', 'Fiber internet service explicitly advertised as available to this property; no active subscription or guaranteed speed.', ['Utilities', 'InteriorFeatures']),
+    feature(49, 'high_speed_internet_advertised', 'High-speed internet advertised', 'High-speed internet explicitly advertised as available; no guaranteed speed, uptime or active connection.', ['Utilities', 'InteriorFeatures']),
+    feature(50, 'irrigation_system', 'Irrigation system', 'An installed landscape irrigation system; irrigation rights or nearby water alone are insufficient.', ['ExteriorFeatures', 'LotFeatures']),
+    feature(50, 'low_maintenance_landscaping', 'Low-maintenance landscaping claim', 'The source explicitly describes existing landscaping as low maintenance; no cost or labor savings estimate.', ['LotFeatures', 'ExteriorFeatures']),
+    feature(50, 'xeriscaping', 'Xeriscaping', 'Existing xeriscaping explicitly described; a dry climate or sparse yard is insufficient.', ['LotFeatures', 'ExteriorFeatures']),
+    feature(51, 'impact_windows', 'Impact windows', 'Explicit impact-resistant windows; ordinary double glazing is insufficient and no insurance or compliance claim is implied.', ['WindowFeatures']),
+    feature(51, 'hurricane_shutters', 'Hurricane shutters', 'Existing hurricane or storm shutters explicitly installed or included; no protection rating implied.', ['WindowFeatures', 'ExteriorFeatures']),
+    feature(51, 'fire_resistant_materials', 'Fire-resistant material claim', 'Explicit named fire-resistant construction materials; ordinary material names alone do not establish fire resistance or compliance.', ['ConstructionMaterials', 'Roof']),
+    feature(52, 'land_tenure', 'Land tenure claim', 'Explicit land ownership or lease tenure; property subtype and absence of a fee are insufficient.', ['ListingTerms'], {
+        ...consequential,
+        values: {
+            owned: 'Source explicitly states land is owned with the property.',
+            leased: 'Source explicitly states land is leased or subject to a ground lease.',
+        },
+    }),
+    exact(52, 'ground_lease_amount', 'Ground lease amount', 'Exact source ground-lease amount with separately preserved currency and frequency.', 'number', ['attributes.ground_lease_amount']),
+    exact(52, 'ground_lease_currency', 'Ground lease currency', 'Explicit supported currency for the ground-lease amount; never inferred from the listing price.', 'string', ['attributes.ground_lease_currency']),
+    exact(52, 'ground_lease_period', 'Ground lease period', 'Explicit canonical ground-lease billing period; missing frequency stays unknown.', 'string', ['attributes.ground_lease_period']),
+    exact(52, 'ground_lease_expiry', 'Ground lease expiry', 'Exact normalized source date of ground-lease expiry; no date extraction by Jev.', 'string', ['attributes.ground_lease_expiry']),
+].map((definition) => PropertyFeatureDefinitionSchema.parse(definition));
+const propertyFeatureById = new Map(PROPERTY_FEATURE_REGISTRY.map((feature) => [feature.id, feature]));
+export function propertyFeature(id) {
+    return propertyFeatureById.get(id);
+}

package/contracts/src/publication.d.ts

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+export declare const PublicationReportRequest: z.ZodObject<{
+    dataset_id: z.ZodString;
+    listing_id: z.ZodString;
+    sequence: z.ZodString;
+    state: z.ZodEnum<{
+        unavailable: "unavailable";
+        available: "available";
+    }>;
+    url: z.ZodNullable<z.ZodURL>;
+    listing_revision: z.ZodString;
+    listing_published_at: z.ZodISODateTime;
+    observed_at: z.ZodISODateTime;
+}, z.core.$strict>;
+export declare const PublicationReceipt: z.ZodObject<{
+    listing_id: z.ZodString;
+    product_id: z.ZodString;
+    sequence: z.ZodString;
+    state: z.ZodEnum<{
+        unavailable: "unavailable";
+        available: "available";
+    }>;
+    expires_at: z.ZodISODateTime;
+}, z.core.$strict>;
+export declare const DestinationQuery: z.ZodObject<{
+    id: z.ZodString;
+    dataset_id: z.ZodString;
+    product_id: z.ZodString;
+}, z.core.$strict>;
+export declare const DestinationResponse: z.ZodObject<{
+    listing_id: z.ZodString;
+    product_id: z.ZodString;
+    url: z.ZodNullable<z.ZodString>;
+    available: z.ZodBoolean;
+    reason: z.ZodEnum<{
+        unavailable: "unavailable";
+        expired: "expired";
+        available: "available";
+        not_reported: "not_reported";
+        listing_changed: "listing_changed";
+        source_stale: "source_stale";
+    }>;
+    checked_at: z.ZodISODateTime;
+}, z.core.$strict>;

package/contracts/src/publication.js

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+// Products report their own publication state. This is not a license to publish a listing.
+const Identifier = z.string().min(1).max(256);
+export const PublicationReportRequest = z
+    .strictObject({
+    dataset_id: Identifier,
+    listing_id: Identifier,
+    sequence: z.string().regex(/^[1-9]\d{0,17}$/),
+    state: z.enum(['available', 'unavailable']),
+    url: z.url().max(2048).nullable(),
+    listing_revision: z.string().min(1).max(64),
+    listing_published_at: z.iso.datetime({ offset: true }),
+    observed_at: z.iso.datetime({ offset: true }),
+})
+    .refine((input) => (input.state === 'unavailable' ? input.url === null : input.url !== null), 'Available publications need a URL; unavailable publications must clear it.');
+export const PublicationReceipt = z.strictObject({
+    listing_id: Identifier,
+    product_id: Identifier,
+    sequence: z.string(),
+    state: z.enum(['available', 'unavailable']),
+    expires_at: z.iso.datetime({ offset: true }),
+});
+export const DestinationQuery = z.strictObject({
+    id: Identifier,
+    dataset_id: Identifier,
+    product_id: Identifier,
+});
+export const DestinationResponse = z.strictObject({
+    listing_id: Identifier,
+    product_id: Identifier,
+    url: z.string().nullable(),
+    available: z.boolean(),
+    reason: z.enum([
+        'available',
+        'not_reported',
+        'unavailable',
+        'expired',
+        'listing_changed',
+        'source_stale',
+    ]),
+    checked_at: z.iso.datetime({ offset: true }),
+});