bmlt-query-client 1.4.2 → 1.5.0

package/CHANGELOG.md

@@ -6,6 +6,13 @@ 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

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

@@ -797,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
      */
@@ -943,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
      */
@@ -1026,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 */