Add @neaps/api HTTP JSON API package (#192)

Author: bkeepers

README.md

@@ -9,6 +9,14 @@ A tide prediction engine written in TypeScript.
 >
 > Do not use calculations from this project for navigation, or depend on them in any situation where inaccuracies could result in harm to a person or property. Tide predictions are only as good as the harmonics data available, and these can be inconsistent and vary widely based on the accuracy of the source data and local conditions. The tide predictions do not factor events such as storm surge, wind waves, uplift, tsunamis, or sadly, climate change. 😢
 
+## Packages
+
+This monorepo contains:
+
+- **[neaps](packages/neaps)** - Main tide prediction library with station finding
+- **[@neaps/api](packages/api)** - HTTP JSON API for tide predictions with OpenAPI specification
+- **[@neaps/tide-predictor](packages/tide-predictor)** - Core harmonic tide prediction engine
+
 ## Installation
 
 ```sh

eslint.config.js

@@ -1,12 +1,18 @@
 import eslint from "@eslint/js";
 import tseslint from "typescript-eslint";
 import prettier from "eslint-config-prettier";
+import globals from "globals";
 
 export default [
   { ignores: ["dist/", "node_modules/", "packages/*/dist"] },
   eslint.configs.recommended,
   ...tseslint.configs.recommended,
   prettier,
   { files: ["**/*.ts"], languageOptions: { parser: tseslint.parser } },
-  { files: ["**/*.js"] },
+  {
+    files: ["packages/api/**/*.{js,ts}"],
+    languageOptions: {
+      globals: globals.node,
+    },
+  },
 ];

package.json

@@ -16,6 +16,7 @@
     "@vitest/coverage-v8": "^4.0.15",
     "eslint": "^9.39.2",
     "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.2.0",
     "make-fetch-happen": "^15.0.3",
     "npm-run-all": "^4.1.5",
     "prettier": "^3.7.4",
@@ -25,6 +26,8 @@
     "vitest": "^4.0.15"
   },
   "workspaces": [
-    "packages/*"
+    "packages/tide-predictor",
+    "packages/neaps",
+    "packages/api"
   ]
 }

packages/api/README.md

@@ -0,0 +1,146 @@
+# @neaps/api
+
+HTTP JSON API for tide predictions using [neaps](https://github.com/neaps/neaps).
+
+## Installation
+
+```bash
+npm install @neaps/api
+```
+
+## Usage
+
+### As a standalone server
+
+```typescript
+import { createApp } from "@neaps/api";
+
+const app = createApp();
+
+app.listen(3000, () => {
+  console.log("Server listening on port 3000");
+});
+```
+
+### As an Express middleware
+
+```typescript
+import { createApp } from "@neaps/api";
+import express from "express";
+
+const mainApp = express();
+
+// Mount the API at a specific path
+mainApp.use("/api", createApp());
+
+mainApp.listen(3000, () => {
+  console.log("Server listening on port 3000");
+});
+```
+
+## API Endpoints
+
+### GET /tides/extremes
+
+Get high and low tide predictions for the nearest station to given coordinates.
+
+**Query Parameters:**
+
+- `latitude` (required): Latitude (-90 to 90)
+- `longitude` (required): Longitude (-180 to 180)
+- `start` (required): Start date/time in ISO 8601 format
+- `end` (required): End date/time in ISO 8601 format
+- `datum` (optional): Vertical datum (MLLW, MLW, MTL, MSL, MHW, MHHW)
+- `units` (optional): Units for water levels (meters or feet, defaults to meters)
+
+**Example:**
+
+```bash
+curl "http://localhost:3000/tides/extremes?latitude=26.772&longitude=-80.05&start=2025-12-17T00:00:00Z&end=2025-12-18T00:00:00Z&datum=MLLW&units=feet"
+```
+
+### GET /tides/timeline
+
+Get water level predictions at regular intervals for the nearest station.
+
+**Query Parameters:** Same as `/extremes`
+
+**Example:**
+
+```bash
+curl "http://localhost:3000/tides/timeline?latitude=26.772&longitude=-80.05&start=2025-12-17T00:00:00Z&end=2025-12-18T00:00:00Z"
+```
+
+### GET /tides/stations
+
+Find stations by ID or near a location.
+
+**Query Parameters:**
+
+- `id` (optional): Station ID or source ID
+- `latitude` (optional): Latitude for proximity search
+- `longitude` (optional): Longitude for proximity search
+- `limit` (optional): Maximum number of stations to return (1-100, defaults to 10)
+
+**Examples:**
+
+```bash
+# Find a specific station
+curl "http://localhost:3000/tides/stations?id=noaa/8722588"
+
+# Find stations near coordinates
+curl "http://localhost:3000/tides/stations?latitude=26.772&longitude=-80.05&limit=5"
+```
+
+### GET /tides/stations/:id/extremes
+
+Get extremes prediction for a specific station.
+
+**Path Parameters:**
+
+- `id` (required): Station ID (URL-encoded if contains special characters)
+
+**Query Parameters:**
+
+- `start` (required): Start date/time in ISO 8601 format
+- `end` (required): End date/time in ISO 8601 format
+- `datum` (optional): Vertical datum
+- `units` (optional): Units for water levels
+
+**Example:**
+
+```bash
+curl "http://localhost:3000/tides/stations/noaa%2F8722588/extremes?start=2025-12-17T00:00:00Z&end=2025-12-18T00:00:00Z"
+```
+
+### GET /tides/stations/:id/timeline
+
+Get timeline prediction for a specific station.
+
+**Parameters:** Same as `/stations/:id/extremes`
+
+**Note:** Timeline predictions are not supported for subordinate stations.
+
+### GET /tides/openapi.json
+
+Get the OpenAPI 3.0 specification for this API.
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npx vitest
+
+# Run tests with coverage
+npx vitest run --coverage
+```
+
+## License
+
+MIT

packages/api/bin/server.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+import { createApp } from "@neaps/api";
+
+const port = process.env.PORT || 3000;
+const app = createApp();
+
+app.listen(port, () => {
+  console.log(`Neaps API listening on http://localhost:${port}`);
+});

packages/api/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@neaps/api",
+  "version": "0.2.0",
+  "description": "HTTP JSON API for tide predictions",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/neaps/neaps.git",
+    "directory": "packages/api"
+  },
+  "author": "Brandon Keepers <brandon@openwaters.io>",
+  "license": "MIT",
+  "type": "module",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "bin": {
+    "neaps-server": "./bin/server.js"
+  },
+  "scripts": {
+    "build": "tsc && tsdown",
+    "prepack": "npm run build",
+    "start": "node bin/server.js"
+  },
+  "dependencies": {
+    "express": "^4.18.2",
+    "express-openapi-validator": "^5.1.6",
+    "neaps": "^0.3.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/supertest": "^6.0.2",
+    "supertest": "^6.3.3"
+  }
+}

packages/api/src/index.ts

@@ -0,0 +1,9 @@
+import express from "express";
+import routes from "./routes.js";
+import openapi from "./openapi.js";
+
+export function createApp() {
+  return express().use("/", routes);
+}
+
+export { routes, openapi };