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

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", "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")

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;
@@ -80,20 +81,84 @@ exports.SEARCH_CRITERIA_DOMAINS = [
         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",
+    "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}
@@ -182,10 +247,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 +287,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";

package/package.json

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