bmlt-query-client 1.4.1 → 1.5.0

package/.claude/settings.local.json

@@ -1,10 +1,17 @@
 {
   "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)"
+      "Bash(npm view:*)",
+      "Bash(npm ls *)",
+      "Bash(curl -s https://raw.githubusercontent.com/qmhc/unplugin-dts/main/README.md)",
+      "Bash(curl -s https://raw.githubusercontent.com/qmhc/unplugin-dts/main/docs/en/migration-v4-to-v5.md)",
+      "Bash(npm run *)",
+      "Bash(npm test *)",
+      "Bash(tar -xzf bmlt-query-client-1.4.0.tgz)",
+      "Bash(grep -nA 12 '\"scripts\"' /Users/patrick/workspace/git/bmlt-enabled/bmlt-query-client/package.json)",
+      "Bash(grep -nA 3 \"interface Format\" /Users/patrick/workspace/git/bmlt-enabled/crumb-widget/node_modules/bmlt-query-client/dist/app.d.ts)",
+      "Bash(grep -nA 30 \"^function makeMeeting\\\\|^function rawMeeting\\\\|^function rawFormat\\\\|^function makeFormat\\\\|^  function makeGeoMeeting\\\\|^  function makeFormat\" src/tests/unit/format.test.ts src/tests/unit/data.svelte.test.ts src/tests/unit/Controls.svelte.test.ts)",
+      "Bash(grep -nA 30 \"^function makeMeeting\" src/tests/unit/MapView.svelte.test.ts src/tests/unit/MeetingDetail.svelte.test.ts src/tests/unit/MeetingList.svelte.test.ts)"
     ]
-  },
-  "disabledMcpjsonServers": [
-    "laravel-boost"
-  ]
+  }
 }

package/CHANGELOG.md

@@ -6,6 +6,19 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [Unreleased]
 
+## [1.5.0] - 2026-09-13
+
+### Added
+
+- Virtual-meeting ordering params on `SearchResultsParams`, mirroring the BMLT aggregator's timezone-aware "starting soonest" support: `sort_results_by_next_start` (order by each meeting's next occurrence as an absolute instant), `next_start_grace_minutes` (keep recently-started meetings sorting high), and `target_time_zone` (evaluate weekday/time-of-day filters in the reader's IANA zone). All three are aggregator-mode only and ignored on ordinary root servers.
+- Fluent builder helpers `MeetingQueryBuilder.sortByNextStart(graceMinutes?)` and `.targetTimeZone(tz)`, plus `QuickSearch.virtualSoonest(tz?)` (virtual + hybrid, ordered soonest-first).
+
+## [1.4.2] - 2026-05-19
+
+### Fixed
+
+- `countUniqueGroups` now matches crouton's long-standing definition: groups are identified by `(service_body, normalized meeting name, location)` — physical coordinates for in-person/hybrid (`venue_type !== 2`), virtual link + additional info for virtual (`venue_type === 2`). The previous algorithm keyed only on `(service_body, name)`, which under-counted whenever two distinct home groups happened to share a name but met at different locations (real-world example: MCANA returned 12 groups vs. crouton's 17 for the same 30 meetings). Bug; widget headers and downstream callers now agree with crouton.
+
 ## [1.4.1] - 2026-05-15
 
 ### Fixed
@@ -92,7 +105,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 - 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.4.1...HEAD
+[Unreleased]: https://github.com/bmlt-enabled/bmlt-query-client/compare/v1.4.2...HEAD
+[1.4.2]: https://github.com/bmlt-enabled/bmlt-query-client/compare/v1.4.1...v1.4.2
 [1.4.1]: https://github.com/bmlt-enabled/bmlt-query-client/compare/v1.4.0...v1.4.1
 [1.4.0]: https://github.com/bmlt-enabled/bmlt-query-client/compare/v1.3.0...v1.4.0
 [1.3.0]: https://github.com/bmlt-enabled/bmlt-query-client/compare/v1.2.0...v1.3.0

package/CLAUDE.md

@@ -0,0 +1,39 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+TypeScript client library for querying BMLT (Basic Meeting List Tool) servers with built-in Nominatim geocoding. Published to NPM as `bmlt-query-client`. ESM-only, targets Node.js 20+ and modern browsers (ES2020).
+
+## Commands
+
+- **Build:** `npm run build` (Vite → `dist/app.js` single ES module + type declarations)
+- **Test:** `npm test` (Vitest, runs integration tests against live server `https://latest.aws.bmlt.app/main_server`)
+- **Lint:** `npm run lint`
+- **Format:** `npm run format` (Prettier) / `npm run format:check`
+- **Type check:** `npm run type-check` (tsc --noEmit)
+- **Clean:** `npm run clean` (removes dist/)
+
+Tests hit a real BMLT server and Nominatim, so they require network access and have 15-second timeouts.
+
+## Architecture
+
+**Entry point:** `src/index.ts` — re-exports everything from the modules below.
+
+**Core modules:**
+
+- `src/client/bmlt-client.ts` — **BmltClient** class. Main API client wrapping all BMLT endpoints (searchMeetings, getFormats, getServiceBodies, getChanges, getFieldKeys, getFieldValues, getNAWSDump, getServerInfo, getCoverageArea). Also provides geocoded search methods (searchMeetingsByAddress, searchMeetingsByCoordinates) and reverse geocoding.
+- `src/client/query-builder.ts` — **MeetingQueryBuilder** (fluent/chainable query API) and **QuickSearch** (convenience presets like today(), weekend(), virtual()). QueryBuilder holds a reference to BmltClient and delegates execution.
+- `src/services/geocoding.ts` — **GeocodingService** wrapping Nominatim OpenStreetMap API with rate limiting (p-queue) and retry logic (p-retry).
+- `src/utils/url-builder.ts` — URL construction and parameter validation for BMLT API calls.
+- `src/utils/errors.ts` — **BmltQueryError** custom error class with BmltErrorType enum, plus ErrorFactory, ErrorHandler, and RetryHandler utilities.
+- `src/types/` — TypeScript interfaces and enums: BmltDataFormat, BmltEndpoint, Weekday (1-7, Sun-Sat), VenueType (1-3), SortKey, Language, request/response interfaces.
+
+**Build output:** Vite bundles all dependencies (including p-queue, p-retry) into a single `dist/app.js` with no externals, plus `dist/app.d.ts` type declarations.
+
+## Code Style
+
+- Strict TypeScript (`strict: true` in tsconfig)
+- Prettier: single quotes, trailing commas (es5), 100 char print width, 2-space indent, no semicolons optional (semi: true)
+- ESLint: prefer-const, no-var enforced

