@vepler/sdk 2.33.0 → 2.37.0

package/src/sdk/models/operations/querylistingsbysource.ts

@@ -3,6 +3,7 @@
  */
 
 import * as z from "zod/v3";
+import { remap as remap$ } from "../../../lib/primitives.js";
 import { safeParse } from "../../../lib/schemas.js";
 import * as openEnums from "../../types/enums.js";
 import { ClosedEnum, OpenEnum } from "../../types/enums.js";
@@ -10,125 +11,125 @@ import { Result as SafeParseResult } from "../../types/fp.js";
 import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 
 /**
- * Query listings by provider keys
+ * Batch lookup of listings by their provider-specific keys. Queries the aggregated listing index and returns enriched records. Useful for synchronising an external system with specific known listings.
  */
 export type QueryListingsBySourceRequestBody = {
   /**
-   * Provider listing keys (max 500)
+   * Array of provider-specific listing reference keys to retrieve. Each key corresponds to a unique listing within the specified provider's system. Maximum 500 keys per request. Keys that do not match any listing are silently omitted from the response.
    */
   keys: Array<string>;
   /**
-   * Data provider
+   * Data provider identifier to query listings from. All keys in the request must belong to this single provider.
    */
   provider: string;
 };
 
 /**
- * Listing address
+ * Structured postal address for the listed property. Fields are parsed from the original listing data and may be incomplete depending on what the agent provided. The postcode is always present and serves as the primary geographic key.
  */
 export type QueryListingsBySourceAddress = {
   /**
-   * City
+   * City, town, or village name as used by Royal Mail for postal addressing.
    */
   city?: string | undefined;
   /**
-   * Country code
+   * ISO 3166-1 alpha-2 country code. Defaults to 'GB' for Great Britain. Currently only UK properties are supported.
    */
   country: string;
   /**
-   * District
+   * Local district, borough, or neighbourhood within the city (e.g. 'Westminster', 'Shoreditch', 'Didsbury').
    */
   district?: string | undefined;
   /**
-   * Postcode incode
+   * Inward code — the second part of the UK postcode after the space (e.g. '1AA', '4QE'). Combined with outcode forms the full postcode.
    */
   incode?: string | undefined;
   /**
-   * Original address string from source
+   * The raw, unstructured address string exactly as received from the source data feed, before any parsing or normalisation. Useful for display purposes or debugging address-matching issues.
    */
   originalAddress: string;
   /**
-   * Postcode outcode
+   * Outward code — the first part of the UK postcode before the space (e.g. 'SW1A', 'M1', 'EC2'). Useful for area-level grouping and search.
    */
   outcode?: string | undefined;
   /**
-   * UK postcode
+   * Full UK postcode in standard Royal Mail format (e.g. 'SW1A 1AA'). Always present and is the primary geographic identifier used for location matching.
    */
   postcode: string;
   /**
-   * Property number
+   * Building or house number, including any suffix (e.g. '12A', '3-5'). May be absent for named properties or new-build plots.
    */
   propertyNumber?: string | undefined;
   /**
-   * Region
+   * County or administrative region (e.g. 'Greater London', 'West Yorkshire', 'Surrey').
    */
   region?: string | undefined;
   /**
-   * Street name
+   * Street or road name, without the property number. May include thoroughfare type (e.g. 'High Street', 'Park Lane', 'The Crescent').
    */
   street?: string | undefined;
 };
 
 /**
- * Agent information
+ * Contact and identification details for the estate agent marketing this property. All agent data is publicly available information sourced from property portal listings. Null if agent details were not available in the source feed.
  */
 export type QueryListingsBySourceAgent = {
   /**
-   * Agency address
+   * Postal address of the estate agency branch office, as a single formatted string.
    */
   address?: string | undefined;
   /**
-   * Provider's agency ID
+   * Opaque identifier for the agency within the source provider's system. Can be used to group listings across all branches of the same agency.
    */
   agencyId?: string | undefined;
   /**
-   * Agency name
+   * Trading name of the parent estate agency company (e.g. 'Savills', 'Foxtons', 'Purplebricks'). This is the top-level brand that owns one or more branches.
    */
   agencyName?: string | undefined;
   /**
-   * Provider's agent ID
+   * Opaque identifier for the individual agent within the source provider's system. Format varies by provider.
    */
   agentId?: string | undefined;
   /**
-   * Agent name
+   * Name of the individual estate agent or negotiator handling this listing. This is publicly available information from property portals.
    */
   agentName?: string | undefined;
   /**
-   * Provider's branch ID
+   * Opaque identifier for the branch within the source provider's system. Can be used to group listings by branch.
    */
   branchId?: string | undefined;
   /**
-   * Branch name
+   * Name of the specific estate agency branch marketing this property (e.g. 'Kensington Office', 'Manchester City Centre'). A single agency may have multiple branches.
    */
   branchName?: string | undefined;
   /**
-   * Contact email
+   * Primary contact email address for the branch. This is publicly listed contact information from property portals.
    */
   email?: string | undefined;
   /**
-   * Additional email addresses
+   * Additional email addresses for the branch or individual agents. These are publicly available from property portal listings.
    */
   emails?: Array<string> | undefined;
   /**
-   * Contact phone
+   * Primary contact telephone number for the branch, typically a UK landline or local rate number. This is publicly listed contact information from property portals. Format varies (e.g. '020 1234 5678', '02012345678').
    */
   phone?: string | undefined;
   /**
-   * Additional phone numbers
+   * Additional contact telephone numbers for the branch (e.g. mobile numbers, out-of-hours lines). These are publicly available from property portal listings.
    */
   phones?: Array<string> | undefined;
   /**
-   * Agency postcode
+   * UK postcode of the estate agency branch office.
    */
   postcode?: string | undefined;
   /**
-   * Agency website
+   * URL of the agency's website. May point to the branch-specific page or the agency homepage.
    */
   website?: string | undefined;
 };
 
 /**
- * Type of image
+ * Classification of the image asset. 'standard': property photography (exterior, rooms, garden, etc.). 'floorplan': annotated floor plan diagram with room dimensions. 'epc': Energy Performance Certificate chart or graph image. 'brochure': marketing brochure page scan or PDF-derived image.
  */
 export const QueryListingsBySourceListingsType = {
   Standard: "standard",
@@ -137,50 +138,50 @@ export const QueryListingsBySourceListingsType = {
   Brochure: "brochure",
 } as const;
 /**
- * Type of image
+ * Classification of the image asset. 'standard': property photography (exterior, rooms, garden, etc.). 'floorplan': annotated floor plan diagram with room dimensions. 'epc': Energy Performance Certificate chart or graph image. 'brochure': marketing brochure page scan or PDF-derived image.
  */
 export type QueryListingsBySourceListingsType = OpenEnum<
   typeof QueryListingsBySourceListingsType
 >;
 
 /**
- * Listing image
+ * A single image asset associated with a property listing. Images are sourced from property portal CDNs and are publicly accessible.
  */
 export type QueryListingsBySourceBrochureImages = {
   /**
-   * Image caption
+   * Human-readable caption describing the image content, as provided by the listing agent (e.g. 'Master bedroom', 'Rear garden', 'Kitchen/diner').
    */
   caption?: string | undefined;
   /**
-   * Display order
+   * Zero-based display order for the image within its type group. The first image (order 0) is typically the hero/primary image used for thumbnails and search results.
    */
   order?: number | undefined;
   /**
-   * Type of image
+   * Classification of the image asset. 'standard': property photography (exterior, rooms, garden, etc.). 'floorplan': annotated floor plan diagram with room dimensions. 'epc': Energy Performance Certificate chart or graph image. 'brochure': marketing brochure page scan or PDF-derived image.
    */
   type?: QueryListingsBySourceListingsType | undefined;
   /**
-   * Image URL
+   * Absolute URL to the image file. Images are typically served from provider CDNs (e.g. media.rightmove.co.uk, lid.zoocdn.com). URLs may include query parameters for resizing. These are publicly accessible and do not require authentication.
    */
   url: string;
 };
 
 /**
- * Property category
+ * Broad property category. 'residential': dwellings including houses, flats, bungalows, and maisonettes. 'commercial': non-residential premises such as offices, retail units, warehouses, and mixed-use buildings.
  */
 export const QueryListingsBySourceCategory = {
   Residential: "residential",
   Commercial: "commercial",
 } as const;
 /**
- * Property category
+ * Broad property category. 'residential': dwellings including houses, flats, bungalows, and maisonettes. 'commercial': non-residential premises such as offices, retail units, warehouses, and mixed-use buildings.
  */
 export type QueryListingsBySourceCategory = OpenEnum<
   typeof QueryListingsBySourceCategory
 >;
 
 /**
- * Type of image
+ * Classification of the image asset. 'standard': property photography (exterior, rooms, garden, etc.). 'floorplan': annotated floor plan diagram with room dimensions. 'epc': Energy Performance Certificate chart or graph image. 'brochure': marketing brochure page scan or PDF-derived image.
  */
 export const QueryListingsBySourceListingsResponseType = {
   Standard: "standard",
@@ -189,50 +190,50 @@ export const QueryListingsBySourceListingsResponseType = {
   Brochure: "brochure",
 } as const;
 /**
- * Type of image
+ * Classification of the image asset. 'standard': property photography (exterior, rooms, garden, etc.). 'floorplan': annotated floor plan diagram with room dimensions. 'epc': Energy Performance Certificate chart or graph image. 'brochure': marketing brochure page scan or PDF-derived image.
  */
 export type QueryListingsBySourceListingsResponseType = OpenEnum<
   typeof QueryListingsBySourceListingsResponseType
 >;
 
 /**
- * Listing image
+ * A single image asset associated with a property listing. Images are sourced from property portal CDNs and are publicly accessible.
  */
 export type QueryListingsBySourceEnergyRatingImages = {
   /**
-   * Image caption
+   * Human-readable caption describing the image content, as provided by the listing agent (e.g. 'Master bedroom', 'Rear garden', 'Kitchen/diner').
    */
   caption?: string | undefined;
   /**
-   * Display order
+   * Zero-based display order for the image within its type group. The first image (order 0) is typically the hero/primary image used for thumbnails and search results.
    */
   order?: number | undefined;
   /**
-   * Type of image
+   * Classification of the image asset. 'standard': property photography (exterior, rooms, garden, etc.). 'floorplan': annotated floor plan diagram with room dimensions. 'epc': Energy Performance Certificate chart or graph image. 'brochure': marketing brochure page scan or PDF-derived image.
    */
   type?: QueryListingsBySourceListingsResponseType | undefined;
   /**
-   * Image URL
+   * Absolute URL to the image file. Images are typically served from provider CDNs (e.g. media.rightmove.co.uk, lid.zoocdn.com). URLs may include query parameters for resizing. These are publicly accessible and do not require authentication.
    */
   url: string;
 };
 
 /**
- * Property feature
+ * A structured key-value property feature extracted from the listing. Features capture specific property attributes such as tenure, EPC rating, parking arrangements, and amenities.
  */
 export type QueryListingsBySourceFeatures = {
   /**
-   * Feature identifier
+   * Normalised feature identifier key. Common values include: 'parking', 'garden', 'garage', 'central_heating', 'double_glazing', 'epc_rating', 'council_tax_band', 'tenure', 'chain_free', 'conservatory', 'fireplace'. The set of available feature IDs varies by data provider and is not strictly enumerated — treat as a free-form key.
    */
   featureId: string;
   /**
-   * Feature value
+   * Human-readable feature value as stated by the agent. For boolean-style features this may be 'Yes'/'No'; for categorical features it contains the specific value (e.g. 'Band D' for council_tax_band, 'C' for epc_rating, 'Freehold' for tenure).
    */
   value: string;
 };
 
 /**
- * Type of image
+ * Classification of the image asset. 'standard': property photography (exterior, rooms, garden, etc.). 'floorplan': annotated floor plan diagram with room dimensions. 'epc': Energy Performance Certificate chart or graph image. 'brochure': marketing brochure page scan or PDF-derived image.
  */
 export const QueryListingsBySourceListingsResponse200Type = {
   Standard: "standard",
@@ -241,36 +242,36 @@ export const QueryListingsBySourceListingsResponse200Type = {
   Brochure: "brochure",
 } as const;
 /**
- * Type of image
+ * Classification of the image asset. 'standard': property photography (exterior, rooms, garden, etc.). 'floorplan': annotated floor plan diagram with room dimensions. 'epc': Energy Performance Certificate chart or graph image. 'brochure': marketing brochure page scan or PDF-derived image.
  */
 export type QueryListingsBySourceListingsResponse200Type = OpenEnum<
   typeof QueryListingsBySourceListingsResponse200Type
 >;
 
 /**
- * Listing image
+ * A single image asset associated with a property listing. Images are sourced from property portal CDNs and are publicly accessible.
  */
 export type QueryListingsBySourceFloorPlanImages = {
   /**
-   * Image caption
+   * Human-readable caption describing the image content, as provided by the listing agent (e.g. 'Master bedroom', 'Rear garden', 'Kitchen/diner').
    */
   caption?: string | undefined;
   /**
-   * Display order
+   * Zero-based display order for the image within its type group. The first image (order 0) is typically the hero/primary image used for thumbnails and search results.
    */
   order?: number | undefined;
   /**
-   * Type of image
+   * Classification of the image asset. 'standard': property photography (exterior, rooms, garden, etc.). 'floorplan': annotated floor plan diagram with room dimensions. 'epc': Energy Performance Certificate chart or graph image. 'brochure': marketing brochure page scan or PDF-derived image.
    */
   type?: QueryListingsBySourceListingsResponse200Type | undefined;
   /**
-   * Image URL
+   * Absolute URL to the image file. Images are typically served from provider CDNs (e.g. media.rightmove.co.uk, lid.zoocdn.com). URLs may include query parameters for resizing. These are publicly accessible and do not require authentication.
    */
   url: string;
 };
 
 /**
- * Type of image
+ * Classification of the image asset. 'standard': property photography (exterior, rooms, garden, etc.). 'floorplan': annotated floor plan diagram with room dimensions. 'epc': Energy Performance Certificate chart or graph image. 'brochure': marketing brochure page scan or PDF-derived image.
  */
 export const QueryListingsBySourceListingsResponse200ApplicationJSONType = {
   Standard: "standard",
@@ -279,42 +280,42 @@ export const QueryListingsBySourceListingsResponse200ApplicationJSONType = {
   Brochure: "brochure",
 } as const;
 /**
- * Type of image
+ * Classification of the image asset. 'standard': property photography (exterior, rooms, garden, etc.). 'floorplan': annotated floor plan diagram with room dimensions. 'epc': Energy Performance Certificate chart or graph image. 'brochure': marketing brochure page scan or PDF-derived image.
  */
 export type QueryListingsBySourceListingsResponse200ApplicationJSONType =
   OpenEnum<typeof QueryListingsBySourceListingsResponse200ApplicationJSONType>;
 
 /**
- * Listing image
+ * A single image asset associated with a property listing. Images are sourced from property portal CDNs and are publicly accessible.
  */
 export type QueryListingsBySourceImages = {
   /**
-   * Image caption
+   * Human-readable caption describing the image content, as provided by the listing agent (e.g. 'Master bedroom', 'Rear garden', 'Kitchen/diner').
    */
   caption?: string | undefined;
   /**
-   * Display order
+   * Zero-based display order for the image within its type group. The first image (order 0) is typically the hero/primary image used for thumbnails and search results.
    */
   order?: number | undefined;
   /**
-   * Type of image
+   * Classification of the image asset. 'standard': property photography (exterior, rooms, garden, etc.). 'floorplan': annotated floor plan diagram with room dimensions. 'epc': Energy Performance Certificate chart or graph image. 'brochure': marketing brochure page scan or PDF-derived image.
    */
   type?:
     | QueryListingsBySourceListingsResponse200ApplicationJSONType
     | undefined;
   /**
-   * Image URL
+   * Absolute URL to the image file. Images are typically served from provider CDNs (e.g. media.rightmove.co.uk, lid.zoocdn.com). URLs may include query parameters for resizing. These are publicly accessible and do not require authentication.
    */
   url: string;
 };
 
 /**
- * Narrative content (string or array of strings)
+ * The narrative text body. When a string: a single block of prose (may contain HTML line breaks or plain text). When an array: an ordered list of paragraphs or bullet points, each element being one distinct point. Null if the narrative section exists in the source feed but its content was empty or could not be extracted.
  */
 export type QueryListingsBySourceContent = string | Array<string> | any;
 
 /**
- * Type of narrative content
+ * Type of narrative content. summary: brief overview of the property (1-2 sentences). description: full marketing description. features: bullet-pointed key selling points. location: description of the surrounding area, transport links, and amenities. other: additional narrative that does not fit other categories.
  */
 export const QueryListingsBySourceListingsResponse200ApplicationJSONResponseBodyType =
   {
@@ -325,7 +326,7 @@ export const QueryListingsBySourceListingsResponse200ApplicationJSONResponseBody
     Other: "other",
   } as const;
 /**
- * Type of narrative content
+ * Type of narrative content. summary: brief overview of the property (1-2 sentences). description: full marketing description. features: bullet-pointed key selling points. location: description of the surrounding area, transport links, and amenities. other: additional narrative that does not fit other categories.
  */
 export type QueryListingsBySourceListingsResponse200ApplicationJSONResponseBodyType =
   OpenEnum<
@@ -333,21 +334,21 @@ export type QueryListingsBySourceListingsResponse200ApplicationJSONResponseBodyT
   >;
 
 /**
- * Listing narrative content
+ * A block of descriptive marketing copy associated with the listing. Narratives are authored by estate agents and extracted from property portal feeds. Content may contain marketing language and should not be treated as verified fact.
  */
 export type QueryListingsBySourceNarratives = {
   /**
-   * Narrative content (string or array of strings)
+   * The narrative text body. When a string: a single block of prose (may contain HTML line breaks or plain text). When an array: an ordered list of paragraphs or bullet points, each element being one distinct point. Null if the narrative section exists in the source feed but its content was empty or could not be extracted.
    */
   content?: string | Array<string> | any | null | undefined;
   /**
-   * Type of narrative content
+   * Type of narrative content. summary: brief overview of the property (1-2 sentences). description: full marketing description. features: bullet-pointed key selling points. location: description of the surrounding area, transport links, and amenities. other: additional narrative that does not fit other categories.
    */
   type: QueryListingsBySourceListingsResponse200ApplicationJSONResponseBodyType;
 };
 
 /**
- * Direction of price change
+ * Direction of a price revision. 'increase': the asking price or rent was raised. 'decrease': the asking price or rent was reduced (commonly signals motivated seller or market correction). 'nochange': a price event was recorded but the value remained unchanged (e.g. relisting at the same price).
  */
 export const QueryListingsBySourceDirection = {
   Increase: "increase",
@@ -355,38 +356,38 @@ export const QueryListingsBySourceDirection = {
   Nochange: "nochange",
 } as const;
 /**
- * Direction of price change
+ * Direction of a price revision. 'increase': the asking price or rent was raised. 'decrease': the asking price or rent was reduced (commonly signals motivated seller or market correction). 'nochange': a price event was recorded but the value remained unchanged (e.g. relisting at the same price).
  */
 export type QueryListingsBySourceDirection = OpenEnum<
   typeof QueryListingsBySourceDirection
 >;
 
 /**
- * Price change record
+ * A single price revision event in the listing's history. Price changes are tracked chronologically and can be used to analyse market trends, seller motivation, and time-on-market patterns. All monetary values are in GBP pence.
  */
 export type QueryListingsBySourcePriceHistory = {
   /**
-   * Price change amount in pence
+   * Absolute price change in GBP pence (new price minus old price). Negative values indicate a price reduction; positive values indicate an increase.
    */
   amount?: number | undefined;
   /**
-   * Date of price change
+   * ISO 8601 date when the price change was observed or published on the portal.
    */
   date: Date;
   /**
-   * Direction of price change
+   * Direction of a price revision. 'increase': the asking price or rent was raised. 'decrease': the asking price or rent was reduced (commonly signals motivated seller or market correction). 'nochange': a price event was recorded but the value remained unchanged (e.g. relisting at the same price).
    */
   direction?: QueryListingsBySourceDirection | undefined;
   /**
-   * Previous price in pence
+   * The previous listing price before the change, in GBP pence. Divide by 100 to convert to pounds sterling. May be absent for the initial listing event.
    */
   oldPrice?: number | undefined;
   /**
-   * Price change percentage
+   * Price change expressed as a percentage of the old price. Negative values indicate a reduction (e.g. -3.85 means a 3.85% reduction). Positive values indicate an increase.
    */
   percent?: number | undefined;
   /**
-   * New price in pence
+   * The new listing price after the change, in GBP pence. Divide by 100 to convert to pounds sterling. For sales listings this is the revised asking price; for rental listings this is the revised monthly rent (per calendar month).
    */
   price: number;
 };
@@ -394,20 +395,20 @@ export type QueryListingsBySourcePriceHistory = {
 /**
  * GeoJSON geometry type
  */
-export const QueryListingsBySourceListingsResponse200ApplicationJSONResponseBodyResultType =
+export const QueryListingsBySourceListingsResponse200ApplicationJSONResponseBodyDataType =
   {
     Point: "Point",
   } as const;
 /**
  * GeoJSON geometry type
  */
-export type QueryListingsBySourceListingsResponse200ApplicationJSONResponseBodyResultType =
+export type QueryListingsBySourceListingsResponse200ApplicationJSONResponseBodyDataType =
   ClosedEnum<
-    typeof QueryListingsBySourceListingsResponse200ApplicationJSONResponseBodyResultType
+    typeof QueryListingsBySourceListingsResponse200ApplicationJSONResponseBodyDataType
   >;
 
 /**
- * GeoJSON point geometry
+ * GeoJSON Point geometry representing the property's geographic location. Coordinates are in WGS84 (EPSG:4326) as [longitude, latitude]. May be null if the property could not be geocoded. Accuracy varies — some coordinates represent postcode centroids rather than exact property positions.
  */
 export type QueryListingsBySourceGeoJSONPoint = {
   /**
@@ -418,11 +419,11 @@ export type QueryListingsBySourceGeoJSONPoint = {
    * GeoJSON geometry type
    */
   type:
-    QueryListingsBySourceListingsResponse200ApplicationJSONResponseBodyResultType;
+    QueryListingsBySourceListingsResponse200ApplicationJSONResponseBodyDataType;
 };
 
 /**
- * Current status of the listing
+ * Current status of the listing. 'live': actively marketed on one or more property portals. 'archived': listing was taken off market by the agent but retained for historical analysis (e.g. price comparisons). 'removed': listing has been permanently withdrawn or the source feed no longer includes it. Typical lifecycle: live -> archived -> removed.
  */
 export const QueryListingsBySourceStatus = {
   Live: "live",
@@ -430,194 +431,211 @@ export const QueryListingsBySourceStatus = {
   Removed: "removed",
 } as const;
 /**
- * Current status of the listing
+ * Current status of the listing. 'live': actively marketed on one or more property portals. 'archived': listing was taken off market by the agent but retained for historical analysis (e.g. price comparisons). 'removed': listing has been permanently withdrawn or the source feed no longer includes it. Typical lifecycle: live -> archived -> removed.
  */
 export type QueryListingsBySourceStatus = OpenEnum<
   typeof QueryListingsBySourceStatus
 >;
 
 /**
- * Whether listing is for sale or rent
+ * Market type for the listing. 'sale': property is listed for purchase — the price field represents the asking price in GBP pence. 'rent': property is listed for tenancy — the price field represents the monthly rental amount in GBP pence (per calendar month).
  */
 export const QueryListingsBySourceType = {
   Sale: "sale",
   Rent: "rent",
 } as const;
 /**
- * Whether listing is for sale or rent
+ * Market type for the listing. 'sale': property is listed for purchase — the price field represents the asking price in GBP pence. 'rent': property is listed for tenancy — the price field represents the monthly rental amount in GBP pence (per calendar month).
  */
 export type QueryListingsBySourceType = OpenEnum<
   typeof QueryListingsBySourceType
 >;
 
 /**
- * Property listing
+ * A property listing representing a single residential or commercial property advertised for sale or rent on a UK property portal. Listings are sourced from multiple data providers and may be aggregated to combine information from different feeds for the same physical property. All prices are in GBP pence.
  */
-export type QueryListingsBySourceResult = {
+export type QueryListingsBySourceData = {
   /**
-   * Listing address
+   * Structured postal address for the listed property. Fields are parsed from the original listing data and may be incomplete depending on what the agent provided. The postcode is always present and serves as the primary geographic key.
    */
   address: QueryListingsBySourceAddress;
   /**
-   * Agent information
+   * Contact and identification details for the estate agent marketing this property. All agent data is publicly available information sourced from property portal listings. Null if agent details were not available in the source feed.
    */
   agent?: QueryListingsBySourceAgent | null | undefined;
   /**
-   * Number of bathrooms
+   * Number of bathrooms as advertised by the agent, including en-suites and shower rooms. Null if not specified in the listing.
    */
   baths?: number | null | undefined;
   /**
-   * Number of bedrooms
+   * Number of bedrooms as advertised by the agent. Null if the listing does not specify bedroom count (common for studios or commercial properties). A value of 0 typically indicates a studio flat.
    */
   beds?: number | null | undefined;
   /**
-   * Brochure images
+   * Marketing brochure images, typically scanned pages or PDF-derived images from the agent's printed particulars. Empty array if no brochure material is available.
    */
   brochureImages?: Array<QueryListingsBySourceBrochureImages> | undefined;
   /**
-   * Property category
+   * Broad property category. 'residential': dwellings including houses, flats, bungalows, and maisonettes. 'commercial': non-residential premises such as offices, retail units, warehouses, and mixed-use buildings.
    */
   category: QueryListingsBySourceCategory;
   /**
-   * Record creation timestamp
+   * ISO 8601 datetime when this listing record was first created in our system. This may differ from publishedDate if the listing was retrospectively imported.
    */
   createdAt?: Date | undefined;
   /**
-   * Currency code
+   * ISO 4217 currency code for all monetary values in this listing. Currently always 'GBP' (British Pound Sterling). All price fields are denominated in the smallest currency unit (pence).
    */
   currency: string;
   /**
-   * Formatted display address
+   * Pre-formatted address string suitable for display in search results and listing cards. This is the agent's preferred public-facing address and may be intentionally vague (e.g. omitting house number for privacy). Use the structured 'address' object for programmatic access.
    */
   displayAddress?: string | undefined;
   /**
-   * EPC images
+   * Energy Performance Certificate (EPC) chart images. In England and Wales, an EPC is legally required when a property is marketed for sale or rent. Typically contains one image showing the energy efficiency rating (A-G scale). Empty array if no EPC image is available.
    */
   energyRatingImages?:
     | Array<QueryListingsBySourceEnergyRatingImages>
     | undefined;
   /**
-   * Property features
+   * Structured key-value property features extracted from the listing (e.g. tenure, EPC rating, council tax band, parking type). Null if the source data did not include any structured features. See ListingFeature for the full set of common feature IDs.
    */
   features?: Array<QueryListingsBySourceFeatures> | null | undefined;
   /**
-   * Floor plan images
+   * Floor plan diagram images showing room layouts and approximate dimensions. May contain multiple images for multi-storey properties (one per floor). Empty array if no floor plans are available.
    */
   floorPlanImages?: Array<QueryListingsBySourceFloorPlanImages> | undefined;
   /**
-   * Unique listing identifier
+   * System-generated UUID that uniquely identifies this listing record. Stable across updates — the same listing retains its ID even when price or status changes.
    */
   id: string;
   /**
-   * Property images
+   * Property photography images (exterior shots, room photos, garden views, etc.). Ordered by the agent's preferred display sequence. Images are hosted on provider CDNs and are publicly accessible. Empty array if no photographs are available.
    */
   images?: Array<QueryListingsBySourceImages> | undefined;
   /**
-   * Auction property
+   * Whether this property is being sold via auction rather than private treaty. Auction properties typically require exchange of contracts on the fall of the hammer and completion within 28 days.
    */
   isAuction?: boolean | undefined;
   /**
-   * New build property
+   * Whether this is a newly constructed property that has not previously been occupied. New-build properties may be available off-plan (before construction is complete) and often qualify for government schemes such as Help to Buy.
    */
   isNewBuild?: boolean | undefined;
   /**
-   * Retirement property
+   * Whether this is an age-restricted retirement or sheltered housing property. Retirement properties typically have minimum age requirements (usually 55+) and may include communal facilities.
    */
   isRetirement?: boolean | undefined;
   /**
-   * Shared ownership
+   * Whether this listing is offered under a shared ownership scheme, where the buyer purchases a percentage share (typically 25-75%) and pays rent on the remainder to a housing association. Common in affordable housing programmes.
    */
   isSharedOwnership?: boolean | undefined;
   /**
-   * Provider's listing reference
+   * The listing's unique reference within the source provider's system. Combined with 'provider', this forms a globally unique source reference. Typically a numeric or alphanumeric ID assigned by the portal.
    */
   key: string;
   /**
-   * Latitude
+   * WGS84 latitude of the property location in decimal degrees. May represent an approximate position (e.g. postcode centroid) rather than the exact building location.
    */
   lat?: number | undefined;
   /**
-   * Longitude
+   * WGS84 longitude of the property location in decimal degrees. May represent an approximate position (e.g. postcode centroid) rather than the exact building location.
    */
   lng?: number | undefined;
   /**
-   * Location identifier
+   * Internal location identifier used for geographic grouping, typically derived from the property's postcode (spaces removed, e.g. 'SW1A1AA'). Used to link listings to location-level analytics and nearby properties.
    */
   locationId?: string | null | undefined;
   /**
-   * Descriptive content
+   * Marketing description text blocks authored by the estate agent, categorised by type (summary, full description, features list, location guide). Null if no descriptive content was available in the source feed.
    */
   narratives?: Array<QueryListingsBySourceNarratives> | null | undefined;
   /**
-   * Current price in pence
+   * Current listing price in GBP pence. Divide by 100 to convert to pounds sterling. For sale listings: the asking price (e.g. 50000000 = £500,000). For rental listings: the monthly rent per calendar month (e.g. 150000 = £1,500 pcm). Always reflects the most recent price after any revisions.
    */
   price: number;
   /**
-   * Price change history
+   * Chronological history of price changes since the listing was first published. Each entry records a revision event with the old and new prices. Useful for tracking asking-price reductions and market sentiment. Ordered from earliest to most recent change.
    */
   priceHistory?: Array<QueryListingsBySourcePriceHistory> | undefined;
   /**
-   * Property type
+   * Primary property type classification. Common values for residential include: 'detached', 'semi-detached', 'terraced', 'flat', 'bungalow', 'maisonette', 'end_terrace', 'cottage', 'park_home'. For commercial: 'office', 'retail', 'warehouse', 'industrial', 'land'. Values are normalised from provider-specific taxonomies but may occasionally contain non-standard entries.
    */
   propertyType: string;
   /**
-   * Data provider
+   * Identifier for the data provider or property portal that supplied this listing (e.g. a feed aggregator or portal). Used alongside 'key' to form a unique composite reference to the source record.
    */
   provider: string;
   /**
-   * Date listing was published
+   * ISO 8601 datetime when the listing was first published or appeared on the source portal. This date remains unchanged even if the listing is subsequently updated.
    */
   publishedDate: Date;
   /**
-   * Number of reception rooms
+   * Number of reception rooms (living rooms, dining rooms, sitting rooms) as advertised by the agent. This is a UK-specific property metric. Null if not specified in the listing.
    */
   receptions?: number | null | undefined;
   /**
-   * Date listing was removed
+   * ISO 8601 datetime when the listing was removed from the source portal, or null if the listing is still active. A removed date typically indicates the property has been sold, let, or withdrawn from the market.
    */
   removedDate?: Date | null | undefined;
   /**
-   * GeoJSON point geometry
+   * GeoJSON Point geometry representing the property's geographic location. Coordinates are in WGS84 (EPSG:4326) as [longitude, latitude]. May be null if the property could not be geocoded. Accuracy varies — some coordinates represent postcode centroids rather than exact property positions.
    */
   spatial?: QueryListingsBySourceGeoJSONPoint | null | undefined;
   /**
-   * Current status of the listing
+   * Current status of the listing. 'live': actively marketed on one or more property portals. 'archived': listing was taken off market by the agent but retained for historical analysis (e.g. price comparisons). 'removed': listing has been permanently withdrawn or the source feed no longer includes it. Typical lifecycle: live -> archived -> removed.
    */
   status: QueryListingsBySourceStatus;
   /**
-   * Property sub-type
+   * Secondary property type qualifier providing additional architectural or style context (e.g. 'Victorian', 'Georgian', 'Purpose Built', 'Conversion', 'Studio'). Null when the source data does not provide a sub-classification.
    */
   subPropertyType?: string | null | undefined;
   /**
-   * Whether listing is for sale or rent
+   * Market type for the listing. 'sale': property is listed for purchase — the price field represents the asking price in GBP pence. 'rent': property is listed for tenancy — the price field represents the monthly rental amount in GBP pence (per calendar month).
    */
   type: QueryListingsBySourceType;
   /**
-   * Record last update timestamp
+   * ISO 8601 datetime when this listing record was last modified in our system. Updated whenever any field changes, including price revisions, status transitions, or image additions.
    */
   updatedAt?: Date | undefined;
 };
 
 /**
- * Multiple listings response
+ * Object type identifier
+ */
+export const QueryListingsBySourceObject = {
+  List: "list",
+} as const;
+/**
+ * Object type identifier
+ */
+export type QueryListingsBySourceObject = ClosedEnum<
+  typeof QueryListingsBySourceObject
+>;
+
+/**
+ * Paginated response containing a list of property listings. Includes pagination metadata (total_count, has_more) following the Stripe-style list envelope pattern.
  */
 export type QueryListingsBySourceResponseBody = {
   /**
-   * Array of listings
+   * Array of items
    */
-  result: Array<QueryListingsBySourceResult>;
+  data: Array<QueryListingsBySourceData>;
   /**
-   * Number of listings returned
+   * Whether more items exist
    */
-  size: number;
+  hasMore: boolean;
   /**
-   * Request success status
+   * Object type identifier
    */
-  success: boolean;
+  object: QueryListingsBySourceObject;
   /**
-   * Total number of matching listings
+   * Total number of items available
    */
-  totalSize?: number | undefined;
+  totalCount?: number | undefined;
+  /**
+   * URL of the request
+   */
+  url: string;
 };
 
 /** @internal */
@@ -943,11 +961,11 @@ export function queryListingsBySourcePriceHistoryFromJSON(
 }
 
 /** @internal */
-export const QueryListingsBySourceListingsResponse200ApplicationJSONResponseBodyResultType$inboundSchema:
+export const QueryListingsBySourceListingsResponse200ApplicationJSONResponseBodyDataType$inboundSchema:
   z.ZodNativeEnum<
-    typeof QueryListingsBySourceListingsResponse200ApplicationJSONResponseBodyResultType
+    typeof QueryListingsBySourceListingsResponse200ApplicationJSONResponseBodyDataType
   > = z.nativeEnum(
-    QueryListingsBySourceListingsResponse200ApplicationJSONResponseBodyResultType,
+    QueryListingsBySourceListingsResponse200ApplicationJSONResponseBodyDataType,
   );
 
 /** @internal */
@@ -958,7 +976,7 @@ export const QueryListingsBySourceGeoJSONPoint$inboundSchema: z.ZodType<
 > = z.object({
   coordinates: z.array(z.number()),
   type:
-    QueryListingsBySourceListingsResponse200ApplicationJSONResponseBodyResultType$inboundSchema,
+    QueryListingsBySourceListingsResponse200ApplicationJSONResponseBodyDataType$inboundSchema,
 });
 
 export function queryListingsBySourceGeoJSONPointFromJSON(
@@ -986,8 +1004,8 @@ export const QueryListingsBySourceType$inboundSchema: z.ZodType<
 > = openEnums.inboundSchema(QueryListingsBySourceType);
 
 /** @internal */
-export const QueryListingsBySourceResult$inboundSchema: z.ZodType<
-  QueryListingsBySourceResult,
+export const QueryListingsBySourceData$inboundSchema: z.ZodType<
+  QueryListingsBySourceData,
   z.ZodTypeDef,
   unknown
 > = z.object({
@@ -1050,26 +1068,37 @@ export const QueryListingsBySourceResult$inboundSchema: z.ZodType<
     .optional(),
 });
 
-export function queryListingsBySourceResultFromJSON(
+export function queryListingsBySourceDataFromJSON(
   jsonString: string,
-): SafeParseResult<QueryListingsBySourceResult, SDKValidationError> {
+): SafeParseResult<QueryListingsBySourceData, SDKValidationError> {
   return safeParse(
     jsonString,
-    (x) => QueryListingsBySourceResult$inboundSchema.parse(JSON.parse(x)),
-    `Failed to parse 'QueryListingsBySourceResult' from JSON`,
+    (x) => QueryListingsBySourceData$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'QueryListingsBySourceData' from JSON`,
   );
 }
 
+/** @internal */
+export const QueryListingsBySourceObject$inboundSchema: z.ZodNativeEnum<
+  typeof QueryListingsBySourceObject
+> = z.nativeEnum(QueryListingsBySourceObject);
+
 /** @internal */
 export const QueryListingsBySourceResponseBody$inboundSchema: z.ZodType<
   QueryListingsBySourceResponseBody,
   z.ZodTypeDef,
   unknown
 > = z.object({
-  result: z.array(z.lazy(() => QueryListingsBySourceResult$inboundSchema)),
-  size: z.number(),
-  success: z.boolean(),
-  totalSize: z.number().optional(),
+  data: z.array(z.lazy(() => QueryListingsBySourceData$inboundSchema)),
+  has_more: z.boolean(),
+  object: QueryListingsBySourceObject$inboundSchema,
+  total_count: z.number().optional(),
+  url: z.string(),
+}).transform((v) => {
+  return remap$(v, {
+    "has_more": "hasMore",
+    "total_count": "totalCount",
+  });
 });
 
 export function queryListingsBySourceResponseBodyFromJSON(