@cyanheads/noaa-marine-mcp-server 0.1.1

package/dist/mcp-server/tools/definitions/noaa-marine-get-tide-predictions.tool.js

@@ -0,0 +1,180 @@
+/**
+ * @fileoverview noaa_marine_get_tide_predictions tool — high/low tide predictions from CO-OPS.
+ * @module mcp-server/tools/definitions/noaa-marine-get-tide-predictions.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode, McpError } from '@cyanheads/mcp-ts-core/errors';
+import { getCoopsService } from '../../../services/coops/coops-service.js';
+/** Parse YYYYMMDD → Date for range validation. */
+function parseDateStr(s) {
+    return new Date(`${s.slice(0, 4)}-${s.slice(4, 6)}-${s.slice(6, 8)}T00:00:00Z`);
+}
+export const noaaMarineGetTidePredictions = tool('noaa_marine_get_tide_predictions', {
+    title: 'Get Tide Predictions',
+    description: 'High/low tide predictions for a CO-OPS tide station over a date range. ' +
+        'Returns time, height, and tide type (H=high, L=low) for each event when using the default hilo interval, ' +
+        'or 6-minute interval predictions for a detailed tide curve. ' +
+        'Datum defaults to MLLW (mean lower low water — standard for US nautical charts). ' +
+        'Date range is limited to 1 year per request; split longer ranges across multiple calls. ' +
+        'Use noaa_marine_find_stations first to resolve a station name or location to a numeric station ID.',
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    input: z.object({
+        station_id: z
+            .string()
+            .regex(/^[A-Za-z0-9_-]{1,20}$/)
+            .describe('CO-OPS tide station ID (numeric, e.g. "9447130" for Seattle). ' +
+            'Obtain from noaa_marine_find_stations with types=["tide"].'),
+        begin_date: z
+            .string()
+            .regex(/^\d{8}$/)
+            .describe('Start date in YYYYMMDD format, e.g. "20240601".'),
+        end_date: z
+            .string()
+            .regex(/^\d{8}$/)
+            .describe('End date in YYYYMMDD format (inclusive), e.g. "20240607".'),
+        datum: z
+            .enum(['MLLW', 'MHHW', 'MSL', 'MTL', 'MHW', 'MLW', 'CD', 'STND'])
+            .default('MLLW')
+            .describe('Tidal datum reference plane. MLLW (default) is the US nautical chart datum. ' +
+            'MSL = mean sea level; MHHW = mean higher high water (flooding reference).'),
+        time_zone: z
+            .enum(['lst_ldt', 'gmt', 'lst'])
+            .default('lst_ldt')
+            .describe('Time zone for returned timestamps. lst_ldt = local standard/daylight time (default); ' +
+            'gmt = UTC; lst = local standard time year-round.'),
+        units: z
+            .enum(['english', 'metric'])
+            .default('english')
+            .describe('Unit system for heights: english = feet; metric = meters.'),
+        interval: z
+            .enum(['hilo', '6min'])
+            .default('hilo')
+            .describe('Prediction interval: hilo (default) returns only high and low tide events; ' +
+            '6min returns a continuous prediction curve at 6-minute intervals.'),
+    }),
+    output: z.object({
+        station_id: z.string().describe('Station ID echoed from the request — for chaining.'),
+        station_name: z
+            .string()
+            .describe('Station name as returned by CO-OPS — confirms the correct station was queried.'),
+        datum: z
+            .string()
+            .describe('Tidal datum used (e.g. MLLW) — echoed for correct interpretation of heights.'),
+        units: z.string().describe('Height units: "english" (feet) or "metric" (meters).'),
+        predictions: z
+            .array(z
+            .object({
+            time: z
+                .string()
+                .describe('Prediction datetime in the requested time zone (YYYY-MM-DD HH:MM format).'),
+            height: z
+                .number()
+                .describe('Predicted water height in the requested units (feet or meters) relative to the datum.'),
+            type: z
+                .string()
+                .optional()
+                .describe('Tide type: H = high tide, L = low tide (only present for hilo interval).'),
+        })
+            .describe('A single tide prediction event.'))
+            .describe('Tide predictions for the requested date range.'),
+    }),
+    errors: [
+        {
+            reason: 'station_not_found',
+            code: JsonRpcErrorCode.InvalidParams,
+            when: 'CO-OPS returned an error for the station ID — likely wrong type or invalid ID.',
+            recovery: 'Use noaa_marine_find_stations with types=["tide"] to obtain a valid tide station ID.',
+        },
+        {
+            reason: 'date_range_exceeded',
+            code: JsonRpcErrorCode.InvalidParams,
+            when: 'Requested date range exceeds the 1-year CO-OPS limit.',
+            recovery: 'Split the request into multiple calls each spanning at most 1 year.',
+        },
+        {
+            reason: 'no_predictions',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'Station exists but CO-OPS returned no prediction data for the date range.',
+            recovery: 'The station may be inactive or not a prediction station. Try a different station ID from noaa_marine_find_stations.',
+        },
+    ],
+    async handler(input, ctx) {
+        // Validate date range ≤ 1 year
+        const begin = parseDateStr(input.begin_date);
+        const end = parseDateStr(input.end_date);
+        const diffDays = (end.getTime() - begin.getTime()) / (1000 * 60 * 60 * 24);
+        if (diffDays > 365) {
+            throw ctx.fail('date_range_exceeded', `Date range of ${Math.ceil(diffDays)} days exceeds the 1-year limit.`, { ...ctx.recoveryFor('date_range_exceeded') });
+        }
+        const svc = getCoopsService();
+        // Fetch station list (for name resolution) and predictions in parallel.
+        // CO-OPS predictions API does not return station metadata — station list is best-effort.
+        const [tideStations, predResult] = await Promise.allSettled([
+            svc.getStations('tidepredictions', ctx),
+            svc.fetchTidePredictions({
+                station: input.station_id,
+                begin_date: input.begin_date,
+                end_date: input.end_date,
+                datum: input.datum,
+                time_zone: input.time_zone,
+                units: input.units,
+                interval: input.interval,
+            }, ctx),
+        ]);
+        const stationMeta = tideStations.status === 'fulfilled'
+            ? tideStations.value.find((s) => s.id === input.station_id)
+            : undefined;
+        if (predResult.status === 'rejected') {
+            const err = predResult.reason;
+            // CO-OPS returns HTTP 400 when the station ID is invalid or wrong type.
+            // fetchWithTimeout intercepts it before service-level JSON parsing — detect via statusCode.
+            if (err instanceof McpError) {
+                const statusCode = err.data?.statusCode;
+                if (statusCode === 400) {
+                    throw ctx.fail('station_not_found', `CO-OPS rejected station ${input.station_id} — use noaa_marine_find_stations with types=["tide"] to verify the ID.`, { ...ctx.recoveryFor('station_not_found') });
+                }
+            }
+            throw err;
+        }
+        const result = predResult.value;
+        if (!result.predictions || result.predictions.length === 0) {
+            throw ctx.fail('no_predictions', `No predictions returned for station ${input.station_id} in the requested date range.`, { ...ctx.recoveryFor('no_predictions') });
+        }
+        const predictions = result.predictions.map((p) => {
+            const entry = {
+                time: p.t,
+                height: Number.parseFloat(p.v),
+            };
+            if (p.type)
+                entry.type = p.type;
+            return entry;
+        });
+        ctx.log.info('Tide predictions fetched', {
+            station_id: input.station_id,
+            count: predictions.length,
+            interval: input.interval,
+        });
+        return {
+            station_id: input.station_id,
+            station_name: stationMeta?.name ?? result.stationName,
+            datum: input.datum,
+            units: input.units,
+            predictions,
+        };
+    },
+    format: (result) => {
+        const lines = [
+            `## Tide Predictions — ${result.station_name} (${result.station_id})`,
+            `**Datum:** ${result.datum} · **Units:** ${result.units}`,
+            '',
+        ];
+        for (const p of result.predictions) {
+            const typeStr = p.type
+                ? ` [${p.type === 'H' ? 'HIGH' : p.type === 'L' ? 'LOW' : p.type}]`
+                : '';
+            lines.push(`${p.time}${typeStr}: ${p.height} ${result.units === 'metric' ? 'm' : 'ft'}`);
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=noaa-marine-get-tide-predictions.tool.js.map

package/dist/mcp-server/tools/definitions/noaa-marine-get-tide-predictions.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"noaa-marine-get-tide-predictions.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/noaa-marine-get-tide-predictions.tool.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/definitions/noaa-marine-get-water-level.tool.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @fileoverview noaa_marine_get_water_level tool — observed water levels with paired predictions.
+ * @module mcp-server/tools/definitions/noaa-marine-get-water-level.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const noaaMarineGetWaterLevel: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    station_id: z.ZodString;
+    begin_date: z.ZodString;
+    end_date: z.ZodString;
+    datum: z.ZodDefault<z.ZodEnum<{
+        MLLW: "MLLW";
+        MHHW: "MHHW";
+        MSL: "MSL";
+        MTL: "MTL";
+        MHW: "MHW";
+        MLW: "MLW";
+        CD: "CD";
+        STND: "STND";
+    }>>;
+    time_zone: z.ZodDefault<z.ZodEnum<{
+        lst_ldt: "lst_ldt";
+        gmt: "gmt";
+        lst: "lst";
+    }>>;
+    units: z.ZodDefault<z.ZodEnum<{
+        english: "english";
+        metric: "metric";
+    }>>;
+}, z.core.$strip>, z.ZodObject<{
+    station_id: z.ZodString;
+    station_name: z.ZodString;
+    datum: z.ZodString;
+    units: z.ZodString;
+    observations: z.ZodArray<z.ZodObject<{
+        time: z.ZodString;
+        value: z.ZodNumber;
+        sigma: z.ZodOptional<z.ZodNumber>;
+        quality: z.ZodString;
+    }, z.core.$strip>>;
+    predictions: z.ZodArray<z.ZodObject<{
+        time: z.ZodString;
+        value: z.ZodNumber;
+    }, z.core.$strip>>;
+    residual_summary: z.ZodOptional<z.ZodObject<{
+        max_surge: z.ZodNumber;
+        max_drawdown: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>, readonly [{
+    readonly reason: "station_not_found";
+    readonly code: JsonRpcErrorCode.InvalidParams;
+    readonly when: "CO-OPS returned an error for the station ID.";
+    readonly recovery: "Use noaa_marine_find_stations with types=[\"water_level\"] to obtain a valid station ID.";
+}, {
+    readonly reason: "date_range_exceeded";
+    readonly code: JsonRpcErrorCode.InvalidParams;
+    readonly when: "Requested date range exceeds the 31-day CO-OPS limit for 6-minute water level data.";
+    readonly recovery: "Split the request into multiple calls each spanning at most 31 days.";
+}, {
+    readonly reason: "no_data";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "Station exists but no observed water-level data for the date range.";
+    readonly recovery: "The station may be offline or the date range may be in the future. Try a different date range or station.";
+}], undefined>;
+//# sourceMappingURL=noaa-marine-get-water-level.tool.d.ts.map

package/dist/mcp-server/tools/definitions/noaa-marine-get-water-level.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"noaa-marine-get-water-level.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/noaa-marine-get-water-level.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAY,MAAM,+BAA+B,CAAC;AAO3E,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAkRlC,CAAC"}

package/dist/mcp-server/tools/definitions/noaa-marine-get-water-level.tool.js

@@ -0,0 +1,232 @@
+/**
+ * @fileoverview noaa_marine_get_water_level tool — observed water levels with paired predictions.
+ * @module mcp-server/tools/definitions/noaa-marine-get-water-level.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode, McpError } from '@cyanheads/mcp-ts-core/errors';
+import { getCoopsService } from '../../../services/coops/coops-service.js';
+function parseDateStr(s) {
+    return new Date(`${s.slice(0, 4)}-${s.slice(4, 6)}-${s.slice(6, 8)}T00:00:00Z`);
+}
+export const noaaMarineGetWaterLevel = tool('noaa_marine_get_water_level', {
+    title: 'Get Water Level',
+    description: 'Observed water level (real-time or historical) for a CO-OPS water-level station, with paired predictions for comparison. ' +
+        'The difference (residual = observed − predicted) indicates storm surge (positive) or anomalous drawdown (negative). ' +
+        'Returns 6-minute observations alongside 6-minute predictions. ' +
+        'Date range is limited to 31 days per request; split longer ranges into multiple calls. ' +
+        'Use noaa_marine_find_stations first to resolve a station name or location to a valid station ID.',
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    input: z.object({
+        station_id: z
+            .string()
+            .regex(/^[A-Za-z0-9_-]{1,20}$/)
+            .describe('CO-OPS water-level station ID (numeric, e.g. "9447130" for Seattle). ' +
+            'Obtain from noaa_marine_find_stations with types=["water_level"].'),
+        begin_date: z
+            .string()
+            .regex(/^\d{8}$/)
+            .describe('Start date in YYYYMMDD format, e.g. "20240601".'),
+        end_date: z
+            .string()
+            .regex(/^\d{8}$/)
+            .describe('End date in YYYYMMDD format (inclusive), e.g. "20240601".'),
+        datum: z
+            .enum(['MLLW', 'MHHW', 'MSL', 'MTL', 'MHW', 'MLW', 'CD', 'STND'])
+            .default('MLLW')
+            .describe('Tidal datum reference plane. MLLW (default) is the US nautical chart datum. ' +
+            'MSL = mean sea level; MHHW = mean higher high water (flooding reference).'),
+        time_zone: z
+            .enum(['lst_ldt', 'gmt', 'lst'])
+            .default('lst_ldt')
+            .describe('Time zone for returned timestamps. lst_ldt = local standard/daylight time (default); ' +
+            'gmt = UTC; lst = local standard time year-round.'),
+        units: z
+            .enum(['english', 'metric'])
+            .default('english')
+            .describe('Unit system: english = feet; metric = meters.'),
+    }),
+    output: z.object({
+        station_id: z.string().describe('Station ID echoed from the request — for chaining.'),
+        station_name: z.string().describe('Station name as returned by CO-OPS.'),
+        datum: z
+            .string()
+            .describe('Tidal datum used — echoed for correct interpretation of water heights.'),
+        units: z.string().describe('Height units: "english" (feet) or "metric" (meters).'),
+        observations: z
+            .array(z
+            .object({
+            time: z.string().describe('Observation datetime in the requested time zone.'),
+            value: z
+                .number()
+                .describe('Observed water height in the requested units relative to the datum.'),
+            sigma: z
+                .number()
+                .optional()
+                .describe('Standard deviation of the water level sensor reading.'),
+            quality: z.string().describe('Quality flag: p = preliminary, v = verified.'),
+        })
+            .describe('A single 6-minute observed water level reading.'))
+            .describe('6-minute observed water level readings.'),
+        predictions: z
+            .array(z
+            .object({
+            time: z.string().describe('Prediction datetime matching the observation time step.'),
+            value: z
+                .number()
+                .describe('Predicted water height in the requested units relative to the datum.'),
+        })
+            .describe('A single 6-minute tide prediction.'))
+            .describe('Paired 6-minute tide predictions for the same period. May be empty if CO-OPS predictions are unavailable for this station.'),
+        residual_summary: z
+            .object({
+            max_surge: z
+                .number()
+                .describe('Maximum positive residual (observed − predicted) in the requested units (feet for english, meters for metric) — storm surge indicator.'),
+            max_drawdown: z
+                .number()
+                .describe('Maximum negative residual magnitude in the requested units (feet for english, meters for metric) — anomalous drawdown indicator.'),
+        })
+            .optional()
+            .describe('Summary of observed-minus-predicted residuals in the requested units. Only present when both observations and predictions are available.'),
+    }),
+    errors: [
+        {
+            reason: 'station_not_found',
+            code: JsonRpcErrorCode.InvalidParams,
+            when: 'CO-OPS returned an error for the station ID.',
+            recovery: 'Use noaa_marine_find_stations with types=["water_level"] to obtain a valid station ID.',
+        },
+        {
+            reason: 'date_range_exceeded',
+            code: JsonRpcErrorCode.InvalidParams,
+            when: 'Requested date range exceeds the 31-day CO-OPS limit for 6-minute water level data.',
+            recovery: 'Split the request into multiple calls each spanning at most 31 days.',
+        },
+        {
+            reason: 'no_data',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'Station exists but no observed water-level data for the date range.',
+            recovery: 'The station may be offline or the date range may be in the future. Try a different date range or station.',
+        },
+    ],
+    async handler(input, ctx) {
+        // Validate date range ≤ 31 days
+        const begin = parseDateStr(input.begin_date);
+        const end = parseDateStr(input.end_date);
+        const diffDays = (end.getTime() - begin.getTime()) / (1000 * 60 * 60 * 24);
+        if (diffDays > 31) {
+            throw ctx.fail('date_range_exceeded', `Date range of ${Math.ceil(diffDays)} days exceeds the 31-day limit for 6-minute water level data.`, { ...ctx.recoveryFor('date_range_exceeded') });
+        }
+        const svc = getCoopsService();
+        const params = {
+            station: input.station_id,
+            begin_date: input.begin_date,
+            end_date: input.end_date,
+            datum: input.datum,
+            time_zone: input.time_zone,
+            units: input.units,
+        };
+        // Fetch observed water level and predictions in parallel
+        const [obsResult, predResult] = await Promise.allSettled([
+            svc.fetchWaterLevel(params, ctx),
+            svc.fetchWaterLevelPredictions(params, ctx),
+        ]);
+        if (obsResult.status === 'rejected') {
+            const err = obsResult.reason;
+            // CO-OPS returns HTTP 400 for invalid station IDs — fetchWithTimeout intercepts before JSON parsing.
+            if (err instanceof McpError) {
+                const statusCode = err.data?.statusCode;
+                if (statusCode === 400) {
+                    throw ctx.fail('station_not_found', `CO-OPS rejected station ${input.station_id} — use noaa_marine_find_stations with types=["water_level"] to verify the ID.`, { ...ctx.recoveryFor('station_not_found') });
+                }
+            }
+            throw err;
+        }
+        const { data: rawObs, stationName } = obsResult.value;
+        if (!rawObs || rawObs.length === 0) {
+            throw ctx.fail('no_data', `No water level data for station ${input.station_id} in the requested date range.`, { ...ctx.recoveryFor('no_data') });
+        }
+        const observations = rawObs.map((row) => {
+            const entry = {
+                time: row.t,
+                value: Number.parseFloat(row.v),
+                quality: row.q ?? 'p',
+            };
+            if (row.s) {
+                const sigma = Number.parseFloat(row.s);
+                if (!Number.isNaN(sigma))
+                    entry.sigma = sigma;
+            }
+            return entry;
+        });
+        const rawPred = predResult.status === 'fulfilled' ? predResult.value : [];
+        const predictions = rawPred.map((p) => ({
+            time: p.t,
+            value: Number.parseFloat(p.v),
+        }));
+        // Compute residual summary when both series are present
+        let residualSummary;
+        if (observations.length > 0 && predictions.length > 0) {
+            const predMap = new Map(predictions.map((p) => [p.time, p.value]));
+            const residuals = [];
+            for (const obs of observations) {
+                const pred = predMap.get(obs.time);
+                if (pred !== undefined)
+                    residuals.push(obs.value - pred);
+            }
+            if (residuals.length > 0) {
+                const maxSurge = Math.max(...residuals);
+                const maxDrawdown = Math.abs(Math.min(...residuals));
+                residualSummary = {
+                    max_surge: Math.round(maxSurge * 100) / 100,
+                    max_drawdown: Math.round(maxDrawdown * 100) / 100,
+                };
+            }
+        }
+        ctx.log.info('Water level data fetched', {
+            station_id: input.station_id,
+            obs_count: observations.length,
+            pred_count: predictions.length,
+        });
+        return {
+            station_id: input.station_id,
+            station_name: stationName,
+            datum: input.datum,
+            units: input.units,
+            observations,
+            predictions,
+            ...(residualSummary ? { residual_summary: residualSummary } : {}),
+        };
+    },
+    format: (result) => {
+        const lines = [
+            `## Water Level — ${result.station_name} (${result.station_id})`,
+            `**Datum:** ${result.datum} · **Units:** ${result.units}`,
+        ];
+        if (result.residual_summary) {
+            const unitLabel = result.units === 'metric' ? 'm' : 'ft';
+            lines.push(`**Max surge:** ${result.residual_summary.max_surge} ${unitLabel} · **Max drawdown:** ${result.residual_summary.max_drawdown} ${unitLabel}`);
+        }
+        lines.push('', `**Observations** (${result.observations.length} records):`);
+        const obsToShow = result.observations.slice(0, 10);
+        for (const o of obsToShow) {
+            const sig = o.sigma !== undefined ? ` ±${o.sigma}` : '';
+            lines.push(`${o.time}: ${o.value} ${result.units === 'metric' ? 'm' : 'ft'}${sig} [${o.quality}]`);
+        }
+        if (result.observations.length > 10) {
+            lines.push(`... and ${result.observations.length - 10} more observations`);
+        }
+        if (result.predictions.length > 0) {
+            lines.push('', `**Predictions** (${result.predictions.length} records):`);
+            const predToShow = result.predictions.slice(0, 5);
+            for (const p of predToShow) {
+                lines.push(`${p.time}: ${p.value} ${result.units === 'metric' ? 'm' : 'ft'} (predicted)`);
+            }
+            if (result.predictions.length > 5) {
+                lines.push(`... and ${result.predictions.length - 5} more predictions`);
+            }
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=noaa-marine-get-water-level.tool.js.map

package/dist/mcp-server/tools/definitions/noaa-marine-get-water-level.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"noaa-marine-get-water-level.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/noaa-marine-get-water-level.tool.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,74 @@
+/**
+ * @fileoverview CO-OPS Tides & Currents API service — station list cache and data fetching.
+ * @module services/coops/coops-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 { ServerConfig } from '../../config/server-config.js';
+import type { CoopsCurrent6MinRow, CoopsCurrentRow, CoopsDataRow, CoopsPredictionRow, CoopsStation, CoopsStationType } from './types.js';
+export declare class CoopsService {
+    private readonly applicationId;
+    private readonly stationCache;
+    constructor(_config: AppConfig, _storage: StorageService, serverConfig: ServerConfig);
+    /** Fetch (or return cached) station list for the given type. */
+    getStations(type: CoopsStationType, ctx: Context): Promise<CoopsStation[]>;
+    /**
+     * Pre-warm the most-used station lists. Called during server setup.
+     * Errors are caught and logged — pre-warm is best-effort.
+     */
+    preWarm(ctx: Context): Promise<void>;
+    /** Fetch tide predictions for a station over a date range. */
+    fetchTidePredictions(params: {
+        station: string;
+        begin_date: string;
+        end_date: string;
+        datum: string;
+        time_zone: string;
+        units: string;
+        interval: string;
+    }, ctx: Context): Promise<{
+        predictions: CoopsPredictionRow[];
+        stationName: string;
+    }>;
+    /** Fetch observed water levels for a station. */
+    fetchWaterLevel(params: {
+        station: string;
+        begin_date: string;
+        end_date: string;
+        datum: string;
+        time_zone: string;
+        units: string;
+    }, ctx: Context): Promise<{
+        data: CoopsDataRow[];
+        stationName: string;
+    }>;
+    /** Fetch water level predictions for the same date range as a water_level request (companion fetch). */
+    fetchWaterLevelPredictions(params: {
+        station: string;
+        begin_date: string;
+        end_date: string;
+        datum: string;
+        time_zone: string;
+        units: string;
+    }, ctx: Context): Promise<CoopsPredictionRow[]>;
+    /** Fetch current predictions for a station. */
+    fetchCurrentPredictions(params: {
+        station: string;
+        begin_date: string;
+        end_date: string;
+        time_zone: string;
+        units: string;
+        interval: string;
+    }, ctx: Context): Promise<{
+        events?: CoopsCurrentRow[];
+        predictions?: CoopsCurrent6MinRow[];
+        stationName: string;
+    }>;
+    private buildDataUrl;
+    private detectHtmlError;
+    private checkCoopsError;
+}
+export declare function initCoopsService(config: AppConfig, storage: StorageService, serverConfig: ServerConfig): void;
+export declare function getCoopsService(): CoopsService;
+//# sourceMappingURL=coops-service.d.ts.map

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

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