@land-catalyst/batch-data-sdk 1.2.1 → 1.2.3

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

@@ -26,6 +26,16 @@ export interface SearchCriteriaDomain {
  * All available SearchCriteria domains with their descriptions
  */
 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", "intel", "demographics", "general", "ids", "involuntaryLien", "legal", "permit", "propertyOwnerProfile", "quickList"];
+/**
+ * Type representing valid SearchCriteria domain names
+ * This union type provides better autocomplete in IDEs
+ */
+export type SearchCriteriaDomainName = (typeof SEARCH_CRITERIA_DOMAIN_NAMES)[number];
 /**
  * Options for building AI context
  */
@@ -41,17 +51,51 @@ export interface SearchCriteriaAIContextOptions {
      */
     maxExamplesPerField?: number;
 }
+/**
+ * Build domain context documentation for specified domains
+ * @param domains Array of domain names to include (e.g., ["address", "building", "assessment"])
+ *                If undefined or empty array, includes all domains (default)
+ *                Type-safe: only valid domain names from SEARCH_CRITERIA_DOMAINS are allowed
+ * @param options Options for customizing the context (applies to all specified domains)
+ * @returns Formatted domain documentation string
+ * @example
+ * ```typescript
+ * // Get context for all domains (default)
+ * const allContext = buildSearchCriteriaContext();
+ *
+ * // Get context for specific domains
+ * const context = buildSearchCriteriaContext(["address", "building", "assessment"]);
+ *
+ * // Get context for all domains with options
+ * const allContextWithOptions = buildSearchCriteriaContext(undefined, { maxFieldsPerDomain: 5 });
+ *
+ * // Get context for specific domains with options
+ * const selectiveContext = buildSearchCriteriaContext(["address", "building"], { maxFieldsPerDomain: 5 });
+ * ```
+ */
+export declare function buildSearchCriteriaContext(domains?: SearchCriteriaDomainName[], options?: SearchCriteriaAIContextOptions): string;
 /**
  * Build complete system prompt for AI to generate SearchCriteria from natural language
- * @param options Options for customizing the context
+ * @param domains Optional domain names to include. If not specified, includes all domains.
+ *                Only domains that exist in SEARCH_CRITERIA_DOMAINS are allowed
+ * @param options Options for customizing the context (applies to all specified domains)
  * @returns Complete system prompt string
  * @example
  * ```typescript
+ * // Full context with all domains
  * const systemPrompt = buildSearchCriteriaSystemPrompt();
- * const aiService = createAIService(systemPrompt);
+ *
+ * // Selective context for specific domains
+ * const systemPrompt = buildSearchCriteriaSystemPrompt(["address", "building", "assessment"]);
+ *
+ * // All domains with options
+ * const systemPrompt = buildSearchCriteriaSystemPrompt(undefined, { maxFieldsPerDomain: 5 });
+ *
+ * // Specific domains with options
+ * const systemPrompt = buildSearchCriteriaSystemPrompt(["address", "building"], { maxFieldsPerDomain: 5 });
  * ```
  */
-export declare function buildSearchCriteriaSystemPrompt(options?: SearchCriteriaAIContextOptions): string;
+export declare function buildSearchCriteriaSystemPrompt(domains?: SearchCriteriaDomainName[], options?: SearchCriteriaAIContextOptions): string;
 /**
  * Get context documentation for a specific domain
  * @param domainName The domain name (e.g., "address", "building", "assessment")
@@ -69,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

@@ -6,7 +6,8 @@
  * This includes all domain documentation, filter types, examples, and rules.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SEARCH_CRITERIA_DOMAINS = void 0;
+exports.SEARCH_CRITERIA_DOMAIN_NAMES = exports.SEARCH_CRITERIA_DOMAINS = void 0;
+exports.buildSearchCriteriaContext = buildSearchCriteriaContext;
 exports.buildSearchCriteriaSystemPrompt = buildSearchCriteriaSystemPrompt;
 exports.getDomainContext = getDomainContext;
 exports.buildSearchCriteriaUserPrompt = buildSearchCriteriaUserPrompt;
@@ -74,26 +75,138 @@ 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",
         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.",
     },
 ];
+/**
+ * Array of all valid SearchCriteria domain names (for autocomplete)
+ * Using `as const` preserves literal types for better IDE autocomplete
+ */
+exports.SEARCH_CRITERIA_DOMAIN_NAMES = [
+    "query",
+    "address",
+    "assessment",
+    "building",
+    "lot",
+    "owner",
+    "sale",
+    "tax",
+    "valuation",
+    "listing",
+    "openLien",
+    "foreclosure",
+    "intel",
+    "demographics",
+    "general",
+    "ids",
+    "involuntaryLien",
+    "legal",
+    "permit",
+    "propertyOwnerProfile",
+    "quickList",
+];
+/**
+ * Build domain context documentation for specified domains
+ * @param domains Array of domain names to include (e.g., ["address", "building", "assessment"])
+ *                If undefined or empty array, includes all domains (default)
+ *                Type-safe: only valid domain names from SEARCH_CRITERIA_DOMAINS are allowed
+ * @param options Options for customizing the context (applies to all specified domains)
+ * @returns Formatted domain documentation string
+ * @example
+ * ```typescript
+ * // Get context for all domains (default)
+ * const allContext = buildSearchCriteriaContext();
+ *
+ * // Get context for specific domains
+ * const context = buildSearchCriteriaContext(["address", "building", "assessment"]);
+ *
+ * // Get context for all domains with options
+ * const allContextWithOptions = buildSearchCriteriaContext(undefined, { maxFieldsPerDomain: 5 });
+ *
+ * // Get context for specific domains with options
+ * const selectiveContext = buildSearchCriteriaContext(["address", "building"], { maxFieldsPerDomain: 5 });
+ * ```
+ */
+function buildSearchCriteriaContext(domains, options) {
+    // Default to all domains if undefined or empty array
+    const selectedDomains = !domains || domains.length === 0
+        ? exports.SEARCH_CRITERIA_DOMAINS.map((d) => d.name)
+        : domains;
+    // Validate that all specified domains exist
+    const validDomainNames = new Set(exports.SEARCH_CRITERIA_DOMAINS.map((d) => d.name));
+    const invalidDomains = selectedDomains.filter((d) => !validDomainNames.has(d));
+    if (invalidDomains.length > 0) {
+        throw new Error(`Invalid domain(s): ${invalidDomains.join(", ")}. Valid domains are: ${Array.from(validDomainNames).join(", ")}`);
+    }
+    return buildDomainDocumentation(selectedDomains, options || {});
+}
 /**
  * Build complete system prompt for AI to generate SearchCriteria from natural language
- * @param options Options for customizing the context
+ * @param domains Optional domain names to include. If not specified, includes all domains.
+ *                Only domains that exist in SEARCH_CRITERIA_DOMAINS are allowed
+ * @param options Options for customizing the context (applies to all specified domains)
  * @returns Complete system prompt string
  * @example
  * ```typescript
+ * // Full context with all domains
  * const systemPrompt = buildSearchCriteriaSystemPrompt();
- * const aiService = createAIService(systemPrompt);
+ *
+ * // Selective context for specific domains
+ * const systemPrompt = buildSearchCriteriaSystemPrompt(["address", "building", "assessment"]);
+ *
+ * // All domains with options
+ * const systemPrompt = buildSearchCriteriaSystemPrompt(undefined, { maxFieldsPerDomain: 5 });
+ *
+ * // Specific domains with options
+ * const systemPrompt = buildSearchCriteriaSystemPrompt(["address", "building"], { maxFieldsPerDomain: 5 });
  * ```
  */
-function buildSearchCriteriaSystemPrompt(options = {}) {
-    const { maxFieldsPerDomain, maxExamplesPerField } = options;
-    // Build domain documentation
-    const domainDocs = buildDomainDocumentation(maxFieldsPerDomain, maxExamplesPerField);
+function buildSearchCriteriaSystemPrompt(domains, options) {
+    // Build domain documentation using the unified function
+    const domainDocs = buildSearchCriteriaContext(domains, options);
     return `You are an expert at creating property search criteria for real estate professionals. Your task is to convert natural language requests into structured BatchData.io search criteria.
 
 ${domainDocs}
@@ -102,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 }] }
@@ -121,11 +235,37 @@ IMPORTANT RULES:
 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.`;
+If the prompt suggests multiple distinct searches, return multiple objects. Otherwise, return a single object.
+
+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
@@ -182,10 +322,21 @@ function getDomainContext(domainName, options = {}) {
     return doc;
 }
 /**
- * Build domain documentation string for all domains
+ * Build domain documentation string for specified domains
+ * @param domainNames Array of domain names to include
+ * @param options Options for customizing the context
  */
-function buildDomainDocumentation(maxFieldsPerDomain, maxExamplesPerField) {
-    const domains = exports.SEARCH_CRITERIA_DOMAINS.map((domain) => ({
+function buildDomainDocumentation(domainNames, options = {}) {
+    const { maxFieldsPerDomain, maxExamplesPerField } = options;
+    // Filter domains to only include specified ones
+    const selectedDomains = exports.SEARCH_CRITERIA_DOMAINS.filter((domain) => domainNames.includes(domain.name));
+    // Ensure query is always first if included
+    const queryDomain = selectedDomains.find((d) => d.name === "query");
+    const otherDomains = selectedDomains.filter((d) => d.name !== "query");
+    const orderedDomains = queryDomain
+        ? [queryDomain, ...otherDomains]
+        : otherDomains;
+    const domains = orderedDomains.map((domain) => ({
         ...domain,
         fields: [],
     }));
@@ -211,10 +362,20 @@ function buildDomainDocumentation(maxFieldsPerDomain, maxExamplesPerField) {
         }
     }
     // Build the documentation string
-    let doc = "REQUIRED:\n";
-    doc += `- query: ${domains[0].description}\n\n`;
-    doc += "OPTIONAL DOMAINS:\n";
-    for (const domain of domains.slice(1)) {
+    let doc = "";
+    const queryDomainItem = domains.find((d) => d.name === "query");
+    const optionalDomains = domains.filter((d) => d.name !== "query");
+    if (queryDomainItem) {
+        doc += "REQUIRED:\n";
+        doc += `- query: ${queryDomainItem.description}\n`;
+        if (optionalDomains.length > 0) {
+            doc += "\nOPTIONAL DOMAINS:\n";
+        }
+    }
+    else if (optionalDomains.length > 0) {
+        doc += "OPTIONAL DOMAINS:\n";
+    }
+    for (const domain of optionalDomains) {
         doc += `\n- ${domain.name}: ${domain.description}`;
         if (domain.fields.length > 0) {
             doc += "\n  Available fields:\n";
@@ -236,30 +397,15 @@ function buildDomainDocumentation(maxFieldsPerDomain, maxExamplesPerField) {
  * @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",
@@ -198,6 +200,8 @@ function getFilterGuidance(filterType) {
             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"`;
+        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,6 +261,20 @@ 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('{ maxDate: "2023-12-31" } // before December 31, 2023');

package/package.json

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