@cyanheads/earthquake-mcp-server 0.1.1

package/dist/services/emsc/emsc-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emsc-service.d.ts","sourceRoot":"","sources":["../../../src/services/emsc/emsc-service.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAE/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAOrE,OAAO,KAAK,EACV,eAAe,EACf,qBAAqB,EAItB,MAAM,kBAAkB,CAAC;AA2C1B,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAGjC,OAAO,EAAE,SAAS,EAClB,QAAQ,EAAE,cAAc,EACxB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM;IAMnB,iCAAiC;IACjC,YAAY,CACV,MAAM,EAAE,qBAAqB,EAC7B,GAAG,EAAE,OAAO,GACX,OAAO,CAAC;QACT,MAAM,EAAE,eAAe,EAAE,CAAC;QAC1B,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;IA8CF,qCAAqC;IACrC,WAAW,CACT,MAAM,EAAE,qBAAqB,EAC7B,GAAG,EAAE,OAAO,GACX,OAAO,CAAC;QACT,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;QAC1B,YAAY,EAAE,OAAO,CAAC;KACvB,CAAC;IA8CF,qFAAqF;IACrF,OAAO,CAAC,cAAc;CAsBvB;AAMD,wBAAgB,eAAe,CAC7B,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,cAAc,EACvB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB,IAAI,CAEN;AAED,wBAAgB,cAAc,IAAI,WAAW,CAK5C"}

package/dist/services/emsc/emsc-service.js

