Add @neaps/api HTTP JSON API package

[bkeepers]

Summary

This PR adds a new @neaps/api package that provides a REST API for tide predictions with OpenAPI specification.

Key Features

• ✅ Express-based HTTP API with 6 REST endpoints
• ✅ OpenAPI 3.0 specification for easy integration
• ✅ Comprehensive test coverage (34 tests, 93% coverage)
• ✅ Node-optimized build (ESM-only, target Node 18+)
• ✅ Full coordinate format support (lat/latitude, lon/lng/longitude)
• ✅ Subordinate station handling with appropriate error messages

API Endpoints

• GET /extremes - Get high/low tide predictions for a location
• GET /timeline - Get water level predictions at intervals
• GET /stations - Find stations by ID or near coordinates
• GET /stations/:id/extremes - Get extremes for a specific station
• GET /stations/:id/timeline - Get timeline for a specific station
• GET /openapi.json - OpenAPI 3.0 specification

Usage

import { startServer } from '@neaps/api';

// Start standalone server
startServer(3000);

// Or use as Express middleware
import { createApp } from '@neaps/api';
import express from 'express';

const app = express();
app.use('/api', createApp());
app.listen(3000);

Package Structure

• src/index.ts - Main Express app with middleware
• src/routes/index.ts - Route handlers for all endpoints
• src/openapi.json - OpenAPI 3.0 specification
• test/index.test.ts - Comprehensive test suite
• tsdown.config.js - Node-optimized build configuration

Testing

All tests pass with 93% code coverage:

• ✅ 34 tests across all endpoints
• ✅ Parameter validation tests
• ✅ Station resolution tests (reference and subordinate)
• ✅ Error handling tests
• ✅ OpenAPI spec validation

Documentation

• Added comprehensive README for @neaps/api package
• Updated root README with API usage examples
• All code passes linting and formatting checks

Build Configuration

Uses Node-optimized tsdown config:

• ESM-only output (no CJS)
• Target: Node 18+
• Platform: node
• Smaller, faster builds for server environments

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (84732a2) to head (6c47e33).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##              main      #192   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           65        67    +2     
  Lines          531       581   +50     
  Branches        58        71   +13     
=========================================
+ Hits           531       581   +50     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Copilot]

Pull request overview

Adds a new @neaps/api workspace package that exposes the neaps tide prediction functionality over an Express-based HTTP JSON REST API, including an OpenAPI 3.0 spec and endpoint-level tests.

Changes:

• Introduces @neaps/api package with Express router, OpenAPI spec, and ESM build configuration.
• Adds a comprehensive Vitest + Supertest suite covering the API endpoints and error cases.
• Updates the monorepo root README and workspaces list to include/document the new package.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 13 comments.

Show a summary per file

File	Description
packages/api/vitest.config.ts	Adds Vitest config for the new API package.
packages/api/tsdown.config.js	Adds tsdown build config targeting Node 18+ ESM output.
packages/api/tsconfig.json	Adds package-local TS config (typecheck-oriented).
packages/api/test/index.test.ts	Adds Supertest-driven endpoint tests.
packages/api/src/routes.ts	Implements Express routes + OpenAPI request/response validation + error middleware.
packages/api/src/openapi.ts	Defines the OpenAPI 3.0 document served/used for validation.
packages/api/src/index.ts	Exposes createApp and exports for router/spec.
packages/api/package.json	Defines new workspace package metadata, build scripts, and dependencies.
packages/api/README.md	Adds package-level usage and endpoint documentation.
package.json	Updates workspace list to include packages/api.
README.md	Documents @neaps/api usage and endpoints at the repo root.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

@bkeepers I've opened a new pull request, #194, to work on those changes. Once the pull request is ready, I'll request review from you.

[Copilot]

@bkeepers I've opened a new pull request, #195, to work on those changes. Once the pull request is ready, I'll request review from you.