@land-catalyst/batch-data-sdk 1.5.1 → 1.5.3

package/dist/index.d.ts

@@ -16,6 +16,7 @@ export * from "./property-field/display";
 export * from "./property-field/search-criteria-filter-context";
 export type { SearchCriteriaFilterContext, SearchCriteriaFilterType, } from "./property-field/search-criteria-filter-context";
 export * from "./property-field/search-criteria-ai-context";
+export * from "./property-field/property-data-ai-context";
 export { type PropertyFieldPathType, type PropertyFieldValueType, type FieldMetadataForPath, } from "./property-field/types";
 export type { SearchCriteriaFieldMapping, SearchCriteriaFieldMetadata, } from "./property-field/utils";
 export type { RequestMiddleware, ResponseMiddleware, ErrorMiddleware, HttpMiddleware, } from "./client/client";

package/dist/index.js

@@ -31,3 +31,4 @@ __exportStar(require("./property-field/utils"), exports);
 __exportStar(require("./property-field/display"), exports);
 __exportStar(require("./property-field/search-criteria-filter-context"), exports);
 __exportStar(require("./property-field/search-criteria-ai-context"), exports);
+__exportStar(require("./property-field/property-data-ai-context"), exports);

package/dist/property-field/property-data-ai-context.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Property Data AI Context Builder
+ *
+ * Builds context for AI services to analyze and discuss property data.
+ * Provides field descriptions, interpretations, and investment insights.
+ *
+ * This module focuses on Property RESPONSE fields (data returned from searches),
+ * not SearchCriteria filter fields. Use search-criteria-ai-context.ts for search filters.
+ */
+import type { Property } from "../core/types";
+/**
+ * Property data domain with description and investment relevance
+ */
+export interface PropertyDataDomain {
+    /** Domain name (e.g., "valuation", "permit", "owner") */
+    name: string;
+    /** Human-readable description */
+    description: string;
+    /** Why this domain matters for investment analysis */
+    investmentRelevance: string;
+    /** Key fields to highlight in this domain */
+    keyFields?: string[];
+}
+/**
+ * All property data domains with descriptions and investment relevance
+ */
+export declare const PROPERTY_DATA_DOMAINS: PropertyDataDomain[];
+/**
+ * Options for building property data AI context
+ */
+export interface PropertyDataAIContextOptions {
+    /** Domains to include (defaults to all) */
+    domains?: string[];
+    /** Whether to include raw field values */
+    includeRawValues?: boolean;
+    /** Whether to include field metadata descriptions */
+    includeFieldDescriptions?: boolean;
+    /** Maximum fields per domain to include */
+    maxFieldsPerDomain?: number;
+}
+/**
+ * Extracted property data with AI-friendly formatting
+ */
+export interface PropertyDataContext {
+    /** The property address formatted for display */
+    address: string;
+    /** Key property metrics for quick reference */
+    summary: {
+        estimatedValue?: number;
+        equity?: number;
+        equityPercent?: number;
+        ltv?: number;
+        salePropensity?: number;
+        salePropensityCategory?: string;
+        yearBuilt?: number;
+        sqft?: number;
+        bedrooms?: number;
+        bathrooms?: number;
+        propertyType?: string;
+        ownerName?: string;
+        ownerType?: string;
+        permitCount?: number;
+        ownerPortfolioSize?: number;
+    };
+    /** Motivation signals detected */
+    motivationSignals: string[];
+    /** Investment considerations */
+    considerations: string[];
+    /** Domain-specific data */
+    domains: Record<string, Record<string, unknown>>;
+}
+/**
+ * Build comprehensive property data context for AI
+ * @param property The property object to analyze
+ * @param options Configuration options
+ * @returns Structured context for AI consumption
+ * @example
+ * ```typescript
+ * const context = buildPropertyDataContext(property);
+ * // Use context.summary for quick metrics
+ * // Use context.motivationSignals for seller motivation
+ * // Use context.considerations for investment analysis
+ * ```
+ */
+export declare function buildPropertyDataContext(property: Property, options?: PropertyDataAIContextOptions): PropertyDataContext;
+/**
+ * Build AI system prompt section for property data context
+ * @param context The property data context
+ * @returns Formatted string for AI system prompt
+ */
+export declare function formatPropertyContextForAI(context: PropertyDataContext): string;
+/**
+ * Get domain descriptions for AI context
+ * @param domainNames Optional list of domains to include
+ * @returns Formatted domain descriptions
+ */
+export declare function getPropertyDomainDescriptions(domainNames?: string[]): string;

package/dist/property-field/property-data-ai-context.js

