bmlt-query-client 1.0.1 → 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 BMLT Community
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/app.d.ts

@@ -0,0 +1,977 @@
+export declare interface BaseSearchParams {
+    /** Data format for response */
+    format?: BmltDataFormat;
+    /** Language code for format names */
+    lang_enum?: Language;
+    /** JSONP callback function name */
+    callback?: string;
+}
+
+export declare class BmltClient {
+    private timeout;
+    private userAgent;
+    private geocodingService?;
+    private rootServerURL;
+    private defaultFormat;
+    constructor(options: BmltClientOptions);
+    /**
+     * Make a request to the BMLT API
+     */
+    private makeRequest;
+    /**
+     * Search for meetings
+     */
+    searchMeetings(params?: SearchResultsParams): Promise<Meeting[]>;
+    /**
+     * Search for meetings by geographic location using geocoding
+     */
+    searchMeetingsByAddress(params: GeographicSearchParams): Promise<Meeting[]>;
+    /**
+     * Search for meetings by coordinates
+     */
+    searchMeetingsByCoordinates(coordinates: Coordinates, radiusMiles?: number, radiusKm?: number, searchParams?: Omit<SearchResultsParams, 'lat_val' | 'long_val' | 'geo_width' | 'geo_width_km'>): Promise<Meeting[]>;
+    /**
+     * Get available meeting formats
+     */
+    getFormats(params?: FormatsParams): Promise<Format[]>;
+    /**
+     * Get service bodies
+     */
+    getServiceBodies(params?: ServiceBodiesParams): Promise<ServiceBody[]>;
+    /**
+     * Get meeting changes within a date range
+     */
+    getChanges(params?: ChangesParams): Promise<Change[]>;
+    /**
+     * Get available field keys
+     */
+    getFieldKeys(): Promise<FieldKey[]>;
+    /**
+     * Get field values for a specific field key
+     */
+    getFieldValues(params: FieldValuesParams): Promise<FieldValue[]>;
+    /**
+     * Get NAWS dump for a service body (CSV format only)
+     */
+    getNAWSDump(params: NAWSDumpParams): Promise<string>;
+    /**
+     * Get server information
+     */
+    getServerInfo(): Promise<ServerInfo>;
+    /**
+     * Get server coverage area
+     */
+    getCoverageArea(): Promise<CoverageArea>;
+    /**
+     * Geocode an address using the built-in geocoding service
+     */
+    geocodeAddress(address: string, options?: Partial<GeocodeOptions>): Promise<GeocodeResult>;
+    /**
+     * Reverse geocode coordinates to an address
+     */
+    reverseGeocode(coordinates: Coordinates, options?: Partial<GeocodeOptions>): Promise<GeocodeResult>;
+    /**
+     * Get the root server URL
+     */
+    getRootServerURL(): string;
+    /**
+     * Update the root server URL
+     */
+    setRootServerURL(url: string): void;
+    /**
+     * Get the default data format
+     */
+    getDefaultFormat(): BmltDataFormat;
+    /**
+     * Set the default data format
+     */
+    setDefaultFormat(format: BmltDataFormat): void;
+    /**
+     * Get geocoding service statistics
+     */
+    getGeocodingStats(): {
+        queueSize: number;
+        pendingCount: number;
+    } | null;
+    /**
+     * Clear the geocoding queue
+     */
+    clearGeocodingQueue(): void;
+}
+
+export declare interface BmltClientOptions {
+    /** Root server URL */
+    rootServerURL: string;
+    /** Default data format */
+    defaultFormat?: BmltDataFormat;
+    /** HTTP request timeout in milliseconds */
+    timeout?: number;
+    /** User agent string */
+    userAgent?: string;
+    /** Geocoding options */
+    geocodingOptions?: GeocodeOptions & RateLimitOptions;
+    /** Enable automatic geocoding for address searches */
+    enableGeocoding?: boolean;
+}
+
+/**
+ * Base types and enums for BMLT API
+ */
+export declare enum BmltDataFormat {
+    JSON = "json",
+    JSONP = "jsonp",
+    TSML = "tsml",
+    CSV = "csv"
+}
+
+export declare enum BmltEndpoint {
+    GET_SEARCH_RESULTS = "GetSearchResults",
+    GET_FORMATS = "GetFormats",
+    GET_SERVICE_BODIES = "GetServiceBodies",
+    GET_CHANGES = "GetChanges",
+    GET_FIELD_KEYS = "GetFieldKeys",
+    GET_FIELD_VALUES = "GetFieldValues",
+    GET_NAWS_DUMP = "GetNAWSDump",
+    GET_SERVER_INFO = "GetServerInfo",
+    GET_COVERAGE_AREA = "GetCoverageArea"
+}
+
+export declare interface BmltError extends Error {
+    statusCode?: number;
+    response?: unknown;
+}
+
+/**
+ * Comprehensive error handling for BMLT Query Client
+ */
+export declare enum BmltErrorType {
+    API_ERROR = "ApiError",
+    NETWORK_ERROR = "NetworkError",
+    VALIDATION_ERROR = "ValidationError",
+    GEOCODING_ERROR = "GeocodingError",
+    RATE_LIMIT_ERROR = "RateLimitError",
+    TIMEOUT_ERROR = "TimeoutError",
+    AUTHENTICATION_ERROR = "AuthenticationError",
+    SERVER_ERROR = "ServerError",
+    CLIENT_ERROR = "ClientError",
+    CONFIGURATION_ERROR = "ConfigurationError"
+}
+
+export declare class BmltQueryError extends Error {
+    readonly type: BmltErrorType;
+    readonly statusCode?: number;
+    readonly response?: unknown;
+    readonly originalError?: Error;
+    readonly context?: Record<string, unknown>;
+    constructor(type: BmltErrorType, message: string, options?: {
+        statusCode?: number;
+        response?: unknown;
+        originalError?: Error;
+        context?: Record<string, unknown>;
+    });
+    /**
+     * Check if error is of a specific type
+     */
+    isType(type: BmltErrorType): boolean;
+    /**
+     * Check if error is retryable
+     */
+    isRetryable(): boolean;
+    /**
+     * Check if error is a client-side error (4xx)
+     */
+    isClientError(): boolean;
+    /**
+     * Check if error is a server-side error (5xx)
+     */
+    isServerError(): boolean;
+    /**
+     * Get a user-friendly error message
+     */
+    getUserMessage(): string;
+    /**
+     * Convert error to JSON for logging
+     */
+    toJSON(): {
+        name: string;
+        type: BmltErrorType;
+        message: string;
+        statusCode: number | undefined;
+        response: unknown;
+        context: Record<string, unknown> | undefined;
+        stack: string | undefined;
+        originalError: {
+            name: string;
+            message: string;
+            stack: string | undefined;
+        } | undefined;
+    };
+}
+
+/**
+ * Build a BMLT API URL with parameters
+ */
+export declare function buildBmltURL(options: URLBuilderOptions): string;
+
+export declare interface Change {
+    /** Change ID */
+    change_id: string;
+    /** Meeting ID affected by change */
+    meeting_id: string;
+    /** Service body ID */
+    service_body_id: string;
+    /** User ID who made change */
+    user_id: string;
+    /** User name who made change */
+    user_name: string;
+    /** Change date (YYYY-MM-DD) */
+    change_date: string;
+    /** Change time (HH:MM:SS) */
+    change_time: string;
+    /** Change type */
+    change_type: string;
+    /** Change description */
+    change_description: string;
+    /** Meeting name before change */
+    original_meeting_name?: string;
+    /** Meeting name after change */
+    changed_meeting_name?: string;
+    /** JSON object with detailed changes */
+    json_data?: unknown;
+    /** Root server URI (for aggregator mode) */
+    root_server_uri?: string;
+}
+
+export declare interface ChangesParams extends BaseSearchParams {
+    /** Start date in YYYY-MM-DD format */
+    start_date?: string;
+    /** End date in YYYY-MM-DD format */
+    end_date?: string;
+    /** Specific meeting ID */
+    meeting_id?: number;
+    /** Service body ID */
+    service_body_id?: number;
+}
+
+export declare interface Coordinates {
+    latitude: number;
+    longitude: number;
+}
+
+export declare interface CoverageArea {
+    /** North boundary */
+    north_latitude: number;
+    /** South boundary */
+    south_latitude: number;
+    /** East boundary */
+    east_longitude: number;
+    /** West boundary */
+    west_longitude: number;
+}
+
+/**
+ * Factory class for creating specific error types
+ */
+export declare class ErrorFactory {
+    static createApiError(message: string, statusCode?: number, response?: unknown, originalError?: Error): BmltQueryError;
+    static createNetworkError(message: string, originalError?: Error): BmltQueryError;
+    static createTimeoutError(message: string, originalError?: Error): BmltQueryError;
+    static createValidationError(message: string, context?: Record<string, unknown>): BmltQueryError;
+    static createGeocodingError(message: string, originalError?: Error, context?: Record<string, unknown>): BmltQueryError;
+    static createRateLimitError(message: string, statusCode?: number, response?: unknown): BmltQueryError;
+    static createConfigurationError(message: string, context?: Record<string, unknown>): BmltQueryError;
+}
+
+/**
+ * Error handler utility class
+ */
+export declare class ErrorHandler {
+    /**
+     * Handle and transform fetch errors
+     */
+    static handleFetchError(error: unknown, response?: Response): BmltQueryError;
+    /**
+     * @deprecated Use handleFetchError instead
+     */
+    static handleAxiosError(error: any): BmltQueryError;
+    /**
+     * Handle validation errors with detailed context
+     */
+    static handleValidationError(field: string, value: unknown, expectedType: string, constraints?: string[]): BmltQueryError;
+    /**
+     * Handle endpoint validation errors
+     */
+    static handleEndpointError(endpoint: string, format: string): BmltQueryError;
+    /**
+     * Handle URL validation errors
+     */
+    static handleUrlError(url: string, reason: string): BmltQueryError;
+    /**
+     * Handle coordinate validation errors
+     */
+    static handleCoordinateError(latitude?: number, longitude?: number, reason?: string): BmltQueryError;
+    /**
+     * Wrap and enhance existing errors
+     */
+    static wrapError(originalError: Error, context: string, additionalContext?: Record<string, unknown>): BmltQueryError;
+}
+
+/**
+ * Extract numeric IDs from various parameter formats
+ */
+export declare function extractIds(value: unknown): number[];
+
+export declare interface FieldKey {
+    /** Field key */
+    key: string;
+    /** Field description */
+    description: string;
+}
+
+export declare interface FieldValue {
+    /** Field key */
+    key: string;
+    /** Field value */
+    value: string;
+    /** Meeting ID */
+    meeting_id: string;
+}
+
+export declare interface FieldValuesParams extends BaseSearchParams {
+    /** The field key to get values for (required) */
+    meeting_key: string;
+    /** Comma-separated list of format IDs to limit field values to */
+    specific_formats?: string;
+    /** Include all formats */
+    all_formats?: boolean;
+}
+
+export declare interface Format {
+    /** Format ID */
+    shared_id_bigint: string;
+    /** Format key string */
+    key_string: string;
+    /** Format name */
+    name_string: string;
+    /** Format description */
+    description_string: string;
+    /** Language */
+    lang: string;
+    /** Root server URI (for aggregator mode) */
+    root_server_uri?: string;
+}
+
+export declare interface FormatsParams extends BaseSearchParams {
+    /** Show all formats */
+    show_all?: boolean;
+    /** Array of format IDs to include/exclude */
+    format_ids?: number[];
+    /** Array of format key strings to filter by */
+    key_strings?: string[];
+}
+
+/**
+ * Format time values for BMLT API
+ */
+export declare function formatTimeValue(hours?: number, minutes?: number): {
+    hours?: number;
+    minutes?: number;
+};
+
+export declare interface GeocodeOptions {
+    retryCount?: number;
+    timeout?: number;
+    userAgent?: string;
+    /** Country code for region bias (e.g., 'us', 'ca', 'gb') */
+    countryCode?: string;
+    /** Viewbox for region bias [minLon, minLat, maxLon, maxLat] */
+    viewbox?: [number, number, number, number];
+    /** Bounded search - restrict results to viewbox */
+    bounded?: boolean;
+}
+
+export declare interface GeocodeResult {
+    /** Geocoded coordinates */
+    coordinates: Coordinates;
+    /** Display name of the geocoded address */
+    display_name: string;
+    /** Geocoding confidence (0-1) */
+    confidence?: number;
+    /** Address components */
+    address?: {
+        house_number?: string;
+        road?: string;
+        neighbourhood?: string;
+        suburb?: string;
+        city?: string;
+        county?: string;
+        state?: string;
+        postcode?: string;
+        country?: string;
+    };
+}
+
+export declare class GeocodingService {
+    private baseURL;
+    private queue;
+    private readonly defaultOptions;
+    constructor(options?: GeocodeOptions & RateLimitOptions);
+    /**
+     * Make a fetch request with timeout and error handling
+     */
+    private fetchWithTimeout;
+    /**
+     * Geocode an address using Nominatim
+     */
+    geocode(address: string, options?: Partial<GeocodeOptions>): Promise<GeocodeResult>;
+    /**
+     * Batch geocode multiple addresses
+     */
+    batchGeocode(addresses: string[], options?: Partial<GeocodeOptions>): Promise<GeocodeResult[]>;
+    /**
+     * Reverse geocode coordinates to an address
+     */
+    reverseGeocode(coordinates: Coordinates, options?: Partial<GeocodeOptions>): Promise<GeocodeResult>;
+    /**
+     * Get the current queue size
+     */
+    getQueueSize(): number;
+    /**
+     * Get the number of pending operations
+     */
+    getPendingCount(): number;
+    /**
+     * Clear the queue
+     */
+    clearQueue(): void;
+    /**
+     * Set concurrency limit
+     */
+    setConcurrency(concurrency: number): void;
+}
+
+export declare interface GeographicSearchParams {
+    /** Address to geocode and search around */
+    address: string;
+    /** Search radius in miles */
+    radiusMiles?: number;
+    /** Search radius in kilometers */
+    radiusKm?: number;
+    /** Sort results by distance */
+    sortByDistance?: boolean;
+    /** Other search parameters */
+    searchParams?: Omit<SearchResultsParams, 'lat_val' | 'long_val' | 'geo_width' | 'geo_width_km' | 'sort_results_by_distance'>;
+}
+
+/**
+ * Convert kilometers to miles
+ */
+export declare function kilometersToMiles(km: number): number;
+
+export declare enum Language {
+    ENGLISH = "en",
+    GERMAN = "de",
+    DANISH = "dk",
+    SPANISH = "es",
+    PERSIAN = "fa",
+    FRENCH = "fr",
+    ITALIAN = "it",
+    POLISH = "pl",
+    PORTUGUESE = "pt",
+    SWEDISH = "sv"
+}
+
+export declare interface Meeting {
+    /** Meeting ID */
+    id_bigint: string;
+    /** Weekday (1-7) */
+    weekday_tinyint: number;
+    /** Venue type (1=In-person, 2=Virtual, 3=Hybrid) */
+    venue_type: number;
+    /** Start time (24-hour format HH:MM:SS) */
+    start_time: string;
+    /** Duration time (HH:MM:SS) */
+    duration_time: string;
+    /** Time zone */
+    time_zone?: string;
+    /** Meeting name */
+    meeting_name: string;
+    /** Location text */
+    location_text: string;
+    /** Location info */
+    location_info?: string;
+    /** Location street address */
+    location_street?: string;
+    /** Location neighborhood */
+    location_neighborhood?: string;
+    /** Location borough */
+    location_municipality?: string;
+    /** Location city/town */
+    location_city_subsection?: string;
+    /** Location postal code */
+    location_postal_code_1?: string;
+    /** Location province/state */
+    location_province?: string;
+    /** Location nation */
+    location_nation?: string;
+    /** Latitude */
+    latitude: number;
+    /** Longitude */
+    longitude: number;
+    /** Published status (0=unpublished, 1=published) */
+    published: number;
+    /** Email contact */
+    email_contact?: string;
+    /** World Committee Code */
+    worldid_mixed?: string;
+    /** Shared group ID */
+    shared_group_id_bigint?: string;
+    /** Service body ID */
+    service_body_bigint: string;
+    /** Meeting formats (comma-separated format IDs) */
+    format_shared_id_list?: string;
+    /** Meeting comments */
+    comments?: string;
+    /** Virtual meeting URL */
+    virtual_meeting_link?: string;
+    /** Virtual meeting additional info */
+    virtual_meeting_additional_info?: string;
+    /** Root server URI (for aggregator mode) */
+    root_server_uri?: string;
+    /** Distance from search point (when using geographic search) */
+    distance_in_km?: number;
+    /** Distance in miles from search point */
+    distance_in_miles?: number;
+}
+
+export declare class MeetingQueryBuilder {
+    private params;
+    private client;
+    constructor(client: BmltClient);
+    /**
+     * Include or exclude specific meeting IDs
+     */
+    meetingIds(ids: number | number[], exclude?: boolean): this;
+    /**
+     * Include meetings on specific weekdays
+     */
+    onWeekdays(...days: Weekday[]): this;
+    /**
+     * Exclude meetings on specific weekdays
+     */
+    notOnWeekdays(...days: Weekday[]): this;
+    /**
+     * Filter by venue types
+     */
+    venueTypes(...types: VenueType[]): this;
+    /**
+     * Include only in-person meetings
+     */
+    inPersonOnly(): this;
+    /**
+     * Include only virtual meetings
+     */
+    virtualOnly(): this;
+    /**
+     * Include only hybrid meetings
+     */
+    hybridOnly(): this;
+    /**
+     * Include virtual and hybrid meetings
+     */
+    virtualOrHybrid(): this;
+    /**
+     * Filter by meeting formats
+     */
+    formats(formatIds: number | number[], exclude?: boolean): this;
+    /**
+     * Use OR logic for format matching instead of AND
+     */
+    anyFormat(): this;
+    /**
+     * Filter by service bodies
+     */
+    serviceBodies(serviceBodyIds: number | number[], exclude?: boolean): this;
+    /**
+     * Include child service bodies
+     */
+    includeChildServiceBodies(): this;
+    /**
+     * Search for specific text
+     */
+    searchText(text: string): this;
+    /**
+     * Meetings starting after specific time
+     */
+    startingAfter(hours: number, minutes?: number): this;
+    /**
+     * Meetings starting before specific time
+     */
+    startingBefore(hours: number, minutes?: number): this;
+    /**
+     * Meetings ending before specific time
+     */
+    endingBefore(hours: number, minutes?: number): this;
+    /**
+     * Minimum meeting duration
+     */
+    minimumDuration(hours?: number, minutes?: number): this;
+    /**
+     * Maximum meeting duration
+     */
+    maximumDuration(hours?: number, minutes?: number): this;
+    /**
+     * Search within geographic area by coordinates
+     */
+    nearCoordinates(coordinates: Coordinates, radiusMiles?: number, radiusKm?: number): this;
+    /**
+     * Search for specific field value
+     */
+    fieldValue(fieldKey: string, value: string): this;
+    /**
+     * Return only specific fields
+     */
+    selectFields(...fields: string[]): this;
+    /**
+     * Sort results by specific fields
+     */
+    sortBy(...fields: string[]): this;
+    /**
+     * Sort by predefined aliases
+     */
+    sortByAlias(alias: SortKey): this;
+    /**
+     * Sort by distance (requires geographic search)
+     */
+    sortByDistance(): this;
+    /**
+     * Set pagination
+     */
+    paginate(pageSize: number, pageNumber?: number): this;
+    /**
+     * Include unpublished meetings
+     */
+    includeUnpublished(): this;
+    /**
+     * Include only unpublished meetings
+     */
+    unpublishedOnly(): this;
+    /**
+     * Set language for format names
+     */
+    language(lang: Language): this;
+    /**
+     * Set response format
+     */
+    format(format: BmltDataFormat): this;
+    /**
+     * Include formats used in search results
+     */
+    includeFormats(): this;
+    /**
+     * Return only formats (requires includeFormats)
+     */
+    formatsOnly(): this;
+    /**
+     * Filter by root server IDs (aggregator mode)
+     */
+    rootServerIds(serverIds: number | number[], exclude?: boolean): this;
+    /**
+     * Get the current query parameters
+     */
+    getParams(): SearchResultsParams;
+    /**
+     * Reset the query builder
+     */
+    reset(): this;
+    /**
+     * Clone the current query builder
+     */
+    clone(): MeetingQueryBuilder;
+    /**
+     * Execute the search and return results
+     */
+    execute(): Promise<Meeting[]>;
+    /**
+     * Execute the search by geocoding an address first
+     */
+    executeNearAddress(address: string, radiusMiles?: number, radiusKm?: number, sortByDistance?: boolean): Promise<Meeting[]>;
+}
+
+/**
+ * Convert miles to kilometers
+ */
+export declare function milesToKilometers(miles: number): number;
+
+export declare interface NAWSDumpParams extends Record<string, unknown> {
+    /** Service body ID (required) */
+    sb_id: number;
+}
+
+export declare interface NominatimResponse {
+    place_id: number;
+    licence: string;
+    osm_type: string;
+    osm_id: number;
+    lat: string;
+    lon: string;
+    display_name: string;
+    address?: {
+        house_number?: string;
+        road?: string;
+        neighbourhood?: string;
+        suburb?: string;
+        city?: string;
+        town?: string;
+        village?: string;
+        county?: string;
+        state?: string;
+        postcode?: string;
+        country?: string;
+        country_code?: string;
+    };
+    importance?: number;
+    boundingbox: string[];
+}
+
+/**
+ * Normalize parameter values for BMLT API
+ */
+export declare function normalizeParameters(params: Record<string, unknown>): Record<string, unknown>;
+
+/**
+ * Convenience methods for common search patterns
+ */
+export declare class QuickSearch {
+    private client;
+    constructor(client: BmltClient);
+    /**
+     * Search for today's meetings
+     */
+    today(): MeetingQueryBuilder;
+    /**
+     * Search for weekend meetings
+     */
+    weekend(): MeetingQueryBuilder;
+    /**
+     * Search for weekday meetings
+     */
+    weekdays(): MeetingQueryBuilder;
+    /**
+     * Search for evening meetings (after 5 PM)
+     */
+    evening(): MeetingQueryBuilder;
+    /**
+     * Search for morning meetings (before 12 PM)
+     */
+    morning(): MeetingQueryBuilder;
+    /**
+     * Search for virtual meetings only
+     */
+    virtual(): MeetingQueryBuilder;
+    /**
+     * Search for in-person meetings only
+     */
+    inPerson(): MeetingQueryBuilder;
+    /**
+     * Search by meeting name or location
+     */
+    byText(searchText: string): MeetingQueryBuilder;
+}
+
+export declare interface RateLimitOptions {
+    intervalCap?: number;
+    interval?: number;
+    carryoverConcurrencyCount?: boolean;
+    concurrency?: number;
+}
+
+export declare class RetryHandler {
+    static withRetry<T>(operation: () => Promise<T>, options: RetryOptions): Promise<T>;
+}
+
+/**
+ * Retry utility for handling retryable errors
+ */
+export declare interface RetryOptions {
+    maxRetries: number;
+    baseDelay: number;
+    maxDelay: number;
+    factor: number;
+    onRetry?: (error: BmltQueryError, attempt: number) => void;
+}
+
+export declare interface SearchResultsParams extends BaseSearchParams {
+    /** Include specific meeting IDs (positive) or exclude (negative) */
+    meeting_ids?: number | number[];
+    /** Include formats used in search results */
+    get_used_formats?: boolean;
+    /** Return only formats (requires get_used_formats=true) */
+    get_formats_only?: boolean;
+    /** Include meetings on specific days */
+    weekdays?: Weekday | Weekday[];
+    /** Include meetings with specific venue types */
+    venue_types?: VenueType | VenueType[];
+    /** Include meetings with specific formats */
+    formats?: number | number[];
+    /** Use OR logic for format matching (default is AND) */
+    formats_comparison_operator?: 'OR';
+    /** Include meetings from specific service bodies */
+    services?: number | number[];
+    /** Include child service bodies when filtering by services */
+    recursive?: boolean;
+    /** Search for specific text */
+    SearchString?: string;
+    /** Search radius for geographic searches */
+    SearchStringRadius?: number;
+    /** Meetings starting after hour (0-23) */
+    StartsAfterH?: number;
+    /** Meetings starting after minute (0-59) */
+    StartsAfterM?: number;
+    /** Meetings starting before hour (0-23) */
+    StartsBeforeH?: number;
+    /** Meetings starting before minute (0-59) */
+    StartsBeforeM?: number;
+    /** Meetings ending before hour (0-23) */
+    EndsBeforeH?: number;
+    /** Meetings ending before minute (0-59) */
+    EndsBeforeM?: number;
+    /** Minimum duration in hours */
+    MinDurationH?: number;
+    /** Minimum duration in minutes */
+    MinDurationM?: number;
+    /** Maximum duration in hours */
+    MaxDurationH?: number;
+    /** Maximum duration in minutes */
+    MaxDurationM?: number;
+    /** Latitude for geographic search */
+    lat_val?: number;
+    /** Longitude for geographic search */
+    long_val?: number;
+    /** Search radius in miles */
+    geo_width?: number;
+    /** Search radius in kilometers */
+    geo_width_km?: number;
+    /** Sort results by distance when using geographic search */
+    sort_results_by_distance?: boolean;
+    /** Search for specific field value */
+    meeting_key?: string;
+    /** The value to search for */
+    meeting_key_value?: string;
+    /** Return only specific fields (comma-separated) */
+    data_field_key?: string;
+    /** Sort results by specific fields (comma-separated) */
+    sort_keys?: string;
+    /** Use predefined sort aliases */
+    sort_key?: SortKey;
+    /** Number of results per page */
+    page_size?: number;
+    /** Page number (defaults to 1) */
+    page_num?: number;
+    /** Published status: undefined=published only, 0=all, -1=unpublished only */
+    advanced_published?: 0 | -1;
+    /** Include specific root server IDs (for aggregator mode) */
+    root_server_ids?: number | number[];
+}
+
+export declare interface ServerInfo {
+    /** Server version */
+    version: string;
+    /** Available endpoints */
+    availableEndpoints: string[];
+    /** Supported formats */
+    supportedFormats: string[];
+    /** Supported languages */
+    langs: string[];
+    /** Native language */
+    nativeLang: string;
+    /** Server name */
+    name?: string;
+    /** Server description */
+    description?: string;
+    /** Coverage area information */
+    coverageArea?: CoverageArea;
+}
+
+export declare interface ServiceBodiesParams extends BaseSearchParams {
+    /** Array of service body IDs to include/exclude */
+    services?: number[];
+    /** Include child service bodies */
+    recursive?: boolean;
+    /** Include parent service bodies */
+    parents?: boolean;
+}
+
+export declare interface ServiceBody {
+    /** Service body ID */
+    id: string;
+    /** Service body name */
+    name: string;
+    /** Service body description */
+    description?: string;
+    /** Service body type */
+    type: string;
+    /** Service body URL */
+    url?: string;
+    /** Help line */
+    helpline?: string;
+    /** World service committee code */
+    world_id?: string;
+    /** Parent service body ID */
+    parent_id?: string;
+    /** Root server URI (for aggregator mode) */
+    root_server_uri?: string;
+}
+
+export declare enum SortKey {
+    WEEKDAY = "weekday",
+    TIME = "time",
+    TOWN = "town",
+    STATE = "state",
+    WEEKDAY_STATE = "weekday_state"
+}
+
+export declare interface URLBuilderOptions {
+    rootServerURL: string;
+    format: BmltDataFormat;
+    endpoint: BmltEndpoint;
+    parameters?: Record<string, unknown>;
+}
+
+/**
+ * Validate coordinate values
+ */
+export declare function validateCoordinates(latitude: number, longitude: number): void;
+
+/**
+ * Validate endpoint/format combinations
+ */
+export declare function validateEndpointFormat(endpoint: BmltEndpoint, format: BmltDataFormat): void;
+
+/**
+ * Validate radius values
+ */
+export declare function validateRadius(radius: number): void;
+
+/**
+ * Clean and validate a root server URL
+ */
+export declare function validateRootServerURL(url: string): string;
+
+export declare enum VenueType {
+    IN_PERSON = 1,
+    VIRTUAL = 2,
+    HYBRID = 3
+}
+
+export declare enum Weekday {
+    SUNDAY = 1,
+    MONDAY = 2,
+    TUESDAY = 3,
+    WEDNESDAY = 4,
+    THURSDAY = 5,
+    FRIDAY = 6,
+    SATURDAY = 7
+}
+
+export { }

