bmlt-query-client 1.1.0 → 1.3.0

package/AGENTS.md

@@ -97,6 +97,20 @@ Key rules:
 4. Export any new public types from `src/types/index.ts` and any new public classes/functions from `src/index.ts`.
 5. Add a usage example in `examples/basic-usage.ts`.
 6. Add or extend a test in `test/basic.test.ts`.
+7. Update `CHANGELOG.md` under `[Unreleased]`.
+
+## Raw Query
+
+`BmltClient.rawQuery<T>(queryString, format?)` sends a raw BMLT query string directly to the server. The first token is treated as the switcher value when it has no `=` sign:
+
+- `'GetSearchResults&venue_types=2'` → `switcher=GetSearchResults&venue_types=2`
+- `'switcher=GetSearchResults&venue_types=2'` → passed through unchanged
+
+The internal HTTP fetch+parse logic lives in the private `fetchAndParse` method shared with `makeRequest`. Do not duplicate it.
+
+## Array Parameters
+
+`meeting_key_value` in `SearchResultsParams` accepts `string | string[]`. The URL builder serialises arrays as repeated `key[]=value` entries (e.g. `meeting_key_value[]=USA&meeting_key_value[]=US`). This same pattern applies to all other array-typed parameters (`weekdays`, `venue_types`, `formats`, `services`, `root_server_ids`, `meeting_ids`).
 
 ## Geocoding
 

package/CHANGELOG.md

