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

package/dist/builders/builders.d.ts

@@ -16,7 +16,7 @@
  *   .build();
  * ```
  */
-import { StringFilter, NumericRangeFilter, DateRangeFilter, GeoLocationDistance, GeoLocationBoundingBox, GeoLocationPolygon, AddressSearchCriteria, AssessmentSearchCriteria, BuildingSearchCriteria, CompAddressSearchCriteria, DemographicsSearchCriteria, ForeclosureSearchCriteria, GeneralSearchCriteria, IdsSearchCriteria, IntelSearchCriteria, InvoluntaryLienSearchCriteria, LegalSearchCriteria, ListingSearchCriteria, LotSearchCriteria, OpenLienSearchCriteria, OwnerSearchCriteria, PermitSearchCriteria, PropertyOwnerProfileSearchCriteria, SaleSearchCriteria, TaxSearchCriteria, ValuationSearchCriteria, OrSearchCriteria, SearchCriteria, DeliveryConfig, EventHubConfig, PropertySubscriptionRequest, QuickListValueWithNot, PropertyLookupRequest, PropertyLookupRequestItem, PropertyLookupRequestAddress, PropertyLookupOptions, PropertyPermitRequest, PropertyCountRequest, PropertySearchRequest, PropertySearchAsyncRequest, PropertyLookupAsyncRequest, GeoPoint, AirConditioningSource, BasementType, BuildingClass, BuildingCondition, BuildingQuality, ConstructionType, Driveway, ExteriorWalls, FloorCover, Garage, HeatSource, HeatingFuelType, InteriorWalls, Patio, Pool, Porch, RoofCover, RoofType, Sewer, Style, WaterService, Features, HomeownerRenter, BusinessOwner, Gender, Investments, DemographicsValue, ReligiousAffiliation, ForeclosureStatus, PropertyTypeCategory, PropertyTypeDetail, LienType, LienTypeCode, LoanType, OwnerStatusType, LastSaleDocumentType, ZoningCode } from "../core/types";
+import { StringFilter, NumericRangeFilter, DateRangeFilter, GeoLocationDistance, GeoLocationBoundingBox, GeoLocationPolygon, AddressSearchCriteria, AssessmentSearchCriteria, BuildingSearchCriteria, CompAddressSearchCriteria, DemographicsSearchCriteria, ForeclosureSearchCriteria, GeneralSearchCriteria, IdsSearchCriteria, IntelSearchCriteria, InvoluntaryLienSearchCriteria, LegalSearchCriteria, ListingSearchCriteria, LotSearchCriteria, OpenLienSearchCriteria, OwnerSearchCriteria, PermitSearchCriteria, PropertyOwnerProfileSearchCriteria, SaleSearchCriteria, TaxSearchCriteria, ValuationSearchCriteria, OrSearchCriteria, SearchCriteria, DeliveryConfig, EventHubConfig, PropertySubscriptionRequest, QuickListValueWithNot, PropertyLookupRequest, PropertyLookupRequestItem, PropertyLookupRequestAddress, PropertyLookupOptions, PropertyPermitRequest, PropertyCountRequest, PropertySearchRequest, PropertySearchAsyncRequest, PropertyLookupAsyncRequest, RequestWithLookupOptions, RequestWithSearchCriteria, GeoPoint, AirConditioningSource, BasementType, BuildingClass, BuildingCondition, BuildingQuality, ConstructionType, Driveway, ExteriorWalls, FloorCover, Garage, HeatSource, HeatingFuelType, InteriorWalls, Patio, Pool, Porch, RoofCover, RoofType, Sewer, Style, WaterService, Features, HomeownerRenter, BusinessOwner, Gender, Investments, DemographicsValue, ReligiousAffiliation, ForeclosureStatus, PropertyTypeCategory, PropertyTypeDetail, LienType, LienTypeCode, LoanType, OwnerStatusType, LastSaleDocumentType, ZoningCode } from "../core/types";
 import type { PropertyFieldMetadata } from "../property-field/metadata";
 /**
  * Base interface for all builders
@@ -145,6 +145,79 @@ declare abstract class BaseBuilder<T> implements Builder<T> {
     protected setPropertyWithBuilderClass<K extends keyof T, B extends Builder<T[K]>>(key: K, valueOrConfigurator: T[K] | ((builder: B) => void), BuilderClass: new () => B): this;
     build(): T;
 }
+/**
+ * Base class for builders that work with RequestWithLookupOptions types.
+ * Provides the common `options` method implementation.
+ *
+ * Builders that work with requests that have PropertyLookupOptions should extend
+ * this class instead of BaseBuilder directly.
+ */
+export declare abstract class RequestWithLookupOptionsBuilder<T extends RequestWithLookupOptions> extends BaseBuilder<T> {
+    /**
+     * Set PropertyLookupOptions either directly or via a builder configurator.
+     *
+     * @param optionsOrConfigurator - Either the direct options object or a configurator function
+     * @returns This builder instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * // Direct value
+     * builder.options({ take: 10, skip: 0 });
+     *
+     * // Builder configurator
+     * builder.options((opts) => {
+     *   opts.take(10).skip(0).skipTrace(true);
+     * });
+     * ```
+     */
+    options(options: PropertyLookupOptions): this;
+    options(configurator: (builder: PropertyLookupOptionsBuilder) => void): this;
+    /**
+     * Helper method to build options into a request object.
+     * This is used by subclasses in their build() methods.
+     *
+     * @param request - The request object being built
+     * @returns The request object with options applied (if any)
+     */
+    protected buildOptionsIntoRequest<R extends RequestWithLookupOptions>(request: R): R;
+}
+/**
+ * Base class for builders that work with RequestWithSearchCriteria types.
+ * Provides the common `searchCriteria` and `options` method implementations.
+ *
+ * Builders that work with requests that have both searchCriteria and options
+ * should extend this class instead of RequestWithLookupOptionsBuilder directly.
+ */
+export declare abstract class RequestWithSearchCriteriaBuilder<T extends RequestWithSearchCriteria> extends RequestWithLookupOptionsBuilder<T> {
+    /**
+     * Set SearchCriteria either directly or via a builder configurator.
+     *
+     * @param criteriaOrConfigurator - Either the direct SearchCriteria object or a configurator function
+     * @returns This builder instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * // Direct value
+     * builder.searchCriteria({ query: "123 Main St" });
+     *
+     * // Builder configurator
+     * builder.searchCriteria((sc) => {
+     *   sc.address((addr) => {
+     *     addr.street("Main St").city("Phoenix").state("AZ");
+     *   });
+     * });
+     * ```
+     */
+    searchCriteria(criteria: SearchCriteria): this;
+    searchCriteria(configurator: (builder: SearchCriteriaBuilder) => void): this;
+    /**
+     * Helper method to validate that searchCriteria is present in build() methods.
+     * Throws an error if searchCriteria is missing.
+     *
+     * @throws Error if searchCriteria is not set
+     */
+    protected validateSearchCriteria(): void;
+}
 /**
  * Base builder for string filters
  * @template T - Optional union type of allowed string values. Defaults to `string` for backward compatibility.
@@ -743,10 +816,8 @@ export declare class DeliveryConfigBuilder {
 /**
  * Main builder for property subscription requests
  */
