@land-catalyst/batch-data-sdk 1.3.2 → 1.3.3

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export * from "./client/client.interface";
 export * from "./core/logger.interface";
 export * from "./property-field/metadata";
 export * from "./property-field/utils";
+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";

package/dist/index.js

@@ -28,5 +28,6 @@ __exportStar(require("./client/client.interface"), exports);
 __exportStar(require("./core/logger.interface"), exports);
 __exportStar(require("./property-field/metadata"), exports);
 __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);

package/dist/property-field/display.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Property Field Display Utilities
+ *
+ * Utilities for formatting property field values for display in the UI.
+ * These helpers take raw property data and field metadata and produce
+ * human-readable formatted strings.
+ */
+import type { Property } from "../core/types";
+import { type PropertyFieldMetadata, type PropertyFieldType } from "./metadata";
+/**
+ * Display field entry for rendering property data
+ */
+export interface PropertyDisplayField {
+    /** The field path (e.g., "building.yearBuilt") */
+    fieldPath: string;
+    /** Human-readable label */
+    label: string;
+    /** Formatted display value */
+    value: string;
+    /** The field's data type */
+    dataType: PropertyFieldType;
+}
+/**
+ * Format a property field value based on its metadata
+ *
+ * @param value The raw field value
+ * @param metadata The field's metadata
+ * @returns Formatted display string, or empty string for null/undefined
+ *
+ * @example
+ * ```typescript
+ * const meta = getPropertyFieldMetadata("valuation.estimatedValue");
+ * formatPropertyFieldValue(450000, meta); // "$450,000"
+ *
+ * const yearMeta = getPropertyFieldMetadata("building.yearBuilt");
+ * formatPropertyFieldValue(1985, yearMeta); // "1985"
+ * ```
+ */
+export declare function formatPropertyFieldValue(value: unknown, metadata: PropertyFieldMetadata): string;
+/**
+ * Get the display label for a property field path
+ *
+ * @param fieldPath The field path (e.g., "building.yearBuilt")
+ * @returns Human-readable label (e.g., "Year Built")
+ *
+ * @example
+ * ```typescript
+ * getPropertyFieldDisplayLabel("building.yearBuilt"); // "Year Built"
+ * getPropertyFieldDisplayLabel("owner.mailingAddress.city"); // "City"
+ * ```
+ */
+export declare function getPropertyFieldDisplayLabel(fieldPath: string): string;
+/**
+ * Get the display name for a property response group
+ *
+ * @param groupName The group name (e.g., "building", "propertyOwnerProfile")
+ * @returns Human-readable display name (e.g., "Building", "Owner Portfolio")
+ *
+ * @example
+ * ```typescript
+ * getPropertyGroupDisplayName("building"); // "Building"
+ * getPropertyGroupDisplayName("propertyOwnerProfile"); // "Owner Portfolio"
+ * ```
+ */
+export declare function getPropertyGroupDisplayName(groupName: string): string;
+/**
+ * Get all displayable fields for a property within a specific group
+ *
+ * Returns formatted field data for rendering in the UI. Fields with
+ * null/undefined values are excluded.
+ *
+ * @param property The property object (can be raw BatchData JSON)
+ * @param groupName The response group name (e.g., "building", "valuation")
+ * @returns Array of display field objects with label, formatted value, etc.
+ *
+ * @example
+ * ```typescript
+ * const buildingFields = getPropertyFieldsForDisplay(property, "building");
+ * // Returns:
+ * // [
+ * //   { fieldPath: "building.yearBuilt", label: "Year Built", value: "1985", dataType: "number" },
+ * //   { fieldPath: "building.bedrooms", label: "Bedrooms", value: "3", dataType: "number" },
+ * //   ...
+ * // ]
+ * ```
+ */
+export declare function getPropertyFieldsForDisplay(property: Property | Record<string, unknown>, groupName: string): PropertyDisplayField[];
+/**
+ * Get all response groups that have displayable data in a property
+ *
+ * @param property The property object
+ * @returns Array of group names that have at least one displayable field
+ *
+ * @example
+ * ```typescript
+ * const groups = getPropertyGroupsWithData(property);
+ * // Returns: ["address", "building", "valuation", "owner", ...]
+ * ```
+ */
+export declare function getPropertyGroupsWithData(property: Property | Record<string, unknown>): string[];

