@ibicash/geolayers-sdk 1.0.2 → 1.1.0

package/dist/index.js

@@ -327,7 +327,9 @@ var ObservationStatsResultSchema = z2.object({
 var DEFAULT_CONFIG = {
   baseUrl: (typeof process !== "undefined" ? process.env.GEOLAYERS_BASE_URL : void 0) || "",
   timeout: 3e4,
-  retries: 2
+  retries: 2,
+  apiVersion: "v1",
+  apiBasePath: "/api"
 };
 
 // src/core/errors.ts
@@ -357,14 +359,79 @@ var GeoLayersValidationError = class extends GeoLayersError {
 var BaseClient = class {
   http;
   config;
+  preferredVersion;
   constructor(config) {
-    this.config = { ...DEFAULT_CONFIG, ...config };
+    this.config = {
+      ...DEFAULT_CONFIG,
+      ...config,
+      apiBasePath: config.apiBasePath ?? DEFAULT_CONFIG.apiBasePath ?? "/api",
+      apiVersion: config.apiVersion ?? DEFAULT_CONFIG.apiVersion ?? "v1"
+    };
+    this.preferredVersion = this.config.apiVersion;
     this.http = axios.create({
       baseURL: this.config.baseUrl,
       timeout: this.config.timeout
     });
     this.setupInterceptors();
   }
+  /**
+   * Returns true if the SDK prefers API v2.
+   */
+  get isV2() {
+    return this.preferredVersion === "v2";
+  }
+  /**
+   * Returns the preferred API version.
+   */
+  get apiVersion() {
+    return this.preferredVersion;
+  }
+  /**
+   * Builds a versioned URL path.
+   * @param version API version to use
+   * @param endpoint Endpoint path (without version prefix)
+   */
+  buildVersionedPath(version, endpoint) {
+    const basePath = this.config.apiBasePath;
+    const normalizedEndpoint = endpoint.startsWith("/") ? endpoint : `/${endpoint}`;
+    return `${basePath}/${version}${normalizedEndpoint}`;
+  }
+  /**
+   * Resolves the appropriate URL based on API version and availability.
+   * Falls back to the other version if preferred is not available.
+   *
+   * @param endpoints Object with v1 and v2 URL paths (use null if unavailable)
+   * @returns ResolvedUrl with full path and selected version
+   * @throws Error if no endpoint is available for either version
+   */
+  resolveEndpoint(endpoints) {
+    if (this.isV2 && endpoints.v2 !== null) {
+      return {
+        url: this.buildVersionedPath("v2", endpoints.v2),
+        version: "v2"
+      };
+    }
+    if (endpoints.v1 !== null) {
+      return {
+        url: this.buildVersionedPath("v1", endpoints.v1),
+        version: "v1"
+      };
+    }
+    if (endpoints.v2 !== null) {
+      return {
+        url: this.buildVersionedPath("v2", endpoints.v2),
+        version: "v2"
+      };
+    }
+    throw new Error("No endpoint available for either API version");
+  }
+  /**
+   * Resolves URL - convenience method that returns just the URL string.
+   * Use resolveEndpoint() if you need to know which version was selected.
+   */
+  resolveUrl(endpoints) {
+    return this.resolveEndpoint(endpoints).url;
+  }
   setupInterceptors() {
     this.http.interceptors.request.use((config) => {
       config.headers["X-API-Key"] = this.config.apiKey;
@@ -433,6 +500,33 @@ var BaseClient = class {
     const schema = createLayerResponseSchema(createFeatureCollectionSchema(propsSchema));
     return schema.parse(data);
   }
+  /**
+   * Normalizes API responses to a consistent LayerResponse format.
+   * Handles both:
+   * - v1 responses: LayerResponse envelope with data field
+   * - v2 responses: Direct FeatureCollection
+   *
+   * @param data Raw response data from the API
+   * @param propsSchema Zod schema for feature properties
+   * @param provider Provider name to use when wrapping v2 responses
+   */
+  normalizeGeoJSONResponse(data, propsSchema, provider) {
+    const record = data;
+    if (record?.provider && record?.data && record?.timestamp) {
+      return this.parseGeoJSON(data, propsSchema);
+    }
+    if (record?.type === "FeatureCollection" && Array.isArray(record?.features)) {
+      const featureCollectionSchema = createFeatureCollectionSchema(propsSchema);
+      const featureCollection = featureCollectionSchema.parse(data);
+      return {
+        provider,
+        data: featureCollection,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        count: featureCollection.features.length
+      };
+    }
+    return this.parseGeoJSON(data, propsSchema);
+  }
 };
 
 // src/domains/aviation.ts
@@ -442,33 +536,41 @@ var AviationDomain = class extends BaseClient {
    * @param filters Optional bounding box filters. Defaults to whole world.
    */
   async getGlobalFlights(filters = {}) {
+    const url = this.resolveUrl({
+      v1: "/geojson/flights/global",
+      v2: null
+    });
     const params = {
       lamin: filters.lamin ?? -90,
       lomin: filters.lomin ?? -180,
       lamax: filters.lamax ?? 90,
       lomax: filters.lomax ?? 180
     };
-    const data = await this.get("/geojson/flights/global", params);
-    return this.parseGeoJSON(data, FlightPropsSchema);
+    const data = await this.get(url, params);
+    return this.normalizeGeoJSONResponse(data, FlightPropsSchema, "global-flights");
   }
   /**
    * Get live flights (subset of global flights).
    * @param filters Center point and radius filters. Defaults to New York if not provided.
    */
   async getLiveFlights(filters = { lat: 40.7128, lng: -74.006 }) {
+    const url = this.resolveUrl({
+      v1: "/geojson/flights/live",
+      v2: null
+    });
     const params = {
       lat: filters.lat,
       lng: filters.lng,
       radius: filters.radius ?? 250
     };
-    const data = await this.get("/geojson/flights/live", params);
-    return this.parseGeoJSON(data, FlightPropsSchema);
+    const data = await this.get(url, params);
+    return this.normalizeGeoJSONResponse(data, FlightPropsSchema, "live-flights");
   }
   /**
    * Get flight schedule/details by callsign from AeroDataBox.
    * @param callsign Flight identifier (e.g., 'UAL1234', 'AA100')
    * @returns Raw flight schedule data from AeroDataBox API.
-   * 
+   *
    * @example
    * ```ts
    * const schedule = await sdk.aviation.getFlightSchedule('UAL1234');
@@ -476,7 +578,11 @@ var AviationDomain = class extends BaseClient {
    * ```
    */
   async getFlightSchedule(callsign) {
-    const data = await this.get("/geojson/flights/schedule", { callsign });
+    const url = this.resolveUrl({
+      v1: "/geojson/flights/schedule",
+      v2: null
+    });
+    const data = await this.get(url, { callsign });
     return FlightScheduleResponseSchema.parse(data);
   }
 };
@@ -503,7 +609,7 @@ var EventsDomain = class extends BaseClient {
   /**
    * Get list of available event types for the event stream.
    * @returns Object with event types array and their descriptions.
-   * 
+   *
    * @example
    * ```ts
    * const { types, descriptions } = await sdk.eventsMeta.getEventTypes();
@@ -512,7 +618,11 @@ var EventsDomain = class extends BaseClient {
    * ```
    */
   async getEventTypes() {
-    const data = await this.get("/events/types");
+    const url = this.resolveUrl({
+      v1: "/events/types",
+      v2: null
+    });
+    const data = await this.get(url);
     return EventTypesResponseSchema.parse(data);
   }
 };
@@ -524,9 +634,13 @@ var FireDomain = class extends BaseClient {
    * @param filters Optional filters. Default: last 1 day.
    */
   async getWildfires(filters = {}) {
+    const url = this.resolveUrl({
+      v1: "/geojson/wildfires",
+      v2: null
+    });
     const params = { days: filters.days ?? 1 };
-    const data = await this.get("/geojson/wildfires", params);
-    return this.parseGeoJSON(data, WildfirePropsSchema);
+    const data = await this.get(url, params);
+    return this.normalizeGeoJSONResponse(data, WildfirePropsSchema, "wildfires");
   }
 };
 
@@ -536,15 +650,23 @@ var MaritimeDomain = class extends BaseClient {
    * Get NOAA buoy stations (locations).
    */
   async getBuoyStations() {
-    const data = await this.get("/geojson/buoys/stations");
-    return this.parseGeoJSON(data, WeatherStationPropsSchema);
+    const url = this.resolveUrl({
+      v1: "/geojson/buoys/stations",
+      v2: "/stations?provider=buoy"
+    });
+    const data = await this.get(url);
+    return this.normalizeGeoJSONResponse(data, WeatherStationPropsSchema, "buoy-stations");
   }
   /**
    * Get latest buoy observations (real-time-ish).
    */
   async getLatestBuoyObservations() {
-    const data = await this.get("/geojson/buoys/observations");
-    return this.parseGeoJSON(data, WeatherStationPropsSchema);
+    const url = this.resolveUrl({
+      v1: "/geojson/buoys/observations",
+      v2: null
+    });
+    const data = await this.get(url);
+    return this.normalizeGeoJSONResponse(data, WeatherStationPropsSchema, "buoy-observations");
   }
   /**
    * Get historical observations for a specific buoy.
@@ -552,7 +674,11 @@ var MaritimeDomain = class extends BaseClient {
    * @param filters Date range filters.
    */
   async getBuoyObservations(buoyId, filters) {
-    const data = await this.get(`/observations/buoy/${buoyId}`, filters);
+    const url = this.resolveUrl({
+      v1: `/observations/buoy/${buoyId}`,
+      v2: null
+    });
+    const data = await this.get(url, filters);
     return ObservationQueryResultSchema.parse(data);
   }
 };
@@ -563,15 +689,23 @@ var ObservationsDomain = class extends BaseClient {
    * Get active WIS2 stations that reported data in the last 24 hours.
    */
   async getActiveWis2Stations() {
-    const rawData = await this.get("/observations/wis2/stations/active");
-    return this.parseActiveStationsResponse(rawData, "wis2");
+    const url = this.resolveUrl({
+      v1: "/observations/wis2/stations/active",
+      v2: null
+    });
+    const rawData = await this.get(url);
+    return this.normalizeGeoJSONResponse(rawData, WeatherStationPropsSchema, "active-wis2-stations");
   }
   /**
    * Get active IEM/AZOS stations that reported data in the last 24 hours.
    */
   async getActiveIemStations() {
-    const rawData = await this.get("/observations/iem/stations/active");
-    return this.parseActiveStationsResponse(rawData, "iem");
+    const url = this.resolveUrl({
+      v1: "/observations/iem/stations/active",
+      v2: null
+    });
+    const rawData = await this.get(url);
+    return this.normalizeGeoJSONResponse(rawData, WeatherStationPropsSchema, "active-iem-stations");
   }
   /**
    * Get observations for a station from the data warehouse.
@@ -579,8 +713,12 @@ var ObservationsDomain = class extends BaseClient {
    * @param filters Query filters including provider and date range.
    */
   async getStationObservations(stationId, filters) {
+    const url = this.resolveUrl({
+      v1: `/observations/station/${stationId}`,
+      v2: null
+    });
     const params = this.buildDateParams(filters);
-    const data = await this.get(`/observations/station/${stationId}`, params);
+    const data = await this.get(url, params);
     return StationObservationsResultSchema.parse(data);
   }
   /**
@@ -589,7 +727,11 @@ var ObservationsDomain = class extends BaseClient {
    * @param provider The observation provider.
    */
   async getLatestObservation(stationId, provider) {
-    const data = await this.get(`/observations/station/${stationId}/latest`, { provider });
+    const url = this.resolveUrl({
+      v1: `/observations/station/${stationId}/latest`,
+      v2: null
+    });
+    const data = await this.get(url, { provider });
     return LatestObservationResultSchema.parse(data);
   }
   /**
@@ -597,6 +739,10 @@ var ObservationsDomain = class extends BaseClient {
    * @param filters Bounding box coordinates and query filters.
    */
   async getObservationsByBbox(filters) {
+    const url = this.resolveUrl({
+      v1: "/observations/bbox",
+      v2: null
+    });
     const params = {
       ...this.buildDateParams(filters),
       minLon: filters.minLon,
@@ -604,7 +750,7 @@ var ObservationsDomain = class extends BaseClient {
       maxLon: filters.maxLon,
       maxLat: filters.maxLat
     };
-    const data = await this.get("/observations/bbox", params);
+    const data = await this.get(url, params);
     return BboxObservationsResultSchema.parse(data);
   }
   /**
@@ -612,8 +758,12 @@ var ObservationsDomain = class extends BaseClient {
    * @param provider Optional provider filter. If not specified, returns stats for all providers.
    */
   async getStats(provider) {
+    const url = this.resolveUrl({
+      v1: "/observations/stats",
+      v2: null
+    });
     const params = provider ? { provider } : {};
-    const data = await this.get("/observations/stats", params);
+    const data = await this.get(url, params);
     return ObservationStatsResultSchema.parse(data);
   }
   /**
@@ -645,34 +795,6 @@ var ObservationsDomain = class extends BaseClient {
     }
     return params;
   }
-  /**
-   * Parse active stations response.
-   * The endpoint may return either a FeatureCollection directly or wrapped in LayerResponse.
-   */
-  parseActiveStationsResponse(rawData, provider) {
-    const featureCollection = rawData;
-    if (featureCollection?.type === "FeatureCollection") {
-      const features = (featureCollection.features ?? []).map((f) => {
-        const feature = f;
-        return {
-          type: "Feature",
-          geometry: feature.geometry,
-          properties: WeatherStationPropsSchema.parse(feature.properties ?? {}),
-          id: feature.id
-        };
-      });
-      return {
-        provider: `active-stations-${provider}`,
-        data: {
-          type: "FeatureCollection",
-          features
-        },
-        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-        count: features.length
-      };
-    }
-    return this.parseGeoJSON(rawData, WeatherStationPropsSchema);
-  }
 };
 
 // src/domains/seismic.ts
@@ -724,8 +846,12 @@ var SeismicDomain = class extends BaseClient {
       ...timeRange,
       ...minMagnitude !== void 0 && { minMagnitude }
     };
-    const data = await this.get("/geojson/earthquakes", params);
-    return this.parseGeoJSON(data, EarthquakePropsSchema);
+    const url = this.resolveUrl({
+      v1: "/geojson/earthquakes",
+      v2: null
+    });
+    const data = await this.get(url, params);
+    return this.normalizeGeoJSONResponse(data, EarthquakePropsSchema, "earthquakes");
   }
 };
 
@@ -735,15 +861,23 @@ var TropicalDomain = class extends BaseClient {
    * Get list of currently active tropical storms/hurricanes.
    */
   async getActiveStorms() {
-    const data = await this.get("/geojson/storms/active");
-    return this.parseGeoJSON(data, StormPropsSchema);
+    const url = this.resolveUrl({
+      v1: "/geojson/storms/active",
+      v2: null
+    });
+    const data = await this.get(url);
+    return this.normalizeGeoJSONResponse(data, StormPropsSchema, "active-storms");
   }
   /**
    * Get list of recent tropical storms/hurricanes.
    */
   async getRecentStorms() {
-    const data = await this.get("/geojson/storms/recent");
-    return this.parseGeoJSON(data, StormPropsSchema);
+    const url = this.resolveUrl({
+      v1: "/geojson/storms/recent",
+      v2: null
+    });
+    const data = await this.get(url);
+    return this.normalizeGeoJSONResponse(data, StormPropsSchema, "recent-storms");
   }
 };
 
@@ -762,7 +896,11 @@ var VolcanicDomain = class extends BaseClient {
    * Note: API returns array of Features, normalized to FeatureCollection here.
    */
   async getVolcanoes() {
-    const raw = await this.get("/geojson/volcanoes");
+    const url = this.resolveUrl({
+      v1: "/geojson/volcanoes",
+      v2: null
+    });
+    const raw = await this.get(url);
     const parsed = VolcanoesResponseSchema.parse(raw);
     return {
       provider: parsed.provider,
@@ -779,8 +917,12 @@ var VolcanicDomain = class extends BaseClient {
    * Get list of currently active volcanoes (GDACS).
    */
   async getActiveVolcanoes() {
-    const data = await this.get("/geojson/volcanoes/active");
-    return this.parseGeoJSON(data, ActiveVolcanoPropsSchema);
+    const url = this.resolveUrl({
+      v1: "/geojson/volcanoes/active",
+      v2: null
+    });
+    const data = await this.get(url);
+    return this.normalizeGeoJSONResponse(data, ActiveVolcanoPropsSchema, "active-volcanoes");
   }
 };
 
@@ -791,12 +933,16 @@ var WeatherDomain = class extends BaseClient {
    * @param filters Optional pagination filters.
    */
   async getWis2Stations(filters = {}) {
-    const params = {
+    const { url, version } = this.resolveEndpoint({
+      v1: "/geojson/stations/wis2",
+      v2: "/stations?provider=wis2"
+    });
+    const params = version === "v2" ? filters : {
       limit: filters.limit ?? 100,
       offset: filters.offset ?? 0
     };
-    const data = await this.get("/geojson/stations/wis2", params);
-    return this.parseGeoJSON(data, WeatherStationPropsSchema);
+    const data = await this.get(url, params);
+    return this.normalizeGeoJSONResponse(data, WeatherStationPropsSchema, "wis2-stations");
   }
   /**
    * Get historical observations for a WIS2 station.
@@ -804,15 +950,23 @@ var WeatherDomain = class extends BaseClient {
    * @param filters Date range and optional WIS2-specific filters.
    */
   async getWis2Observations(stationId, filters) {
-    const data = await this.get(`/observations/wis2/${stationId}`, filters);
+    const url = this.resolveUrl({
+      v1: `/observations/wis2/${stationId}`,
+      v2: null
+    });
+    const data = await this.get(url, filters);
     return ObservationQueryResultSchema.parse(data);
   }
   /**
    * Get weather stations from IEM/AZOS network.
    */
   async getIemStations() {
-    const data = await this.get("/geojson/stations/azos");
-    return this.parseGeoJSON(data, WeatherStationPropsSchema);
+    const { url, version } = this.resolveEndpoint({
+      v1: "/geojson/stations/azos",
+      v2: "/stations?provider=iem"
+    });
+    const data = await this.get(url);
+    return this.normalizeGeoJSONResponse(data, WeatherStationPropsSchema, "iem-stations");
   }
   /**
    * Get historical observations for an IEM station.
@@ -820,46 +974,35 @@ var WeatherDomain = class extends BaseClient {
    * @param filters Date range filters.
    */
   async getIemObservations(stationId, filters) {
-    const data = await this.get(`/observations/iem/${stationId}`, filters);
+    const url = this.resolveUrl({
+      v1: `/observations/iem/${stationId}`,
+      v2: null
+    });
+    const data = await this.get(url, filters);
     return ObservationQueryResultSchema.parse(data);
   }
   /**
    * Get weather stations from NWS (National Weather Service) network.
    */
   async getNWSWeatherStations() {
-    const data = await this.get("/geojson/stations/nws");
-    return this.parseGeoJSON(data, WeatherStationPropsSchema);
+    const url = this.resolveUrl({
+      v1: "/geojson/stations/nws",
+      v2: null
+    });
+    const data = await this.get(url);
+    return this.normalizeGeoJSONResponse(data, WeatherStationPropsSchema, "nws-stations");
   }
   /**
    * Get active stations that have reported data in the last 24 hours.
    * @param type The station network type ('iem' or 'wis2').
-   * 
-   * Note: This endpoint returns FeatureCollection directly (not LayerResponse envelope).
    */
   async getActiveStations(type) {
-    const rawData = await this.get("/stations/active", { type });
-    const featureCollection = rawData;
-    if (featureCollection?.type === "FeatureCollection") {
-      const features = (featureCollection.features ?? []).map((f) => {
-        const feature = f;
-        return {
-          type: "Feature",
-          geometry: feature.geometry,
-          properties: WeatherStationPropsSchema.parse(feature.properties ?? {}),
-          id: feature.id
-        };
-      });
-      return {
-        provider: `active-stations-${type}`,
-        data: {
-          type: "FeatureCollection",
-          features
-        },
-        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-        count: features.length
-      };
-    }
-    return this.parseGeoJSON(rawData, WeatherStationPropsSchema);
+    const url = this.resolveUrl({
+      v1: "/stations/active",
+      v2: null
+    });
+    const rawData = await this.get(url, { type });
+    return this.normalizeGeoJSONResponse(rawData, WeatherStationPropsSchema, `active-stations-${type}`);
   }
 };
 
@@ -870,7 +1013,9 @@ var EventStream = class extends EventEmitter {
   url;
   constructor(config) {
     super();
-    this.url = `${config.baseUrl}/events/stream?apiKey=${config.apiKey}`;
+    const baseUrl = config.baseUrl;
+    const apiBasePath = config.apiBasePath ?? DEFAULT_CONFIG.apiBasePath ?? "/api";
+    this.url = `${baseUrl}${apiBasePath}/v1/events/stream?apiKey=${config.apiKey}`;
   }
   /**
    * Start listening to the event stream.