bmlt-query-client 1.1.0 → 1.2.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,59 @@
+# 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.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.2.0...HEAD
+[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
      */
@@ -729,9 +746,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 +996,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) */