package/package.json

@@ -1,60 +1,58 @@
 {
   "name": "bmlt-query-client",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "A TypeScript client for querying BMLT (Basic Meeting List Tool) servers with built-in geocoding support",
   "type": "module",
-  "main": "dist/index.cjs.js",
-  "module": "dist/index.es.js",
-  "types": "dist/index.d.ts",
+  "main": "dist/app.js",
+  "module": "dist/app.js",
+  "types": "dist/app.d.ts",
+  "browser": "dist/app.js",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.es.js",
-      "require": "./dist/index.cjs.js"
+      "types": "./dist/app.d.ts",
+      "import": "./dist/app.js",
+      "browser": "./dist/app.js",
+      "default": "./dist/app.js"
     }
   },
   "scripts": {
     "build": "vite build",
-    "build:esm": "vite build --config vite.esm.config.ts",
-    "build:all": "npm run build && npm run build:esm",
-    "dev": "vite build --watch",
+    "clean": "rimraf dist",
     "test": "vitest",
-    "test:ui": "vitest --ui",
-    "lint": "eslint src --ext .ts",
-    "prepublishOnly": "npm run build:all",
-    "clean": "rimraf dist"
+    "test:ci": "vitest run",
+    "lint": "eslint src --ext ts",
+    "type-check": "tsc --noEmit"
   },
   "keywords": [
     "bmlt",
     "meetings",
     "recovery",
     "na",
-    "aa",
     "typescript",
     "geocoding",
     "api-client"
   ],
