actual types

Author: pjaudiomv

CHANGELOG.md

@@ -6,6 +6,19 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [Unreleased]
 
+## [1.4.0] - 2026-05-15
+
+### Added
+
+- Response transforms applied inside `searchMeetings`, `searchMeetingsByAddress`, `searchMeetingsByCoordinates`, `searchMeetingsWithFormats`, `getServerInfo`, and `getCoverageArea`. BMLT serializes numeric fields as quoted strings; the client now coerces them to real `number` values so consumers get idiomatic types without needing to parse manually.
+
+### Changed
+
+- **Breaking:** `Meeting` numeric fields are now typed and returned as `number` (were `string` in 1.3.0): `weekday_tinyint`, `venue_type`, `published`, `latitude`, `longitude`.
+- **Breaking:** `Meeting.distance_in_km` and `Meeting.distance_in_miles` are `number | undefined` (were `string | undefined`); the transform maps the empty strings BMLT returns for non-geographic searches to `undefined`.
+- **Breaking:** `ServerInfo` numeric fields are now `number` (were `string`): `versionInt`, `centerLongitude`, `centerLatitude`, `centerZoom`, `semanticAdmin`, `changesPerMeeting`.
+- **Breaking:** `CoverageArea` corner fields are now `number` (were `string`): `nw_corner_longitude`, `nw_corner_latitude`, `se_corner_longitude`, `se_corner_latitude`.
+
 ## [1.3.0] - 2026-05-15
 
 ### Added
