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

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

@@ -3,6 +3,11 @@
  *
  * Builds complete context for AI services to generate SearchCriteria from natural language.
  * This includes all domain documentation, filter types, examples, and rules.
+ *
+ * IMPORTANT: This module only documents SEARCHABLE fields (fields that can be used in SearchCriteria).
+ * Response-only fields (like openLien.mortgages[], owner.names[], sale.lastSale.mortgages[], etc.)
+ * are intentionally excluded as they appear in Property responses but cannot be used as search filters.
+ * All fields documented here correspond to the SearchCriteria type interfaces in types.ts.
  */
 /**
  * Domain metadata with description

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

@@ -4,6 +4,11 @@
  *
  * Builds complete context for AI services to generate SearchCriteria from natural language.
  * This includes all domain documentation, filter types, examples, and rules.
+ *
+ * IMPORTANT: This module only documents SEARCHABLE fields (fields that can be used in SearchCriteria).
+ * Response-only fields (like openLien.mortgages[], owner.names[], sale.lastSale.mortgages[], etc.)
+ * are intentionally excluded as they appear in Property responses but cannot be used as search filters.
+ * All fields documented here correspond to the SearchCriteria type interfaces in types.ts.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SEARCH_CRITERIA_DOMAIN_NAMES = exports.SEARCH_CRITERIA_DOMAINS = void 0;
@@ -212,19 +217,73 @@ function buildSearchCriteriaSystemPrompt(domains, options) {
 ${domainDocs}
 
 FILTER TYPES:
-- StringFilter: { equals?, contains?, startsWith?, endsWith?, inList?, matches? }
+- StringFilter: { equals?, contains?, startsWith?, endsWith?, inList?, notInList?, matches? }
+  * equals: Exact string match - use for precise value matching
+  * contains: Substring match - matches if the field value contains the specified string anywhere
+  * startsWith: Prefix match - matches if the field value starts with the specified string
+  * endsWith: Suffix match - matches if the field value ends with the specified string
+  * inList: Array of allowed values - matches if field value is in the list (PREFERRED for fields with predefined possible values)
+  * notInList: Array of excluded values - matches if field value is NOT in the list (PREFERRED for excluding predefined values)
+  * matches: Array of pattern matches - similar to inList but for pattern-based matching
+  * For fields with predefined possible values (shown in field documentation), prefer inList (match any) or notInList (exclude) over equals/contains
+  * Example: { inList: ["Central", "Window Unit"] } or { notInList: ["None"] } or { contains: "Street" }
+
 - NumericRangeFilter: { min?, max? }
-- 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" })
+  * min: Minimum value (inclusive) - matches if field value >= min
+  * max: Maximum value (inclusive) - matches if field value <= max
+  * Can use both min and max together for a range, or just one for one-sided filtering
+  * Example: { min: 3, max: 5 } for "3 to 5 bedrooms", { min: 500000 } for "at least $500k", { max: 1000000 } for "under $1M"
+
+- DateRangeFilter: { minDate?, maxDate? }
+  * minDate: Minimum date (inclusive) - dates in ISO 8601 format YYYY-MM-DD
+  * maxDate: Maximum date (inclusive) - dates in ISO 8601 format YYYY-MM-DD
+  * For "after [year]" queries, use next year's January 1st: "after 2015" = { minDate: "2016-01-01" }
+  * For "before [year]" queries, use that year's December 31st: "before 2020" = { maxDate: "2020-12-31" }
+  * Example: { minDate: "2016-01-01" } for "built after 2015", { maxDate: "2020-12-31" } for "sold before 2021"
+
 - 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 }] }
+  * equals: Exact boolean match - must be true or false
+  * Use for fields that only have true/false values (e.g., ownerOccupied, hasChildren)
+  * Example: { equals: true } for "owner occupied properties", { equals: false } for "non-owner occupied"
+
+- QuickListValue: string
+  * Single quickList value string - matches properties with that specific characteristic
+  * Can prefix with "not-" to exclude: "not-vacant" excludes vacant properties
+  * Valid values include: "vacant", "preforeclosure", "tax-default", "fix-and-flip", "absentee-owner", etc.
+  * See QUICKLIST VALUES section for complete list and descriptions
+  * Example: "vacant" or "not-active-listing"
+
+- GeoLocationDistance: { geoPoint: { latitude, longitude }, distanceMiles?, distanceKilometers?, distanceMeters?, distanceFeet?, distanceYards? }
+  * geoPoint: Center point with latitude and longitude (both required)
+  * distanceMiles: Search radius in miles (one distance unit required)
+  * distanceKilometers: Search radius in kilometers (alternative to miles)
+  * distanceMeters: Search radius in meters (alternative to miles)
+  * distanceFeet: Search radius in feet (alternative to miles)
+  * distanceYards: Search radius in yards (alternative to miles)
+  * Matches properties within the specified distance of the center point
+  * Example: { geoPoint: { latitude: 33.4484, longitude: -112.0740 }, distanceMiles: "5" } for "within 5 miles of Phoenix"
+
+- GeoLocationBoundingBox: { nwGeoPoint: { latitude, longitude }, seGeoPoint: { latitude, longitude } }
+  * nwGeoPoint: Northwest corner of the bounding box (top-left)
+  * seGeoPoint: Southeast corner of the bounding box (bottom-right)
+  * Matches properties within the rectangular area defined by these two points
+  * Useful for filtering by geographic regions or specific areas
+  * Example: { nwGeoPoint: { latitude: 33.5, longitude: -112.1 }, seGeoPoint: { latitude: 33.3, longitude: -112.0 } }
+
+- GeoLocationPolygon: { geoPoints: [{ latitude, longitude }, ...] }
+  * geoPoints: Array of GeoPoint objects defining the polygon vertices
+  * Matches properties within the polygon area defined by connecting the points in order
+  * Requires at least 3 points to form a valid polygon
+  * Useful for irregularly shaped geographic areas
+  * Example: { geoPoints: [{ latitude: 33.5, longitude: -112.1 }, { latitude: 33.4, longitude: -112.1 }, { latitude: 33.4, longitude: -112.0 }, { latitude: 33.5, longitude: -112.0 }] }
 
 IMPORTANT RULES:
 1. Always include a "query" field with geographic scope (state, county, city, or "US")
 2. Use numeric ranges (min/max) for numeric filters like yearBuilt, bedroomCount, price, etc.
-3. Use string filters (equals, contains, inList) for text fields
+3. Use string filters appropriately:
+   - For fields with predefined possible values (shown in field documentation): Use inList (match any) or notInList (exclude) instead of equals/contains
+   - For free-text fields: Use equals (exact match), contains (substring), startsWith, endsWith, or inList
+   - Example: building.airConditioningSource has predefined values ["Central", "Window Unit", "Wall", ...] - use { inList: ["Central", "Window Unit"] } instead of { equals: "Central" }
 4. Be specific and realistic:
    - "3 bedrooms" = building.bedroomCount: {min: 3, max: 3}
    - "at least 3 bedrooms" = building.bedroomCount: {min: 3}
@@ -283,6 +342,55 @@ Example response format:
 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.`;
 }
+/**
+ * Consolidate repetitive openLien loan fields into groups
+ * Groups fields like firstLoanType, secondLoanType, thirdLoanType, fourthLoanType together
+ */
+function consolidateOpenLienFields(fields) {
+    const result = [];
+    const processed = new Set();
+    // Patterns to consolidate: [first|second|third|fourth]Loan[Type|InterestRate]
+    const loanTypePattern = /^(first|second|third|fourth)LoanType$/;
+    const loanInterestRatePattern = /^(first|second|third|fourth)LoanInterestRate$/;
+    // Group loan type fields
+    const loanTypeFields = fields.filter((f) => loanTypePattern.test(f.name));
+    if (loanTypeFields.length >= 2) {
+        // All should have same type and similar descriptions
+        const firstField = loanTypeFields[0];
+        const allSameType = loanTypeFields.every((f) => f.type === firstField.type);
+        if (allSameType) {
+            result.push({
+                type: "grouped",
+                pattern: firstField.description.replace(/^(First|Second|Third|Fourth)\s+/i, "[First/Second/Third/Fourth] "),
+                fieldNames: loanTypeFields.map((f) => f.name).sort(),
+                templateField: firstField,
+            });
+            loanTypeFields.forEach((f) => processed.add(f.name));
+        }
+    }
+    // Group loan interest rate fields
+    const loanInterestRateFields = fields.filter((f) => loanInterestRatePattern.test(f.name));
+    if (loanInterestRateFields.length >= 2) {
+        const firstField = loanInterestRateFields[0];
+        const allSameType = loanInterestRateFields.every((f) => f.type === firstField.type);
+        if (allSameType) {
+            result.push({
+                type: "grouped",
+                pattern: firstField.description.replace(/^(first|second|third|fourth)/i, "[first/second/third/fourth]") + " (applies to all listed fields)",
+                fieldNames: loanInterestRateFields.map((f) => f.name).sort(),
+                templateField: firstField,
+            });
+            loanInterestRateFields.forEach((f) => processed.add(f.name));
+        }
+    }
+    // Add remaining unprocessed fields
+    for (const field of fields) {
+        if (!processed.has(field.name)) {
+            result.push(field);
+        }
+    }
+    return result;
+}
 /**
  * Get context documentation for a specific domain
  * @param domainName The domain name (e.g., "address", "building", "assessment")
@@ -327,6 +435,15 @@ function getDomainContext(domainName, options = {}) {
         doc += "\n  Available fields:\n";
         for (const field of fields) {
             doc += `    - ${field.name} (${field.type}): ${field.description}\n`;
+            // Add possible values information if available
+            const fieldContext = (0, search_criteria_filter_context_1.getSearchCriteriaFilterContext)(field.name);
+            if (fieldContext?.possibleValues &&
+                fieldContext.possibleValues.length > 0) {
+                doc += `      Possible Values (${fieldContext.possibleValues.length} total): `;
+                // Show all possible values inline
+                doc += fieldContext.possibleValues.map((v) => `"${v}"`).join(", ");
+                doc += `\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`;
@@ -392,6 +509,8 @@ function buildDomainDocumentation(domainNames, options = {}) {
     else if (optionalDomains.length > 0) {
         doc += "OPTIONAL DOMAINS:\n";
     }
+    // Note: Possible values are shown inline with each field for better context
+    // We no longer need a separate constants section since values appear with their fields
     // Add QuickList values section once if quickList domain is included
     if (hasQuickListDomain) {
         doc += "\n";
@@ -405,6 +524,15 @@ function buildDomainDocumentation(domainNames, options = {}) {
             doc += "\n  Available fields:\n";
             for (const field of quickListDomain.fields) {
                 doc += `    - ${field.name} (${field.type}): ${field.description}\n`;
+                // Add possible values information if available
+                const fieldContext = (0, search_criteria_filter_context_1.getSearchCriteriaFilterContext)(field.name);
+                if (fieldContext?.possibleValues &&
+                    fieldContext.possibleValues.length > 0) {
+                    doc += `      Possible Values (${fieldContext.possibleValues.length} total): `;
+                    // Show all possible values inline
+                    doc += fieldContext.possibleValues.map((v) => `"${v}"`).join(", ");
+                    doc += `\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`;
@@ -417,11 +545,69 @@ function buildDomainDocumentation(domainNames, options = {}) {
         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`;
-                // Removed filterGuidance - filter types are already defined in FILTER TYPES section
-                if (field.examples && field.examples.length > 0) {
-                    doc += `      Examples: ${field.examples.join(", ")}\n`;
+            // Special handling for openLien domain to consolidate repetitive loan fields
+            if (domain.name === "openLien") {
+                const consolidatedFields = consolidateOpenLienFields(domain.fields);
+                for (const fieldOrGroup of consolidatedFields) {
+                    if (fieldOrGroup.type === "grouped") {
+                        // Handle grouped fields (e.g., firstLoanType, secondLoanType, etc.)
+                        const group = fieldOrGroup;
+                        doc += `    - ${group.fieldNames.join(", ")} (${group.templateField.type}): ${group.pattern}\n`;
+                        const templateContext = (0, search_criteria_filter_context_1.getDomainFilterContexts)(domain.name).find((ctx) => ctx.searchCriteriaPath.split(".").pop() ===
+                            group.templateField.name ||
+                            ctx.searchCriteriaPath === group.templateField.name);
+                        if (templateContext?.possibleValues &&
+                            templateContext.possibleValues.length > 0) {
+                            doc += `      Possible Values (${templateContext.possibleValues.length} total): `;
+                            // Show all possible values inline
+                            doc +=
+                                templateContext.possibleValues.map((v) => `"${v}"`).join(", ") +
+                                    `\n`;
+                        }
+                        if (group.templateField.examples &&
+                            group.templateField.examples.length > 0) {
+                            doc += `      Examples: ${group.templateField.examples.join(", ")}\n`;
+                        }
+                    }
+                    else {
+                        // Handle individual fields
+                        const field = fieldOrGroup;
+                        doc += `    - ${field.name} (${field.type}): ${field.description}\n`;
+                        const fieldContext = (0, search_criteria_filter_context_1.getDomainFilterContexts)(domain.name).find((ctx) => ctx.searchCriteriaPath.split(".").pop() === field.name ||
+                            ctx.searchCriteriaPath === field.name);
+                        if (fieldContext?.possibleValues &&
+                            fieldContext.possibleValues.length > 0) {
+                            doc += `      Possible Values (${fieldContext.possibleValues.length} total): `;
+                            // Show all possible values inline
+                            doc +=
+                                fieldContext.possibleValues.map((v) => `"${v}"`).join(", ") +
+                                    `\n`;
+                        }
+                        if (field.examples && field.examples.length > 0) {
+                            doc += `      Examples: ${field.examples.join(", ")}\n`;
+                        }
+                    }
+                }
+            }
+            else {
+                // Standard output for other domains
+                for (const field of domain.fields) {
+                    doc += `    - ${field.name} (${field.type}): ${field.description}\n`;
+                    // Add possible values information if available
+                    const fieldContext = (0, search_criteria_filter_context_1.getDomainFilterContexts)(domain.name).find((ctx) => ctx.searchCriteriaPath.split(".").pop() === field.name ||
+                        ctx.searchCriteriaPath === field.name);
+                    if (fieldContext?.possibleValues &&
+                        fieldContext.possibleValues.length > 0) {
+                        doc += `      Possible Values (${fieldContext.possibleValues.length} total): `;
+                        // Show all possible values inline
+                        doc +=
+                            fieldContext.possibleValues.map((v) => `"${v}"`).join(", ") +
+                                `\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

@@ -41,6 +41,14 @@ export interface SearchCriteriaFilterContext {
      * Additional context about how this filter should be used
      */
     filterGuidance: string;