@@ -0,0 +1,80 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.3.0] - 2026-05-15
+
+### Added
+
+- `Meeting` response type now includes fields previously missing from the interface: `formats` (comma-separated format key strings), `phone_meeting_number`, `bus_lines`, `train_lines`, `shared_group_id_bigint`, `lang_enum`, `contact_name_1`/`contact_name_2`, `contact_phone_1`/`contact_phone_2`, `contact_email_1`/`contact_email_2`, and `admin_notes`.
+- `ServerInfo` response type rewritten to match the actual `GetServerInfo` response: added `versionInt`, `centerLongitude`, `centerLatitude`, `centerZoom`, `defaultDuration`, `regionBias`, `charSet`, `distanceUnits`, `semanticAdmin`, `changesPerMeeting`, `meeting_states_and_provinces`, `meeting_counties_and_sub_provinces`, `available_keys`, `google_api_key`, `dbVersion`, `dbPrefix`, `phpVersion`, `auto_geocoding_enabled`, `county_auto_geocoding_enabled`, `zip_auto_geocoding_enabled`, `commit`, `default_closed_status`, and `aggregator_mode_enabled`.
+
+### Changed
+
+- **Breaking:** `Meeting` numeric fields are now typed as `string` to match the actual JSON response (BMLT returns these as quoted strings): `weekday_tinyint`, `venue_type`, `published`, `latitude`, `longitude`, `distance_in_km`, `distance_in_miles`.
+- **Breaking:** `ServiceBody` fields `description`, `url`, `helpline`, `world_id`, and `parent_id` are now required (the server always returns them, possibly as empty strings).
+- **Breaking:** `Format` fields `world_id` and `format_type_enum` are now required (the server always returns them, possibly as empty strings).
+- **Breaking:** `ServerInfo` interface no longer includes the fictional fields `availableEndpoints`, `supportedFormats`, `name`, `description`, or `coverageArea`. `langs` is now a comma-separated `string` (was `string[]`).
+- **Breaking:** `CoverageArea` rewritten with the actual response fields (`nw_corner_longitude`, `nw_corner_latitude`, `se_corner_longitude`, `se_corner_latitude` — all numeric strings); replaces the previous `north_latitude`/`south_latitude`/`east_longitude`/`west_longitude` fields.
+- `BmltClient.getServerInfo()` and `getCoverageArea()` now unwrap the single-element array returned by the server, preserving the single-object return type.
+
+### Fixed
+
+- Misleading doc comment on `Meeting.format_shared_id_list` — clarified that this field is comma-separated format IDs while the new `formats` field is comma-separated format key strings.
+
+## [1.2.0] - 2026-05-12
+
+### Added
+
+- `BmltClient.rawQuery<T>(queryString, format?)` — execute a raw BMLT query string directly against the server. The switcher can be written as a bare endpoint name (`GetSearchResults&...`) or with the explicit `switcher=` key (`switcher=GetSearchResults&...`).
+- `meeting_key_value` in `SearchResultsParams` now accepts `string | string[]`, enabling multi-value field searches (e.g. `meeting_key_value: ['USA', 'US']` serialises as `meeting_key_value[]=USA&meeting_key_value[]=US`).
+- `MeetingQueryBuilder.fieldValue()` now accepts `string | string[]` to match multiple values for a field key.
+- Raw query input section added to the browser demo (`docs/index.html`).
+
+## [1.1.0] - 2026-04-27
+
+### Added
+
+- `BmltClient.searchMeetingsWithFormats()` — fetches meetings and the formats they reference in a single round-trip using `get_used_formats=true`. Avoids a separate `getFormats()` call on large servers.
+- `MeetingQueryBuilder.executeWithFormats()` — equivalent fluent builder method that returns `MeetingsWithFormats`.
+- `BmltClient.getServerURL()` and `BmltClient.setServerURL()` — read and update the server URL after construction.
+- `findDuplicateMeetings(lists, options?)` utility — identifies the same meeting appearing across multiple result lists. Configurable comparison fields and normalization.
+- `countUniqueGroups(meetings)` utility — counts distinct groups (service body + meeting name) in a meeting list.
+- Additional language codes added to the `Language` enum.
+
+## [1.0.6] - 2026-03-26
+
+### Fixed
+
+- Response type corrections in `responses.ts`.
+
+### Changed
+
+- Dependency updates.
+
+## [1.0.0] - 2025-09-06
+
+### Added
+
+- Initial release.
+- `BmltClient` with full BMLT Semantic API coverage: `searchMeetings`, `getFormats`, `getServiceBodies`, `getChanges`, `getFieldKeys`, `getFieldValues`, `getNAWSDump`, `getServerInfo`, `getCoverageArea`.
+- `MeetingQueryBuilder` — fluent, chainable query builder for meeting searches.
+- `QuickSearch` — convenience helpers (`today()`, `virtual()`, `evening()`, `weekend()`, etc.).
+- Built-in geocoding via OpenStreetMap Nominatim with rate limiting and retry.
+- `BmltClient.searchMeetingsByAddress()` and `searchMeetingsByCoordinates()` for geographic searches.
+- `BmltClient.geocodeAddress()` and `reverseGeocode()`.
+- Configurable user agent, timeout, default format, and geocoding options.
+- `BmltQueryError` / `BmltErrorType` for typed error handling.
+- Zero external runtime dependencies — p-queue and p-retry are bundled via Vite.
+- ES module only; native `fetch` API; TypeScript declarations included.
+
+[Unreleased]: https://github.com/bmlt-enabled/bmlt-query-client/compare/v1.3.0...HEAD
+[1.3.0]: https://github.com/bmlt-enabled/bmlt-query-client/compare/v1.2.0...v1.3.0
+[1.2.0]: https://github.com/bmlt-enabled/bmlt-query-client/compare/v1.1.0...v1.2.0
+[1.1.0]: https://github.com/bmlt-enabled/bmlt-query-client/compare/v1.0.6...v1.1.0
+[1.0.6]: https://github.com/bmlt-enabled/bmlt-query-client/compare/v1.0.0...v1.0.6
+[1.0.0]: https://github.com/bmlt-enabled/bmlt-query-client/releases/tag/v1.0.0

package/README.md

