@land-catalyst/batch-data-sdk 1.2.5 → 1.2.8

package/dist/builders/builders.d.ts

@@ -16,7 +16,7 @@
  *   .build();
  * ```
  */
-import { StringFilter, NumericRangeFilter, DateRangeFilter, GeoLocationDistance, GeoLocationBoundingBox, GeoLocationPolygon, AddressSearchCriteria, AssessmentSearchCriteria, BuildingSearchCriteria, CompAddressSearchCriteria, DemographicsSearchCriteria, ForeclosureSearchCriteria, GeneralSearchCriteria, IdsSearchCriteria, IntelSearchCriteria, InvoluntaryLienSearchCriteria, LegalSearchCriteria, ListingSearchCriteria, LotSearchCriteria, OpenLienSearchCriteria, OwnerSearchCriteria, PermitSearchCriteria, PropertyOwnerProfileSearchCriteria, SaleSearchCriteria, TaxSearchCriteria, ValuationSearchCriteria, OrSearchCriteria, SearchCriteria, DeliveryConfig, EventHubConfig, PropertySubscriptionRequest, QuickListValueWithNot, PropertyLookupRequest, PropertyLookupRequestItem, PropertyLookupRequestAddress, PropertyLookupOptions, PropertyPermitRequest, PropertySearchRequest, PropertySearchAsyncRequest, PropertyLookupAsyncRequest, GeoPoint } from "../core/types";
+import { StringFilter, NumericRangeFilter, DateRangeFilter, GeoLocationDistance, GeoLocationBoundingBox, GeoLocationPolygon, AddressSearchCriteria, AssessmentSearchCriteria, BuildingSearchCriteria, CompAddressSearchCriteria, DemographicsSearchCriteria, ForeclosureSearchCriteria, GeneralSearchCriteria, IdsSearchCriteria, IntelSearchCriteria, InvoluntaryLienSearchCriteria, LegalSearchCriteria, ListingSearchCriteria, LotSearchCriteria, OpenLienSearchCriteria, OwnerSearchCriteria, PermitSearchCriteria, PropertyOwnerProfileSearchCriteria, SaleSearchCriteria, TaxSearchCriteria, ValuationSearchCriteria, OrSearchCriteria, SearchCriteria, DeliveryConfig, EventHubConfig, PropertySubscriptionRequest, QuickListValueWithNot, PropertyLookupRequest, PropertyLookupRequestItem, PropertyLookupRequestAddress, PropertyLookupOptions, PropertyPermitRequest, PropertyCountRequest, PropertySearchRequest, PropertySearchAsyncRequest, PropertyLookupAsyncRequest, GeoPoint } from "../core/types";
 import type { PropertyFieldMetadata } from "../property-field/metadata";
 /**
  * Base interface for all builders
@@ -813,6 +813,17 @@ export declare class PropertyLookupRequestBuilder extends BaseBuilder<PropertyLo
     options(configurator: (builder: PropertyLookupOptionsBuilder) => void): this;
     build(): PropertyLookupRequest;
 }
+/**
+ * Builder for property count requests
+ *
+ * Used specifically for count-only requests that should never fetch property data.
+ */
+export declare class PropertyCountRequestBuilder extends BaseBuilder<PropertyCountRequest> {
+    static from(request: PropertyCountRequest): PropertyCountRequestBuilder;
+    searchCriteria(criteria: SearchCriteria): this;
+    searchCriteria(configurator: (builder: SearchCriteriaBuilder) => void): this;
+    build(): PropertyCountRequest;
+}
 /**
  * Builder for property search requests
  */

package/dist/builders/builders.js

@@ -18,7 +18,7 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PropertyPermitRequestBuilder = exports.PropertyLookupAsyncRequestBuilder = exports.PropertySearchAsyncRequestBuilder = exports.PropertySearchRequestBuilder = exports.PropertyLookupRequestBuilder = exports.AsyncPropertyLookupOptionsBuilder = exports.PropertyLookupOptionsBuilder = exports.PropertyLookupRequestItemBuilder = exports.PropertySubscriptionBuilder = exports.DeliveryConfigBuilder = exports.SearchCriteriaBuilder = exports.OrSearchCriteriaBuilder = exports.ValuationSearchCriteriaBuilder = exports.TaxSearchCriteriaBuilder = exports.SaleSearchCriteriaBuilder = exports.PropertyOwnerProfileSearchCriteriaBuilder = exports.PermitSearchCriteriaBuilder = exports.OwnerSearchCriteriaBuilder = exports.OpenLienSearchCriteriaBuilder = exports.LotSearchCriteriaBuilder = exports.ListingSearchCriteriaBuilder = exports.LegalSearchCriteriaBuilder = exports.InvoluntaryLienSearchCriteriaBuilder = exports.IntelSearchCriteriaBuilder = exports.IdsSearchCriteriaBuilder = exports.GeneralSearchCriteriaBuilder = exports.ForeclosureSearchCriteriaBuilder = exports.DemographicsSearchCriteriaBuilder = exports.CompAddressSearchCriteriaBuilder = exports.BuildingSearchCriteriaBuilder = exports.AssessmentSearchCriteriaBuilder = exports.AddressSearchCriteriaBuilder = exports.GeoLocationFactory = exports.DateRangeFilterBuilder = exports.NumericRangeFilterBuilder = exports.StringFilterBuilder = void 0;
+exports.PropertyPermitRequestBuilder = exports.PropertyLookupAsyncRequestBuilder = exports.PropertySearchAsyncRequestBuilder = exports.PropertySearchRequestBuilder = exports.PropertyCountRequestBuilder = exports.PropertyLookupRequestBuilder = exports.AsyncPropertyLookupOptionsBuilder = exports.PropertyLookupOptionsBuilder = exports.PropertyLookupRequestItemBuilder = exports.PropertySubscriptionBuilder = exports.DeliveryConfigBuilder = exports.SearchCriteriaBuilder = exports.OrSearchCriteriaBuilder = exports.ValuationSearchCriteriaBuilder = exports.TaxSearchCriteriaBuilder = exports.SaleSearchCriteriaBuilder = exports.PropertyOwnerProfileSearchCriteriaBuilder = exports.PermitSearchCriteriaBuilder = exports.OwnerSearchCriteriaBuilder = exports.OpenLienSearchCriteriaBuilder = exports.LotSearchCriteriaBuilder = exports.ListingSearchCriteriaBuilder = exports.LegalSearchCriteriaBuilder = exports.InvoluntaryLienSearchCriteriaBuilder = exports.IntelSearchCriteriaBuilder = exports.IdsSearchCriteriaBuilder = exports.GeneralSearchCriteriaBuilder = exports.ForeclosureSearchCriteriaBuilder = exports.DemographicsSearchCriteriaBuilder = exports.CompAddressSearchCriteriaBuilder = exports.BuildingSearchCriteriaBuilder = exports.AssessmentSearchCriteriaBuilder = exports.AddressSearchCriteriaBuilder = exports.GeoLocationFactory = exports.DateRangeFilterBuilder = exports.NumericRangeFilterBuilder = exports.StringFilterBuilder = void 0;
 const metadata_1 = require("../property-field/metadata");
 /**
  * Abstract base class for builders that store nested builders
@@ -2421,6 +2421,40 @@ class PropertyLookupRequestBuilder extends BaseBuilder {
     }
 }
 exports.PropertyLookupRequestBuilder = PropertyLookupRequestBuilder;
+/**
+ * Builder for property count requests
+ *
+ * Used specifically for count-only requests that should never fetch property data.
+ */
+class PropertyCountRequestBuilder extends BaseBuilder {
+    static from(request) {
+        const builder = new PropertyCountRequestBuilder();
+        builder.searchCriteria(request.searchCriteria);
+        return builder;
+    }
+    searchCriteria(criteriaOrConfigurator) {
+        if (typeof criteriaOrConfigurator === "function") {
+            const builder = new SearchCriteriaBuilder("");
+            criteriaOrConfigurator(builder);
+            this.criteria.searchCriteria = builder.build();
+            this.builders.searchCriteria = undefined;
+        }
+        else {
+            this.criteria.searchCriteria = criteriaOrConfigurator;
+            this.builders.searchCriteria = undefined;
+        }
+        return this;
+    }
+    build() {
+        if (!this.criteria.searchCriteria) {
+            throw new Error("Search criteria is required");
+        }
+        return {
+            searchCriteria: this.criteria.searchCriteria,
+        };
+    }
+}
+exports.PropertyCountRequestBuilder = PropertyCountRequestBuilder;
 /**
  * Builder for property search requests
  */

package/dist/client/client.d.ts

@@ -1,7 +1,7 @@
 import { AxiosInstance, AxiosResponse, AxiosError, InternalAxiosRequestConfig } from "axios";
 import { IBatchDataClient } from "./client.interface";
 import { ILogger } from "../core/logger.interface";
-import { PropertySubscriptionRequest, PropertySubscriptionResponse, PropertySearchRequest, PropertySearchResponse, AddressVerifyRequest, AddressVerifyResponse, AddressAutocompleteRequest, AddressAutocompleteResponse, AddressGeocodeRequest, AddressGeocodeResponse, AddressReverseGeocodeRequest, AddressReverseGeocodeResponse, PropertyLookupRequest, PropertyLookupResponse, PropertyLookupAsyncRequest, PropertyLookupAsyncResponse, PropertySearchAsyncRequest, PropertySearchAsyncResponse, PropertySkipTraceRequest, PropertySkipTraceResponse, PropertySkipTraceAsyncRequest, PropertySkipTraceAsyncResponse, PhoneVerificationRequest, PhoneVerificationResponse, PhoneVerificationAsyncRequest, PhoneVerificationAsyncResponse, PhoneDNCRequest, PhoneDNCResponse, PhoneDNCAsyncRequest, PhoneDNCAsyncResponse, PhoneTCPARequest, PhoneTCPAResponse, PhoneTCPAAsyncRequest, PhoneTCPAAsyncResponse, GetPropertySubscriptionsResponse, GetPropertySubscriptionDetailResponse, DeletePropertySubscriptionResponse, PropertyPermitRequest, PropertyPermitResponse, PropertySkipTraceV3Request, PropertySkipTraceV3Response, PropertySkipTraceV3AsyncRequest, PropertySkipTraceV3AsyncResponse } from "../core/types";
+import { PropertySubscriptionRequest, PropertySubscriptionResponse, PropertyCountRequest, PropertySearchRequest, PropertySearchResponse, AddressVerifyRequest, AddressVerifyResponse, AddressAutocompleteRequest, AddressAutocompleteResponse, AddressGeocodeRequest, AddressGeocodeResponse, AddressReverseGeocodeRequest, AddressReverseGeocodeResponse, PropertyLookupRequest, PropertyLookupResponse, PropertyLookupAsyncRequest, PropertyLookupAsyncResponse, PropertySearchAsyncRequest, PropertySearchAsyncResponse, PropertySkipTraceRequest, PropertySkipTraceResponse, PropertySkipTraceAsyncRequest, PropertySkipTraceAsyncResponse, PhoneVerificationRequest, PhoneVerificationResponse, PhoneVerificationAsyncRequest, PhoneVerificationAsyncResponse, PhoneDNCRequest, PhoneDNCResponse, PhoneDNCAsyncRequest, PhoneDNCAsyncResponse, PhoneTCPARequest, PhoneTCPAResponse, PhoneTCPAAsyncRequest, PhoneTCPAAsyncResponse, GetPropertySubscriptionsResponse, GetPropertySubscriptionDetailResponse, DeletePropertySubscriptionResponse, PropertyPermitRequest, PropertyPermitResponse, PropertySkipTraceV3Request, PropertySkipTraceV3Response, PropertySkipTraceV3AsyncRequest, PropertySkipTraceV3AsyncResponse } from "../core/types";
 /**
  * Middleware function that executes before an HTTP request is sent.
  * Can modify the request config or perform side effects (logging, metrics, etc.).
@@ -258,10 +258,14 @@ export declare class BatchDataClient implements IBatchDataClient {
     searchProperties(request: PropertySearchRequest): Promise<PropertySearchResponse>;
     /**
      * Get the count of properties matching the search criteria
-     * @param searchCriteria Search criteria to match properties
+     *
+     * Uses PropertyCountRequest to ensure no property data is fetched (count-only).
+     * This prevents accidental charges for property data retrieval.
+     *
+     * @param searchRequest Count request with search criteria (no options allowed)
      * @returns Number of matching properties, or null if the endpoint is unavailable
      */
-    getPropertyCount(searchRequest: PropertySearchRequest): Promise<number | null>;
+    getPropertyCount(searchRequest: PropertyCountRequest): Promise<number | null>;
     /**
      * Verify and normalize addresses (v1 API)
      * POST /api/v1/address/verify

package/dist/client/client.interface.d.ts

@@ -1,4 +1,4 @@
-import { PropertySubscriptionRequest, PropertySubscriptionResponse, PropertySearchRequest, PropertySearchResponse, AddressVerifyRequest, AddressVerifyResponse, AddressAutocompleteRequest, AddressAutocompleteResponse, AddressGeocodeRequest, AddressGeocodeResponse, AddressReverseGeocodeRequest, AddressReverseGeocodeResponse, PropertyLookupRequest, PropertyLookupResponse, PropertyLookupAsyncRequest, PropertyLookupAsyncResponse, PropertySearchAsyncRequest, PropertySearchAsyncResponse, PropertySkipTraceRequest, PropertySkipTraceResponse, PropertySkipTraceAsyncRequest, PropertySkipTraceAsyncResponse, PhoneVerificationRequest, PhoneVerificationResponse, PhoneVerificationAsyncRequest, PhoneVerificationAsyncResponse, PhoneDNCRequest, PhoneDNCResponse, PhoneDNCAsyncRequest, PhoneDNCAsyncResponse, PhoneTCPARequest, PhoneTCPAResponse, PhoneTCPAAsyncRequest, PhoneTCPAAsyncResponse, GetPropertySubscriptionsResponse, GetPropertySubscriptionDetailResponse, DeletePropertySubscriptionResponse, PropertyPermitRequest, PropertyPermitResponse, PropertySkipTraceV3Request, PropertySkipTraceV3Response, PropertySkipTraceV3AsyncRequest, PropertySkipTraceV3AsyncResponse } from "../core/types";
+import { PropertySubscriptionRequest, PropertySubscriptionResponse, PropertyCountRequest, PropertySearchRequest, PropertySearchResponse, AddressVerifyRequest, AddressVerifyResponse, AddressAutocompleteRequest, AddressAutocompleteResponse, AddressGeocodeRequest, AddressGeocodeResponse, AddressReverseGeocodeRequest, AddressReverseGeocodeResponse, PropertyLookupRequest, PropertyLookupResponse, PropertyLookupAsyncRequest, PropertyLookupAsyncResponse, PropertySearchAsyncRequest, PropertySearchAsyncResponse, PropertySkipTraceRequest, PropertySkipTraceResponse, PropertySkipTraceAsyncRequest, PropertySkipTraceAsyncResponse, PhoneVerificationRequest, PhoneVerificationResponse, PhoneVerificationAsyncRequest, PhoneVerificationAsyncResponse, PhoneDNCRequest, PhoneDNCResponse, PhoneDNCAsyncRequest, PhoneDNCAsyncResponse, PhoneTCPARequest, PhoneTCPAResponse, PhoneTCPAAsyncRequest, PhoneTCPAAsyncResponse, GetPropertySubscriptionsResponse, GetPropertySubscriptionDetailResponse, DeletePropertySubscriptionResponse, PropertyPermitRequest, PropertyPermitResponse, PropertySkipTraceV3Request, PropertySkipTraceV3Response, PropertySkipTraceV3AsyncRequest, PropertySkipTraceV3AsyncResponse } from "../core/types";
 /**
  * BatchData API Client Interface
  *
@@ -26,10 +26,14 @@ export interface IBatchDataClient {
     searchProperties(request: PropertySearchRequest): Promise<PropertySearchResponse>;
     /**
      * Get the count of properties matching the search criteria
-     * @param searchCriteria Search criteria to match properties
+     *
+     * Uses PropertyCountRequest to ensure no property data is fetched (count-only).
+     * This prevents accidental charges for property data retrieval.
+     *
+     * @param searchRequest Count request with search criteria (no options allowed)
      * @returns Number of matching properties, or null if the endpoint is unavailable
      */
-    getPropertyCount(searchRequest: PropertySearchRequest): Promise<number | null>;
+    getPropertyCount(searchRequest: PropertyCountRequest): Promise<number | null>;
     /**
      * Verify and normalize addresses (v1 API)
      * POST /api/v1/address/verify

package/dist/client/client.js

@@ -321,14 +321,17 @@ class BatchDataClient {
     }
     /**
      * Get the count of properties matching the search criteria
-     * @param searchCriteria Search criteria to match properties
+     *
+     * Uses PropertyCountRequest to ensure no property data is fetched (count-only).
+     * This prevents accidental charges for property data retrieval.
+     *
+     * @param searchRequest Count request with search criteria (no options allowed)
      * @returns Number of matching properties, or null if the endpoint is unavailable
      */
     async getPropertyCount(searchRequest) {
-        const { searchCriteria, options } = searchRequest;
-        const lookupOptions = options
-            ? builders_1.PropertyLookupOptionsBuilder.from(options).take(0)
-            : new builders_1.PropertyLookupOptionsBuilder();
+        const { searchCriteria } = searchRequest;
+        // Always use take(0) to ensure no property data is fetched
+        const lookupOptions = new builders_1.PropertyLookupOptionsBuilder().take(0);
         const response = await this.searchProperties({
             searchCriteria,
             options: lookupOptions.build(),

package/dist/core/types.d.ts

@@ -1654,6 +1654,22 @@ export interface PropertySearchRequest {
     searchCriteria: SearchCriteria;
     options?: PropertyLookupOptions;
 }
+/**
+ * Property count request
+ *
+ * Used specifically for getting property counts without fetching property data.
+ * This type does NOT include options to prevent accidental property data fetching
+ * (which incurs charges). For count-only requests, use this type instead of
+ * PropertySearchRequest to ensure no property data is retrieved.
+ *
+ * Note: All filtering needed for an accurate count should be specified in
+ * searchCriteria. PropertyLookupOptions contains some duplicate filter fields
+ * (useBedrooms, useBathrooms, useYearBuilt, etc.) that mirror SearchCriteria fields,
+ * but these are redundant and should not be needed for accurate counts.
+ */
+export interface PropertyCountRequest {
+    searchCriteria: SearchCriteria;
+}
 /**
  * Property lookup request
  */

package/dist/property-field/metadata.d.ts

@@ -53,6 +53,10 @@ export interface PropertyFieldMetadata {
      * Whether this field is an array element (indicated by [n] in the path)
      */
     isArrayElement: boolean;
+    /**
+     * Optional array of possible values for this field (for enum-like fields)
+     */
+    possibleValues?: string[];
 }
 /**
  * Registry of all property field metadata, indexed by field path

package/dist/property-field/metadata.js

@@ -47,6 +47,7 @@ exports.PROPERTY_FIELD_METADATA = {
         dataType: "string",
         description: "The validity of the address (e.g. Valid, Invalid, Partially Valid)",
         isArrayElement: false,
+        possibleValues: ["Valid", "Invalid", "Partially Valid"],
     },
     "address.city": {
         fieldPath: "address.city",
@@ -187,6 +188,7 @@ exports.PROPERTY_FIELD_METADATA = {
         dataType: "string",
         description: "The validity of the address (e.g. Valid, Invalid, Partially Valid)",
         isArrayElement: false,
+        possibleValues: ["Valid", "Invalid", "Partially Valid"],
     },
     "owner.names.[n].first": {
         fieldPath: "owner.names.[n].first",

package/dist/property-field/search-criteria-ai-context.js

@@ -78,7 +78,7 @@ exports.SEARCH_CRITERIA_DOMAINS = [
     {
         name: "intel",
         responseGroup: "intel",
-        description: "Intelligence and predictive analytics (sale propensity, last sold information)",
+        description: "Intelligence and predictive analytics (sale propensity score 0-100 predicting likelihood to list/sell, last sold date and price derived from assessor and listing data, length of residence)",
     },
     {
         name: "demographics",
@@ -113,12 +113,12 @@ exports.SEARCH_CRITERIA_DOMAINS = [
     {
         name: "propertyOwnerProfile",
         responseGroup: "propertyOwnerProfile",
-        description: "Property owner profile information (total properties owned, equity, mortgages, etc.)",
+        description: "Property owner profile information - aggregate values across ALL properties owned by the owner (total properties owned, total equity, total mortgages, averages, etc.)",
     },
     {
         name: "quickList",
         responseGroup: "quickList",
-        description: "Pre-defined quick filters (owner-occupied, vacant, absentee-owner, high-equity, low-equity, free-and-clear, active-listing, recently-sold, preforeclosure, tax-default, etc.). Can be negated with 'not-' prefix.",
+        description: "Pre-defined quick filters (owner-occupied, vacant, absentee-owner, high-equity, low-equity, free-and-clear, active-listing, recently-sold, preforeclosure, tax-default, etc.). Available as top-level fields: quickList (single value), quickLists (array, AND logic), orQuickLists (array, OR logic). Values can be negated with 'not-' prefix. Use orQuickLists for conceptual categories (e.g., 'distressed properties' = orQuickLists: ['vacant', 'preforeclosure', 'tax-default']).",
     },
 ];
 /**
@@ -214,8 +214,9 @@ ${domainDocs}
 FILTER TYPES:
 - StringFilter: { equals?, contains?, startsWith?, endsWith?, inList?, matches? }
 - NumericRangeFilter: { min?, max? }
-- DateRangeFilter: { minDate?, maxDate? }
+- DateRangeFilter: { minDate?, maxDate? } (Dates in ISO 8601 format YYYY-MM-DD. For "after [year]", use next year's January 1st, e.g., "after 2015" = { minDate: "2016-01-01" })
 - BooleanFilter: { equals: boolean }
+- QuickListValue: string (can prefix with "not-" to exclude, e.g., "not-vacant")
 - GeoLocationDistance: { latitude, longitude, distanceMiles }
 - GeoLocationBoundingBox: { minLat, maxLat, minLon, maxLon }
 - GeoLocationPolygon: { geoPoints: [{ latitude, longitude }] }
@@ -232,9 +233,23 @@ IMPORTANT RULES:
    - "over $500,000" = assessment.totalMarketValue: {min: 500000}
    - "built after 2010" = building.yearBuilt: {min: 2010}
    - "last sold after 2015" = sale.lastSaleDate: {minDate: "2016-01-01"} (use next year's January 1st for "after [year]")
+   - "high sale propensity" = intel.salePropensity: {min: 70} (salePropensity is 0-100, higher = more likely to sell)
+   - "flip properties" = properties bought and sold quickly (use sale.flipLength or quickList: "fix-and-flip")
 5. Extract geographic information and populate both query and address filters appropriately
 6. Only include domains that are clearly relevant to the prompt
 7. If modifying existing criteria, merge intelligently - update what's mentioned, keep what's not
+8. Conceptual groupings and orQuickLists: When prompts describe conceptual categories that map to multiple quickList values with OR logic, use orQuickLists:
+   - "distressed properties" or "distressed" = orQuickLists: ["vacant", "preforeclosure", "tax-default"] (properties with financial distress indicators)
+   - "motivated sellers" = orQuickLists: ["preforeclosure", "tax-default", "inherited", "vacant"] (properties where owner may be motivated to sell)
+   - "investment properties" = orQuickLists: ["absentee-owner", "corporate-owned", "out-of-state-owner"] (non-owner-occupied investment properties)
+   - "off-market" = orQuickLists: ["not-active-listing", "not-on-market", "not-pending-listing"] (properties not currently listed)
+   - "equity-rich" = orQuickLists: ["high-equity", "free-and-clear"] (properties with significant equity)
+9. Field-specific notes:
+   - building.totalBuildingAreaSquareFeet: Often includes both living and non-living areas (cumulative total)
+   - intel.lastSoldDate vs sale.lastSaleDate: intel.lastSoldDate is derived from assessor and listing data, sale.lastSaleDate is from sale records
+   - foreclosure.filingDate vs foreclosure.recordingDate: filingDate may differ from recordingDate
+   - owner.ownershipStartDate: Date when the current owner took ownership
+   - owner.lengthOfResidence*: Based on last sale date from assessor and listing data
 
 INPUT FORMAT:
 You will receive:
@@ -312,9 +327,7 @@ function getDomainContext(domainName, options = {}) {
         doc += "\n  Available fields:\n";
         for (const field of fields) {
             doc += `    - ${field.name} (${field.type}): ${field.description}\n`;
-            if (field.filterGuidance) {
-                doc += `      Filter: ${field.filterGuidance}\n`;
-            }
+            // Removed filterGuidance - filter types are already defined in FILTER TYPES section
             if (field.examples && field.examples.length > 0) {
                 doc += `      Examples: ${field.examples.join(", ")}\n`;
             }
@@ -366,6 +379,9 @@ function buildDomainDocumentation(domainNames, options = {}) {
     let doc = "";
     const queryDomainItem = domains.find((d) => d.name === "query");
     const optionalDomains = domains.filter((d) => d.name !== "query");
+    const quickListDomain = optionalDomains.find((d) => d.name === "quickList");
+    const otherOptionalDomains = optionalDomains.filter((d) => d.name !== "quickList");
+    const hasQuickListDomain = !!quickListDomain;
     if (queryDomainItem) {
         doc += "REQUIRED:\n";
         doc += `- query: ${queryDomainItem.description}\n`;
@@ -376,15 +392,34 @@ function buildDomainDocumentation(domainNames, options = {}) {
     else if (optionalDomains.length > 0) {
         doc += "OPTIONAL DOMAINS:\n";
     }
-    for (const domain of optionalDomains) {
+    // Add QuickList values section once if quickList domain is included
+    if (hasQuickListDomain) {
+        doc += "\n";
+        doc += (0, search_criteria_filter_context_1.getQuickListValuesSection)();
+        doc += "\n";
+    }
+    // Output quickList domain immediately after QUICKLIST VALUES section for clarity
+    if (quickListDomain) {
+        doc += `\n- ${quickListDomain.name}: ${quickListDomain.description}`;
+        if (quickListDomain.fields.length > 0) {
+            doc += "\n  Available fields:\n";
+            for (const field of quickListDomain.fields) {
+                doc += `    - ${field.name} (${field.type}): ${field.description}\n`;
+                // Removed filterGuidance - filter types are already defined in FILTER TYPES section
+                if (field.examples && field.examples.length > 0) {
+                    doc += `      Examples: ${field.examples.join(", ")}\n`;
+                }
+            }
+        }
+    }
+    // Output all other domains
+    for (const domain of otherOptionalDomains) {
         doc += `\n- ${domain.name}: ${domain.description}`;
         if (domain.fields.length > 0) {
             doc += "\n  Available fields:\n";
             for (const field of domain.fields) {
                 doc += `    - ${field.name} (${field.type}): ${field.description}\n`;
-                if (field.filterGuidance) {
-                    doc += `      Filter: ${field.filterGuidance}\n`;
-                }
+                // Removed filterGuidance - filter types are already defined in FILTER TYPES section
                 if (field.examples && field.examples.length > 0) {
                     doc += `      Examples: ${field.examples.join(", ")}\n`;
                 }

package/dist/property-field/search-criteria-filter-context.d.ts

@@ -70,6 +70,11 @@ export declare function getSearchCriteriaFilterContext(searchCriteriaPath: strin
  * ```
  */
 export declare function getSearchCriteriaFilterContextString(searchCriteriaPath: string): string;