package/README.md

@@ -183,6 +183,27 @@ const todaysVirtualMeetings = await quickSearch
   .execute();
 ```
 
+### Virtual Meetings ("starting soonest")
+
+On an aggregator (`aggregator_mode_enabled`), the server can order virtual/hybrid
+meetings by whichever starts soonest across every timezone — handy for a
+"what can I join right now?" list. `QuickSearch.virtualSoonest(tz)` wires this up:
+
+```javascript
+const tz = Intl.DateTimeFormat().resolvedOptions().timeZone; // e.g. 'America/New_York'
+
+const result = await new QuickSearch(client)
+  .virtualSoonest(tz) // venue_types=[2,3] + sort_results_by_next_start + target_time_zone
+  .sortByNextStart(15) // optional: keep meetings that started ≤15 min ago near the top
+  .executeWithFormats();
+```
+
+These ordering params are **aggregator-mode only** — ordinary root servers ignore
+`sort_results_by_next_start`, `next_start_grace_minutes`, and `target_time_zone`,
+returning the venue-filtered meetings in their usual order. `target_time_zone`
+affects only filtering/ordering; each meeting's `start_time`/`weekday_tinyint`
+still come back in its own local time, so convert client-side for display.
+
 ### 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`:

package/dist/app.d.ts

@@ -304,9 +304,15 @@ export declare interface Coordinates {
 /**
  * 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.
+ * A "group" is identified by the combination of service body, meeting name
+ * (case-insensitive, trimmed), and meeting location — physical coordinates
+ * for in-person/hybrid (venue_type !== 2), or the virtual meeting link plus
+ * additional info for virtual (venue_type === 2). Multiple weekly meetings of
+ * the same group count once; two distinct groups that happen to share a name
+ * but meet at different locations count separately. Matches the long-standing
+ * "group_id" definition used by crouton.
+ *
+ * Meetings missing a service body or name are skipped.
  */
 export declare function countUniqueGroups(meetings: Meeting[]): number;
 
@@ -791,6 +797,19 @@ export declare class MeetingQueryBuilder {
      * Sort by distance (requires geographic search)
      */
     sortByDistance(): this;
+    /**
+     * Order results by each meeting's next upcoming start as an absolute instant
+     * ("starting soonest" across timezones). Optionally pass a grace window in
+     * minutes so recently-started meetings still sort near the top.
+     * Aggregator-mode only — ignored on ordinary root servers.
+     */
+    sortByNextStart(graceMinutes?: number): this;
+    /**
+     * Evaluate weekday/time-of-day filters against each meeting's next occurrence
+     * in the given IANA time zone (e.g. `'America/New_York'`).
+     * Aggregator-mode only — ignored on ordinary root servers.
+     */
+    targetTimeZone(tz: string): this;
     /**
      * Set pagination
      */
@@ -937,6 +956,14 @@ export declare class QuickSearch {
      * Search for in-person meetings only
      */
     inPerson(): MeetingQueryBuilder;
+    /**
+     * Find virtual + hybrid meetings ordered by which starts soonest across
+     * timezones. Pass the reader's IANA time zone (e.g. from
+     * `Intl.DateTimeFormat().resolvedOptions().timeZone`) to reckon any further
+     * weekday/time filters in their local zone. Aggregator-mode only — on
+     * ordinary root servers the ordering params are ignored.
+     */
+    virtualSoonest(tz?: string): MeetingQueryBuilder;
     /**
      * Search by meeting name or location
      */
@@ -1020,6 +1047,26 @@ export declare interface SearchResultsParams extends BaseSearchParams {
     geo_width_km?: number;
     /** Sort results by distance when using geographic search */
     sort_results_by_distance?: boolean;
+    /**
+     * Order results by each meeting's next upcoming start as an absolute instant
+     * (timezone-aware "starting soonest"), built for virtual meetings spanning
+     * timezones. Aggregator-mode only — ignored on ordinary root servers.
+     */
+    sort_results_by_next_start?: boolean;
+    /**
+     * Minutes (0–1440) to shift the "now" reference backward when using
+     * {@link sort_results_by_next_start}, so recently-started / in-progress
+     * meetings still sort near the top. Aggregator-mode only.
+     */
+    next_start_grace_minutes?: number;
+    /**
+     * IANA time zone (e.g. `'America/New_York'`) the reader is in. When set, the
+     * `weekdays` and start/end time-of-day filters are evaluated against each
+     * meeting's next occurrence converted into this zone. Aggregator-mode only —
+     * ignored on ordinary root servers. Note: this does not change the returned
+     * `start_time`/`weekday_tinyint`, which remain the meeting's native values.
+     */
+    target_time_zone?: string;
     /** Search for specific field value */
     meeting_key?: string;
     /** The value to search for; pass an array to match any of multiple values */