@land-catalyst/batch-data-sdk 1.1.12 → 1.1.19

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

@@ -0,0 +1,33 @@
+/**
+ * Property Field Type Utilities
+ *
+ * Type-level utilities for working with property field paths
+ */
+import type { Property } from "../core/types";
+import type { PropertyFieldMetadata } from "./metadata";
+/**
+ * Extract all possible field paths from Property type
+ * This is a helper type for type-safe field path access
+ */
+export type PropertyFieldPathType = {
+    [K in keyof Property]: K extends string ? Property[K] extends object | undefined ? K | `${K}.${NestedFieldPath<NonNullable<Property[K]>>}` : K : never;
+}[keyof Property];
+type NestedFieldPath<T> = T extends (infer U)[] ? U extends object ? `[n].${NestedFieldPath<U>}` : never : T extends object ? {
+    [K in keyof T]: K extends string ? T[K] extends object | undefined ? K | `${K}.${NestedFieldPath<NonNullable<T[K]>>}` : K : never;
+}[keyof T] : never;
+/**
+ * Get the TypeScript type for a property field path
+ * @template TPath The field path type
+ * @example
+ * ```typescript
+ * type CityType = PropertyFieldValueType<"address.city">; // string | undefined
+ * ```
+ */
+export type PropertyFieldValueType<TPath extends string> = TPath extends `${infer K}.${infer Rest}` ? K extends keyof Property ? Property[K] extends object | undefined ? Rest extends string ? NestedFieldType<NonNullable<Property[K]>, Rest> : never : never : never : TPath extends keyof Property ? Property[TPath] : unknown;
+type NestedFieldType<T, Path extends string> = Path extends `[n].${infer Rest}` ? T extends (infer U)[] ? U extends object ? Rest extends string ? NestedFieldType<U, Rest> : U : U : never : Path extends `${infer K}.${infer Rest}` ? K extends keyof T ? T[K] extends object | undefined ? Rest extends string ? NestedFieldType<NonNullable<T[K]>, Rest> : T[K] : T[K] : never : Path extends keyof T ? T[Path] : unknown;
+/**
+ * Type-safe field metadata lookup
+ * @template TPath The field path
+ */
+export type FieldMetadataForPath<TPath extends string> = TPath extends keyof typeof import("./metadata").PROPERTY_FIELD_METADATA ? (typeof import("./metadata").PROPERTY_FIELD_METADATA)[TPath] : PropertyFieldMetadata | undefined;
+export {};

package/dist/property-field/types.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * Property Field Type Utilities
+ *
+ * Type-level utilities for working with property field paths
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+// Note: PropertyFieldPathType is the main type-safe field path type
+// SimplePropertyFieldPath from property-field-utils provides a simpler alternative

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