@@ -183,6 +183,44 @@ const todaysVirtualMeetings = await quickSearch
   .execute();
 ```
 
+### Raw Query
+
+When you need to pass a BMLT query string exactly as-is — including parameters like `meeting_key_value[]` that match multiple values — use `rawQuery`:
+
+```javascript
+// Bare endpoint shorthand (most common)
+const meetings = await client.rawQuery(
+  'GetSearchResults&venue_types=2&meeting_key=location_nation&meeting_key_value[]=USA&meeting_key_value[]=US'
+);
+
+// Explicit switcher= form also works
+const meetings2 = await client.rawQuery('switcher=GetSearchResults&page_size=10');
+
+// With get_used_formats — returns { meetings, formats }
+import type { MeetingsWithFormats } from 'bmlt-query-client';
+
+const result = await client.rawQuery<MeetingsWithFormats>(
+  'GetSearchResults&get_used_formats=1&venue_types=2'
+);
+```
+
+Multi-value `meeting_key_value` is also available through the typed API:
+
+```javascript
+// Typed params — array serialises as meeting_key_value[]=USA&meeting_key_value[]=US
+const meetings = await client.searchMeetings({
+  venue_types: VenueType.IN_PERSON,
+  meeting_key: 'location_nation',
+  meeting_key_value: ['USA', 'US'],
+});
+
+// Or via query builder
+const meetings2 = await new MeetingQueryBuilder(client)
+  .inPersonOnly()
+  .fieldValue('location_nation', ['USA', 'US'])
+  .execute();
+```
+
 ### Finding Duplicate Meetings
 
 When querying meetings from multiple service bodies or servers, use `findDuplicateMeetings` to identify the same meeting appearing in more than one list:

package/dist/app.d.ts

@@ -14,10 +14,27 @@ export declare class BmltClient {
     private serverURL;
     private defaultFormat;
     constructor(options: BmltClientOptions);
+    /**
+     * Fetch a URL and parse the response according to format
+     */
+    private fetchAndParse;
     /**
      * Make a request to the BMLT API
      */
     private makeRequest;
+    /**
+     * Execute a raw BMLT query string against the server.
+     *
+     * Pass the query exactly as you'd append it to a BMLT URL.  The switcher
+     * can be written with or without the key name:
+     *
+     *   // bare endpoint name — most common shorthand
+     *   client.rawQuery('GetSearchResults&venue_types=2&meeting_key=location_nation&meeting_key_value[]=USA&meeting_key_value[]=US')
+     *
+     *   // explicit switcher= key also works
+     *   client.rawQuery('switcher=GetSearchResults&venue_types=2')
+     */
+    rawQuery<T = unknown>(queryString: string, format?: BmltDataFormat): Promise<T>;
     /**
      * Search for meetings
      */
@@ -75,11 +92,11 @@ export declare class BmltClient {
     /**
      * Geocode an address using the built-in geocoding service
      */
-    geocodeAddress(address: string, options?: Partial<GeocodeOptions>): Promise<GeocodeResult>;
+    geocodeAddress(address: string, options?: Partial<GeocodeOptions>): Promise< GeocodeResult>;
     /**
      * Reverse geocode coordinates to an address
      */
-    reverseGeocode(coordinates: Coordinates, options?: Partial<GeocodeOptions>): Promise<GeocodeResult>;
+    reverseGeocode(coordinates: Coordinates, options?: Partial<GeocodeOptions>): Promise< GeocodeResult>;
     /**
      * Get the server URL
      */
@@ -294,14 +311,14 @@ export declare interface Coordinates {
 export declare function countUniqueGroups(meetings: Meeting[]): 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;
+    /** Northwest corner longitude as a numeric string */
+    nw_corner_longitude: string;
+    /** Northwest corner latitude as a numeric string */
+    nw_corner_latitude: string;
+    /** Southeast corner longitude as a numeric string */
+    se_corner_longitude: string;
+    /** Southeast corner latitude as a numeric string */
+    se_corner_latitude: string;
 }
 
 /** A single meeting paired with the index of the list it came from */
@@ -438,10 +455,10 @@ export declare interface Format {
     description_string: string;
     /** Language */
     lang: string;
-    /** World format ID */
-    world_id?: string;
-    /** Format type enum */
-    format_type_enum?: string;
+    /** World format ID (may be empty string) */
+    world_id: string;
+    /** Format type enum (may be empty string) */
+    format_type_enum: string;
     /** Root server URI (for aggregator mode) */
     root_server_uri?: string;
 }
@@ -579,10 +596,10 @@ export declare enum Language {
 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;
+    /** Weekday (1-7) as a numeric string */
+    weekday_tinyint: string;
+    /** Venue type (1=In-person, 2=Virtual, 3=Hybrid) as a numeric string */
+    venue_type: string;
     /** Start time (24-hour format HH:MM:SS) */
     start_time: string;
     /** Duration time (HH:MM:SS) */
@@ -611,12 +628,12 @@ export declare interface Meeting {
     location_sub_province?: string;
     /** Location nation */
     location_nation?: string;
-    /** Latitude */
-    latitude: number;
-    /** Longitude */
-    longitude: number;
-    /** Published status (0=unpublished, 1=published) */
-    published: number;
+    /** Latitude as a numeric string */
+    latitude: string;
+    /** Longitude as a numeric string */
+    longitude: string;
+    /** Published status (0=unpublished, 1=published) as a numeric string */
+    published: string;
     /** Email contact */
     email_contact?: string;
     /** World Committee Code */
@@ -625,20 +642,46 @@ export declare interface Meeting {
     service_body_bigint: string;
     /** Service body Name */
     service_body_name?: string;
+    /** Shared group ID */
+    shared_group_id_bigint?: string;
+    /** Meeting formats (comma-separated format key strings, e.g. "O,D,NS,FD") */
+    formats: string;
     /** Meeting formats (comma-separated format IDs) */
     format_shared_id_list?: string;
+    /** Language enum (e.g. "en") */
+    lang_enum?: string;
     /** Meeting comments */
     comments?: string;
     /** Virtual meeting URL */
     virtual_meeting_link?: string;
     /** Virtual meeting additional info */
     virtual_meeting_additional_info?: string;
+    /** Phone meeting number (may be empty string) */
+    phone_meeting_number: string;
+    /** Bus lines serving the meeting location (may be empty string) */
+    bus_lines: string;
+    /** Train lines serving the meeting location (may be empty string) */
+    train_lines: string;
+    /** Primary contact name (only returned to authenticated admins) */
+    contact_name_1?: string;
+    /** Secondary contact name (only returned to authenticated admins) */
+    contact_name_2?: string;
+    /** Primary contact phone (only returned to authenticated admins) */
+    contact_phone_1?: string;
+    /** Secondary contact phone (only returned to authenticated admins) */
+    contact_phone_2?: string;
+    /** Primary contact email (only returned to authenticated admins) */
+    contact_email_1?: string;
+    /** Secondary contact email (only returned to authenticated admins) */
+    contact_email_2?: string;
+    /** Admin notes (only returned to authenticated admins) */
+    admin_notes?: 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;
+    /** Distance from search point in km as a numeric string (when using geographic search; may be empty string otherwise) */
+    distance_in_km?: string;
+    /** Distance from search point in miles as a numeric string (when using geographic search; may be empty string otherwise) */
+    distance_in_miles?: string;
 }
 
 export declare class MeetingQueryBuilder {
@@ -729,9 +772,9 @@ export declare class MeetingQueryBuilder {
      */
     nearCoordinates(coordinates: Coordinates, radiusMiles?: number, radiusKm?: number): this;
     /**
-     * Search for specific field value
+     * Search for specific field value; pass an array to match any of multiple values
      */
-    fieldValue(fieldKey: string, value: string): this;
+    fieldValue(fieldKey: string, value: string | string[]): this;
     /**
      * Return only specific fields
      */
@@ -979,8 +1022,8 @@ export declare interface SearchResultsParams extends BaseSearchParams {
     sort_results_by_distance?: boolean;
     /** Search for specific field value */
     meeting_key?: string;
-    /** The value to search for */
-    meeting_key_value?: string;
+    /** The value to search for; pass an array to match any of multiple values */
+    meeting_key_value?: string | string[];
     /** Return only specific fields (comma-separated) */
     data_field_key?: string;
     /** Sort results by specific fields (comma-separated) */
@@ -998,22 +1041,58 @@ export declare interface SearchResultsParams extends BaseSearchParams {
 }
 
 export declare interface ServerInfo {
-    /** Server version */
+    /** Server version (e.g. "4.2.0") */
     version: string;
-    /** Available endpoints */
-    availableEndpoints: string[];
-    /** Supported formats */
-    supportedFormats: string[];
-    /** Supported languages */
-    langs: string[];
-    /** Native language */
+    /** Server version as integer string (e.g. "4002000") */
+    versionInt: string;
+    /** Supported languages, comma-separated (e.g. "da,de,el,en,es") */
+    langs: string;
+    /** Native language code (e.g. "en") */
     nativeLang: string;
-    /** Server name */
-    name?: string;
-    /** Server description */
-    description?: string;
-    /** Coverage area information */
-    coverageArea?: CoverageArea;
+    /** Map center longitude as a numeric string */
+    centerLongitude: string;
+    /** Map center latitude as a numeric string */
+    centerLatitude: string;
+    /** Default map zoom level as a numeric string */
+    centerZoom: string;
+    /** Default meeting duration (HH:MM:SS) */
+    defaultDuration: string;
+    /** Region bias for geocoding (e.g. "us") */
+    regionBias: string;
+    /** Character set (e.g. "UTF-8") */
+    charSet: string;
+    /** Distance units ("mi" or "km") */
+    distanceUnits: string;
+    /** Semantic admin enabled flag as a numeric string ("0" or "1") */
+    semanticAdmin: string;
+    /** Number of changes tracked per meeting as a numeric string */
+    changesPerMeeting: string;
+    /** Comma-separated list of states/provinces with meetings */
+    meeting_states_and_provinces: string;
+    /** Comma-separated list of counties/sub-provinces with meetings */
+    meeting_counties_and_sub_provinces: string;
+    /** Comma-separated list of meeting fields available in search results */
+    available_keys: string;
+    /** Google Maps API key */
+    google_api_key: string;
+    /** Database migration version */
+    dbVersion: string;
+    /** Database table prefix */
+    dbPrefix: string;
+    /** PHP version running on the server */
+    phpVersion: string;
+    /** Whether automatic geocoding is enabled */
+    auto_geocoding_enabled: boolean;
+    /** Whether county auto-geocoding is enabled */
+    county_auto_geocoding_enabled: boolean;
+    /** Whether ZIP auto-geocoding is enabled */
+    zip_auto_geocoding_enabled: boolean;
+    /** Git commit hash of the server build */
+    commit: string;
+    /** Whether new meetings default to closed status */
+    default_closed_status: boolean;
+    /** Whether aggregator mode is enabled */
+    aggregator_mode_enabled: boolean;
 }
 
 export declare interface ServiceBodiesParams extends BaseSearchParams {
@@ -1030,18 +1109,18 @@ export declare interface ServiceBody {
     id: string;
     /** Service body name */
     name: string;
-    /** Service body description */
-    description?: string;
+    /** Service body description (may be empty string) */
+    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;
+    /** Service body URL (may be empty string) */
+    url: string;
+    /** Help line (may be empty string) */
+    helpline: string;
+    /** World service committee code (may be empty string) */
+    world_id: string;
+    /** Parent service body ID ("0" for root service bodies) */
+    parent_id: string;
     /** Root server URI (for aggregator mode) */
     root_server_uri?: string;
 }