+    /**
+     * Possible values for this field (if it has a limited set of allowed values)
+     */
+    possibleValues?: string[];
+    /**
+     * Reference to the constant name for possible values (if applicable)
+     */
+    possibleValuesRef?: string;
 }
 /**
  * Get filter context for a SearchCriteria field path
@@ -75,6 +83,12 @@ export declare function getSearchCriteriaFilterContextString(searchCriteriaPath:
  * @returns Formatted string with all QuickList values and descriptions
  */
 export declare function getQuickListValuesSection(): string;
+/**
+ * Get formatted Possible Values Constants section for documentation
+ * This defines all possible value constants once, which can then be referenced by fields
+ * @returns Formatted string with all possible value constants
+ */
+export declare function getPossibleValuesConstantsSection(): 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

@@ -9,6 +9,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getSearchCriteriaFilterContext = getSearchCriteriaFilterContext;
 exports.getSearchCriteriaFilterContextString = getSearchCriteriaFilterContextString;
 exports.getQuickListValuesSection = getQuickListValuesSection;
+exports.getPossibleValuesConstantsSection = getPossibleValuesConstantsSection;
 exports.getDomainFilterContexts = getDomainFilterContexts;
 exports.getDomainFilterContextDocumentation = getDomainFilterContextDocumentation;
 const metadata_1 = require("./metadata");