@@ -0,0 +1,306 @@
+/**
+ * Property Field Utilities
+ *
+ * Utilities for working with property field paths and metadata
+ */
+import type { Property } from "../core/types";
+import { type PropertyFieldMetadata } from "./metadata";
+/**
+ * Simple property field path type (string union)
+ * For more advanced type-safe paths, use PropertyFieldPathType from property-field-types
+ */
+export type SimplePropertyFieldPath = keyof Property | string;
+/**
+ * Get metadata for a property field by its path
+ * @param fieldPath The field path (e.g., "address.city", "owner.fullName")
+ * @returns The field metadata, or undefined if not found
+ * @example
+ * ```typescript
+ * const cityMeta = getPropertyFieldMetadata("address.city");
+ * console.log(cityMeta?.description); // "The city (e.g. Chicago)"
+ * ```
+ */
+export declare function getPropertyFieldMetadata(fieldPath: string): PropertyFieldMetadata | undefined;
+/**
+ * Get the value at a field path from a property object
+ * @param property The property object
+ * @param fieldPath The field path (e.g., "address.city", "owner.fullName")
+ * @returns The value at the path, or undefined if not found
+ * @example
+ * ```typescript
+ * const city = getPropertyFieldValue(property, "address.city");
+ * ```
+ */
+export declare function getPropertyFieldValue(property: Property, fieldPath: string): unknown;
+/**
+ * Get metadata for all fields in a response group
+ * @param groupName The response group name (e.g., "address", "owner", "building")
+ * @returns Array of field metadata for that group
+ * @example
+ * ```typescript
+ * const addressFields = getPropertyGroupFields("address");
+ * // Returns all fields under address.*
+ * ```
+ */
+export declare function getPropertyGroupFields(groupName: string): PropertyFieldMetadata[];
+/**
+ * Get metadata for a nested field path
+ * Handles nested paths like "owner.mailingAddress.city"
+ * @param fieldPath The full field path
+ * @returns The field metadata, or undefined if not found
+ */
+export declare function getNestedFieldMetadata(fieldPath: string): PropertyFieldMetadata | undefined;
+/**
+ * Type guard to check if a field path exists in metadata
+ * @param fieldPath The field path to check
+ * @returns True if the field exists in metadata
+ */
+export declare function isValidPropertyField(fieldPath: string): boolean;
+/**
+ * Get all field paths for a specific property group
+ * @param groupName The response group name
+ * @returns Array of field paths
+ */
+export declare function getPropertyGroupFieldPaths(groupName: string): string[];
+/**
+ * Get field description for a property field
+ * @param fieldPath The field path
+ * @returns The description, or undefined if not found
+ */
+export declare function getPropertyFieldDescription(fieldPath: string): string | undefined;
+/**
+ * Get field data type for a property field
+ * @param fieldPath The field path
+ * @returns The data type, or undefined if not found
+ */
+export declare function getPropertyFieldType(fieldPath: string): PropertyFieldMetadata["dataType"] | undefined;
+/**
+ * SearchCriteria field metadata inferred from Property field metadata
+ * This helps users understand what Property field they're filtering on
+ */
+export interface SearchCriteriaFieldMetadata {
+    /**
+     * The SearchCriteria field path (e.g., "address.city", "building.yearBuilt")
+     */
+    searchCriteriaPath: string;
+    /**
+     * The corresponding Property field path, if found
+     */
+    propertyPath: string | undefined;
+    /**
+     * The Property field metadata, if found
+     */
+    propertyMetadata: PropertyFieldMetadata | undefined;
+    /**
+     * Whether this SearchCriteria field has a corresponding Property field
+     */
+    hasPropertyMapping: boolean;
+    /**
+     * Description for the SearchCriteria field (inferred from Property metadata)
+     * Explains what Property field is being filtered on
+     */
+    description: string;
+    /**
+     * The data type of the Property field being filtered (e.g., "string", "number")
+     */
+    propertyDataType: string | undefined;
+    /**
+     * The dataset the Property field belongs to
+     */
+    dataset: string | undefined;
+}
+/**
+ * Map a SearchCriteria field path to its corresponding Property field path
+ * Most SearchCriteria fields map directly to Property fields (e.g., "address.city" -> "address.city")
+ * @param searchCriteriaPath The field path in SearchCriteria (e.g., "address.city", "building.yearBuilt")
+ * @returns The corresponding Property field path, or undefined if no mapping exists
+ * @example
+ * ```typescript
+ * const propertyPath = mapSearchCriteriaToPropertyPath("address.city");
+ * // Returns "address.city"
+ *
+ * const propertyPath = mapSearchCriteriaToPropertyPath("building.yearBuilt");
+ * // Returns "building.yearBuilt"
+ * ```
+ */
+export declare function mapSearchCriteriaToPropertyPath(searchCriteriaPath: string): string | undefined;
+/**
+ * Get Property field metadata for a SearchCriteria field path
+ * This helps users understand what Property field they're filtering on
+ * @param searchCriteriaPath The field path in SearchCriteria (e.g., "address.city", "building.yearBuilt")
+ * @returns The Property field metadata, or undefined if not found
+ * @example
+ * ```typescript
+ * // When building a search criteria, see what Property field you're filtering on
+ * const metadata = getSearchCriteriaFieldMetadata("address.city");
+ * console.log(metadata?.description); // "The city (e.g. Chicago)"
+ * console.log(metadata?.dataType); // "string"
+ *
+ * const builder = new AddressSearchCriteriaBuilder();
+ * builder.city((c) => {
+ *   // You're filtering on Property.address.city
+ *   const meta = getSearchCriteriaFieldMetadata("address.city");
+ *   console.log(`Filtering on: ${meta?.description}`);
+ *   c.equals("Phoenix");
+ * });
+ * ```
+ */
+export declare function getSearchCriteriaFieldMetadata(searchCriteriaPath: string): PropertyFieldMetadata | undefined;
+/**
+ * Get SearchCriteria field metadata inferred from Property field metadata
+ * This creates a SearchCriteria-specific metadata object that references the Property field
+ * @param searchCriteriaPath The field path in SearchCriteria (e.g., "address.city", "building.yearBuilt")
+ * @returns SearchCriteria field metadata with Property field information
+ * @example
+ * ```typescript
+ * // Get metadata for a SearchCriteria field, even if it doesn't map exactly
+ * const scMetadata = getSearchCriteriaMetadata("address.city");
+ * console.log(scMetadata.description); // "Filter on: The city (e.g. Chicago)"
+ * console.log(scMetadata.propertyPath); // "address.city"
+ * console.log(scMetadata.hasPropertyMapping); // true
+ *
+ * // Works even for fields that might not have exact Property mappings
+ * const scMetadata2 = getSearchCriteriaMetadata("assessment.assessmentYear");
+ * if (scMetadata2.hasPropertyMapping) {
+ *   console.log(`Filtering on: ${scMetadata2.propertyMetadata?.description}`);
+ * }
+ * ```
+ */
+export declare function getSearchCriteriaMetadata(searchCriteriaPath: string): SearchCriteriaFieldMetadata;
+/**
+ * Get all SearchCriteria field paths that map to a specific Property response group
+ * @param propertyGroupName The Property response group name (e.g., "address", "owner", "building")
+ * @returns Array of SearchCriteria field paths that filter on fields in that group
+ * @example
+ * ```typescript
+ * // Get all SearchCriteria fields that filter on address fields
+ * const addressSearchFields = getSearchCriteriaFieldsForPropertyGroup("address");
+ * // Returns: ["address.street", "address.city", "address.state", ...]
+ * ```
+ */
+export declare function getSearchCriteriaFieldsForPropertyGroup(propertyGroupName: string): string[];
+/**
+ * Get metadata for all SearchCriteria fields that correspond to a Property response group
+ * @param propertyGroupName The Property response group name (e.g., "address", "owner", "building")
+ * @returns Array of objects containing both the SearchCriteria path and its Property metadata
+ * @example
+ * ```typescript
+ * // Get all address-related SearchCriteria fields with their metadata
+ * const addressFields = getSearchCriteriaFieldsWithMetadata("address");
+ * // Returns: [
+ * //   { searchCriteriaPath: "address.city", metadata: {...}, propertyPath: "address.city" },
+ * //   { searchCriteriaPath: "address.street", metadata: {...}, propertyPath: "address.street" },
+ * //   ...
+ * // ]
+ * ```
+ */
+export interface SearchCriteriaFieldMapping {
+    /**
+     * The field path in SearchCriteria
+     */
+    searchCriteriaPath: string;
+    /**
+     * The corresponding Property field path
+     */
+    propertyPath: string;
+    /**
+     * The Property field metadata
+     */
+    metadata: PropertyFieldMetadata;
+}
+export declare function getSearchCriteriaFieldsWithMetadata(propertyGroupName: string): SearchCriteriaFieldMapping[];
+/**
+ * Get SearchCriteria metadata for all fields in a Property response group
+ * @param propertyGroupName The Property response group name (e.g., "address", "owner", "building")
+ * @returns Array of SearchCriteria field metadata objects
+ * @example
+ * ```typescript
+ * // Get all address-related SearchCriteria fields with inferred metadata
+ * const addressFields = getSearchCriteriaMetadataForGroup("address");
+ * // Returns SearchCriteriaFieldMetadata[] with descriptions like
+ * // "Filter on: The city (e.g. Chicago)"
+ * ```
+ */
+export declare function getSearchCriteriaMetadataForGroup(propertyGroupName: string): SearchCriteriaFieldMetadata[];
+/**
+ * Extract all field paths from a SearchCriteria object
+ * Recursively walks through the SearchCriteria structure and collects all field paths
+ * @param searchCriteria The SearchCriteria object to analyze
+ * @param prefix Optional prefix for nested paths (used internally for recursion)
+ * @returns Array of field paths found in the SearchCriteria
+ * @example
+ * ```typescript
+ * const criteria = {
+ *   address: { city: { equals: "Phoenix" }, state: { equals: "AZ" } },
+ *   building: { yearBuilt: { min: 1990, max: 2020 } }
+ * };
+ * const paths = extractSearchCriteriaFieldPaths(criteria);
+ * // Returns: ["address.city", "address.state", "building.yearBuilt"]
+ * ```
+ */
+export declare function extractSearchCriteriaFieldPaths(searchCriteria: Record<string, unknown>, prefix?: string): string[];
+/**
+ * Get metadata for all fields present in a SearchCriteria object
+ * Extracts all field paths and generates metadata for each one
+ * @param searchCriteria The SearchCriteria object to analyze
+ * @returns Array of SearchCriteria field metadata for all fields found
+ * @example
+ * ```typescript
+ * const criteria = new SearchCriteriaBuilder("US")
+ *   .address((a) => {
+ *     a.city((c) => c.equals("Phoenix"))
+ *       .state((s) => s.equals("AZ"));
+ *   })
+ *   .building((b) => {
+ *     b.yearBuilt((y) => y.min(1990).max(2020));
+ *   })
+ *   .build();
+ *
+ * const metadata = getSearchCriteriaFieldsMetadata(criteria);
+ * // Returns metadata for address.city, address.state, building.yearBuilt
+ * ```
+ */
+export declare function getSearchCriteriaFieldsMetadata(searchCriteria: Record<string, unknown>): SearchCriteriaFieldMetadata[];
+/**
+ * Field metadata entry for a property object
+ */
+export interface PropertyFieldMetadataEntry {
+    /**
+     * The field path (e.g., "address.city", "owner.fullName")
+     */
+    fieldPath: string;
+    /**
+     * The actual value at this path in the property object
+     */
+    value: unknown;
+    /**
+     * The metadata for this field, if available
+     */
+    metadata: PropertyFieldMetadata | undefined;
+    /**
+     * Whether this field has metadata available
+     */
+    hasMetadata: boolean;
+}
+/**
+ * Get metadata for all fields present in a property object
+ * Recursively iterates through the property object and collects metadata for each field.
+ *
+ * Note: This function is designed for Property response objects, not SearchCriteria.
+ * The metadata describes Property response fields (their types, descriptions, datasets),
+ * which are different from SearchCriteria filter objects.
+ *
+ * @param property The property object to analyze
+ * @param prefix Optional prefix for nested paths (used internally for recursion)
+ * @returns Array of field metadata entries
+ * @example
+ * ```typescript
+ * const property = {
+ *   address: { city: "Phoenix", state: "AZ" },
+ *   owner: { fullName: "John Doe" }
+ * };
+ * const metadata = getPropertyFieldsMetadata(property);
+ * // Returns metadata for address.city, address.state, owner.fullName
+ * ```
+ */
+export declare function getPropertyFieldsMetadata(property: Property | Partial<Property>, prefix?: string): PropertyFieldMetadataEntry[];