bmlt-query-client 1.0.7 → 1.0.9

package/.claude/settings.local.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(wc -l /Users/pjoyce/workspace/git/bmlt-enabled/bmlt-query-client/src/**/*.ts /Users/pjoyce/workspace/git/bmlt-enabled/bmlt-query-client/test/*.ts)"
+    ]
+  },
+  "disabledMcpjsonServers": [
+    "laravel-boost"
+  ]
+}

package/PROJECT_SUMMARY.md

@@ -87,7 +87,7 @@ import { BmltClient, Weekday, VenueType } from 'bmlt-query-client';
 
 // Initialize client with NYC demo server
 const client = new BmltClient({
-  rootServerURL: 'https://latest.aws.bmlt.app/main_server',
+  serverURL: 'https://latest.aws.bmlt.app/main_server',
 });
 
 // Search by address with automatic geocoding

package/README.md

@@ -38,7 +38,7 @@ The easiest way to use the BMLT Query Client in the browser is via ES modules:
 
   // Initialize the client
   const client = new BmltClient({
-    rootServerURL: 'https://latest.aws.bmlt.app/main_server', // NYC demo server
+    serverURL: 'https://latest.aws.bmlt.app/main_server', // NYC demo server
   });
 
   // Search for virtual meetings
@@ -72,7 +72,7 @@ npm install bmlt-query-client
 import { BmltClient, VenueType, MeetingQueryBuilder } from 'bmlt-query-client';
 
 const client = new BmltClient({
-  rootServerURL: 'https://your-bmlt-server.org/main_server',
+  serverURL: 'https://your-bmlt-server.org/main_server',
 });
 
 // Search for meetings
@@ -183,6 +183,50 @@ const todaysVirtualMeetings = await quickSearch
   .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:
+
+```javascript
+import { findDuplicateMeetings } from 'bmlt-query-client';
+
+const [listA, listB] = await Promise.all([
+  client.searchMeetings({ services: [1] }),
+  client.searchMeetings({ services: [2] }),
+]);
+
+const duplicates = findDuplicateMeetings([listA, listB]);
+
+for (const group of duplicates) {
+  console.log(`Duplicate: ${group.key}`);
+  for (const { meeting, listIndex } of group.entries) {
+    console.log(`  List ${listIndex}: id=${meeting.id_bigint}`);
+  }
+}
+```
+
+By default, meetings are compared on `weekday_tinyint`, `start_time`, `meeting_name`, and `location_text` (case-insensitive). You can customize the fields:
+
+```javascript
+// Compare only on name and street address
+const duplicates = findDuplicateMeetings([listA, listB], {
+  fields: ['meeting_name', 'location_street'],
+  normalize: true, // lowercase + trim (default)
+});
+```
+
+### Counting Unique Groups
+
+Use `countUniqueGroups` to get the total number of distinct groups in a meeting list. A group is identified by its service body plus meeting name (case-insensitive, trimmed), so multiple weekly occurrences of the same group count once:
+
+```javascript
+import { countUniqueGroups } from 'bmlt-query-client';
+
+const meetings = await client.searchMeetings();
+const total = countUniqueGroups(meetings);
+console.log(`Total unique groups: ${total}`);
+```
+
 ## Error Handling
 
 The client provides comprehensive error handling with specific error types:
@@ -253,9 +297,9 @@ console.log(client.getUserAgent()); // 'my-updated-app/2.0.0'
 client.setTimeout(60000); // 60 seconds
 console.log(client.getTimeout()); // 60000
 
-// Update root server URL
-client.setRootServerURL('https://new-server.org/main_server');
-console.log(client.getRootServerURL());
+// Update server URL
+client.setServerURL('https://new-server.org/main_server');
+console.log(client.getServerURL());
 
 // Update default data format
 client.setDefaultFormat(BmltDataFormat.JSONP);
@@ -266,7 +310,7 @@ console.log(client.getDefaultFormat());
 
 ```javascript
 const client = new BmltClient({
-  rootServerURL: 'https://your-server.org/main_server', // Required
+  serverURL: 'https://your-server.org/main_server', // Required
   defaultFormat: BmltDataFormat.JSON, // Optional
   timeout: 30000, // 30 seconds
   userAgent: 'my-app/1.0.0', // Custom user agent
@@ -283,7 +327,7 @@ const client = new BmltClient({
 
 ```javascript
 const client = new BmltClient({
-  rootServerURL: 'https://your-server.org/main_server',
+  serverURL: 'https://your-server.org/main_server',
   geocodingOptions: {
     countryCode: 'us', // ISO country code bias
     viewbox: [-74.2, 40.4, -73.7, 40.9], // Geographic bounding box [w,s,e,n]

package/dist/app.d.ts

@@ -11,7 +11,7 @@ export declare class BmltClient {
     private timeout;
     private userAgent;
     private readonly geocodingService?;
-    private rootServerURL;
+    private serverURL;
     private defaultFormat;
     constructor(options: BmltClientOptions);
     /**
@@ -81,13 +81,13 @@ export declare class BmltClient {
      */
     reverseGeocode(coordinates: Coordinates, options?: Partial<GeocodeOptions>): Promise<GeocodeResult>;
     /**
-     * Get the root server URL
+     * Get the server URL
      */
-    getRootServerURL(): string;
+    getServerURL(): string;
     /**
-     * Update the root server URL
+     * Update the server URL
      */
-    setRootServerURL(url: string): void;
+    setServerURL(url: string): void;
     /**
      * Get the default data format
      */
@@ -126,8 +126,8 @@ export declare class BmltClient {
 }
 
 export declare interface BmltClientOptions {
-    /** Root server URL */
-    rootServerURL: string;
+    /** Server URL */
+    serverURL: string;
     /** Default data format */
     defaultFormat?: BmltDataFormat;
     /** HTTP request timeout in milliseconds */
@@ -284,6 +284,15 @@ export declare interface Coordinates {
     longitude: number;
 }
 
+/**
+ * Count unique groups across a list of meetings.
+ *
+ * A "group" is identified by the combination of service body and meeting name
+ * (case-insensitive, trimmed), so multiple weekly meetings of the same group
+ * count once.
+ */
+export declare function countUniqueGroups(meetings: Meeting[]): number;
+
 export declare interface CoverageArea {
     /** North boundary */
     north_latitude: number;
@@ -295,6 +304,21 @@ export declare interface CoverageArea {
     west_longitude: number;
 }
 
+/** A single meeting paired with the index of the list it came from */
+export declare interface DuplicateMeetingEntry {
+    meeting: Meeting;
+    /** Index of the source list in the array passed to findDuplicateMeetings */
+    listIndex: number;
+}
+
+/** A group of meetings from different lists that match on the comparison key */
+export declare interface DuplicateMeetingGroup {
+    /** Composite key used for matching */
+    key: string;
+    /** All matching entries, one per occurrence across the lists */
+    entries: DuplicateMeetingEntry[];
+}
+
 /**
  * Factory class for creating specific error types
  */
@@ -372,6 +396,37 @@ export declare interface FieldValuesParams extends BaseSearchParams {
     all_formats?: boolean;
 }
 
+/**
+ * Find meetings that appear in more than one of the provided lists.
+ *
+ * Comparison is done via a composite key built from the specified fields
+ * (default: weekday, start time, meeting name, location). Only groups that
+ * span at least two different lists are returned.
+ *
+ * @example
+ * const duplicates = findDuplicateMeetings([listA, listB]);
+ * for (const group of duplicates) {
+ *   console.log(`Duplicate: ${group.key}`);
+ *   for (const { meeting, listIndex } of group.entries) {
+ *     console.log(`  List ${listIndex}: id=${meeting.id_bigint}`);
+ *   }
+ * }
+ */
+export declare function findDuplicateMeetings(meetingLists: Meeting[][], options?: FindDuplicatesOptions): DuplicateMeetingGroup[];
+
+export declare interface FindDuplicatesOptions {
+    /**
+     * Meeting fields used to build the composite comparison key.
+     * Defaults to weekday, start time, meeting name, and location.
+     */
+    fields?: Array<keyof Meeting>;
+    /**
+     * Normalize string values before comparing (lowercase + trim).
+     * Defaults to true.
+     */
+    normalize?: boolean;
+}
+
 export declare interface Format {
     /** Format ID */
     id: string;
@@ -640,6 +695,13 @@ export declare class MeetingQueryBuilder {
      * Search for specific text
      */
     searchText(text: string): this;
+    /**
+     * Search by address using server-side geocoding (StringSearchIsAnAddress=1).
+     * Note: typically broken on most BMLT servers because their Google API key uses
+     * HTTP referer restrictions rather than server IP allowlisting. Prefer
+     * BmltClient.searchMeetingsByAddress() which uses Nominatim client-side.
+     */
+    searchAddress(address: string, radius?: number): this;
     /**
      * Meetings starting after specific time
      */
@@ -881,6 +943,8 @@ export declare interface SearchResultsParams extends BaseSearchParams {
     SearchString?: string;
     /** Search radius for geographic searches */
     SearchStringRadius?: number;
+    /** Treat SearchString as an address and have the server geocode it. Note: typically broken on most servers because the Google API key uses HTTP referer restrictions rather than server IP allowlisting. Prefer searchMeetingsByAddress() which uses Nominatim client-side. */
+    StringSearchIsAnAddress?: boolean;
     /** Meetings starting after hour (0-23) */
     StartsAfterH?: number;
     /** Meetings starting after minute (0-59) */
@@ -989,7 +1053,7 @@ export declare enum SortKey {
 }
 
 export declare interface URLBuilderOptions {
-    rootServerURL: string;
+    serverURL: string;
     format: BmltDataFormat;
     endpoint: BmltEndpoint;
     parameters?: Record<string, unknown>;
@@ -1011,9 +1075,9 @@ export declare function validateEndpointFormat(endpoint: BmltEndpoint, format: B
 export declare function validateRadius(radius: number): void;
 
 /**
- * Clean and validate a root server URL
+ * Clean and validate a server URL
  */
-export declare function validateRootServerURL(url: string): string;
+export declare function validateServerURL(url: string): string;
 
 export declare enum VenueType {
     IN_PERSON = 1,