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

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.6",
   "description": "TypeScript SDK for BatchData.io Property API - Types, Builders, and Utilities",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",