@ibicash/geolayers-sdk 1.0.2 → 1.1.0

package/dist/index.d.cts

@@ -2,11 +2,27 @@ import { AxiosInstance } from 'axios';
 import { z } from 'zod';
 import { EventEmitter } from 'events';
 
+type ApiVersion = 'v1' | 'v2';
 interface GeoLayersConfig {
+    /**
+     * Base URL of the geo-layers service (host only, no /api path).
+     * Example: 'http://localhost:3000' or 'https://geo.example.com'
+     */
     baseUrl: string;
     apiKey: string;
     timeout?: number;
     retries?: number;
+    /**
+     * Preferred API version. Default: 'v1'
+     * When set to 'v2', the SDK will use v2 endpoints where available,
+     * falling back to v1 for endpoints not yet migrated.
+     */
+    apiVersion?: ApiVersion;
+    /**
+     * Base path for API routes. Default: '/api'
+     * The SDK builds URLs as: baseUrl + apiBasePath + /v1 or /v2 + endpoint
+     */
+    apiBasePath?: string;
 }
 declare const DEFAULT_CONFIG: Partial<GeoLayersConfig>;
 
@@ -569,10 +585,58 @@ declare const ObservationStatsResultSchema: z.ZodObject<{
 }, z.core.$strip>;
 type ObservationStatsResult = z.infer<typeof ObservationStatsResultSchema>;
 
+/**
+ * URL mapping for endpoints that differ between API versions.
+ * Use null to indicate an endpoint is not available in that version.
+ */
+interface VersionedEndpoint {
+    /** v1 endpoint path (without /api/v1 prefix). Use null if not available in v1. */
+    v1: string | null;
+    /** v2 endpoint path (without /api/v2 prefix). Use null if not available in v2. */
+    v2: string | null;
+}
+/**
+ * Result of URL resolution, includes which version was actually selected.
+ */
+interface ResolvedUrl {
+    /** Full URL path including version prefix */
+    url: string;
+    /** The API version that was selected */
+    version: ApiVersion;
+}
 declare abstract class BaseClient {
     protected readonly http: AxiosInstance;
-    protected readonly config: GeoLayersConfig;
+    protected readonly config: Required<Pick<GeoLayersConfig, 'baseUrl' | 'apiKey' | 'apiBasePath' | 'apiVersion'>> & GeoLayersConfig;
+    private readonly preferredVersion;
     constructor(config: GeoLayersConfig);
+    /**
+     * Returns true if the SDK prefers API v2.
+     */
+    protected get isV2(): boolean;
+    /**
+     * Returns the preferred API version.
+     */
+    protected get apiVersion(): ApiVersion;
+    /**
+     * Builds a versioned URL path.
+     * @param version API version to use
+     * @param endpoint Endpoint path (without version prefix)
+     */
+    private buildVersionedPath;
+    /**
+     * 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
+     */
+    protected resolveEndpoint(endpoints: VersionedEndpoint): ResolvedUrl;
+    /**
+     * Resolves URL - convenience method that returns just the URL string.
+     * Use resolveEndpoint() if you need to know which version was selected.
+     */
+    protected resolveUrl(endpoints: VersionedEndpoint): string;
     private setupInterceptors;
     private isRetryableError;
     private delay;
@@ -584,6 +648,17 @@ declare abstract class BaseClient {
      * Eliminates repetitive schema creation across domains.
      */
     protected parseGeoJSON<T extends z.ZodTypeAny>(data: unknown, propsSchema: T): LayerResponse<FeatureCollection<z.infer<T>>>;
+    /**
+     * 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
+     */
+    protected normalizeGeoJSONResponse<T extends z.ZodTypeAny>(data: unknown, propsSchema: T, provider: string): LayerResponse<FeatureCollection<z.infer<T>>>;
 }
 
 /**
@@ -742,8 +817,6 @@ declare class WeatherDomain extends BaseClient {
     /**
      * 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).
      */
     getActiveStations(type: 'iem' | 'wis2'): Promise<LayerResponse<FeatureCollection<WeatherStationProps>>>;
 }