@@ -191,11 +192,14 @@ const SEARCH_CRITERIA_FILTER_TYPE_MAP = {
     "valuation.equityPercent": "NumericRangeFilter",
 };
 /**
- * Get filter guidance text based on filter type
+ * Get filter guidance text based on filter type and whether field has possible values
  */
-function getFilterGuidance(filterType) {
+function getFilterGuidance(filterType, hasPossibleValues) {
     switch (filterType) {
         case "StringFilter":
+            if (hasPossibleValues) {
+                return `Use StringFilter with: equals (exact match), inList (array of allowed values - RECOMMENDED for fields with predefined values), or notInList (array of excluded values). For fields with multiple possible values, prefer inList/notInList over equals/contains. Example: { equals: "Central" } or { inList: ["Central", "Window Unit", "Wall"] } or { notInList: ["None"] }`;
+            }
             return `Use StringFilter with: equals (exact match), contains (substring), startsWith, endsWith, inList (array of values), or matches (regex). Example: { equals: "Phoenix" } or { inList: ["Phoenix", "Tucson"] }`;
         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"`;
@@ -212,39 +216,62 @@ function getFilterGuidance(filterType) {
 /**
  * Get example values based on field and filter type
  */
-function getExamples(fieldPath, filterType, _propertyMetadata) {
+function getExamples(fieldPath, filterType, propertyMetadata) {
     const examples = [];
     switch (filterType) {
-        case "StringFilter":
-            if (fieldPath.includes("city")) {
-                examples.push('{ equals: "Phoenix" }');
-                examples.push('{ inList: ["Phoenix", "Tucson", "Mesa"] }');
-            }
-            else if (fieldPath.includes("state")) {
-                examples.push('{ equals: "AZ" }');
-            }
-            else if (fieldPath.includes("status")) {
-                examples.push('{ equals: "active" }');
-            }
-            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"');
+        case "StringFilter": {
+            // If field has possible values, prioritize inList/notInList examples
+            const possibleValues = propertyMetadata
+                ? (0, metadata_1.getPossibleValues)(propertyMetadata)
+                : undefined;
+            if (possibleValues && possibleValues.length > 0) {
+                // Show examples using inList and notInList for fields with predefined values
+                const sampleValues = possibleValues.slice(0, 3);
+                examples.push(`{ equals: "${sampleValues[0]}" } // exact match`);
+                examples.push(`{ inList: [${sampleValues.map((v) => `"${v}"`).join(", ")}] } // match any of these values`);
+                if (possibleValues.length > 3) {
+                    examples.push(`{ inList: [${sampleValues.map((v) => `"${v}"`).join(", ")}, ...] } // can include more values from the allowed set`);
+                }
+                examples.push(`{ notInList: ["${sampleValues[0]}"] } // exclude this value`);
+                if (possibleValues.length > 1) {
+                    examples.push(`{ notInList: [${sampleValues
+                        .slice(0, 2)
+                        .map((v) => `"${v}"`)
+                        .join(", ")}] } // exclude multiple values`);
+                }
             }
-            else if (fieldPath.includes("Name") &&
-                (fieldPath.includes("firstName") || fieldPath.includes("lastName"))) {
-                examples.push('{ equals: "Smith" }');
-                examples.push('{ contains: "Smith" } // names containing "Smith"');
+            else {
+                // Generic string filter examples for fields without predefined values
+                if (fieldPath.includes("city")) {
+                    examples.push('{ equals: "Phoenix" }');
+                    examples.push('{ inList: ["Phoenix", "Tucson", "Mesa"] }');
+                }
+                else if (fieldPath.includes("state")) {
+                    examples.push('{ equals: "AZ" }');
+                }
+                else if (fieldPath.includes("status")) {
+                    examples.push('{ equals: "active" }');
+                }
+                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 AVM score predicting likelihood to go on market and sell
@@ -513,7 +540,7 @@ function getSearchCriteriaFilterContext(searchCriteriaPath) {
                     ]
                     : []),
             ],
-            filterGuidance: getFilterGuidance("QuickListValue"),
+            filterGuidance: getFilterGuidance("QuickListValue", false), // hasPossibleValues not used for QuickListValue
         };
     }
     const filterType = SEARCH_CRITERIA_FILTER_TYPE_MAP[searchCriteriaPath] || "StringFilter";
@@ -562,9 +589,14 @@ function getSearchCriteriaFilterContext(searchCriteriaPath) {
         const fieldName = parts[parts.length - 1] || searchCriteriaPath;
         description = `Filter on ${fieldName} field`;
     }
+    // Get possible values if available
+    const possibleValues = propertyMetadata
+        ? (0, metadata_1.getPossibleValues)(propertyMetadata)
+        : undefined;
+    const possibleValuesRef = propertyMetadata?.possibleValuesRef;
     // Get examples and guidance
     const examples = getExamples(searchCriteriaPath, filterType, propertyMetadata);
-    const filterGuidance = getFilterGuidance(filterType);
+    const filterGuidance = getFilterGuidance(filterType, !!possibleValues && possibleValues.length > 0);
     return {
         searchCriteriaPath,
         filterType,
@@ -573,6 +605,8 @@ function getSearchCriteriaFilterContext(searchCriteriaPath) {
         description,
         examples,
         filterGuidance,
+        possibleValues,
+        possibleValuesRef,
     };
 }
 /**
@@ -595,6 +629,20 @@ function getSearchCriteriaFilterContextString(searchCriteriaPath) {
     if (context.propertyMetadata) {
         parts.push(`Property Field: ${context.propertyPath} (${context.propertyMetadata.dataType})`);
     }
+    // Add possible values information if available
+    if (context.possibleValues && context.possibleValues.length > 0) {
+        parts.push(`\nPossible Values:`);
+        if (context.possibleValuesRef) {
+            parts.push(`  Reference: ${context.possibleValuesRef} (see POSSIBLE VALUES CONSTANTS section for complete list)`);
+        }
+        // Show first 3-5 values as sample for quick reference
+        const sampleSize = Math.min(5, context.possibleValues.length);
+        const sampleValues = context.possibleValues.slice(0, sampleSize);
+        parts.push(`  Sample (${sampleSize} of ${context.possibleValues.length}): ${sampleValues.map((v) => `"${v}"`).join(", ")}${context.possibleValues.length > sampleSize
+            ? ` ... (see ${context.possibleValuesRef || "constants"} for all ${context.possibleValues.length} values)`
+            : ""}`);
+        parts.push(`  Note: Use inList (match any) or notInList (exclude) for fields with predefined values`);
+    }
     parts.push(`\nFilter Guidance:\n${context.filterGuidance}`);
     if (context.examples.length > 0) {
         parts.push(`\nExamples:`);
@@ -615,6 +663,28 @@ function getQuickListValuesSection() {
     }
     return section;
 }
+/**
+ * Get formatted Possible Values Constants section for documentation
+ * This defines all possible value constants once, which can then be referenced by fields
+ * @returns Formatted string with all possible value constants
+ */
+function getPossibleValuesConstantsSection() {
+    let section = `POSSIBLE VALUES CONSTANTS:\n`;
+    section += `These constants define allowed values for fields with predefined value sets. Fields reference these constants by name.\n\n`;
+    const constants = Object.entries(metadata_1.POSSIBLE_VALUES_CONSTANTS)
+        .filter(([constantName]) => constantName !== "StateAbbreviation") // Exclude common knowledge constants
+        .sort((a, b) => a[0].localeCompare(b[0]));
+    for (const [constantName, values] of constants) {
+        const valueArray = values;
+        section += `${constantName} (${valueArray.length} values):\n`;
+        // Show ALL values - this is the authoritative definition, no truncation
+        valueArray.forEach((value) => {
+            section += `  - "${value}"\n`;
+        });
+        section += "\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.8",
+  "version": "1.2.10",
   "description": "TypeScript SDK for BatchData.io Property API - Types, Builders, and Utilities",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",