bmlt-query-client 1.0.5 → 1.0.7

package/AGENTS.md

@@ -0,0 +1,124 @@
+# AGENTS.md
+
+This file provides guidance for AI agents working in this repository.
+
+## Project Overview
+
+`bmlt-query-client` is a TypeScript/ES module client library for querying [BMLT (Basic Meeting List Tool)](https://bmlt.app) servers. It wraps the BMLT Semantic API with a zero-external-dependency bundle, a fluent query builder, and built-in geocoding via OpenStreetMap Nominatim.
+
+Published to NPM as `bmlt-query-client`. Minimum Node.js version: 22.
+
+## Repository Layout
+
+```
+src/
+  client/
+    bmlt-client.ts       # Main BmltClient class — primary public API
+    query-builder.ts     # MeetingQueryBuilder (fluent) and QuickSearch helpers
+  services/
+    geocoding.ts         # Nominatim geocoding with rate limiting and retry
+  types/
+    base.ts              # Enums: BmltDataFormat, BmltEndpoint, Weekday, VenueType, etc.
+    requests.ts          # Request parameter interfaces for each BMLT endpoint
+    responses.ts         # Response types: Meeting, Format, ServiceBody, etc.
+    index.ts             # Re-exports all types
+  utils/
+    errors.ts            # BmltQueryError, BmltErrorType enum, ErrorHandler
+    url-builder.ts       # URL construction and parameter validation
+  index.ts               # Public package exports
+
+test/
+  basic.test.ts          # Integration tests against the NYC BMLT demo server
+  setup.ts               # Vitest setup
+
+examples/
+  basic-usage.ts         # Runnable usage examples
+
+docs/
+  index.html             # Browser demo using the ES module directly
+```
+
+## Common Commands
+
+```bash
+npm install          # Install dependencies
+npm run build        # Compile TypeScript → dist/ (Vite + vite-plugin-dts)
+npm run type-check   # Type-check without emitting
+npm run lint         # ESLint on src/
+npm run format       # Prettier auto-format
+npm run format:check # Check formatting without modifying files
+npm test             # Run Vitest integration tests (requires network)
+npm run clean        # Delete dist/
+```
+
+## Build Output
+
+Vite produces a single ES module bundle:
+
+- `dist/app.js` — bundle with p-queue and p-retry inlined (~55 KB, ~15 KB gzipped)
+- `dist/app.d.ts` — TypeScript declarations (generated by vite-plugin-dts)
+- `dist/app.js.map` — source map
+
+The package is ESM-only (`"type": "module"` in package.json). Do not add CommonJS output.
+
+## Testing
+
+Tests in `test/basic.test.ts` are **integration tests** that call the live NYC BMLT demo server (`https://latest.aws.bmlt.app/main_server`). There are no unit tests with mocks.
+
+- Run `npm test` to execute all tests.
+- Tests verify real API response shapes and client behaviour including error scenarios.
+- Do not add mock-based tests; keep tests hitting the real demo server.
+- If a test requires network access and CI is offline, mark it with `test.skip`.
+
+## Code Style
+
+Enforced by Prettier and ESLint — run `npm run format` and `npm run lint` before committing.
+
+Key rules:
+
+- 2-space indentation, single quotes, semicolons required, trailing commas (ES5), 100-char line width.
+- `const` over `let`; `var` is banned.
+- TypeScript strict mode is on; avoid `any`.
+- Arrow functions: no parentheses for single parameters (`x => x`, not `(x) => x`).
+
+## Architecture Constraints
+
+- **Zero runtime dependencies in the bundle.** `p-queue` and `p-retry` are bundled via Vite. Do not add new production dependencies without bundling them. Verify with `npm run build` and inspect `dist/app.js`.
+- **No CommonJS.** All source files use ES module syntax (`import`/`export`). `tsconfig.json` targets `ESNext` modules.
+- **Native fetch only.** HTTP requests use the global `fetch` API (Node 22 built-in). Do not introduce axios, node-fetch, or similar.
+- **Enums over magic strings.** Use `Weekday`, `VenueType`, `BmltEndpoint`, etc. when representing BMLT-specific values.
+- **Custom error types.** Throw `BmltQueryError` (from `src/utils/errors.ts`), never plain `Error`, for library errors. Use `BmltErrorType` to classify the error.
+
+## Adding or Changing API Surface
+
+1. Add or update the relevant type in `src/types/requests.ts` or `src/types/responses.ts`.
+2. Implement or update the method in `src/client/bmlt-client.ts`.
+3. If the feature is chainable, expose it via `MeetingQueryBuilder` in `src/client/query-builder.ts`.
+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`.
+
+## Geocoding
+
+The geocoding service (`src/services/geocoding.ts`) calls OpenStreetMap Nominatim. Key constraints:
+
+- Rate limit: 1 request per second by default (configurable via `GeocodeOptions`).
+- Uses `p-queue` for queuing and `p-retry` for exponential backoff.
+- Respects Nominatim's usage policy — do not remove the rate limiter.
+- Default country bias: `'us'`. Callers can override via `GeocodeOptions`.
+
+## CI/CD
+
+GitHub Actions (`.github/workflows/ci-cd.yml`):
+
+- **test job**: runs on push and PRs; matrix over Node 22 and 24; runs lint → build → test.
+- **publish job**: triggered on version tags (`v*`); publishes to NPM using `NPM_TOKEN` secret and creates a GitHub Release.
+- **security job**: runs `npm audit --audit-level moderate` on every push/PR.
+
+Publishing is tag-driven. To release, create and push a semver tag (e.g., `v1.1.0`).
+
+## Key Invariants
+
+- `dist/` is generated and must not be committed.
+- `package.json` version is updated automatically by the publish CI job from the git tag.
+- The BMLT demo server URL (`https://latest.aws.bmlt.app/main_server`) is used only in tests and examples — it must not be hardcoded in library source.

package/dist/app.d.ts

@@ -22,6 +22,16 @@ export declare class BmltClient {
      * Search for meetings
      */
     searchMeetings(params?: SearchResultsParams): Promise<Meeting[]>;
+    /**
+     * Search for meetings and return both meetings and the formats they reference in a
+     * single request. Uses get_used_formats=true so the server wraps the response as
+     * { meetings: Meeting[], formats: Format[] } instead of a bare Meeting[].
+     *
+     * This replaces the common pattern of Promise.all([getFormats(), searchMeetings()])
+     * with a single round-trip, which matters for large servers where getFormats() can
+     * return hundreds of unused format records.
+     */
+    searchMeetingsWithFormats(params?: Omit<SearchResultsParams, 'get_used_formats' | 'get_formats_only'>): Promise<MeetingsWithFormats>;
     /**
      * Search for meetings by geographic location using geocoding
      */
@@ -364,7 +374,7 @@ export declare interface FieldValuesParams extends BaseSearchParams {
 
 export declare interface Format {
     /** Format ID */
-    shared_id_bigint: string;
+    id: string;
     /** Format key string */
     key_string: string;
     /** Format name */
@@ -373,6 +383,10 @@ export declare interface Format {
     description_string: string;
     /** Language */
     lang: string;
+    /** World format ID */
+    world_id?: string;
+    /** Format type enum */
+    format_type_enum?: string;
     /** Root server URI (for aggregator mode) */
     root_server_uri?: string;
 }
@@ -718,12 +732,29 @@ export declare class MeetingQueryBuilder {
      * Execute the search and return results
      */
     execute(): Promise<Meeting[]>;
+    /**
+     * Execute the search and return both meetings and the formats they reference
+     * in a single request. Equivalent to execute() but avoids a separate getFormats() call.
+     */
+    executeWithFormats(): Promise<MeetingsWithFormats>;
     /**
      * Execute the search by geocoding an address first
      */
     executeNearAddress(address: string, radiusMiles?: number, radiusKm?: number, sortByDistance?: boolean): Promise<Meeting[]>;
 }
 
+/**
+ * Combined response when get_used_formats=true is passed to GetSearchResults.
+ * The BMLT API wraps the response in an object with separate meetings and formats arrays
+ * instead of returning a bare meetings array.
+ */
+export declare interface MeetingsWithFormats {
+    /** Meetings matching the search criteria */
+    meetings: Meeting[];
+    /** Only the formats actually referenced by the returned meetings */
+    formats: Format[];
+}
+
 /**
  * Convert miles to kilometers
  */