+/**
+ * Get formatted QuickList values section for documentation
+ * @returns Formatted string with all QuickList values and descriptions
+ */
+export declare function getQuickListValuesSection(): string;
 /**
  * Get filter context for all fields in a SearchCriteria domain/group
  * @param domainName The domain name (e.g., "address", "building", "assessment", "quickList")

package/dist/property-field/search-criteria-filter-context.js

@@ -8,6 +8,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getSearchCriteriaFilterContext = getSearchCriteriaFilterContext;
 exports.getSearchCriteriaFilterContextString = getSearchCriteriaFilterContextString;
+exports.getQuickListValuesSection = getQuickListValuesSection;
 exports.getDomainFilterContexts = getDomainFilterContexts;
 exports.getDomainFilterContextDocumentation = getDomainFilterContextDocumentation;
 const metadata_1 = require("./metadata");
@@ -225,14 +226,28 @@ function getExamples(fieldPath, filterType, _propertyMetadata) {
             else if (fieldPath.includes("status")) {
                 examples.push('{ equals: "active" }');
             }
-            else {
-                examples.push('{ equals: "value" }');
-                examples.push('{ contains: "substring" }');
+            else if (fieldPath.includes("street")) {
+                examples.push('{ equals: "123 Main Street" }');
+                examples.push('{ contains: "Main" } // streets containing "Main"');
+            }
+            else if (fieldPath.includes("description")) {
+                examples.push('{ contains: "pool" } // listings containing "pool"');
+                examples.push('{ contains: "renovated" } // listings containing "renovated"');
+            }
+            else if (fieldPath.includes("subdivisionName")) {
+                examples.push('{ equals: "Sunset Hills" }');
+                examples.push('{ contains: "Hills" } // subdivisions containing "Hills"');
+            }
+            else if (fieldPath.includes("Name") &&
+                (fieldPath.includes("firstName") || fieldPath.includes("lastName"))) {
+                examples.push('{ equals: "Smith" }');
+                examples.push('{ contains: "Smith" } // names containing "Smith"');
             }
+            // Removed generic examples - only include meaningful, field-specific ones
             break;
         case "NumericRangeFilter":
             if (fieldPath.includes("salePropensity")) {
-                // Sale propensity is a 0-100 score predicting likelihood to go on market and sell
+                // Sale propensity is a 0-100 AVM score predicting likelihood to go on market and sell
                 // Higher scores = higher likelihood
                 examples.push("{ min: 70 } // Very high propensity (70-100) - properties most likely to list/sell soon");
                 examples.push("{ min: 80 } // Extremely high propensity (80-100) - highest likelihood properties");
@@ -250,16 +265,29 @@ function getExamples(fieldPath, filterType, _propertyMetadata) {
                 examples.push("{ min: 2010 } // built after 2010");
                 examples.push("{ max: 2000 } // built before 2000");
             }
+            else if (fieldPath.includes("totalBuildingAreaSquareFeet")) {
+                // Note: This field is often a cumulative total including both living and non-living areas
+                examples.push("{ min: 1500 } // at least 1500 sq ft");
+                examples.push("{ max: 2500 } // under 2500 sq ft");
+                examples.push("{ min: 2000, max: 3000 } // between 2000 and 3000 sq ft");
+            }
+            else if (fieldPath.includes("flipLength") ||
+                fieldPath.includes("flipProfit")) {
+                // Flip properties are those bought and sold within a short timeframe
+                if (fieldPath.includes("flipLength")) {
+                    examples.push("{ max: 12 } // flipped within 12 months (short-term flips)");
+                    examples.push("{ min: 6, max: 12 } // flipped between 6-12 months");
+                }
+                else if (fieldPath.includes("flipProfit")) {
+                    examples.push("{ min: 50000 } // flip profit of at least $50,000");
+                    examples.push("{ min: 30000, max: 100000 } // flip profit between $30k-$100k");
+                }
+            }
             else if (fieldPath.includes("Value") || fieldPath.includes("Price")) {
                 examples.push("{ max: 400000 } // under $400,000");
                 examples.push("{ min: 500000 } // over $500,000");
                 examples.push("{ min: 300000, max: 500000 } // between $300k and $500k");
             }
-            else {
-                examples.push("{ min: 0 }");
-                examples.push("{ max: 100 }");
-                examples.push("{ min: 10, max: 50 }");
-            }
             break;
         case "BooleanFilter":
             if (fieldPath.includes("ownerOccupied")) {
@@ -270,16 +298,23 @@ function getExamples(fieldPath, filterType, _propertyMetadata) {
                 examples.push("{ equals: true } // properties with children");
                 examples.push("{ equals: false } // properties without children");
             }
-            else {
-                examples.push("{ equals: true }");
-                examples.push("{ equals: false }");
-            }
             break;
         case "DateRangeFilter":
-            examples.push('{ minDate: "2020-01-01" } // on or after January 1, 2020');
-            examples.push('{ minDate: "2016-01-01" } // last sold after 2015 (use next year for "after [year]")');
-            examples.push('{ maxDate: "2023-12-31" } // before December 31, 2023');
-            examples.push('{ minDate: "2020-01-01", maxDate: "2023-12-31" } // between dates');
+            if (fieldPath.includes("ownershipStartDate")) {
+                examples.push('{ minDate: "2020-01-01" } // owner took ownership on or after January 1, 2020');
+                examples.push('{ maxDate: "2015-12-31" } // owner took ownership before 2016');
+            }
+            else if (fieldPath.includes("filingDate")) {
+                examples.push('{ minDate: "2020-01-01" } // filed on or after January 1, 2020 (filing date may differ from recording date)');
+                examples.push('{ minDate: "2020-01-01", maxDate: "2023-12-31" } // filed between dates');
+            }
+            else {
+                // Include one example for general date filtering
+                examples.push('{ minDate: "2020-01-01" } // on or after January 1, 2020');
+                examples.push('{ minDate: "2016-01-01" } // last sold after 2015 (use next year for "after [year]")');
+                examples.push('{ maxDate: "2023-12-31" } // before December 31, 2023');
+                examples.push('{ minDate: "2020-01-01", maxDate: "2023-12-31" } // between dates');
+            }
             break;
     }
     return examples;
@@ -466,12 +501,17 @@ function getSearchCriteriaFilterContext(searchCriteriaPath) {
             filterType: "QuickListValue",
             propertyPath: undefined,
             propertyMetadata: undefined,
-            description: `Pre-defined quick filter${searchCriteriaPath === "quickList" ? "" : "s"} for common property characteristics. Values can be prefixed with "not-" to exclude (e.g., "not-vacant" excludes vacant properties). Use ${searchCriteriaPath === "orQuickLists" ? "orQuickLists array for OR logic" : searchCriteriaPath === "quickLists" ? "quickLists array for multiple values" : "quickList for a single value"}.`,
+            description: `Pre-defined quick filter${searchCriteriaPath === "quickList" ? "" : "s"} for common property characteristics. Values can be prefixed with "not-" to exclude (e.g., "not-vacant" excludes vacant properties). Use ${searchCriteriaPath === "orQuickLists" ? "orQuickLists array for OR logic (e.g., conceptual categories like 'distressed properties' = ['vacant', 'preforeclosure', 'tax-default'])" : searchCriteriaPath === "quickLists" ? "quickLists array for multiple values (AND logic)" : "quickList for a single value"}. See QUICKLIST VALUES section for all available values.`,
             examples: [
-                ...QUICK_LIST_VALUES_WITH_DESCRIPTIONS.slice(0, 5).map((item) => `"${item.value}" // ${item.description}`),
+                ...QUICK_LIST_VALUES_WITH_DESCRIPTIONS.slice(0, 3).map((item) => `"${item.value}" // ${item.description}`),
                 '"not-vacant" // Exclude vacant properties',
                 '"not-owner-occupied" // Exclude owner-occupied properties',
-                `\nAll available QuickList values (${QUICK_LIST_VALUES_WITH_DESCRIPTIONS.length} total):\n${QUICK_LIST_VALUES_WITH_DESCRIPTIONS.map((item) => `  - "${item.value}": ${item.description}`).join("\n")}`,
+                ...(searchCriteriaPath === "orQuickLists"
+                    ? [
+                        '["vacant", "preforeclosure", "tax-default"] // Distressed properties (OR logic)',
+                        '["absentee-owner", "corporate-owned", "out-of-state-owner"] // Investment properties (OR logic)',
+                    ]
+                    : []),
             ],
             filterGuidance: getFilterGuidance("QuickListValue"),
         };
@@ -480,10 +520,42 @@ function getSearchCriteriaFilterContext(searchCriteriaPath) {
     // Try to get Property field metadata
     const propertyMetadata = (0, metadata_1.getFieldMetadata)(searchCriteriaPath);
     const propertyPath = propertyMetadata ? searchCriteriaPath : undefined;
-    // Build description
+    // Build description with additional context from data dictionary
     let description;
     if (propertyMetadata) {
         description = `Filter on ${propertyMetadata.description}`;
+        // Add additional important context for specific fields based on data dictionary
+        if (searchCriteriaPath === "building.totalBuildingAreaSquareFeet") {
+            description +=
+                " (Note: Often includes cumulative total of living and non-living areas when county doesn't differentiate)";
+        }
+        else if (searchCriteriaPath === "intel.salePropensity") {
+            description +=
+                " (0-100 score where higher values indicate greater likelihood to list/sell)";
+        }
+        else if (searchCriteriaPath === "intel.lastSoldDate") {
+            description += " (Derived from assessor and listing data)";
+        }
+        else if (searchCriteriaPath === "owner.ownershipStartDate") {
+            description += " (Date current owner took ownership)";
+        }
+        else if (searchCriteriaPath.includes("lengthOfResidence")) {
+            description +=
+                " (Based on last sale date from assessor and listing data)";
+        }
+        else if (searchCriteriaPath === "foreclosure.filingDate") {
+            description +=
+                " (Preforeclosure filing date, may differ from recording date)";
+        }
+        else if (searchCriteriaPath === "involuntaryLien.filingDate") {
+            description += " (Lien filing date, may differ from recording date)";
+        }
+        else if (searchCriteriaPath.includes("flipLength")) {
+            description += " (Time between purchase and sale for flipped properties)";
+        }
+        else if (searchCriteriaPath.includes("flipProfit")) {
+            description += " (Profit from flipped property transactions)";
+        }
     }
     else {
         const parts = searchCriteriaPath.split(".");
@@ -532,6 +604,17 @@ function getSearchCriteriaFilterContextString(searchCriteriaPath) {
     }
     return parts.join("\n");
 }
+/**
+ * Get formatted QuickList values section for documentation
+ * @returns Formatted string with all QuickList values and descriptions
+ */
+function getQuickListValuesSection() {
+    let section = `QUICKLIST VALUES (${QUICK_LIST_VALUES_WITH_DESCRIPTIONS.length} total):\n`;
+    for (const item of QUICK_LIST_VALUES_WITH_DESCRIPTIONS) {
+        section += `  - "${item.value}": ${item.description}\n`;
+    }
+    return section;
+}
 /**
  * Get filter context for all fields in a SearchCriteria domain/group
  * @param domainName The domain name (e.g., "address", "building", "assessment", "quickList")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@land-catalyst/batch-data-sdk",
-  "version": "1.2.5",
+  "version": "1.2.8",
   "description": "TypeScript SDK for BatchData.io Property API - Types, Builders, and Utilities",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -21,6 +21,7 @@
     "generate:metadata": "node scripts/generate-property-field-metadata.js",
     "generate:docs": "npx tsx scripts/generate-property-type-docs.ts",
     "add:jsdoc": "node scripts/add-jsdoc-to-types.js",
+    "preversion": "npm run build",
     "v:patch": "npm version patch && git push --follow-tags",
     "v:minor": "npm version minor && git push --follow-tags",
     "v:major": "npm version major && git push --follow-tags"