@@ -0,0 +1,464 @@
+"use strict";
+/**
+ * Property Data AI Context Builder
+ *
+ * Builds context for AI services to analyze and discuss property data.
+ * Provides field descriptions, interpretations, and investment insights.
+ *
+ * This module focuses on Property RESPONSE fields (data returned from searches),
+ * not SearchCriteria filter fields. Use search-criteria-ai-context.ts for search filters.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROPERTY_DATA_DOMAINS = void 0;
+exports.buildPropertyDataContext = buildPropertyDataContext;
+exports.formatPropertyContextForAI = formatPropertyContextForAI;
+exports.getPropertyDomainDescriptions = getPropertyDomainDescriptions;
+const utils_1 = require("./utils");
+/**
+ * All property data domains with descriptions and investment relevance
+ */
+exports.PROPERTY_DATA_DOMAINS = [
+    {
+        name: "address",
+        description: "Property location and address details",
+        investmentRelevance: "Location drives value appreciation, rental rates, and exit strategy options. Neighborhood, school districts, and proximity to amenities affect marketability.",
+        keyFields: ["street", "city", "state", "zip", "county"],
+    },
+    {
+        name: "building",
+        description: "Building characteristics, size, and features",
+        investmentRelevance: "Building specs determine renovation costs, rental potential, and buyer appeal. Year built affects maintenance costs; square footage and bedroom/bath count drive value.",
+        keyFields: [
+            "yearBuilt",
+            "size",
+            "bedroomCount",
+            "bathCount",
+            "generalPropertyType",
+            "buildingCondition",
+        ],
+    },
+    {
+        name: "valuation",
+        description: "Property value estimates including AVM, equity, and loan-to-value",
+        investmentRelevance: "AVM provides baseline value for offer calculations. Equity indicates owner flexibility; high equity owners may accept creative deals. LTV over 80% suggests potential distress.",
+        keyFields: [
+            "estimatedValue",
+            "equityCurrentEstimatedBalance",
+            "equityPercent",
+            "ltv",
+            "confidenceScore",
+        ],
+    },
+    {
+        name: "permit",
+        description: "Building permit history and renovation activity",
+        investmentRelevance: "Recent permits indicate property condition and improvements. High permit activity may signal deferred maintenance being addressed or active renovation. Solar/HVAC permits suggest energy efficiency upgrades.",
+        keyFields: [
+            "permitCount",
+            "totalJobValue",
+            "latestDate",
+            "allTags",
+            "tags",
+        ],
+    },
+    {
+        name: "propertyOwnerProfile",
+        description: "Owner portfolio size and financial position across all owned properties",
+        investmentRelevance: "Portfolio owners may be more sophisticated sellers but also more motivated if over-leveraged. High mortgage balance across portfolio suggests potential cash flow pressure. Multiple properties indicate experienced investor who may want quick, clean deals.",
+        keyFields: [
+            "propertiesCount",
+            "propertiesTotalEquity",
+            "propertiesTotalEstimatedValue",
+            "mortgagesTotalBalance",
+            "mortgagesCount",
+        ],
+    },
+    {
+        name: "owner",
+        description: "Property owner information and contact details",
+        investmentRelevance: "Owner type (individual vs corporate vs trust) affects negotiation approach. Absentee owners may be more motivated. Length of ownership indicates attachment level.",
+        keyFields: ["fullName", "type", "mailingAddress", "phoneNumbers", "emails"],
+    },
+    {
+        name: "intel",
+        description: "Predictive analytics including sale propensity",
+        investmentRelevance: "Sale propensity score (0-100) predicts likelihood to sell. Scores above 70 indicate high motivation. Combined with other signals (length of residence, life events), helps prioritize outreach.",
+        keyFields: [
+            "salePropensity",
+            "salePropensityCategory",
+            "lastSoldDate",
+            "lastSoldPrice",
+        ],
+    },
+    {
+        name: "openLien",
+        description: "Current mortgages and liens on the property",
+        investmentRelevance: "Mortgage balance vs value determines equity and seller flexibility. Multiple liens may indicate financial stress. High interest rates on existing mortgages may motivate seller.",
+        keyFields: [
+            "totalOpenLienCount",
+            "totalOpenLienBalance",
+            "mortgages",
+            "firstLoanAmount",
+            "firstLoanInterestRate",
+        ],
+    },
+    {
+        name: "assessment",
+        description: "Tax assessment values and market value estimates",
+        investmentRelevance: "Assessed value vs market value gap indicates potential appreciation not yet taxed. Assessment increases may pressure cash-strapped owners. Useful for estimating property taxes.",
+        keyFields: [
+            "totalAssessedValue",
+            "totalMarketValue",
+            "assessmentYear",
+            "landValue",
+            "improvementValue",
+        ],
+    },
+    {
+        name: "quickLists",
+        description: "Pre-computed property flags and characteristics",
+        investmentRelevance: "Quick indicators of motivated seller situations. Vacant, pre-foreclosure, tax delinquent, and inherited properties often have motivated sellers. Free-and-clear properties have maximum flexibility.",
+        keyFields: [
+            "vacant",
+            "preforeclosure",
+            "taxDefault",
+            "inherited",
+            "freeAndClear",
+            "highEquity",
+            "absenteeOwner",
+        ],
+    },
+    {
+        name: "foreclosure",
+        description: "Foreclosure status and auction information",
+        investmentRelevance: "Active foreclosure indicates highly motivated seller with timeline pressure. Auction dates create urgency. Pre-foreclosure is often best window for negotiation.",
+        keyFields: ["status", "auctionDate", "defaultAmount", "filingDate"],
+    },
+    {
+        name: "sale",
+        description: "Sale history and transaction records",
+        investmentRelevance: "Recent sale price establishes baseline. Rapid appreciation or depreciation indicates market trends. Multiple sales in short period may indicate flipper activity or problem property.",
+        keyFields: [
+            "lastSaleDate",
+            "lastSalePrice",
+            "lastSaleType",
+            "priorSaleDate",
+            "priorSalePrice",
+        ],
+    },
+    {
+        name: "demographics",
+        description: "Owner demographic information",
+        investmentRelevance: "Demographics inform communication approach. Senior owners may be considering downsizing. Income and net worth estimates help gauge financial position and deal size capability.",
+        keyFields: ["estimatedAge", "estimatedIncome", "estimatedNetWorth"],
+    },
+];
+/**
+ * Extract key motivation signals from property data
+ */
+function extractMotivationSignals(property) {
+    const signals = [];
+    const ql = property.quickLists;
+    const intel = property.intel;
+    const valuation = property.valuation;
+    const ownerProfile = property
+        .propertyOwnerProfile;
+    // QuickList signals
+    if (ql?.vacant)
+        signals.push("Property appears vacant");
+    if (ql?.preforeclosure)
+        signals.push("Property is in pre-foreclosure");
+    if (ql?.taxDefault)
+        signals.push("Property taxes are delinquent");
+    if (ql?.inherited)
+        signals.push("Property was inherited");
+    if (ql?.absenteeOwner)
+        signals.push("Owner does not live at property");
+    if (ql?.outOfStateOwner)
+        signals.push("Owner lives out of state");
+    if (ql?.seniorOwner)
+        signals.push("Owner is a senior (65+)");
+    if (ql?.freeAndClear)
+        signals.push("Property is free and clear (no mortgage)");
+    if (ql?.highEquity)
+        signals.push("High equity position");
+    if (ql?.lowEquity)
+        signals.push("Low equity position");
+    // Sale propensity
+    const salePropensity = intel?.salePropensity;
+    if (salePropensity !== undefined) {
+        if (salePropensity >= 80) {
+            signals.push(`Very high sale propensity (${salePropensity}%)`);
+        }
+        else if (salePropensity >= 60) {
+            signals.push(`High sale propensity (${salePropensity}%)`);
+        }
+    }
+    // LTV signals
+    const ltv = valuation?.ltv;
+    if (ltv !== undefined) {
+        if (ltv > 100) {
+            signals.push(`Underwater property (LTV: ${ltv.toFixed(0)}%)`);
+        }
+        else if (ltv > 80) {
+            signals.push(`High LTV may indicate financial pressure (${ltv.toFixed(0)}%)`);
+        }
+    }
+    // Portfolio stress signals
+    const portfolioMortgages = ownerProfile?.mortgagesTotalBalance;
+    const portfolioValue = ownerProfile?.propertiesTotalEstimatedValue;
+    if (portfolioMortgages && portfolioValue && portfolioMortgages > 0) {
+        const portfolioLtv = (portfolioMortgages / portfolioValue) * 100;
+        if (portfolioLtv > 70) {
+            signals.push(`Owner portfolio is leveraged (${portfolioLtv.toFixed(0)}% across all properties)`);
+        }
+    }
+    return signals;
+}
+/**
+ * Generate investment considerations based on property data
+ */
+function generateConsiderations(property) {
+    const considerations = [];
+    const valuation = property.valuation;
+    const permit = property.permit;
+    const building = property.building;
+    // Equity-based considerations
+    const equity = valuation?.equityCurrentEstimatedBalance;
+    const estimatedValue = valuation?.estimatedValue;
+    if (equity && estimatedValue) {
+        const equityPercent = (equity / estimatedValue) * 100;
+        if (equityPercent > 50) {
+            considerations.push("High equity position gives seller flexibility on terms");
+        }
+        else if (equityPercent < 20) {
+            considerations.push("Low equity may limit seller's ability to negotiate on price");
+        }
+    }
+    // Permit-based considerations
+    const permitCount = permit?.permitCount;
+    const permitTags = permit?.tags;
+    if (permitCount && permitCount > 0) {
+        considerations.push(`${permitCount} permits on file indicate renovation history`);
+        if (permitTags?.solar) {
+            considerations.push("Solar installation may reduce operating costs");
+        }
+        if (permitTags?.remodel || permitTags?.kitchen || permitTags?.bathroom) {
+            considerations.push("Recent remodel permits suggest updated interior");
+        }
+        if (permitTags?.roofing) {
+            considerations.push("Roofing permit suggests recent roof work");
+        }
+    }
+    // Building condition considerations
+    const yearBuilt = building?.yearBuilt;
+    if (yearBuilt) {
+        const age = new Date().getFullYear() - yearBuilt;
+        if (age > 50) {
+            considerations.push(`Built ${age} years ago - may need significant updates`);
+        }
+        else if (age > 30) {
+            considerations.push(`Built ${age} years ago - likely needs some updates`);
+        }
+        else if (age < 10) {
+            considerations.push("Newer construction - likely lower maintenance costs");
+        }
+    }
+    // Confidence considerations
+    const confidence = valuation?.confidenceScore;
+    if (confidence !== undefined) {
+        if (confidence < 50) {
+            considerations.push(`Low AVM confidence (${confidence}) - value estimate may be unreliable`);
+        }
+        else if (confidence >= 80) {
+            considerations.push(`High AVM confidence (${confidence}) - value estimate is reliable`);
+        }
+    }
+    return considerations;
+}
+/**
+ * Format address from property data
+ */
+function formatAddress(property) {
+    const addr = property.address;
+    if (!addr)
+        return "Unknown Address";
+    const street = addr.street ||
+        [
+            addr.houseNumber,
+            addr.streetName,
+            addr.streetSuffix,
+        ]
+            .filter(Boolean)
+            .join(" ");
+    const city = addr.city || "";
+    const state = addr.state || "";
+    const zip = addr.zip || "";
+    const formatted = `${street}, ${city}, ${state} ${zip}`.trim();
+    return formatted.replace(/[,\s]+$/, "") || "Unknown Address";
+}
+/**
+ * Extract summary metrics from property data
+ */
+function extractSummary(property) {
+    const building = property.building;
+    const valuation = property.valuation;
+    const intel = property.intel;
+    const permit = property.permit;
+    const ownerProfile = property
+        .propertyOwnerProfile;
+    const owner = property.owner;
+    return {
+        estimatedValue: valuation?.estimatedValue,
+        equity: valuation?.equityCurrentEstimatedBalance,
+        equityPercent: valuation?.equityPercent,
+        ltv: valuation?.ltv,
+        salePropensity: intel?.salePropensity,
+        salePropensityCategory: intel?.salePropensityCategory,
+        yearBuilt: building?.yearBuilt,
+        sqft: building?.size ||
+            building?.livingSquareFeet,
+        bedrooms: building?.bedroomCount,
+        bathrooms: building?.bathCount,
+        propertyType: building?.generalPropertyType,
+        ownerName: owner?.fullName,
+        ownerType: owner?.type,
+        permitCount: permit?.permitCount,
+        ownerPortfolioSize: ownerProfile?.propertiesCount,
+    };
+}
+/**
+ * Extract domain-specific data from property
+ */
+function extractDomainData(property, domainName, options) {
+    const data = {};
+    const domain = exports.PROPERTY_DATA_DOMAINS.find((d) => d.name === domainName);
+    if (!domain)
+        return data;
+    // Get fields for this domain
+    const fields = (0, utils_1.getPropertyGroupFields)(domainName);
+    const keyFields = new Set(domain.keyFields || []);
+    // Prioritize key fields, then add others up to limit
+    const sortedFields = [...fields].sort((a, b) => {
+        const aKey = keyFields.has(a.fieldPath.split(".").pop() || "");
+        const bKey = keyFields.has(b.fieldPath.split(".").pop() || "");
+        if (aKey && !bKey)
+            return -1;
+        if (!aKey && bKey)
+            return 1;
+        return 0;
+    });
+    const limit = options.maxFieldsPerDomain || 20;
+    const fieldsToProcess = sortedFields.slice(0, limit);
+    for (const field of fieldsToProcess) {
+        const value = (0, utils_1.getPropertyFieldValue)(property, field.fieldPath);
+        if (value !== undefined && value !== null) {
+            const fieldName = field.fieldPath.split(".").pop() || field.fieldPath;
+            data[fieldName] = value;
+        }
+    }
+    return data;
+}
+/**
+ * Build comprehensive property data context for AI
+ * @param property The property object to analyze
+ * @param options Configuration options
+ * @returns Structured context for AI consumption
+ * @example
+ * ```typescript
+ * const context = buildPropertyDataContext(property);
+ * // Use context.summary for quick metrics
+ * // Use context.motivationSignals for seller motivation
+ * // Use context.considerations for investment analysis
+ * ```
+ */
+function buildPropertyDataContext(property, options = {}) {
+    const selectedDomains = options.domains || exports.PROPERTY_DATA_DOMAINS.map((d) => d.name);
+    const domains = {};
+    for (const domainName of selectedDomains) {
+        const domainData = extractDomainData(property, domainName, options);
+        if (Object.keys(domainData).length > 0) {
+            domains[domainName] = domainData;
+        }
+    }
+    return {
+        address: formatAddress(property),
+        summary: extractSummary(property),
+        motivationSignals: extractMotivationSignals(property),
+        considerations: generateConsiderations(property),
+        domains,
+    };
+}
+/**
+ * Build AI system prompt section for property data context
+ * @param context The property data context
+ * @returns Formatted string for AI system prompt
+ */
+function formatPropertyContextForAI(context) {
+    const sections = [];
+    // Address
+    sections.push(`**Address:** ${context.address}`);
+    // Summary metrics
+    const s = context.summary;
+    sections.push("", "## Property Summary");
+    if (s.estimatedValue)
+        sections.push(`- Estimated Value: $${s.estimatedValue.toLocaleString()}`);
+    if (s.equity !== undefined)
+        sections.push(`- Equity: $${s.equity.toLocaleString()}`);
+    if (s.equityPercent !== undefined)
+        sections.push(`- Equity Percent: ${s.equityPercent.toFixed(1)}%`);
+    if (s.ltv !== undefined)
+        sections.push(`- LTV: ${s.ltv.toFixed(1)}%`);
+    if (s.salePropensity !== undefined)
+        sections.push(`- Sale Propensity: ${s.salePropensity}% (${s.salePropensityCategory || "Unknown"})`);
+    if (s.propertyType)
+        sections.push(`- Property Type: ${s.propertyType}`);
+    if (s.yearBuilt)
+        sections.push(`- Year Built: ${s.yearBuilt}`);
+    if (s.sqft)
+        sections.push(`- Square Feet: ${s.sqft.toLocaleString()}`);
+    if (s.bedrooms !== undefined)
+        sections.push(`- Bedrooms: ${s.bedrooms}`);
+    if (s.bathrooms !== undefined)
+        sections.push(`- Bathrooms: ${s.bathrooms}`);
+    if (s.ownerName)
+        sections.push(`- Owner: ${s.ownerName}`);
+    if (s.ownerType)
+        sections.push(`- Owner Type: ${s.ownerType}`);
+    if (s.permitCount)
+        sections.push(`- Permit Count: ${s.permitCount}`);
+    if (s.ownerPortfolioSize)
+        sections.push(`- Owner Portfolio Size: ${s.ownerPortfolioSize} properties`);
+    // Motivation signals
+    if (context.motivationSignals.length > 0) {
+        sections.push("", "## Motivation Signals");
+        for (const signal of context.motivationSignals) {
+            sections.push(`- ${signal}`);
+        }
+    }
+    // Investment considerations
+    if (context.considerations.length > 0) {
+        sections.push("", "## Investment Considerations");
+        for (const consideration of context.considerations) {
+            sections.push(`- ${consideration}`);
+        }
+    }
+    return sections.join("\n");
+}
+/**
+ * Get domain descriptions for AI context
+ * @param domainNames Optional list of domains to include
+ * @returns Formatted domain descriptions
+ */
+function getPropertyDomainDescriptions(domainNames) {
+    const selectedDomains = domainNames
+        ? exports.PROPERTY_DATA_DOMAINS.filter((d) => domainNames.includes(d.name))
+        : exports.PROPERTY_DATA_DOMAINS;
+    const lines = ["## Property Data Domains", ""];
+    for (const domain of selectedDomains) {
+        lines.push(`**${domain.name}**: ${domain.description}`);
+        lines.push(`  Investment Relevance: ${domain.investmentRelevance}`);
+        lines.push("");
+    }
+    return lines.join("\n");
+}

package/package.json

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