-  "author": "Your Name",
+  "author": "Patrick Joyce",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/your-username/bmlt-query-client.git"
+    "url": "https://github.com/bmlt-enabled/bmlt-query-client.git"
   },
   "dependencies": {
-    "p-retry": "^6.2.0",
-    "p-queue": "^8.0.1"
+    "p-queue": "^8.0.1",
+    "p-retry": "^6.2.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "@typescript-eslint/eslint-plugin": "^6.0.0",
     "@typescript-eslint/parser": "^6.0.0",
+    "@vitest/ui": "^3.2.4",
     "eslint": "^8.0.0",
     "rimraf": "^5.0.0",
     "typescript": "^5.0.0",
     "vite": "^7.0.0",
-    "vitest": "^3.0.0",
-    "@vitest/ui": "^3.2.4",
-    "vite-plugin-dts": "^4.5.4"
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^3.0.0"
   },
   "engines": {
     "node": ">=16"

package/vite.config.ts

@@ -1,35 +1,28 @@
-/// <reference types="vitest/config" />
-
 import { defineConfig } from 'vite';
 import { resolve } from 'path';
 import dts from 'vite-plugin-dts';
 
+// ES Module build for direct browser import via <script type="module">
 export default defineConfig({
-  plugins: [dts()],
+  plugins: [
+    dts({
+      outDir: 'dist',
+      insertTypesEntry: true,
+      rollupTypes: true
+    })
+  ],
   build: {
     lib: {
       entry: resolve(__dirname, 'src/index.ts'),
-      name: 'BmltQueryClient',
-      fileName: (format) => `index.${format}.js`,
-      formats: ['es', 'cjs']
-    },
-    rollupOptions: {
-      external: ['axios', 'p-retry', 'p-queue'],
-      output: {
-        globals: {
-          axios: 'axios',
-          'p-retry': 'pRetry',
-          'p-queue': 'PQueue'
-        }
-      }
+      fileName: () => 'app.js',
+      formats: ['es']
     },
+    outDir: 'dist',
     sourcemap: true,
-    target: 'es2020'
-  },
-  test: {
-    environment: 'node',
-    globals: true,
-    timeout: 30000,
-    setupFiles: ['./test/setup.ts']
+    target: 'es2020',
+    rollupOptions: {
+      // Don't externalize any dependencies - bundle everything for browser use
+      external: []
+    }
   }
 });

package/vite.esm.config.ts

@@ -1,20 +0,0 @@
-import { defineConfig } from 'vite';
-import { resolve } from 'path';
-
-// ES Module build for direct browser import via <script type="module">
-export default defineConfig({
-  build: {
-    lib: {
-      entry: resolve(__dirname, 'src/index.ts'),
-      fileName: () => 'app.js',
-      formats: ['es']
-    },
-    outDir: 'dist',
-    sourcemap: true,
-    target: 'es2020',
-    rollupOptions: {
-      // Don't externalize any dependencies - bundle everything for browser use
-      external: []
-    }
-  }
-});