@land-catalyst/batch-data-sdk 1.2.2 → 1.2.4

package/dist/builders/builders.js

@@ -89,7 +89,6 @@ class BaseBuilder {
      */
     getSearchCriteriaFieldMetadata(searchCriteriaPath) {
         // Dynamic import to avoid circular dependency
-        // eslint-disable-next-line @typescript-eslint/no-require-imports
         const { getSearchCriteriaFieldMetadata, } = require("../property-field/utils");
         return getSearchCriteriaFieldMetadata(searchCriteriaPath);
     }

package/dist/property-field/metadata.js

@@ -2555,7 +2555,7 @@ exports.PROPERTY_FIELD_METADATA = {
         resourceSubGroupName: undefined,
         name: "salePropensity",
         dataType: "number",
-        description: "An automated value metric (AVM) that predicts the likelihood that a property is likely to go on market and sell.",
+        description: "sale propensity score (0-100). This is a highly impactful automated value metric (AVM) that predicts the likelihood that a property will go on market and sell. Higher scores indicate higher likelihood. This is one of the most valuable predictive indicators for identifying properties likely to be listed soon. Use min values to target high-propensity properties (e.g., min: 70 for very high likelihood, min: 80 for extremely high likelihood).",
         isArrayElement: false,
     },
     "intel.salePropensityStatus": {

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

@@ -30,7 +30,7 @@ export declare const SEARCH_CRITERIA_DOMAINS: SearchCriteriaDomain[];
  * Array of all valid SearchCriteria domain names (for autocomplete)
  * Using `as const` preserves literal types for better IDE autocomplete
  */
-export declare const SEARCH_CRITERIA_DOMAIN_NAMES: readonly ["query", "address", "assessment", "building", "lot", "owner", "sale", "tax", "valuation", "listing", "openLien", "foreclosure", "quickList"];
+export declare const SEARCH_CRITERIA_DOMAIN_NAMES: readonly ["query", "address", "assessment", "building", "lot", "owner", "sale", "tax", "valuation", "listing", "openLien", "foreclosure", "intel", "demographics", "general", "ids", "involuntaryLien", "legal", "permit", "propertyOwnerProfile", "quickList"];
 /**
  * Type representing valid SearchCriteria domain names
  * This union type provides better autocomplete in IDEs
@@ -113,5 +113,8 @@ export declare function getDomainContext(domainName: string, options?: SearchCri
  * @param userPrompt The user's natural language prompt
  * @param existingCriteria Optional existing search criteria to modify
  * @returns Formatted user prompt string
+ * @deprecated This function is kept for backward compatibility but is no longer needed.
+ *             The service should format the user prompt and existing criteria directly.
+ *             The system prompt already describes the expected input and output format.
  */
 export declare function buildSearchCriteriaUserPrompt(userPrompt: string, existingCriteria?: unknown): string;

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

@@ -75,6 +75,46 @@ exports.SEARCH_CRITERIA_DOMAINS = [
         responseGroup: "foreclosure",
         description: "Foreclosure status and auction information",
     },
+    {
+        name: "intel",
+        responseGroup: "intel",
+        description: "Intelligence and predictive analytics (sale propensity, last sold information)",
+    },
+    {
+        name: "demographics",
+        responseGroup: "demographics",
+        description: "Demographic information about property owners (age, income, net worth, household size, etc.)",
+    },
+    {
+        name: "general",
+        responseGroup: "general",
+        description: "General property type and category filters",
+    },
+    {
+        name: "ids",
+        responseGroup: "ids",
+        description: "Property identifiers (APN, tax ID, FIPS code, address hash, etc.)",
+    },
+    {
+        name: "involuntaryLien",
+        responseGroup: "involuntaryLien",
+        description: "Involuntary lien information (liens recorded against the property)",
+    },
+    {
+        name: "legal",
+        responseGroup: "legal",
+        description: "Legal information (subdivision name, etc.)",
+    },
+    {
+        name: "permit",
+        responseGroup: "permit",
+        description: "Building permit information (permit count, dates, job values, etc.)",
+    },
+    {
+        name: "propertyOwnerProfile",
+        responseGroup: "propertyOwnerProfile",
+        description: "Property owner profile information (total properties owned, equity, mortgages, etc.)",
+    },
     {
         name: "quickList",
         responseGroup: "quickList",
@@ -98,6 +138,14 @@ exports.SEARCH_CRITERIA_DOMAIN_NAMES = [
     "listing",
     "openLien",
     "foreclosure",
+    "intel",
+    "demographics",
+    "general",
+    "ids",
+    "involuntaryLien",
+    "legal",
+    "permit",
+    "propertyOwnerProfile",
     "quickList",
 ];
 /**
@@ -167,6 +215,7 @@ FILTER TYPES:
 - StringFilter: { equals?, contains?, startsWith?, endsWith?, inList?, matches? }
 - NumericRangeFilter: { min?, max? }
 - DateRangeFilter: { minDate?, maxDate? }
+- BooleanFilter: { equals: boolean }
 - GeoLocationDistance: { latitude, longitude, distanceMiles }
 - GeoLocationBoundingBox: { minLat, maxLat, minLon, maxLon }
 - GeoLocationPolygon: { geoPoints: [{ latitude, longitude }] }
@@ -182,15 +231,42 @@ IMPORTANT RULES:
    - "under $400,000" = assessment.totalMarketValue: {max: 400000}
    - "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]")
 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
 
+INPUT FORMAT:
+You will receive:
+1. A user prompt in natural language describing the property search criteria they want
+2. Optionally, existing search criteria in JSON format that should be modified
+
+RESPONSE FORMAT:
 Return your response as a JSON array. Each object should have:
 - searchCriteria: The complete SearchCriteria object
 - description: A natural language description of what this search criteria finds
 
-If the prompt suggests multiple distinct searches, return multiple objects. Otherwise, return a single object.`;
+IMPORTANT: Only return multiple objects if they represent DISTINCT, meaningfully different searches. Do not return duplicate or near-duplicate search criteria. If the prompt describes a single search, return a single object. If the prompt describes multiple distinct searches (e.g., "luxury homes in Scottsdale" AND "starter homes in Tempe"), return multiple objects.
+
+Example response format:
+[
+  {
+    "searchCriteria": {
+      "query": "Maricopa County, AZ",
+      "building": {
+        "bedroomCount": { "min": 3, "max": 3 },
+        "yearBuilt": { "min": 2000 }
+      },
+      "assessment": {
+        "totalMarketValue": { "max": 500000 }
+      }
+    },
+    "description": "3-bedroom homes built after 2000 in Maricopa County, Arizona, with a market value under $500,000"
+  }
+]
+
+If existing criteria is provided, merge intelligently - update fields mentioned in the prompt, preserve others.
+Return only valid JSON, no markdown formatting or code blocks.`;
 }
 /**
  * Get context documentation for a specific domain
@@ -322,30 +398,15 @@ function buildDomainDocumentation(domainNames, options = {}) {
  * @param userPrompt The user's natural language prompt
  * @param existingCriteria Optional existing search criteria to modify
  * @returns Formatted user prompt string
+ * @deprecated This function is kept for backward compatibility but is no longer needed.
+ *             The service should format the user prompt and existing criteria directly.
+ *             The system prompt already describes the expected input and output format.
  */
 function buildSearchCriteriaUserPrompt(userPrompt, existingCriteria) {
-    const basePrompt = `Example response format:
-[
-  {
-    "searchCriteria": {
-      "query": "Maricopa County, AZ",
-      "building": {
-        "bedroomCount": { "min": 3, "max": 3 },
-        "yearBuilt": { "min": 2000 }
-      },
-      "assessment": {
-        "totalMarketValue": { "max": 500000 }
-      }
-    },
-    "description": "3-bedroom homes built after 2000 in Maricopa County, Arizona, with a market value under $500,000"
-  }
-]
-
-${existingCriteria ? `\nEXISTING SEARCH CRITERIA TO MODIFY:\n${JSON.stringify(existingCriteria, null, 2)}\n\nModify the existing criteria based on the user's prompt. Merge intelligently - update fields mentioned in the prompt, preserve others.` : ""}
-
-USER PROMPT:
-${userPrompt}
-
-Return only valid JSON, no markdown formatting or code blocks.`;
-    return basePrompt;
+    // Simple format - service can customize this as needed
+    let prompt = userPrompt;
+    if (existingCriteria) {
+        prompt = `EXISTING SEARCH CRITERIA TO MODIFY:\n${JSON.stringify(existingCriteria, null, 2)}\n\nModify the existing criteria based on the following prompt:\n\n${userPrompt}`;
+    }
+    return prompt;
 }

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

@@ -8,7 +8,7 @@ import type { PropertyFieldMetadata } from "./metadata";
 /**
  * Filter type for a SearchCriteria field
  */
-export type SearchCriteriaFilterType = "StringFilter" | "NumericRangeFilter" | "DateRangeFilter" | "QuickListValue";
+export type SearchCriteriaFilterType = "StringFilter" | "NumericRangeFilter" | "DateRangeFilter" | "BooleanFilter" | "QuickListValue";
 /**
  * Context about how a SearchCriteria field should be filtered
  */

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

@@ -84,6 +84,7 @@ const SEARCH_CRITERIA_FILTER_TYPE_MAP = {
     "demographics.homeownerRenter": "StringFilter",
     "demographics.businessOwner": "StringFilter",
     "demographics.gender": "StringFilter",
+    "demographics.hasChildren": "BooleanFilter",
     "demographics.investments": "StringFilter",
     "demographics.demographics": "StringFilter",
     "demographics.religiousAffiliation": "StringFilter",
@@ -150,6 +151,7 @@ const SEARCH_CRITERIA_FILTER_TYPE_MAP = {
     // Owner - mix
     "owner.firstName": "StringFilter",
     "owner.lastName": "StringFilter",
+    "owner.ownerOccupied": "BooleanFilter",
     "owner.mailingStreet": "StringFilter",
     "owner.mailingCity": "StringFilter",
     "owner.mailingState": "StringFilter",
@@ -197,7 +199,9 @@ function getFilterGuidance(filterType) {
         case "NumericRangeFilter":
             return `Use NumericRangeFilter with: min (minimum value), max (maximum value), or both. Example: { min: 3, max: 5 } for "3-5 bedrooms" or { min: 2010 } for "built after 2010"`;
         case "DateRangeFilter":
-            return `Use DateRangeFilter with: minDate (earliest date), maxDate (latest date), or both. Dates should be in ISO 8601 format (YYYY-MM-DD). Example: { minDate: "2020-01-01" } for "after 2020"`;
+            return `Use DateRangeFilter with: minDate (earliest date), maxDate (latest date), or both. Dates should be in ISO 8601 format (YYYY-MM-DD). For "after [year]", use the next year's January 1st. Example: "last sold after 2015" = { minDate: "2016-01-01" }, "after 2020" = { minDate: "2021-01-01" }`;
+        case "BooleanFilter":
+            return `Use BooleanFilter with: { equals: boolean }. Example: { equals: true } for ownerOccupied or { equals: false } for hasChildren`;
         case "QuickListValue":
             return `Use a QuickListValue string. Can be prefixed with "not-" to exclude. Available as: quickList (single value), quickLists (array), orQuickLists (array for OR logic). Example: "owner-occupied" or "not-vacant"`;
         default:
@@ -227,7 +231,17 @@ function getExamples(fieldPath, filterType, _propertyMetadata) {
             }
             break;
         case "NumericRangeFilter":
-            if (fieldPath.includes("bedroom") || fieldPath.includes("bathroom")) {
+            if (fieldPath.includes("salePropensity")) {
+                // Sale propensity is a 0-100 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");
+                examples.push("{ min: 50, max: 70 } // Medium-high propensity (50-70) - moderate likelihood");
+                examples.push("{ min: 60 } // High propensity (60-100) - good likelihood of listing/selling");
+                examples.push("{ min: 75, max: 100 } // Very high to maximum propensity range");
+            }
+            else if (fieldPath.includes("bedroom") ||
+                fieldPath.includes("bathroom")) {
                 examples.push("{ min: 3, max: 3 } // exactly 3");
                 examples.push("{ min: 3 } // at least 3");
                 examples.push("{ min: 3, max: 5 } // between 3 and 5");
@@ -247,8 +261,23 @@ function getExamples(fieldPath, filterType, _propertyMetadata) {
                 examples.push("{ min: 10, max: 50 }");
             }
             break;
+        case "BooleanFilter":
+            if (fieldPath.includes("ownerOccupied")) {
+                examples.push("{ equals: true } // owner-occupied properties");
+                examples.push("{ equals: false } // non-owner-occupied properties");
+            }
+            else if (fieldPath.includes("hasChildren")) {
+                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" } // after January 1, 2020');
+            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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@land-catalyst/batch-data-sdk",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "description": "TypeScript SDK for BatchData.io Property API - Types, Builders, and Utilities",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",