package/dist/property-field/display.js

@@ -0,0 +1,338 @@
+"use strict";
+/**
+ * Property Field Display Utilities
+ *
+ * Utilities for formatting property field values for display in the UI.
+ * These helpers take raw property data and field metadata and produce
+ * human-readable formatted strings.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatPropertyFieldValue = formatPropertyFieldValue;
+exports.getPropertyFieldDisplayLabel = getPropertyFieldDisplayLabel;
+exports.getPropertyGroupDisplayName = getPropertyGroupDisplayName;
+exports.getPropertyFieldsForDisplay = getPropertyFieldsForDisplay;
+exports.getPropertyGroupsWithData = getPropertyGroupsWithData;
+const metadata_1 = require("./metadata");
+const utils_1 = require("./utils");
+/**
+ * Group display name mappings
+ */
+const GROUP_DISPLAY_NAMES = {
+    address: "Address",
+    assessment: "Assessment",
+    building: "Building",
+    deedHistory: "Deed History",
+    demographics: "Demographics",
+    foreclosure: "Foreclosure",
+    general: "General",
+    ids: "Identifiers",
+    intel: "Intel",
+    involuntaryLien: "Involuntary Liens",
+    legal: "Legal",
+    listing: "Listing",
+    lot: "Lot",
+    meta: "Meta",
+    mortgageHistory: "Mortgage History",
+    openLien: "Open Liens",
+    owner: "Owner",
+    permit: "Permits",
+    propertyOwnerProfile: "Owner Portfolio",
+    quickLists: "Quick Lists",
+    sale: "Sale History",
+    tax: "Tax",
+    valuation: "Valuation",
+};
+/**
+ * Convert a field name to a display label
+ * Handles camelCase and common abbreviations
+ */
+function fieldNameToLabel(name) {
+    // Handle common abbreviations
+    const abbrevs = {
+        sqft: "Sq Ft",
+        apn: "APN",
+        adu: "ADU",
+        avm: "AVM",
+        hoa: "HOA",
+        id: "ID",
+        mls: "MLS",
+        url: "URL",
+    };
+    const lower = name.toLowerCase();
+    if (abbrevs[lower]) {
+        return abbrevs[lower];
+    }
+    // Split camelCase and capitalize
+    return name
+        .replace(/([A-Z])/g, " $1")
+        .replace(/^./, (c) => c.toUpperCase())
+        .trim();
+}
+/**
+ * Format a number as currency (USD)
+ */
+function formatCurrency(value) {
+    return new Intl.NumberFormat("en-US", {
+        style: "currency",
+        currency: "USD",
+        minimumFractionDigits: 0,
+        maximumFractionDigits: 0,
+    }).format(value);
+}
+/**
+ * Format a number with commas
+ */
+function formatNumber(value) {
+    return new Intl.NumberFormat("en-US").format(value);
+}
+/**
+ * Format a date string
+ */
+function formatDate(value) {
+    try {
+        const date = typeof value === "string" ? new Date(value) : value;
+        if (isNaN(date.getTime()))
+            return String(value);
+        return date.toLocaleDateString("en-US", {
+            year: "numeric",
+            month: "short",
+            day: "numeric",
+        });
+    }
+    catch {
+        return String(value);
+    }
+}
+/**
+ * Check if a field name suggests currency formatting
+ */
+function isCurrencyField(fieldPath, name) {
+    const lower = (fieldPath + name).toLowerCase();
+    return (lower.includes("value") ||
+        lower.includes("price") ||
+        lower.includes("assessment") ||
+        lower.includes("amount") ||
+        lower.includes("equity") ||
+        lower.includes("balance") ||
+        lower.includes("cost"));
+}
+/**
+ * Check if a field name suggests year formatting
+ */
+function isYearField(name) {
+    const lower = name.toLowerCase();
+    return lower.includes("year") && !lower.includes("years");
+}
+/**
+ * Check if a field name suggests square footage formatting
+ */
+function isSqftField(name) {
+    const lower = name.toLowerCase();
+    return (lower.includes("sqft") ||
+        lower.includes("area") ||
+        lower.includes("squarefeet"));
+}
+/**
+ * Check if a field name suggests acreage formatting
+ */
+function isAcresField(name) {
+    const lower = name.toLowerCase();
+    return lower.includes("acre") || lower.includes("acreage");
+}
+/**
+ * Format a property field value based on its metadata
+ *
+ * @param value The raw field value
+ * @param metadata The field's metadata
+ * @returns Formatted display string, or empty string for null/undefined
+ *
+ * @example
+ * ```typescript
+ * const meta = getPropertyFieldMetadata("valuation.estimatedValue");
+ * formatPropertyFieldValue(450000, meta); // "$450,000"
+ *
+ * const yearMeta = getPropertyFieldMetadata("building.yearBuilt");
+ * formatPropertyFieldValue(1985, yearMeta); // "1985"
+ * ```
+ */
+function formatPropertyFieldValue(value, metadata) {
+    // Handle null/undefined
+    if (value == null) {
+        return "";
+    }
+    const { dataType, name, fieldPath, possibleValuesRef } = metadata;
+    // Handle boolean
+    if (dataType === "boolean") {
+        return value ? "Yes" : "No";
+    }
+    // Handle date
+    if (dataType === "date") {
+        return formatDate(value);
+    }
+    // Handle array[string]
+    if (dataType === "array[string]") {
+        if (Array.isArray(value)) {
+            return value.filter((v) => v != null).join(", ");
+        }
+        return String(value);
+    }
+    // Handle array[number]
+    if (dataType === "array[number]") {
+        if (Array.isArray(value)) {
+            return value
+                .filter((v) => v != null)
+                .map(formatNumber)
+                .join(", ");
+        }
+        return String(value);
+    }
+    // Handle number with formatting rules
+    if (dataType === "number" && typeof value === "number") {
+        // Year - plain integer
+        if (isYearField(name)) {
+            return String(Math.round(value));
+        }
+        // Currency fields
+        if (isCurrencyField(fieldPath, name)) {
+            return formatCurrency(value);
+        }
+        // Square footage
+        if (isSqftField(name)) {
+            return `${formatNumber(Math.round(value))} sq ft`;
+        }
+        // Acreage
+        if (isAcresField(name)) {
+            return `${value.toFixed(2)} acres`;
+        }
+        // Default number formatting
+        if (Number.isInteger(value)) {
+            return formatNumber(value);
+        }
+        return value.toFixed(2);
+    }
+    // Handle string with possibleValues lookup
+    if (dataType === "string" && typeof value === "string") {
+        // If there's a possibleValuesRef, the value itself is usually the display value
+        // in POSSIBLE_VALUES_CONSTANTS (they're already human-readable)
+        if (possibleValuesRef) {
+            const possibleValues = metadata_1.POSSIBLE_VALUES_CONSTANTS[possibleValuesRef];
+            if (possibleValues?.includes(value)) {
+                return value; // Already display-friendly
+            }
+        }
+        return value;
+    }
+    // Handle object - just return stringified for now
+    if (dataType === "object" && typeof value === "object") {
+        return JSON.stringify(value);
+    }
+    // Default: convert to string
+    return String(value);
+}
+/**
+ * Get the display label for a property field path
+ *
+ * @param fieldPath The field path (e.g., "building.yearBuilt")
+ * @returns Human-readable label (e.g., "Year Built")
+ *
+ * @example
+ * ```typescript
+ * getPropertyFieldDisplayLabel("building.yearBuilt"); // "Year Built"
+ * getPropertyFieldDisplayLabel("owner.mailingAddress.city"); // "City"
+ * ```
+ */
+function getPropertyFieldDisplayLabel(fieldPath) {
+    const metadata = metadata_1.PROPERTY_FIELD_METADATA[fieldPath];
+    if (metadata) {
+        return fieldNameToLabel(metadata.name);
+    }
+    // Fallback: use the last part of the path
+    const parts = fieldPath.split(".");
+    const last = parts[parts.length - 1] || fieldPath;
+    return fieldNameToLabel(last);
+}
+/**
+ * Get the display name for a property response group
+ *
+ * @param groupName The group name (e.g., "building", "propertyOwnerProfile")
+ * @returns Human-readable display name (e.g., "Building", "Owner Portfolio")
+ *
+ * @example
+ * ```typescript
+ * getPropertyGroupDisplayName("building"); // "Building"
+ * getPropertyGroupDisplayName("propertyOwnerProfile"); // "Owner Portfolio"
+ * ```
+ */
+function getPropertyGroupDisplayName(groupName) {
+    return GROUP_DISPLAY_NAMES[groupName] || fieldNameToLabel(groupName);
+}
+/**
+ * Get all displayable fields for a property within a specific group
+ *
+ * Returns formatted field data for rendering in the UI. Fields with
+ * null/undefined values are excluded.
+ *
+ * @param property The property object (can be raw BatchData JSON)
+ * @param groupName The response group name (e.g., "building", "valuation")
+ * @returns Array of display field objects with label, formatted value, etc.
+ *
+ * @example
+ * ```typescript
+ * const buildingFields = getPropertyFieldsForDisplay(property, "building");
+ * // Returns:
+ * // [
+ * //   { fieldPath: "building.yearBuilt", label: "Year Built", value: "1985", dataType: "number" },
+ * //   { fieldPath: "building.bedrooms", label: "Bedrooms", value: "3", dataType: "number" },
+ * //   ...
+ * // ]
+ * ```
+ */
+function getPropertyFieldsForDisplay(property, groupName) {
+    const groupFields = (0, utils_1.getPropertyGroupFields)(groupName);
+    const results = [];
+    for (const metadata of groupFields) {
+        // Skip array element placeholders ([n] patterns)
+        if (metadata.isArrayElement)
+            continue;
+        const value = (0, utils_1.getPropertyFieldValue)(property, metadata.fieldPath);
+        // Skip null/undefined values
+        if (value == null)
+            continue;
+        // Skip empty strings
+        if (typeof value === "string" && value.trim() === "")
+            continue;
+        // Skip empty arrays
+        if (Array.isArray(value) && value.length === 0)
+            continue;
+        const formatted = formatPropertyFieldValue(value, metadata);
+        // Skip if formatting returned empty
+        if (!formatted)
+            continue;
+        results.push({
+            fieldPath: metadata.fieldPath,
+            label: getPropertyFieldDisplayLabel(metadata.fieldPath),
+            value: formatted,
+            dataType: metadata.dataType,
+        });
+    }
+    return results;
+}
+/**
+ * Get all response groups that have displayable data in a property
+ *
+ * @param property The property object
+ * @returns Array of group names that have at least one displayable field
+ *
+ * @example
+ * ```typescript
+ * const groups = getPropertyGroupsWithData(property);
+ * // Returns: ["address", "building", "valuation", "owner", ...]
+ * ```
+ */
+function getPropertyGroupsWithData(property) {
+    const allGroups = Object.keys(GROUP_DISPLAY_NAMES);
+    return allGroups.filter((group) => {
+        const fields = getPropertyFieldsForDisplay(property, group);
+        return fields.length > 0;
+    });
+}

package/package.json

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