@@ -835,11 +908,6 @@ declare class ObservationsDomain extends BaseClient {
      * Convert time preset to absolute date range parameters.
      */
     private buildDateParams;
-    /**
-     * Parse active stations response.
-     * The endpoint may return either a FeatureCollection directly or wrapped in LayerResponse.
-     */
-    private parseActiveStationsResponse;
 }
 
 /**
@@ -999,4 +1067,4 @@ declare class GeoLayersSDK {
     constructor(config: GeoLayersConfig);
 }
 
-export { type ActiveVolcanoProps, ActiveVolcanoPropsSchema, type BboxObservationsResult, BboxObservationsResultSchema, DEFAULT_CONFIG, type EarthquakeProps, EarthquakePropsSchema, type EventPayload, EventPayloadSchema, type Feature, type FeatureCollection, type FlightProps, FlightPropsSchema, type FlightScheduleResponse, FlightScheduleResponseSchema, GeoLayersApiError, type GeoLayersConfig, GeoLayersError, GeoLayersSDK, GeoLayersValidationError, type Geometry, GeometrySchema, type LatestObservationResult, LatestObservationResultSchema, type LayerMetadata, LayerMetadataSchema, LayerProvider, type LayerResponse, type MeasurementValue, MeasurementValueSchema, type ObservationProvider, ObservationProviderSchema, type ObservationQueryResult, ObservationQueryResultSchema, type ObservationStatsResult, ObservationStatsResultSchema, type StandardMeasurements, StandardMeasurementsSchema, type StandardObservation, StandardObservationSchema, type StationObservationsResult, StationObservationsResultSchema, type StormProps, StormPropsSchema, type VolcanoProps, VolcanoPropsSchema, type WeatherStationProps, WeatherStationPropsSchema, type WildfireProps, WildfirePropsSchema, createFeatureCollectionSchema, createFeatureSchema, createLayerResponseSchema, GeoLayersSDK as default };
+export { type ActiveVolcanoProps, ActiveVolcanoPropsSchema, type ApiVersion, type BboxObservationsResult, BboxObservationsResultSchema, DEFAULT_CONFIG, type EarthquakeProps, EarthquakePropsSchema, type EventPayload, EventPayloadSchema, type Feature, type FeatureCollection, type FlightProps, FlightPropsSchema, type FlightScheduleResponse, FlightScheduleResponseSchema, GeoLayersApiError, type GeoLayersConfig, GeoLayersError, GeoLayersSDK, GeoLayersValidationError, type Geometry, GeometrySchema, type LatestObservationResult, LatestObservationResultSchema, type LayerMetadata, LayerMetadataSchema, LayerProvider, type LayerResponse, type MeasurementValue, MeasurementValueSchema, type ObservationProvider, ObservationProviderSchema, type ObservationQueryResult, ObservationQueryResultSchema, type ObservationStatsResult, ObservationStatsResultSchema, type StandardMeasurements, StandardMeasurementsSchema, type StandardObservation, StandardObservationSchema, type StationObservationsResult, StationObservationsResultSchema, type StormProps, StormPropsSchema, type VolcanoProps, VolcanoPropsSchema, type WeatherStationProps, WeatherStationPropsSchema, type WildfireProps, WildfirePropsSchema, createFeatureCollectionSchema, createFeatureSchema, createLayerResponseSchema, GeoLayersSDK as default };

package/dist/index.d.ts

@@ -2,11 +2,27 @@ import { AxiosInstance } from 'axios';
 import { z } from 'zod';
 import { EventEmitter } from 'events';
 
+type ApiVersion = 'v1' | 'v2';
 interface GeoLayersConfig {
+    /**
+     * Base URL of the geo-layers service (host only, no /api path).
+     * Example: 'http://localhost:3000' or 'https://geo.example.com'
+     */
     baseUrl: string;
     apiKey: string;
     timeout?: number;
     retries?: number;
+    /**
+     * Preferred API version. Default: 'v1'
+     * When set to 'v2', the SDK will use v2 endpoints where available,
+     * falling back to v1 for endpoints not yet migrated.
+     */
+    apiVersion?: ApiVersion;
+    /**
+     * Base path for API routes. Default: '/api'
+     * The SDK builds URLs as: baseUrl + apiBasePath + /v1 or /v2 + endpoint
+     */
+    apiBasePath?: string;
 }
 declare const DEFAULT_CONFIG: Partial<GeoLayersConfig>;
 
@@ -569,10 +585,58 @@ declare const ObservationStatsResultSchema: z.ZodObject<{
 }, z.core.$strip>;
 type ObservationStatsResult = z.infer<typeof ObservationStatsResultSchema>;
 