@@ -72,7 +85,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.3.0...HEAD
+[Unreleased]: https://github.com/bmlt-enabled/bmlt-query-client/compare/v1.4.0...HEAD
+[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
 [1.2.0]: https://github.com/bmlt-enabled/bmlt-query-client/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/bmlt-enabled/bmlt-query-client/compare/v1.0.6...v1.1.0

package.json

@@ -1,6 +1,6 @@
 {
   "name": "bmlt-query-client",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "A TypeScript client for querying BMLT (Basic Meeting List Tool) servers with built-in geocoding support",
   "type": "module",
   "main": "dist/app.js",

src/client/bmlt-client.ts

@@ -35,6 +35,7 @@ import {
   validateRadius,
 } from '../utils/url-builder';
 import { ErrorHandler } from '../utils/errors';
+import { transformMeeting, transformServerInfo, transformCoverageArea } from '../utils/transforms';
 
 export interface BmltClientOptions {
   /** Server URL */
@@ -181,7 +182,12 @@ export class BmltClient {
    */
   async searchMeetings(params: SearchResultsParams = {}): Promise<Meeting[]> {
     const { format = this.defaultFormat, ...searchParams } = params;
-    return this.makeRequest<Meeting[]>(BmltEndpoint.GET_SEARCH_RESULTS, searchParams, format);
+    const result = await this.makeRequest<unknown[]>(
+      BmltEndpoint.GET_SEARCH_RESULTS,
+      searchParams,
+      format
+    );
+    return result.map(transformMeeting);
   }
 
   /**
@@ -197,11 +203,15 @@ export class BmltClient {
     params: Omit<SearchResultsParams, 'get_used_formats' | 'get_formats_only'> = {}
   ): Promise<MeetingsWithFormats> {
     const { format = this.defaultFormat, ...searchParams } = params;
-    return this.makeRequest<MeetingsWithFormats>(
+    const result = await this.makeRequest<{ meetings: unknown[]; formats: Format[] }>(
       BmltEndpoint.GET_SEARCH_RESULTS,
       { ...searchParams, get_used_formats: true },
       format
     );
+    return {
+      meetings: result.meetings.map(transformMeeting),
+      formats: result.formats,
+    };
   }
 
   /**
@@ -319,16 +329,16 @@ export class BmltClient {
    * Get server information
    */
   async getServerInfo(): Promise<ServerInfo> {
-    const result = await this.makeRequest<ServerInfo[]>(BmltEndpoint.GET_SERVER_INFO);
-    return result[0];
+    const result = await this.makeRequest<unknown[]>(BmltEndpoint.GET_SERVER_INFO);
+    return transformServerInfo(result[0]);
   }
 
   /**
    * Get server coverage area
    */
   async getCoverageArea(): Promise<CoverageArea> {
-    const result = await this.makeRequest<CoverageArea[]>(BmltEndpoint.GET_COVERAGE_AREA);
-    return result[0];
+    const result = await this.makeRequest<unknown[]>(BmltEndpoint.GET_COVERAGE_AREA);
+    return transformCoverageArea(result[0]);
   }
 
   /**

src/types/responses.ts

@@ -8,11 +8,11 @@ export interface Meeting {
   /** Meeting ID */
   id_bigint: string;
 
-  /** Weekday (1-7) as a numeric string */
-  weekday_tinyint: string;
+  /** Weekday (1=Sunday, 7=Saturday) */
+  weekday_tinyint: number;
 
-  /** Venue type (1=In-person, 2=Virtual, 3=Hybrid) as a numeric string */
-  venue_type: string;
+  /** Venue type (1=In-person, 2=Virtual, 3=Hybrid) */
+  venue_type: number;
 
   /** Start time (24-hour format HH:MM:SS) */
   start_time: string;
@@ -56,14 +56,14 @@ export interface Meeting {
   /** Location nation */
   location_nation?: string;
 
-  /** Latitude as a numeric string */
-  latitude: string;
+  /** Latitude */
+  latitude: number;
 
-  /** Longitude as a numeric string */
-  longitude: string;
+  /** Longitude */
+  longitude: number;
 
-  /** Published status (0=unpublished, 1=published) as a numeric string */
-  published: string;
+  /** Published status (0=unpublished, 1=published) */
+  published: number;
 
   /** Email contact */
   email_contact?: string;
@@ -131,11 +131,11 @@ export interface Meeting {
   /** Root server URI (for aggregator mode) */
   root_server_uri?: string;
 
-  /** Distance from search point in km as a numeric string (when using geographic search; may be empty string otherwise) */
-  distance_in_km?: string;
+  /** Distance from search point in km (undefined when not a geographic search) */
+  distance_in_km?: number;
 
-  /** Distance from search point in miles as a numeric string (when using geographic search; may be empty string otherwise) */
-  distance_in_miles?: string;
+  /** Distance from search point in miles (undefined when not a geographic search) */
+  distance_in_miles?: number;
 }
 
 export interface Format {
@@ -238,23 +238,23 @@ export interface ServerInfo {
   /** Server version (e.g. "4.2.0") */
   version: string;
 
-  /** Server version as integer string (e.g. "4002000") */
-  versionInt: string;
+  /** Server version as integer (e.g. 4002000) */
+  versionInt: number;
 
   /** Supported languages, comma-separated (e.g. "da,de,el,en,es") */
   langs: string;
 
   /** Native language code (e.g. "en") */
   nativeLang: string;
 
-  /** Map center longitude as a numeric string */
-  centerLongitude: string;
+  /** Map center longitude */
+  centerLongitude: number;
 
-  /** Map center latitude as a numeric string */
-  centerLatitude: string;
+  /** Map center latitude */
+  centerLatitude: number;
 
-  /** Default map zoom level as a numeric string */
-  centerZoom: string;
+  /** Default map zoom level */
+  centerZoom: number;
 
   /** Default meeting duration (HH:MM:SS) */
   defaultDuration: string;
@@ -268,11 +268,11 @@ export interface ServerInfo {
   /** Distance units ("mi" or "km") */
   distanceUnits: string;
 
-  /** Semantic admin enabled flag as a numeric string ("0" or "1") */
-  semanticAdmin: string;
+  /** Semantic admin enabled flag (0 or 1) */
+  semanticAdmin: number;
 
-  /** Number of changes tracked per meeting as a numeric string */
-  changesPerMeeting: string;
+  /** Number of changes tracked per meeting */
+  changesPerMeeting: number;
 
   /** Comma-separated list of states/provinces with meetings */
   meeting_states_and_provinces: string;
@@ -315,17 +315,17 @@ export interface ServerInfo {
 }
 
 export interface CoverageArea {
-  /** Northwest corner longitude as a numeric string */
-  nw_corner_longitude: string;
+  /** Northwest corner longitude */
+  nw_corner_longitude: number;
 
-  /** Northwest corner latitude as a numeric string */
-  nw_corner_latitude: string;
+  /** Northwest corner latitude */
+  nw_corner_latitude: number;
 
-  /** Southeast corner longitude as a numeric string */
-  se_corner_longitude: string;
+  /** Southeast corner longitude */
+  se_corner_longitude: number;
 
-  /** Southeast corner latitude as a numeric string */
-  se_corner_latitude: string;
+  /** Southeast corner latitude */
+  se_corner_latitude: number;
 }
 
 export interface FieldKey {

src/utils/transforms.ts

@@ -0,0 +1,50 @@
+/**
+ * Response transforms — BMLT serializes numeric fields as quoted strings.
+ * These converters give consumers idiomatic typed numbers.
+ */
+
+import type { Meeting, ServerInfo, CoverageArea } from '../types/responses';
+
+const num = (v: unknown): number => (typeof v === 'number' ? v : parseFloat(v as string));
+
+const optNum = (v: unknown): number | undefined => {
+  if (v === undefined || v === null || v === '') return undefined;
+  return num(v);
+};
+
+export function transformMeeting(raw: unknown): Meeting {
+  const r = raw as Record<string, unknown>;
+  return {
+    ...(r as unknown as Meeting),
+    weekday_tinyint: num(r.weekday_tinyint),
+    venue_type: num(r.venue_type),
+    published: num(r.published),
+    latitude: num(r.latitude),
+    longitude: num(r.longitude),
+    distance_in_km: optNum(r.distance_in_km),
+    distance_in_miles: optNum(r.distance_in_miles),
+  };
+}
+
+export function transformServerInfo(raw: unknown): ServerInfo {
+  const r = raw as Record<string, unknown>;
+  return {
+    ...(r as unknown as ServerInfo),
+    versionInt: num(r.versionInt),
+    centerLongitude: num(r.centerLongitude),
+    centerLatitude: num(r.centerLatitude),
+    centerZoom: num(r.centerZoom),
+    semanticAdmin: num(r.semanticAdmin),
+    changesPerMeeting: num(r.changesPerMeeting),
+  };
+}
+
+export function transformCoverageArea(raw: unknown): CoverageArea {
+  const r = raw as Record<string, unknown>;
+  return {
+    nw_corner_longitude: num(r.nw_corner_longitude),
+    nw_corner_latitude: num(r.nw_corner_latitude),
+    se_corner_longitude: num(r.se_corner_longitude),
+    se_corner_latitude: num(r.se_corner_latitude),
+  };
+}

test/basic.test.ts

@@ -65,7 +65,7 @@ describe('BMLT Query Client - Basic Tests', () => {
 
     expect(Array.isArray(virtualMeetings)).toBe(true);
     virtualMeetings.forEach(meeting => {
-      expect(parseInt(meeting.venue_type.toString())).toBe(VenueType.VIRTUAL);
+      expect(meeting.venue_type).toBe(VenueType.VIRTUAL);
     });
   });
 
@@ -77,7 +77,7 @@ describe('BMLT Query Client - Basic Tests', () => {
 
     expect(Array.isArray(mondayMeetings)).toBe(true);
     mondayMeetings.forEach(meeting => {
-      expect(parseInt(meeting.weekday_tinyint.toString())).toBe(Weekday.MONDAY);
+      expect(meeting.weekday_tinyint).toBe(Weekday.MONDAY);
     });
   });
 
@@ -101,7 +101,7 @@ describe('BMLT Query Client - Basic Tests', () => {
     expect(Array.isArray(meetings)).toBe(true);
     meetings.forEach(meeting => {
       expect(meeting.distance_in_miles).toBeDefined();
-      expect(parseFloat(meeting.distance_in_miles?.toString() || '0')).toBeLessThanOrEqual(2);
+      expect(meeting.distance_in_miles ?? 0).toBeLessThanOrEqual(2);
     });
   });
 
@@ -116,7 +116,7 @@ describe('BMLT Query Client - Basic Tests', () => {
     expect(Array.isArray(meetings)).toBe(true);
     meetings.forEach(meeting => {
       expect(meeting.distance_in_miles).toBeDefined();
-      expect(parseFloat(meeting.distance_in_miles?.toString() || '0')).toBeLessThanOrEqual(1);
+      expect(meeting.distance_in_miles ?? 0).toBeLessThanOrEqual(1);
     });
   });