@@ -0,0 +1,170 @@
+/**
+ * @fileoverview EMSC (European-Mediterranean Seismological Centre) FDSN event API client.
+ * @module services/emsc/emsc-service
+ */
+import { serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
+import { fetchWithTimeout, httpErrorFromResponse, requestContextService, withRetry, } from '@cyanheads/mcp-ts-core/utils';
+/** 1 degree of latitude ≈ 111.2 km. */
+const KM_PER_DEGREE = 111.2;
+/** Normalize an EMSC GeoJSON feature to the shared EarthquakeEvent domain type. */
+function normalizeEmscFeature(f) {
+    const p = f.properties;
+    const [lon, lat, depth] = f.geometry.coordinates;
+    const id = p.unid ?? f.id ?? `emsc-unknown-${Date.now()}`;
+    const place = p.flynn_region ?? 'Unknown location';
+    const magType = p.magtype ?? 'unknown';
+    const time = p.time ?? new Date(0).toISOString();
+    const updated = p.lastupdate ?? time;
+    // EMSC: properties.lat/lon may duplicate geometry coordinates; use them when present
+    const actualLat = typeof p.lat === 'number' ? p.lat : lat;
+    const actualLon = typeof p.lon === 'number' ? p.lon : lon;
+    const actualDepth = typeof p.depth === 'number' ? p.depth : depth;
+    return {
+        id,
+        title: `M ${p.mag ?? '?'} - ${place}`,
+        magnitude: p.mag ?? 0,
+        magnitude_type: magType,
+        time,
+        updated,
+        place,
+        latitude: actualLat,
+        longitude: actualLon,
+        depth_km: actualDepth,
+        // EMSC does not provide USGS-specific impact fields
+        felt: null,
+        cdi: null,
+        mmi: null,
+        alert: null,
+        tsunami: 0,
+        significance: null,
+        status: 'reviewed', // EMSC events are generally reviewed
+    };
+}
+export class EmscService {
+    baseUrl;
+    timeoutMs;
+    constructor(_config, _storage, emscBaseUrl, timeoutMs) {
+        this.baseUrl = emscBaseUrl.replace(/\/$/, '');
+        this.timeoutMs = timeoutMs;
+    }
+    /** Query EMSC FDSN event API. */
+    searchEvents(params, ctx) {
+        const query = this.buildFdsnQuery(params);
+        const url = `${this.baseUrl}/fdsnws/event/1/query?format=json&${query}`;
+        const reqCtx = requestContextService.createRequestContext({
+            operation: 'EmscService.searchEvents',
+            parentContext: {
+                requestId: ctx.requestId,
+                traceId: ctx.traceId,
+                tenantId: ctx.tenantId,
+                timestamp: new Date().toISOString(),
+            },
+        });
+        return withRetry(async () => {
+            const response = await fetchWithTimeout(url, this.timeoutMs, reqCtx, {
+                signal: ctx.signal,
+                headers: { Accept: 'application/json' },
+            });
+            if (!response.ok) {
+                throw await httpErrorFromResponse(response, { service: 'EMSC FDSN', data: { url } });
+            }
+            const text = await response.text();
+            if (/^\s*<(!DOCTYPE\s+html|html[\s>])/i.test(text)) {
+                throw serviceUnavailable('EMSC returned HTML instead of JSON.', { url });
+            }
+            const data = JSON.parse(text);
+            const events = data.features.map(normalizeEmscFeature);
+            return {
+                events,
+                count: events.length,
+            };
+        }, {
+            operation: 'EmscService.searchEvents',
+            context: reqCtx,
+            baseDelayMs: 1000,
+            signal: ctx.signal,
+        });
+    }
+    /** Count events matching a query. */
+    countEvents(params, ctx) {
+        const query = this.buildFdsnQuery(params);
+        const url = `${this.baseUrl}/fdsnws/event/1/count?format=json&${query}`;
+        const reqCtx = requestContextService.createRequestContext({
+            operation: 'EmscService.countEvents',
+            parentContext: {
+                requestId: ctx.requestId,
+                traceId: ctx.traceId,
+                tenantId: ctx.tenantId,
+                timestamp: new Date().toISOString(),
+            },
+        });
+        return withRetry(async () => {
+            const response = await fetchWithTimeout(url, this.timeoutMs, reqCtx, {
+                signal: ctx.signal,
+                headers: { Accept: 'application/json' },
+            });
+            if (!response.ok) {
+                throw await httpErrorFromResponse(response, { service: 'EMSC Count', data: { url } });
+            }
+            const text = await response.text();
+            if (/^\s*<(!DOCTYPE\s+html|html[\s>])/i.test(text)) {
+                throw serviceUnavailable('EMSC returned HTML instead of JSON.', { url });
+            }
+            const data = JSON.parse(text);
+            const EMSC_LIMIT = 20000;
+            return {
+                count: data.count,
+                maxAllowed: null, // EMSC count endpoint does not return maxAllowed
+                exceedsLimit: data.count > EMSC_LIMIT,
+            };
+        }, {
+            operation: 'EmscService.countEvents',
+            context: reqCtx,
+            baseDelayMs: 1000,
+            signal: ctx.signal,
+        });
+    }
+    /** Build FDSN query string from params, converting km radius to degrees for EMSC. */
+    buildFdsnQuery(params) {
+        const q = new URLSearchParams();
+        if (params.startTime)
+            q.set('starttime', params.startTime);
+        if (params.endTime)
+            q.set('endtime', params.endTime);
+        if (params.minMagnitude != null)
+            q.set('minmagnitude', String(params.minMagnitude));
+        if (params.maxMagnitude != null)
+            q.set('maxmagnitude', String(params.maxMagnitude));
+        if (params.latitude != null)
+            q.set('latitude', String(params.latitude));
+        if (params.longitude != null)
+            q.set('longitude', String(params.longitude));
+        if (params.radiusKm != null) {
+            // EMSC only supports maxradius in degrees — convert from km
+            const degrees = params.radiusKm / KM_PER_DEGREE;
+            q.set('maxradius', degrees.toFixed(4));
+        }
+        if (params.minDepthKm != null)
+            q.set('mindepth', String(params.minDepthKm));
+        if (params.maxDepthKm != null)
+            q.set('maxdepth', String(params.maxDepthKm));
+        // EMSC does not support alertlevel, minfelt, minsig — silently omit
+        if (params.limit != null)
+            q.set('limit', String(params.limit));
+        if (params.orderBy)
+            q.set('orderby', params.orderBy);
+        return q.toString();
+    }
+}
+// --- Init/accessor pattern ---
+let _service;
+export function initEmscService(config, storage, emscBaseUrl, timeoutMs) {
+    _service = new EmscService(config, storage, emscBaseUrl, timeoutMs);
+}
+export function getEmscService() {
+    if (!_service) {
+        throw new Error('EmscService not initialized — call initEmscService() in setup()');
+    }
+    return _service;
+}
+//# sourceMappingURL=emsc-service.js.map

package/dist/services/emsc/emsc-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emsc-service.js","sourceRoot":"","sources":["../../../src/services/emsc/emsc-service.ts"],"names":[],"mappings":"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"}

package/dist/services/usgs/types.d.ts

@@ -0,0 +1,136 @@
+/**
+ * @fileoverview Shared domain types for USGS and EMSC earthquake data.
+ * @module services/usgs/types
+ */
+/** Normalized earthquake event returned by both USGS and EMSC sources. */
+export interface EarthquakeEvent {
+    alert: 'green' | 'yellow' | 'orange' | 'red' | null;
+    cdi: number | null;
+    depth_km: number;
+    detail_url?: string;
+    event_url?: string;
+    felt: number | null;
+    id: string;
+    latitude: number;
+    longitude: number;
+    magnitude: number;
+    magnitude_type: string;
+    mmi: number | null;
+    place: string;
+    significance: number | null;
+    status: 'automatic' | 'reviewed' | 'deleted';
+    time: string;
+    title: string;
+    tsunami: number;
+    updated: string;
+}
+/** Raw USGS GeoJSON feature properties from list/query responses. */
+export interface UsgsFeatureProperties {
+    alert?: string | null;
+    cdi?: number | null;
+    code?: string | null;
+    detail?: string | null;
+    dmin?: number | null;
+    felt?: number | null;
+    gap?: number | null;
+    ids?: string | null;
+    mag?: number | null;
+    magType?: string | null;
+    mmi?: number | null;
+    net?: string | null;
+    nst?: number | null;
+    place?: string | null;
+    products?: Record<string, unknown>;
+    rms?: number | null;
+    sig?: number | null;
+    sources?: string | null;
+    status?: string | null;
+    time?: number | null;
+    title?: string | null;
+    tsunami?: number | null;
+    type?: string | null;
+    types?: string | null;
+    tz?: number | null;
+    updated?: number | null;
+    url?: string | null;
+}
+/** Raw USGS GeoJSON feature. */
+export interface UsgsFeature {
+    geometry: {
+        type: 'Point';
+        coordinates: [number, number, number];
+    };
+    id: string;
+    properties: UsgsFeatureProperties;
+    type: 'Feature';
+}
+/** Raw USGS GeoJSON FeatureCollection response. */
+export interface UsgsFeatureCollection {
+    bbox?: number[];
+    features: UsgsFeature[];
+    metadata: {
+        generated: number;
+        url: string;
+        title: string;
+        status: number;
+        api: string;
+        count: number;
+    };
+    type: 'FeatureCollection';
+}
+/** Raw USGS count response. */
+export interface UsgsCountResponse {
+    count: number;
+    maxAllowed: number;
+}
+/** Raw EMSC event properties. */
+export interface EmscEventProperties {
+    auth?: string | null;
+    depth?: number | null;
+    evtype?: string | null;
+    flynn_region?: string | null;
+    lastupdate?: string;
+    lat?: number | null;
+    lon?: number | null;
+    mag?: number | null;
+    magtype?: string | null;
+    time?: string;
+    unid?: string;
+}
+/** Raw EMSC GeoJSON feature. */
+export interface EmscFeature {
+    geometry: {
+        type: 'Point';
+        coordinates: [number, number, number];
+    };
+    id?: string;
+    properties: EmscEventProperties;
+    type: 'Feature';
+}
+/** Raw EMSC JSON response (format=json). */
+export interface EmscFeatureCollection {
+    features: EmscFeature[];
+    type: 'FeatureCollection';
+}
+/** Raw EMSC count response. */
+export interface EmscCountResponse {
+    count: number;
+}
+/** Query parameters shared by both USGS and EMSC search/count endpoints. */
+export interface EarthquakeQueryParams {
+    alertLevel?: string;
+    endTime?: string;
+    latitude?: number;
+    limit?: number;
+    longitude?: number;
+    maxDepthKm?: number;
+    maxMagnitude?: number;
+    minDepthKm?: number;
+    minFelt?: number;
+    minMagnitude?: number;
+    minSignificance?: number;
+    orderBy?: string;
+    radiusKm?: number;
+    startTime?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/services/usgs/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/services/usgs/types.ts"],"names":[],"mappings":"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"}

package/dist/services/usgs/types.js

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Shared domain types for USGS and EMSC earthquake data.
+ * @module services/usgs/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/services/usgs/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/services/usgs/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/services/usgs/usgs-service.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview USGS Earthquake Hazards Program API client — real-time feeds and FDSN event queries.
+ * @module services/usgs/usgs-service
+ */
+import type { Context } from '@cyanheads/mcp-ts-core';
+import type { AppConfig } from '@cyanheads/mcp-ts-core/config';
+import type { StorageService } from '@cyanheads/mcp-ts-core/storage';
+import type { EarthquakeEvent, EarthquakeQueryParams } from './types.js';
+export declare class UsgsService {
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    constructor(_config: AppConfig, _storage: StorageService, usgsBaseUrl: string, timeoutMs: number);
+    /** Fetch a pre-computed USGS real-time feed. */
+    getFeed(magnitudeTier: 'all' | '1.0' | '2.5' | '4.5' | 'significant', timeWindow: 'hour' | 'day' | 'week' | 'month', ctx: Context): Promise<{
+        events: EarthquakeEvent[];
+        generatedAt: string;
+        count: number;
+        feedUrl: string;
+    }>;
+    /** Query USGS FDSN event API. */
+    searchEvents(params: EarthquakeQueryParams, ctx: Context): Promise<{
+        events: EarthquakeEvent[];
+        count: number;
+        totalCount?: number;
+    }>;
+    /** Fetch a single event by USGS event ID. */
+    getEvent(eventId: string, ctx: Context): Promise<EarthquakeEvent>;
+    /** Count events matching a query. */
+    countEvents(params: EarthquakeQueryParams, ctx: Context): Promise<{
+        count: number;
+        maxAllowed: number | null;
+        exceedsLimit: boolean;
+    }>;
+    /** Build FDSN query string from params. */
+    private buildFdsnQuery;
+}
+export declare function initUsgsService(config: AppConfig, storage: StorageService, usgsBaseUrl: string, timeoutMs: number): void;
+export declare function getUsgsService(): UsgsService;
+//# sourceMappingURL=usgs-service.d.ts.map

package/dist/services/usgs/usgs-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usgs-service.d.ts","sourceRoot":"","sources":["../../../src/services/usgs/usgs-service.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAE/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAOrE,OAAO,KAAK,EACV,eAAe,EACf,qBAAqB,EAItB,MAAM,YAAY,CAAC;AA8CpB,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAGjC,OAAO,EAAE,SAAS,EAClB,QAAQ,EAAE,cAAc,EACxB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM;IAMnB,gDAAgD;IAChD,OAAO,CACL,aAAa,EAAE,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,aAAa,EAC5D,UAAU,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,EAC7C,GAAG,EAAE,OAAO,GACX,OAAO,CAAC;QAAE,MAAM,EAAE,eAAe,EAAE,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAqD9F,iCAAiC;IACjC,YAAY,CACV,MAAM,EAAE,qBAAqB,EAC7B,GAAG,EAAE,OAAO,GACX,OAAO,CAAC;QACT,MAAM,EAAE,eAAe,EAAE,CAAC;QAC1B,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;IAiEF,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,eAAe,CAAC;IAqEjE,qCAAqC;IACrC,WAAW,CACT,MAAM,EAAE,qBAAqB,EAC7B,GAAG,EAAE,OAAO,GACX,OAAO,CAAC;QACT,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;QAC1B,YAAY,EAAE,OAAO,CAAC;KACvB,CAAC;IAiDF,2CAA2C;IAC3C,OAAO,CAAC,cAAc;CAoBvB;AAMD,wBAAgB,eAAe,CAC7B,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,cAAc,EACvB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB,IAAI,CAEN;AAED,wBAAgB,cAAc,IAAI,WAAW,CAK5C"}

package/dist/services/usgs/usgs-service.js

@@ -0,0 +1,283 @@
+/**
+ * @fileoverview USGS Earthquake Hazards Program API client — real-time feeds and FDSN event queries.
+ * @module services/usgs/usgs-service
+ */
+import { notFound, serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
+import { fetchWithTimeout, httpErrorFromResponse, requestContextService, withRetry, } from '@cyanheads/mcp-ts-core/utils';
+/** Convert a USGS epoch-millisecond timestamp to an ISO 8601 string. */
+function epochMsToIso(ms) {
+    if (ms == null)
+        return new Date(0).toISOString();
+    return new Date(ms).toISOString();
+}
+/** Normalize a USGS GeoJSON feature to the shared EarthquakeEvent domain type. */
+function normalizeUsgsFeature(f) {
+    const p = f.properties;
+    const [lon, lat, depth] = f.geometry.coordinates;
+    const rawStatus = p.status ?? 'automatic';
+    const status = rawStatus === 'reviewed' || rawStatus === 'deleted' ? rawStatus : 'automatic';
+    const rawAlert = p.alert;
+    const alert = rawAlert === 'green' || rawAlert === 'yellow' || rawAlert === 'orange' || rawAlert === 'red'
+        ? rawAlert
+        : null;
+    return {
+        id: f.id,
+        title: p.title ?? `M ${p.mag ?? '?'} - ${p.place ?? 'Unknown location'}`,
+        magnitude: p.mag ?? 0,
+        magnitude_type: p.magType ?? 'unknown',
+        time: epochMsToIso(p.time),
+        updated: epochMsToIso(p.updated),
+        place: p.place ?? 'Unknown location',
+        latitude: lat,
+        longitude: lon,
+        depth_km: depth,
+        felt: p.felt ?? null,
+        cdi: p.cdi ?? null,
+        mmi: p.mmi ?? null,
+        alert,
+        tsunami: p.tsunami ?? 0,
+        significance: p.sig ?? null,
+        status,
+        ...(p.url ? { event_url: p.url } : {}),
+        ...(p.detail ? { detail_url: p.detail } : {}),
+    };
+}
+export class UsgsService {
+    baseUrl;
+    timeoutMs;
+    constructor(_config, _storage, usgsBaseUrl, timeoutMs) {
+        this.baseUrl = usgsBaseUrl.replace(/\/$/, '');
+        this.timeoutMs = timeoutMs;
+    }
+    /** Fetch a pre-computed USGS real-time feed. */
+    getFeed(magnitudeTier, timeWindow, ctx) {
+        const feedUrl = `${this.baseUrl}/earthquakes/feed/v1.0/summary/${magnitudeTier}_${timeWindow}.geojson`;
+        const reqCtx = requestContextService.createRequestContext({
+            operation: 'UsgsService.getFeed',
+            parentContext: {
+                requestId: ctx.requestId,
+                traceId: ctx.traceId,
+                tenantId: ctx.tenantId,
+                timestamp: new Date().toISOString(),
+            },
+        });
+        return withRetry(async () => {
+            const response = await fetchWithTimeout(feedUrl, this.timeoutMs, reqCtx, {
+                signal: ctx.signal,
+                headers: { Accept: 'application/json' },
+            });
+            if (!response.ok) {
+                throw await httpErrorFromResponse(response, {
+                    service: 'USGS Feed',
+                    data: { feedUrl },
+                });
+            }
+            const text = await response.text();
+            if (/^\s*<(!DOCTYPE\s+html|html[\s>])/i.test(text)) {
+                throw serviceUnavailable('USGS returned HTML instead of GeoJSON — likely rate-limited or a CDN error.', { feedUrl });
+            }
+            const data = JSON.parse(text);
+            const events = data.features.map(normalizeUsgsFeature);
+            return {
+                events,
+                generatedAt: epochMsToIso(data.metadata.generated),
+                count: data.metadata.count,
+                feedUrl: data.metadata.url ?? feedUrl,
+            };
+        }, {
+            operation: 'UsgsService.getFeed',
+            context: reqCtx,
+            baseDelayMs: 1000,
+            signal: ctx.signal,
+        });
+    }
+    /** Query USGS FDSN event API. */
+    searchEvents(params, ctx) {
+        const query = this.buildFdsnQuery(params);
+        const url = `${this.baseUrl}/fdsnws/event/1/query?format=geojson&${query}`;
+        const reqCtx = requestContextService.createRequestContext({
+            operation: 'UsgsService.searchEvents',
+            parentContext: {
+                requestId: ctx.requestId,
+                traceId: ctx.traceId,
+                tenantId: ctx.tenantId,
+                timestamp: new Date().toISOString(),
+            },
+        });
+        return withRetry(async () => {
+            const response = await fetchWithTimeout(url, this.timeoutMs, reqCtx, {
+                signal: ctx.signal,
+                headers: { Accept: 'application/json' },
+            });
+            if (response.status === 400) {
+                // USGS returns plain-text "Error 400: ..." for overly broad queries
+                const body = await response.text();
+                const broadMatch = /(\d+) matching events exceeds search limit/.exec(body);
+                if (broadMatch?.[1]) {
+                    const totalCount = parseInt(broadMatch[1], 10);
+                    throw Object.assign(new Error(`Query matches ${totalCount} events, exceeding the 20,000-event limit. ` +
+                        'Narrow time range, raise min_magnitude, or add location filters.'), { code: -32602, data: { reason: 'query_too_broad', totalCount } });
+                }
+                throw await httpErrorFromResponse(response, { service: 'USGS FDSN' });
+            }
+            if (!response.ok) {
+                throw await httpErrorFromResponse(response, { service: 'USGS FDSN', data: { url } });
+            }
+            const text = await response.text();
+            if (/^\s*<(!DOCTYPE\s+html|html[\s>])/i.test(text)) {
+                throw serviceUnavailable('USGS returned HTML instead of GeoJSON.', { url });
+            }
+            const data = JSON.parse(text);
+            const events = data.features.map(normalizeUsgsFeature);
+            const requestedLimit = params.limit ?? 100;
+            return {
+                events,
+                count: events.length,
+                ...(data.metadata.count > requestedLimit ? { totalCount: data.metadata.count } : {}),
+            };
+        }, {
+            operation: 'UsgsService.searchEvents',
+            context: reqCtx,
+            baseDelayMs: 1000,
+            signal: ctx.signal,
+        });
+    }
+    /** Fetch a single event by USGS event ID. */
+    getEvent(eventId, ctx) {
+        const url = `${this.baseUrl}/fdsnws/event/1/query?eventid=${encodeURIComponent(eventId)}&format=geojson`;
+        const reqCtx = requestContextService.createRequestContext({
+            operation: 'UsgsService.getEvent',
+            parentContext: {
+                requestId: ctx.requestId,
+                traceId: ctx.traceId,
+                tenantId: ctx.tenantId,
+                timestamp: new Date().toISOString(),
+            },
+        });
+        return withRetry(async () => {
+            const response = await fetchWithTimeout(url, this.timeoutMs, reqCtx, {
+                signal: ctx.signal,
+                headers: { Accept: 'application/json' },
+            });
+            if (response.status === 404) {
+                throw notFound(`No earthquake event found for ID "${eventId}". Verify the ID from a feed or search result.`, { eventId });
+            }
+            if (!response.ok) {
+                // USGS sometimes returns 400 with "Error 404" body for unknown IDs
+                const body = await response.text();
+                if (/Error 404/i.test(body)) {
+                    throw notFound(`No earthquake event found for ID "${eventId}". Verify the ID from a feed or search result.`, { eventId });
+                }
+                throw serviceUnavailable(`USGS returned HTTP ${response.status} for event lookup.`, {
+                    eventId,
+                    status: response.status,
+                });
+            }
+            const text = await response.text();
+            if (/^\s*<(!DOCTYPE\s+html|html[\s>])/i.test(text)) {
+                throw serviceUnavailable('USGS returned HTML instead of GeoJSON.', { eventId });
+            }
+            const data = JSON.parse(text);
+            if (!data.features || data.features.length === 0) {
+                throw notFound(`No earthquake event found for ID "${eventId}". Verify the ID from a feed or search result.`, { eventId });
+            }
+            const feature = data.features[0];
+            if (!feature) {
+                throw notFound(`No event data returned for ID "${eventId}".`, { eventId });
+            }
+            return normalizeUsgsFeature(feature);
+        }, {
+            operation: 'UsgsService.getEvent',
+            context: reqCtx,
+            baseDelayMs: 1000,
+            signal: ctx.signal,
+        });
+    }
+    /** Count events matching a query. */
+    countEvents(params, ctx) {
+        const query = this.buildFdsnQuery(params);
+        const url = `${this.baseUrl}/fdsnws/event/1/count?format=geojson&${query}`;
+        const reqCtx = requestContextService.createRequestContext({
+            operation: 'UsgsService.countEvents',
+            parentContext: {
+                requestId: ctx.requestId,
+                traceId: ctx.traceId,
+                tenantId: ctx.tenantId,
+                timestamp: new Date().toISOString(),
+            },
+        });
+        return withRetry(async () => {
+            const response = await fetchWithTimeout(url, this.timeoutMs, reqCtx, {
+                signal: ctx.signal,
+                headers: { Accept: 'application/json' },
+            });
+            if (!response.ok) {
+                throw await httpErrorFromResponse(response, {
+                    service: 'USGS Count',
+                    data: { url },
+                });
+            }
+            const text = await response.text();
+            if (/^\s*<(!DOCTYPE\s+html|html[\s>])/i.test(text)) {
+                throw serviceUnavailable('USGS returned HTML instead of JSON.', { url });
+            }
+            const data = JSON.parse(text);
+            const maxAllowed = data.maxAllowed ?? 20000;
+            return {
+                count: data.count,
+                maxAllowed,
+                exceedsLimit: data.count > maxAllowed,
+            };
+        }, {
+            operation: 'UsgsService.countEvents',
+            context: reqCtx,
+            baseDelayMs: 1000,
+            signal: ctx.signal,
+        });
+    }
+    /** Build FDSN query string from params. */
+    buildFdsnQuery(params) {
+        const q = new URLSearchParams();
+        if (params.startTime)
+            q.set('starttime', params.startTime);
+        if (params.endTime)
+            q.set('endtime', params.endTime);
+        if (params.minMagnitude != null)
+            q.set('minmagnitude', String(params.minMagnitude));
+        if (params.maxMagnitude != null)
+            q.set('maxmagnitude', String(params.maxMagnitude));
+        if (params.latitude != null)
+            q.set('latitude', String(params.latitude));
+        if (params.longitude != null)
+            q.set('longitude', String(params.longitude));
+        if (params.radiusKm != null)
+            q.set('maxradiuskm', String(params.radiusKm));
+        if (params.minDepthKm != null)
+            q.set('mindepth', String(params.minDepthKm));
+        if (params.maxDepthKm != null)
+            q.set('maxdepth', String(params.maxDepthKm));
+        if (params.alertLevel)
+            q.set('alertlevel', params.alertLevel);
+        if (params.minFelt != null)
+            q.set('minfelt', String(params.minFelt));
+        if (params.minSignificance != null)
+            q.set('minsig', String(params.minSignificance));
+        if (params.limit != null)
+            q.set('limit', String(params.limit));
+        if (params.orderBy)
+            q.set('orderby', params.orderBy);
+        return q.toString();
+    }
+}
+// --- Init/accessor pattern ---
+let _service;
+export function initUsgsService(config, storage, usgsBaseUrl, timeoutMs) {
+    _service = new UsgsService(config, storage, usgsBaseUrl, timeoutMs);
+}
+export function getUsgsService() {
+    if (!_service) {
+        throw new Error('UsgsService not initialized — call initUsgsService() in setup()');
+    }
+    return _service;
+}
+//# sourceMappingURL=usgs-service.js.map