bmlt-query-client 1.0.8 → 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/README.md

@@ -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:

package/dist/app.d.ts

@@ -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
      */
@@ -713,9 +775,9 @@ export declare class MeetingQueryBuilder {
      */
     formatsOnly(): this;
     /**
-     * Filter by server IDs (aggregator mode)
+     * Filter by root server IDs (aggregator mode)
      */
-    serverIds(serverIds: number | number[], exclude?: boolean): this;
+    rootServerIds(serverIds: number | number[], exclude?: boolean): this;
     /**
      * Get the current query parameters
      */
@@ -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) */
@@ -927,8 +991,8 @@ export declare interface SearchResultsParams extends BaseSearchParams {
     page_num?: number;
     /** Published status: undefined=published only, 0=all, -1=unpublished only */
     advanced_published?: 0 | -1;
-    /** Include specific server IDs (for aggregator mode) */
-    server_ids?: number | number[];
+    /** Include specific root server IDs (for aggregator mode) */
+    root_server_ids?: number | number[];
 }
 
 export declare interface ServerInfo {