-export declare class PropertySubscriptionBuilder extends BaseBuilder<PropertySubscriptionRequest> {
+export declare class PropertySubscriptionBuilder extends RequestWithSearchCriteriaBuilder<PropertySubscriptionRequest> {
     static from(request: PropertySubscriptionRequest): PropertySubscriptionBuilder;
-    searchCriteria(criteria: SearchCriteria): this;
-    searchCriteria(configurator: (builder: SearchCriteriaBuilder) => void): this;
     deliveryConfig(config: DeliveryConfig): this;
     deliveryConfig(configurator: (builder: DeliveryConfigBuilder) => void): this;
     build(): PropertySubscriptionRequest;
@@ -805,14 +876,12 @@ export declare class AsyncPropertyLookupOptionsBuilder extends PropertyLookupOpt
 /**
  * Builder for property lookup requests
  */
-export declare class PropertyLookupRequestBuilder extends BaseBuilder<PropertyLookupRequest> {
+export declare class PropertyLookupRequestBuilder extends RequestWithLookupOptionsBuilder<PropertyLookupRequest> {
     private requestItems;
     static from(request: PropertyLookupRequest): PropertyLookupRequestBuilder;
     items(items: PropertyLookupRequestItem[]): this;
     addItem(item: PropertyLookupRequestItem): this;
     addItemBuilder(builder: PropertyLookupRequestItemBuilder): this;
-    options(options: PropertyLookupOptions): this;
-    options(configurator: (builder: PropertyLookupOptionsBuilder) => void): this;
     build(): PropertyLookupRequest;
 }
 /**
@@ -829,36 +898,26 @@ export declare class PropertyCountRequestBuilder extends BaseBuilder<PropertyCou
 /**
  * Builder for property search requests
  */
-export declare class PropertySearchRequestBuilder extends BaseBuilder<PropertySearchRequest> {
+export declare class PropertySearchRequestBuilder extends RequestWithSearchCriteriaBuilder<PropertySearchRequest> {
     static from(request: PropertySearchRequest): PropertySearchRequestBuilder;
-    searchCriteria(criteria: SearchCriteria): this;
-    searchCriteria(configurator: (builder: SearchCriteriaBuilder) => void): this;
-    options(options: PropertyLookupOptions): this;
-    options(configurator: (builder: PropertyLookupOptionsBuilder) => void): this;
     build(): PropertySearchRequest;
 }
 /**
  * Builder for property search async requests
  */
-export declare class PropertySearchAsyncRequestBuilder extends BaseBuilder<PropertySearchAsyncRequest> {
+export declare class PropertySearchAsyncRequestBuilder extends RequestWithSearchCriteriaBuilder<PropertySearchAsyncRequest> {
     static from(request: PropertySearchAsyncRequest): PropertySearchAsyncRequestBuilder;
-    searchCriteria(criteria: SearchCriteria): this;
-    searchCriteria(configurator: (builder: SearchCriteriaBuilder) => void): this;
-    options(options: PropertyLookupOptions): this;
-    options(configurator: (builder: PropertyLookupOptionsBuilder) => void): this;
     build(): PropertySearchAsyncRequest;
 }
 /**
  * Builder for property lookup async requests
  */
-export declare class PropertyLookupAsyncRequestBuilder extends BaseBuilder<PropertyLookupAsyncRequest> {
+export declare class PropertyLookupAsyncRequestBuilder extends RequestWithLookupOptionsBuilder<PropertyLookupAsyncRequest> {
     private requestItems;
     static from(request: PropertyLookupAsyncRequest): PropertyLookupAsyncRequestBuilder;
     items(items: PropertyLookupRequestItem[]): this;
     addItem(item: PropertyLookupRequestItem): this;
     addItemBuilder(builder: PropertyLookupRequestItemBuilder): this;
-    options(options: PropertyLookupOptions): this;
-    options(configurator: (builder: PropertyLookupOptionsBuilder) => void): this;
     build(): PropertyLookupAsyncRequest;
 }
 /**

package/dist/builders/builders.js

@@ -18,7 +18,7 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PropertyPermitRequestBuilder = exports.PropertyLookupAsyncRequestBuilder = exports.PropertySearchAsyncRequestBuilder = exports.PropertySearchRequestBuilder = exports.PropertyCountRequestBuilder = exports.PropertyLookupRequestBuilder = exports.AsyncPropertyLookupOptionsBuilder = exports.PropertyLookupOptionsBuilder = exports.PropertyLookupRequestItemBuilder = exports.PropertySubscriptionBuilder = exports.DeliveryConfigBuilder = exports.SearchCriteriaBuilder = exports.OrSearchCriteriaBuilder = exports.ValuationSearchCriteriaBuilder = exports.TaxSearchCriteriaBuilder = exports.SaleSearchCriteriaBuilder = exports.PropertyOwnerProfileSearchCriteriaBuilder = exports.PermitSearchCriteriaBuilder = exports.OwnerSearchCriteriaBuilder = exports.OpenLienSearchCriteriaBuilder = exports.LotSearchCriteriaBuilder = exports.ListingSearchCriteriaBuilder = exports.LegalSearchCriteriaBuilder = exports.InvoluntaryLienSearchCriteriaBuilder = exports.IntelSearchCriteriaBuilder = exports.IdsSearchCriteriaBuilder = exports.GeneralSearchCriteriaBuilder = exports.ForeclosureSearchCriteriaBuilder = exports.DemographicsSearchCriteriaBuilder = exports.CompAddressSearchCriteriaBuilder = exports.BuildingSearchCriteriaBuilder = exports.AssessmentSearchCriteriaBuilder = exports.AddressSearchCriteriaBuilder = exports.GeoLocationFactory = exports.DateRangeFilterBuilder = exports.NumericRangeFilterBuilder = exports.StringFilterBuilder = void 0;
+exports.PropertyPermitRequestBuilder = exports.PropertyLookupAsyncRequestBuilder = exports.PropertySearchAsyncRequestBuilder = exports.PropertySearchRequestBuilder = exports.PropertyCountRequestBuilder = exports.PropertyLookupRequestBuilder = exports.AsyncPropertyLookupOptionsBuilder = exports.PropertyLookupOptionsBuilder = exports.PropertyLookupRequestItemBuilder = exports.PropertySubscriptionBuilder = exports.DeliveryConfigBuilder = exports.SearchCriteriaBuilder = exports.OrSearchCriteriaBuilder = exports.ValuationSearchCriteriaBuilder = exports.TaxSearchCriteriaBuilder = exports.SaleSearchCriteriaBuilder = exports.PropertyOwnerProfileSearchCriteriaBuilder = exports.PermitSearchCriteriaBuilder = exports.OwnerSearchCriteriaBuilder = exports.OpenLienSearchCriteriaBuilder = exports.LotSearchCriteriaBuilder = exports.ListingSearchCriteriaBuilder = exports.LegalSearchCriteriaBuilder = exports.InvoluntaryLienSearchCriteriaBuilder = exports.IntelSearchCriteriaBuilder = exports.IdsSearchCriteriaBuilder = exports.GeneralSearchCriteriaBuilder = exports.ForeclosureSearchCriteriaBuilder = exports.DemographicsSearchCriteriaBuilder = exports.CompAddressSearchCriteriaBuilder = exports.BuildingSearchCriteriaBuilder = exports.AssessmentSearchCriteriaBuilder = exports.AddressSearchCriteriaBuilder = exports.GeoLocationFactory = exports.DateRangeFilterBuilder = exports.NumericRangeFilterBuilder = exports.StringFilterBuilder = exports.RequestWithSearchCriteriaBuilder = exports.RequestWithLookupOptionsBuilder = void 0;
 const metadata_1 = require("../property-field/metadata");
 const utils_1 = require("../property-field/utils");
 /**
@@ -164,6 +164,69 @@ class BaseBuilder {
         return result;
     }
 }
+/**
+ * Base class for builders that work with RequestWithLookupOptions types.
+ * Provides the common `options` method implementation.
+ *
+ * Builders that work with requests that have PropertyLookupOptions should extend
+ * this class instead of BaseBuilder directly.
+ */
+class RequestWithLookupOptionsBuilder extends BaseBuilder {
+    options(optionsOrConfigurator) {
+        return this.setPropertyWithBuilderClass("options", optionsOrConfigurator, PropertyLookupOptionsBuilder);
+    }
+    /**
+     * Helper method to build options into a request object.
+     * This is used by subclasses in their build() methods.
+     *
+     * @param request - The request object being built
+     * @returns The request object with options applied (if any)
+     */
+    buildOptionsIntoRequest(request) {
+        if (this.builders.options) {
+            request.options = this.builders.options.build();
+        }
+        else if (this.criteria.options) {
+            request.options = this.criteria.options;
+        }
+        return request;
+    }
+}
+exports.RequestWithLookupOptionsBuilder = RequestWithLookupOptionsBuilder;
+/**
+ * Base class for builders that work with RequestWithSearchCriteria types.
+ * Provides the common `searchCriteria` and `options` method implementations.
+ *
+ * Builders that work with requests that have both searchCriteria and options
+ * should extend this class instead of RequestWithLookupOptionsBuilder directly.
+ */
+class RequestWithSearchCriteriaBuilder extends RequestWithLookupOptionsBuilder {
+    searchCriteria(criteriaOrConfigurator) {
+        if (typeof criteriaOrConfigurator === "function") {
+            const builder = new SearchCriteriaBuilder("");
+            criteriaOrConfigurator(builder);
+            this.criteria.searchCriteria = builder.build();
+            this.builders.searchCriteria = undefined;
+        }
+        else {
+            this.criteria.searchCriteria = criteriaOrConfigurator;
+            this.builders.searchCriteria = undefined;
+        }
+        return this;
+    }
+    /**
+     * Helper method to validate that searchCriteria is present in build() methods.
+     * Throws an error if searchCriteria is missing.
+     *
+     * @throws Error if searchCriteria is not set
+     */
+    validateSearchCriteria() {
+        if (!this.criteria.searchCriteria) {
+            throw new Error("Search criteria is required");
+        }
+    }
+}
+exports.RequestWithSearchCriteriaBuilder = RequestWithSearchCriteriaBuilder;
 /**
  * Base builder for string filters
  * @template T - Optional union type of allowed string values. Defaults to `string` for backward compatibility.
@@ -2209,25 +2272,15 @@ exports.DeliveryConfigBuilder = DeliveryConfigBuilder;
 /**
  * Main builder for property subscription requests
  */
-class PropertySubscriptionBuilder extends BaseBuilder {
+class PropertySubscriptionBuilder extends RequestWithSearchCriteriaBuilder {
     static from(request) {
         const builder = new PropertySubscriptionBuilder();
         builder.searchCriteria(request.searchCriteria);
         builder.deliveryConfig(request.deliveryConfig);
-        return builder;
-    }
-    searchCriteria(criteriaOrConfigurator) {
-        if (typeof criteriaOrConfigurator === "function") {
-            const builder = new SearchCriteriaBuilder("");
-            criteriaOrConfigurator(builder);
-            this.criteria.searchCriteria = builder.build();
-            this.builders.searchCriteria = undefined;
-        }
-        else {
-            this.criteria.searchCriteria = criteriaOrConfigurator;
-            this.builders.searchCriteria = undefined;
+        if (request.options) {
+            builder.options(request.options);
         }
-        return this;
+        return builder;
     }
     deliveryConfig(configOrConfigurator) {
         if (typeof configOrConfigurator === "function") {
@@ -2243,16 +2296,15 @@ class PropertySubscriptionBuilder extends BaseBuilder {
         return this;
     }
     build() {
-        if (!this.criteria.searchCriteria) {
-            throw new Error("Search criteria is required");
-        }
+        this.validateSearchCriteria();
         if (!this.criteria.deliveryConfig) {
             throw new Error("Delivery configuration is required");
         }
-        return {
+        const request = {
             searchCriteria: this.criteria.searchCriteria,
             deliveryConfig: this.criteria.deliveryConfig,
         };
+        return this.buildOptionsIntoRequest(request);
     }
 }
 exports.PropertySubscriptionBuilder = PropertySubscriptionBuilder;
@@ -2454,7 +2506,7 @@ exports.AsyncPropertyLookupOptionsBuilder = AsyncPropertyLookupOptionsBuilder;
 /**
  * Builder for property lookup requests
  */
-class PropertyLookupRequestBuilder extends BaseBuilder {
+class PropertyLookupRequestBuilder extends RequestWithLookupOptionsBuilder {
     constructor() {
         super(...arguments);
         this.requestItems = [];
@@ -2479,20 +2531,11 @@ class PropertyLookupRequestBuilder extends BaseBuilder {
         this.requestItems.push(builder.build());
         return this;
     }
-    options(optionsOrConfigurator) {
-        return this.setPropertyWithBuilderClass("options", optionsOrConfigurator, PropertyLookupOptionsBuilder);
-    }
     build() {
         const request = {
             requests: this.requestItems,
         };
-        if (this.builders.options) {
-            request.options = this.builders.options.build();
-        }
-        else if (this.criteria.options) {
-            request.options = this.criteria.options;
-        }
-        return request;
+        return this.buildOptionsIntoRequest(request);
     }
 }
 exports.PropertyLookupRequestBuilder = PropertyLookupRequestBuilder;
@@ -2533,7 +2576,7 @@ exports.PropertyCountRequestBuilder = PropertyCountRequestBuilder;
 /**
  * Builder for property search requests
  */
-class PropertySearchRequestBuilder extends BaseBuilder {
+class PropertySearchRequestBuilder extends RequestWithSearchCriteriaBuilder {
     static from(request) {
         const builder = new PropertySearchRequestBuilder();
         builder.searchCriteria(request.searchCriteria);
@@ -2542,43 +2585,19 @@ class PropertySearchRequestBuilder extends BaseBuilder {
         }
         return builder;
     }
-    searchCriteria(criteriaOrConfigurator) {
-        if (typeof criteriaOrConfigurator === "function") {
-            const builder = new SearchCriteriaBuilder("");
-            criteriaOrConfigurator(builder);
-            this.criteria.searchCriteria = builder.build();
-            this.builders.searchCriteria = undefined;
-        }
-        else {
-            this.criteria.searchCriteria = criteriaOrConfigurator;
-            this.builders.searchCriteria = undefined;
-        }
-        return this;
-    }
-    options(optionsOrConfigurator) {
-        return this.setPropertyWithBuilderClass("options", optionsOrConfigurator, PropertyLookupOptionsBuilder);
-    }
     build() {
-        if (!this.criteria.searchCriteria) {
-            throw new Error("Search criteria is required");
-        }
+        this.validateSearchCriteria();
         const request = {
             searchCriteria: this.criteria.searchCriteria,
         };
-        if (this.builders.options) {
-            request.options = this.builders.options.build();
-        }
-        else if (this.criteria.options) {
-            request.options = this.criteria.options;
-        }
-        return request;
+        return this.buildOptionsIntoRequest(request);
     }
 }
 exports.PropertySearchRequestBuilder = PropertySearchRequestBuilder;
 /**
  * Builder for property search async requests
  */
-class PropertySearchAsyncRequestBuilder extends BaseBuilder {
+class PropertySearchAsyncRequestBuilder extends RequestWithSearchCriteriaBuilder {
     static from(request) {
         const builder = new PropertySearchAsyncRequestBuilder();
         builder.searchCriteria(request.searchCriteria);
@@ -2587,43 +2606,19 @@ class PropertySearchAsyncRequestBuilder extends BaseBuilder {
         }
         return builder;
     }
-    searchCriteria(criteriaOrConfigurator) {
-        if (typeof criteriaOrConfigurator === "function") {
-            const builder = new SearchCriteriaBuilder("");
-            criteriaOrConfigurator(builder);
-            this.criteria.searchCriteria = builder.build();
-            this.builders.searchCriteria = undefined;
-        }
-        else {
-            this.criteria.searchCriteria = criteriaOrConfigurator;
-            this.builders.searchCriteria = undefined;
-        }
-        return this;
-    }
-    options(optionsOrConfigurator) {
-        return this.setPropertyWithBuilderClass("options", optionsOrConfigurator, PropertyLookupOptionsBuilder);
-    }
     build() {
-        if (!this.criteria.searchCriteria) {
-            throw new Error("Search criteria is required");
-        }
+        this.validateSearchCriteria();
         const request = {
             searchCriteria: this.criteria.searchCriteria,
         };
-        if (this.builders.options) {
-            request.options = this.builders.options.build();
-        }
-        else if (this.criteria.options) {
-            request.options = this.criteria.options;
-        }
-        return request;
+        return this.buildOptionsIntoRequest(request);
     }
 }
 exports.PropertySearchAsyncRequestBuilder = PropertySearchAsyncRequestBuilder;
 /**
  * Builder for property lookup async requests
  */
-class PropertyLookupAsyncRequestBuilder extends BaseBuilder {
+class PropertyLookupAsyncRequestBuilder extends RequestWithLookupOptionsBuilder {
     constructor() {
         super(...arguments);
         this.requestItems = [];
@@ -2648,20 +2643,11 @@ class PropertyLookupAsyncRequestBuilder extends BaseBuilder {
         this.requestItems.push(builder.build());
         return this;
     }
-    options(optionsOrConfigurator) {
-        return this.setPropertyWithBuilderClass("options", optionsOrConfigurator, PropertyLookupOptionsBuilder);
-    }
     build() {
         const request = {
             requests: this.requestItems,
         };
-        if (this.builders.options) {
-            request.options = this.builders.options.build();
-        }
-        else if (this.criteria.options) {
-            request.options = this.criteria.options;
-        }
-        return request;
+        return this.buildOptionsIntoRequest(request);
     }
 }
 exports.PropertyLookupAsyncRequestBuilder = PropertyLookupAsyncRequestBuilder;

package/dist/client/client.d.ts

@@ -1,7 +1,7 @@
 import { AxiosInstance, AxiosResponse, AxiosError, InternalAxiosRequestConfig } from "axios";
 import { IBatchDataClient } from "./client.interface";
 import { ILogger } from "../core/logger.interface";
-import { PropertySubscriptionRequest, PropertySubscriptionResponse, PropertyCountRequest, PropertySearchRequest, PropertySearchResponse, AddressVerifyRequest, AddressVerifyResponse, AddressAutocompleteRequest, AddressAutocompleteResponse, AddressGeocodeRequest, AddressGeocodeResponse, AddressReverseGeocodeRequest, AddressReverseGeocodeResponse, PropertyLookupRequest, PropertyLookupResponse, PropertyLookupAsyncRequest, PropertyLookupAsyncResponse, PropertySearchAsyncRequest, PropertySearchAsyncResponse, PropertySkipTraceRequest, PropertySkipTraceResponse, PropertySkipTraceAsyncRequest, PropertySkipTraceAsyncResponse, PhoneVerificationRequest, PhoneVerificationResponse, PhoneVerificationAsyncRequest, PhoneVerificationAsyncResponse, PhoneDNCRequest, PhoneDNCResponse, PhoneDNCAsyncRequest, PhoneDNCAsyncResponse, PhoneTCPARequest, PhoneTCPAResponse, PhoneTCPAAsyncRequest, PhoneTCPAAsyncResponse, GetPropertySubscriptionsResponse, GetPropertySubscriptionDetailResponse, DeletePropertySubscriptionResponse, PropertyPermitRequest, PropertyPermitResponse, PropertySkipTraceV3Request, PropertySkipTraceV3Response, PropertySkipTraceV3AsyncRequest, PropertySkipTraceV3AsyncResponse } from "../core/types";
+import { PropertySubscriptionRequest, PropertySubscriptionResponse, PropertyCountRequest, PropertySearchRequest, PropertySearchResponse, PropertyLookupOptions, AddressVerifyRequest, AddressVerifyResponse, AddressAutocompleteRequest, AddressAutocompleteResponse, AddressGeocodeRequest, AddressGeocodeResponse, AddressReverseGeocodeRequest, AddressReverseGeocodeResponse, PropertyLookupRequest, PropertyLookupResponse, PropertyLookupAsyncRequest, PropertyLookupAsyncResponse, PropertySearchAsyncRequest, PropertySearchAsyncResponse, PropertySkipTraceRequest, PropertySkipTraceResponse, PropertySkipTraceAsyncRequest, PropertySkipTraceAsyncResponse, PhoneVerificationRequest, PhoneVerificationResponse, PhoneVerificationAsyncRequest, PhoneVerificationAsyncResponse, PhoneDNCRequest, PhoneDNCResponse, PhoneDNCAsyncRequest, PhoneDNCAsyncResponse, PhoneTCPARequest, PhoneTCPAResponse, PhoneTCPAAsyncRequest, PhoneTCPAAsyncResponse, GetPropertySubscriptionsResponse, GetPropertySubscriptionDetailResponse, DeletePropertySubscriptionResponse, PropertyPermitRequest, PropertyPermitResponse, PropertySkipTraceV3Request, PropertySkipTraceV3Response, PropertySkipTraceV3AsyncRequest, PropertySkipTraceV3AsyncResponse } from "../core/types";
 /**
  * Middleware function that executes before an HTTP request is sent.
  * Can modify the request config or perform side effects (logging, metrics, etc.).
@@ -129,6 +129,41 @@ export interface BatchDataClientOptions {
      * Allows specifying webhook URLs per endpoint type, with fallback to defaults
      */
     webhooks?: AsyncWebhookConfiguration;
+    /**
+     * Optional default PropertyLookupOptions to apply to all requests
+     * These defaults are merged with request-specific options, with request options taking precedence
+     *
+     * @example
+     * ```typescript
+     * const client = new BatchDataClient({
+     *   apiKey: "...",
+     *   defaultOptions: {
+     *     take: 100, // Default to 100 properties if not specified
+     *   }
+     * });
+     * ```
+     */
+    defaultOptions?: PropertyLookupOptions;
+    /**
+     * Optional maximum `take` value to enforce on all requests
+     * If a request specifies a `take` value greater than this, it will be capped to this maximum
+     * This is useful for enforcing API limits or preventing accidental large requests
+     *
+     * @example
+     * ```typescript
+     * const client = new BatchDataClient({
+     *   apiKey: "...",
+     *   maxTake: 100, // Cap all requests to max 100 properties
+     * });
+     *
+     * // Even if request specifies take: 500, it will be capped to 100
+     * await client.searchProperties({
+     *   searchCriteria: { query: "AZ" },
+     *   options: { take: 500 } // Will be capped to 100
+     * });
+     * ```
+     */
+    maxTake?: number;
 }
 /**
  * BatchData API Client
@@ -143,6 +178,8 @@ export declare class BatchDataClient implements IBatchDataClient {
     protected readonly axiosInstance: AxiosInstance;
     protected readonly logger: ILogger;
     private readonly webhooks?;
+    private readonly defaultOptions?;
+    private readonly maxTake?;
     constructor(options: BatchDataClientOptions);
     /**
      * Obfuscate sensitive headers (like Authorization) for logging
@@ -169,6 +206,30 @@ export declare class BatchDataClient implements IBatchDataClient {
      * @returns The request with webhook URLs applied (if needed)
      */
     private applyDefaultWebhookUrls;
+    /**
+     * Get the maximum take value for a request, applying maxTake limit if configured.
+     *
+     * @param originalRequest The original request
+     * @returns The take value to use (capped if necessary)
+     */
+    private getMaxPropertyTake;
+    /**
+     * Apply defaults and limits to a request with search criteria.
+     * Uses the shared RequestWithSearchCriteria interface.
+     * Currently caps the take value based on maxTake config.
+     *
+     * @param request The request with search criteria to apply defaults to
+     * @returns A new request with defaults applied
+     */
+    private applySearchRequestDefaultsAndLimits;
+    /**
+     * Apply default options to a request that supports PropertyLookupOptions.
+     * Defaults are merged with request-specific options, with request options taking precedence.
+     *
+     * @param request The request to apply defaults to
+     * @returns The request with defaults applied (if defaults are configured)
+     */
+    private applyDefaultOptions;
     /**
      * Apply default webhook URLs to a property subscription request if they're not already set.
      * This helper ensures that if webhook URLs are configured in the client,

package/dist/client/client.js

@@ -24,6 +24,8 @@ class BatchDataClient {
         this.v3BaseUrl = options.v3BaseUrl || "https://api.batchdata.com/api/v3";
         this.logger = options.logger || new logger_interface_1.ConsoleLogger();
         this.webhooks = options.webhooks;
+        this.defaultOptions = options.defaultOptions;
+        this.maxTake = options.maxTake;
         this.axiosInstance = axios_1.default.create({
             timeout: options.timeout || 30000,
             headers: {
@@ -211,6 +213,80 @@ class BatchDataClient {
             },
         };
     }
+    /**
+     * Get the maximum take value for a request, applying maxTake limit if configured.
+     *
+     * @param originalRequest The original request
+     * @returns The take value to use (capped if necessary)
+     */
+    getMaxPropertyTake(originalRequest) {
+        if (this.maxTake === undefined) {
+            return originalRequest.options?.take;
+        }
+        const { take: originalTake } = originalRequest.options ?? {};
+        if (!originalTake)
+            return this.maxTake;
+        if (originalTake > this.maxTake) {
+            this.logger.warn(`Property search take value capped from ${originalTake} to ${this.maxTake} (maxTake limit)`);
+            return this.maxTake;
+        }
+        return originalTake;
+    }
+    /**
+     * Apply defaults and limits to a request with search criteria.
+     * Uses the shared RequestWithSearchCriteria interface.
+     * Currently caps the take value based on maxTake config.
+     *
+     * @param request The request with search criteria to apply defaults to
+     * @returns A new request with defaults applied
+     */
+    applySearchRequestDefaultsAndLimits(request) {
+        // First merge defaults if configured
+        let requestWithDefaults = request;
+        if (this.defaultOptions) {
+            requestWithDefaults = this.applyDefaultOptions(request);
+        }
+        // Then apply maxTake limit
+        const maxTake = this.getMaxPropertyTake(requestWithDefaults);
+        if (maxTake !== undefined) {
+            return {
+                ...requestWithDefaults,
+                options: {
+                    ...requestWithDefaults.options,
+                    take: maxTake,
+                },
+            };
+        }
+        return requestWithDefaults;
+    }
+    /**
+     * Apply default options to a request that supports PropertyLookupOptions.
+     * Defaults are merged with request-specific options, with request options taking precedence.
+     *
+     * @param request The request to apply defaults to
+     * @returns The request with defaults applied (if defaults are configured)
+     */
+    applyDefaultOptions(request) {
+        // If no defaults are configured, return original request
+        if (!this.defaultOptions) {
+            return request;
+        }
+        // Merge defaults with request options (request options take precedence)
+        const mergedOptions = {
+            ...this.defaultOptions,
+            ...request.options,
+        };
+        // If no options were actually merged (request had no options and defaults don't add anything),
+        // return original request
+        if (!request.options && Object.keys(mergedOptions).length === 0) {
+            return request;
+        }
+        // Return a new request object with merged options
+        return {
+            ...request,
+            options: mergedOptions,
+        };
+    }
     /**
      * Apply default webhook URLs to a property subscription request if they're not already set.
      * This helper ensures that if webhook URLs are configured in the client,
@@ -374,7 +450,10 @@ class BatchDataClient {
     async createPropertySubscription(request) {
         const url = `${this.v2BaseUrl}/property-subscription`;
         // Apply default webhook URLs if configured
-        const requestWithDefaults = this.applyPropertySubscriptionWebhooks(request);
+        let requestWithDefaults = this.applyPropertySubscriptionWebhooks(request);
+        // Apply defaults and limits (including maxTake)
+        requestWithDefaults =
+            this.applySearchRequestDefaultsAndLimits(requestWithDefaults);
         this.logger.debug(`Creating property subscription: POST ${url}`, {
             query: requestWithDefaults.searchCriteria.query,
         });
@@ -403,12 +482,14 @@ class BatchDataClient {
      */
     async searchProperties(request) {
         const url = `${this.v1BaseUrl}/property/search`;
+        // Apply defaults and limits (including maxTake)
+        const requestWithDefaults = this.applySearchRequestDefaultsAndLimits(request);
         this.logger.debug(`Searching properties: POST ${url}`, {
-            query: request.searchCriteria.query,
-            take: request.options?.take,
-            skip: request.options?.skip,
+            query: requestWithDefaults.searchCriteria.query,
+            take: requestWithDefaults.options?.take,
+            skip: requestWithDefaults.options?.skip,
         });
-        const { data, status } = await this.handleApiCall(() => this.axiosInstance.post(url, request), "Failed to search properties", url);
+        const { data, status } = await this.handleApiCall(() => this.axiosInstance.post(url, requestWithDefaults), "Failed to search properties", url);
         this.logger.debug(`Property search completed`, {
             status,
             hasData: !!data,
@@ -530,10 +611,12 @@ class BatchDataClient {
      */
     async lookupProperty(request) {
         const url = `${this.v1BaseUrl}/property/lookup/all-attributes`;
+        // Apply default options if configured
+        const requestWithDefaults = this.applyDefaultOptions(request);
         this.logger.debug(`Looking up property: POST ${url}`, {
-            requestCount: request.requests.length,
+            requestCount: requestWithDefaults.requests.length,
         });
-        const { data, status } = await this.handleApiCall(() => this.axiosInstance.post(url, request), "Failed to lookup property", url);
+        const { data, status } = await this.handleApiCall(() => this.axiosInstance.post(url, requestWithDefaults), "Failed to lookup property", url);
         this.logger.debug(`Property lookup completed`, {
             status,
             propertyCount: data.results?.properties?.length,
@@ -550,7 +633,9 @@ class BatchDataClient {
     async lookupPropertyAsync(request) {
         const url = `${this.v1BaseUrl}/property/lookup/async`;
         // Apply default webhook URLs if configured
-        const requestWithDefaults = this.applyDefaultWebhookUrls(request, "propertyLookup");
+        let requestWithDefaults = this.applyDefaultWebhookUrls(request, "propertyLookup");
+        // Apply default options if configured
+        requestWithDefaults = this.applyDefaultOptions(requestWithDefaults);
         this.logger.debug(`Looking up property async: POST ${url}`, {
             requestCount: requestWithDefaults.requests.length,
         });
@@ -571,7 +656,10 @@ class BatchDataClient {
     async searchPropertiesAsync(request) {
         const url = `${this.v1BaseUrl}/property/search/async`;
         // Apply default webhook URLs if configured
-        const requestWithDefaults = this.applyDefaultWebhookUrls(request, "propertySearch");
+        let requestWithDefaults = this.applyDefaultWebhookUrls(request, "propertySearch");
+        // Apply defaults and limits (including maxTake)
+        requestWithDefaults =
+            this.applySearchRequestDefaultsAndLimits(requestWithDefaults);
         this.logger.debug(`Searching properties async: POST ${url}`, {
             query: requestWithDefaults.searchCriteria.query,
         });

package/dist/core/types.d.ts

@@ -478,8 +478,7 @@ export interface DeliveryConfig {
 /**
  * Property subscription request payload
  */
-export interface PropertySubscriptionRequest {
-    searchCriteria: SearchCriteria;
+export interface PropertySubscriptionRequest extends RequestWithSearchCriteria {
     deliveryConfig: DeliveryConfig;
 }
 /**
@@ -1712,6 +1711,58 @@ export interface PropertyLookupRequestItem {
     countyFipsCode?: string;
     requestId?: string;
 }
+/**
+ * Base interface for requests that support PropertyLookupOptions
+ * This allows for type-safe application of defaults and limits across request types
+ *
+ * @example
+ * ```typescript
+ * // Apply defaults to any request with lookup options
+ * function applyDefaults<T extends RequestWithLookupOptions>(
+ *   request: T,
+ *   defaults: PropertyLookupOptions
+ * ): T {
+ *   return {
+ *     ...request,
+ *     options: { ...defaults, ...request.options },
+ *   };
+ * }
+ * ```
+ */
+export interface RequestWithLookupOptions {
+    options?: PropertyLookupOptions;
+}
+/**
+ * Base interface for requests that have both searchCriteria and PropertyLookupOptions
+ * Most search-based requests extend this interface
+ *
+ * @example
+ * ```typescript
+ * // Apply defaults to any request with search criteria and options
+ * function applySearchDefaults<T extends RequestWithSearchCriteria>(
+ *   request: T,
+ *   defaults: PropertyLookupOptions
+ * ): T {
+ *   return {
+ *     ...request,
+ *     options: { ...defaults, ...request.options },
+ *   };
+ * }
+ * ```
+ */
+export interface RequestWithSearchCriteria extends RequestWithLookupOptions {
+    searchCriteria: SearchCriteria;
+}
+/**
+ * Type helper to extract request types that support PropertyLookupOptions
+ * Useful for writing generic functions that work with any request type
+ */
+export type RequestWithLookupOptionsType = PropertySearchRequest | PropertySearchAsyncRequest | PropertyLookupRequest | PropertyLookupAsyncRequest | PropertySubscriptionRequest;
+/**
+ * Type helper to extract request types that have both searchCriteria and options
+ * Useful for writing generic functions that work with search-based requests
+ */
+export type RequestWithSearchCriteriaType = PropertySearchRequest | PropertySearchAsyncRequest | PropertySubscriptionRequest;
 /**
  * Property lookup options (shared with property search)
  */
@@ -1764,10 +1815,7 @@ export interface PropertyLookupOptions {
 /**
  * Property search request (synchronous)
  */
-export interface PropertySearchRequest {
-    searchCriteria: SearchCriteria;
-    options?: PropertyLookupOptions;
-}
+export type PropertySearchRequest = RequestWithSearchCriteria;
 /**
  * Property count request
  *
@@ -1787,9 +1835,8 @@ export interface PropertyCountRequest {
 /**
  * Property lookup request
  */
-export interface PropertyLookupRequest {
+export interface PropertyLookupRequest extends RequestWithLookupOptions {
     requests: PropertyLookupRequestItem[];
-    options?: PropertyLookupOptions;
 }
 /**
  * Property lookup API response (same structure as PropertySearchResponse)
@@ -1804,9 +1851,8 @@ export interface PropertyLookupResponse {
 /**
  * Property lookup async request
  */
-export interface PropertyLookupAsyncRequest {
+export interface PropertyLookupAsyncRequest extends RequestWithLookupOptions {
     requests: PropertyLookupRequestItem[];
-    options?: PropertyLookupOptions;
 }
 /**
  * Property lookup async API response
@@ -1823,10 +1869,7 @@ export type PropertyLookupAsyncWebhookPayload = PropertyLookupResponse;
 /**
  * Property search async request
  */
-export interface PropertySearchAsyncRequest {
-    searchCriteria: SearchCriteria;
-    options?: PropertyLookupOptions;
-}
+export type PropertySearchAsyncRequest = RequestWithSearchCriteria;
 /**
  * Property search async API response
  * Async endpoints return only a status object. Full results are delivered to the webhook URL.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@land-catalyst/batch-data-sdk",
-  "version": "1.2.10",
+  "version": "1.3.0",
   "description": "TypeScript SDK for BatchData.io Property API - Types, Builders, and Utilities",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,7 +12,7 @@
   "scripts": {
     "build": "tsc",
     "prepublishOnly": "npm run build",
-    "test": "jest",
+    "test": "jest --testPathIgnorePatterns=integration",
     "test:integration": "jest --testMatch=\"**/*integration*.test.ts\"",
     "lint": "eslint src",
     "lint:fix": "eslint src --fix",