+/**
+ * URL mapping for endpoints that differ between API versions.
+ * Use null to indicate an endpoint is not available in that version.
+ */
+interface VersionedEndpoint {
+    /** v1 endpoint path (without /api/v1 prefix). Use null if not available in v1. */
+    v1: string | null;
+    /** v2 endpoint path (without /api/v2 prefix). Use null if not available in v2. */
+    v2: string | null;
+}
+/**
+ * Result of URL resolution, includes which version was actually selected.
+ */
+interface ResolvedUrl {
+    /** Full URL path including version prefix */
+    url: string;
+    /** The API version that was selected */
+    version: ApiVersion;
+}
 declare abstract class BaseClient {
     protected readonly http: AxiosInstance;
-    protected readonly config: GeoLayersConfig;
+    protected readonly config: Required<Pick<GeoLayersConfig, 'baseUrl' | 'apiKey' | 'apiBasePath' | 'apiVersion'>> & GeoLayersConfig;
+    private readonly preferredVersion;
     constructor(config: GeoLayersConfig);
+    /**
+     * Returns true if the SDK prefers API v2.
+     */
+    protected get isV2(): boolean;
+    /**
+     * Returns the preferred API version.
+     */
+    protected get apiVersion(): ApiVersion;
+    /**
+     * Builds a versioned URL path.
+     * @param version API version to use
+     * @param endpoint Endpoint path (without version prefix)
+     */
+    private buildVersionedPath;
+    /**
+     * 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
+     */
+    protected resolveEndpoint(endpoints: VersionedEndpoint): ResolvedUrl;
+    /**
+     * Resolves URL - convenience method that returns just the URL string.
+     * Use resolveEndpoint() if you need to know which version was selected.
+     */
+    protected resolveUrl(endpoints: VersionedEndpoint): string;
     private setupInterceptors;
     private isRetryableError;
     private delay;
@@ -584,6 +648,17 @@ declare abstract class BaseClient {
      * Eliminates repetitive schema creation across domains.
      */
     protected parseGeoJSON<T extends z.ZodTypeAny>(data: unknown, propsSchema: T): LayerResponse<FeatureCollection<z.infer<T>>>;
+    /**
+     * 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
+     */
+    protected normalizeGeoJSONResponse<T extends z.ZodTypeAny>(data: unknown, propsSchema: T, provider: string): LayerResponse<FeatureCollection<z.infer<T>>>;
 }
 
 /**
@@ -742,8 +817,6 @@ declare class WeatherDomain extends BaseClient {
     /**
      * 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).
      */
     getActiveStations(type: 'iem' | 'wis2'): Promise<LayerResponse<FeatureCollection<WeatherStationProps>>>;
 }
@@ -835,11 +908,6 @@ declare class ObservationsDomain extends BaseClient {
      * Convert time preset to absolute date range parameters.
      */
     private buildDateParams;
-    /**
-     * Parse active stations response.
-     * The endpoint may return either a FeatureCollection directly or wrapped in LayerResponse.
-     */
-    private parseActiveStationsResponse;
 }
 
 /**
@@ -999,4 +1067,4 @@ declare class GeoLayersSDK {
     constructor(config: GeoLayersConfig);
 }
 
-export { type ActiveVolcanoProps, ActiveVolcanoPropsSchema, type BboxObservationsResult, BboxObservationsResultSchema, DEFAULT_CONFIG, type EarthquakeProps, EarthquakePropsSchema, type EventPayload, EventPayloadSchema, type Feature, type FeatureCollection, type FlightProps, FlightPropsSchema, type FlightScheduleResponse, FlightScheduleResponseSchema, GeoLayersApiError, type GeoLayersConfig, GeoLayersError, GeoLayersSDK, GeoLayersValidationError, type Geometry, GeometrySchema, type LatestObservationResult, LatestObservationResultSchema, type LayerMetadata, LayerMetadataSchema, LayerProvider, type LayerResponse, type MeasurementValue, MeasurementValueSchema, type ObservationProvider, ObservationProviderSchema, type ObservationQueryResult, ObservationQueryResultSchema, type ObservationStatsResult, ObservationStatsResultSchema, type StandardMeasurements, StandardMeasurementsSchema, type StandardObservation, StandardObservationSchema, type StationObservationsResult, StationObservationsResultSchema, type StormProps, StormPropsSchema, type VolcanoProps, VolcanoPropsSchema, type WeatherStationProps, WeatherStationPropsSchema, type WildfireProps, WildfirePropsSchema, createFeatureCollectionSchema, createFeatureSchema, createLayerResponseSchema, GeoLayersSDK as default };
+export { type ActiveVolcanoProps, ActiveVolcanoPropsSchema, type ApiVersion, type BboxObservationsResult, BboxObservationsResultSchema, DEFAULT_CONFIG, type EarthquakeProps, EarthquakePropsSchema, type EventPayload, EventPayloadSchema, type Feature, type FeatureCollection, type FlightProps, FlightPropsSchema, type FlightScheduleResponse, FlightScheduleResponseSchema, GeoLayersApiError, type GeoLayersConfig, GeoLayersError, GeoLayersSDK, GeoLayersValidationError, type Geometry, GeometrySchema, type LatestObservationResult, LatestObservationResultSchema, type LayerMetadata, LayerMetadataSchema, LayerProvider, type LayerResponse, type MeasurementValue, MeasurementValueSchema, type ObservationProvider, ObservationProviderSchema, type ObservationQueryResult, ObservationQueryResultSchema, type ObservationStatsResult, ObservationStatsResultSchema, type StandardMeasurements, StandardMeasurementsSchema, type StandardObservation, StandardObservationSchema, type StationObservationsResult, StationObservationsResultSchema, type StormProps, StormPropsSchema, type VolcanoProps, VolcanoPropsSchema, type WeatherStationProps, WeatherStationPropsSchema, type WildfireProps, WildfirePropsSchema, createFeatureCollectionSchema, createFeatureSchema, createLayerResponseSchema, GeoLayersSDK as default };