Adding API Endpoints

make install    # one-time: installs buf, sebuf plugins, npm deps, proto deps

make generate   # regenerate all TypeScript + OpenAPI from protos

syntax = "proto3";
package worldmonitor.seismology.v1;

import "buf/validate/validate.proto";
import "worldmonitor/seismology/v1/earthquake.proto";

// GetEarthquakeDetailsRequest specifies which earthquake to retrieve.
message GetEarthquakeDetailsRequest {
  // USGS event identifier (e.g., "us7000abcd").
  string earthquake_id = 1 [
    (buf.validate.field).required = true,
    (buf.validate.field).string.min_len = 1,
    (buf.validate.field).string.max_len = 100
  ];
}

// GetEarthquakeDetailsResponse contains the full earthquake record.
message GetEarthquakeDetailsResponse {
  // The earthquake matching the requested ID.
  Earthquake earthquake = 1;
}

import "worldmonitor/seismology/v1/get_earthquake_details.proto";

service SeismologyService {
  // ... existing RPCs ...

  // GetEarthquakeDetails retrieves a single earthquake by its USGS event ID.
  rpc GetEarthquakeDetails(GetEarthquakeDetailsRequest) returns (GetEarthquakeDetailsResponse) {
    option (sebuf.http.config) = {path: "/get-earthquake-details"};
  }
}

make check   # lint + generate in one step

import type {
  SeismologyServiceHandler,
  ServerContext,
  GetEarthquakeDetailsRequest,
  GetEarthquakeDetailsResponse,
} from '../../../../src/generated/server/worldmonitor/seismology/v1/service_server';

export const getEarthquakeDetails: SeismologyServiceHandler['getEarthquakeDetails'] = async (
  _ctx: ServerContext,
  req: GetEarthquakeDetailsRequest,
): Promise<GetEarthquakeDetailsResponse> => {
  const response = await fetch(
    `https://earthquake.usgs.gov/earthquakes/feed/v1.0/detail/${req.earthquakeId}.geojson`,
  );
  if (!response.ok) {
    throw new Error(`USGS API error: ${response.status}`);
  }
  const f: any = await response.json();
  return {
    earthquake: {
      id: f.id,
      place: f.properties.place || '',
      magnitude: f.properties.mag ?? 0,
      depthKm: f.geometry.coordinates[2] ?? 0,
      location: {
        latitude: f.geometry.coordinates[1],
        longitude: f.geometry.coordinates[0],
      },
      occurredAt: f.properties.time,
      sourceUrl: f.properties.url || '',
    },
  };
};

import type { SeismologyServiceHandler } from '../../../../src/generated/server/worldmonitor/seismology/v1/service_server';

import { listEarthquakes } from './list-earthquakes';
import { getEarthquakeDetails } from './get-earthquake-details';

export const seismologyHandler: SeismologyServiceHandler = {
  listEarthquakes,
  getEarthquakeDetails,
};

npx tsc --noEmit   # should pass with zero errors

proto/worldmonitor/weather/v1/

syntax = "proto3";
package worldmonitor.weather.v1;

import "buf/validate/validate.proto";
import "sebuf/http/annotations.proto";

// WeatherStation represents a single ground-based observation station.
message WeatherStation {
  // Unique identifier (e.g., WMO station number).
  string id = 1 [
    (buf.validate.field).required = true,
    (buf.validate.field).string.min_len = 1
  ];
  // Human-readable station name.
  string name = 2;
  // Operating network (e.g., "NWS", "WMO", "NOAA").
  string network = 3;
  // ISO 3166-1 alpha-2 country code where the station is located.
  string country_code = 4;
  // Date the station first reported observations, as Unix epoch milliseconds.
  int64 first_seen_at = 5 [(sebuf.http.int64_encoding) = INT64_ENCODING_NUMBER];
}

syntax = "proto3";
package worldmonitor.weather.v1;

import "buf/validate/validate.proto";
import "worldmonitor/core/v1/pagination.proto";
import "worldmonitor/weather/v1/weather_station.proto";

// ListWeatherStationsRequest specifies filters for weather station data.
message ListWeatherStationsRequest {
  // Filter by operating network (e.g., "NWS"). Empty returns all.
  string network = 1;
  // Filter by country code.
  string country_code = 2 [(buf.validate.field).string.max_len = 2];
  // Pagination parameters.
  worldmonitor.core.v1.PaginationRequest pagination = 3;
}

// ListWeatherStationsResponse contains the matching stations.
message ListWeatherStationsResponse {
  // The list of weather stations.
  repeated WeatherStation stations = 1;
  // Pagination metadata.
  worldmonitor.core.v1.PaginationResponse pagination = 2;
}

syntax = "proto3";
package worldmonitor.weather.v1;

import "sebuf/http/annotations.proto";
import "worldmonitor/weather/v1/list_weather_stations.proto";

// WeatherService provides APIs for weather observation stations.
service WeatherService {
  option (sebuf.http.service_config) = {base_path: "/api/weather/v1"};

  // ListWeatherStations retrieves stations matching the given filters.
  rpc ListWeatherStations(ListWeatherStationsRequest) returns (ListWeatherStationsResponse) {
    option (sebuf.http.config) = {path: "/list-weather-stations"};
  }
}

make check   # lint + generate in one step

server/worldmonitor/weather/v1/
├── handler.ts                     # thin re-export
└── list-weather-stations.ts       # RPC implementation

import type {
  WeatherServiceHandler,
  ServerContext,
  ListWeatherStationsRequest,
  ListWeatherStationsResponse,
} from '../../../../src/generated/server/worldmonitor/weather/v1/service_server';

export const listWeatherStations: WeatherServiceHandler['listWeatherStations'] = async (
  _ctx: ServerContext,
  req: ListWeatherStationsRequest,
): Promise<ListWeatherStationsResponse> => {
  // Your implementation here — fetch from upstream API, transform to proto shape
  return { stations: [], pagination: undefined };
};

import type { WeatherServiceHandler } from '../../../../src/generated/server/worldmonitor/weather/v1/service_server';

import { listWeatherStations } from './list-weather-stations';

export const weatherHandler: WeatherServiceHandler = {
  listWeatherStations,
};

export const config = { runtime: 'edge' };

import { createDomainGateway, serverOptions } from '../../../server/gateway';
import { createWeatherServiceRoutes } from '../../../src/generated/server/worldmonitor/weather/v1/service_server';
import { weatherHandler } from '../../../server/worldmonitor/weather/v1/handler';

export default createDomainGateway(
  createWeatherServiceRoutes(weatherHandler, serverOptions),
);

import {
  WeatherServiceClient,
  type WeatherStation,
  type ListWeatherStationsResponse,
} from '@/generated/client/worldmonitor/weather/v1/service_client';
import { createCircuitBreaker } from '@/utils';

export type { WeatherStation };

const client = new WeatherServiceClient('', { fetch: (...args) => globalThis.fetch(...args) });
const breaker = createCircuitBreaker<ListWeatherStationsResponse>({ name: 'Weather' });

const emptyFallback: ListWeatherStationsResponse = { stations: [] };

export async function fetchWeatherStations(network?: string): Promise<WeatherStation[]> {
  const response = await breaker.execute(async () => {
    return client.listWeatherStations({ network: network ?? '', countryCode: '', pagination: undefined });
  }, emptyFallback);
  return response.stations;
}

npx tsc --noEmit   # zero errors

int64 occurred_at = 6 [(sebuf.http.int64_encoding) = INT64_ENCODING_NUMBER];

// Required string with length bounds
string id = 1 [
  (buf.validate.field).required = true,
  (buf.validate.field).string.min_len = 1,
  (buf.validate.field).string.max_len = 100
];

// Numeric range (e.g., score 0-100)
double risk_score = 2 [
  (buf.validate.field).double.gte = 0,
  (buf.validate.field).double.lte = 100
];

// Non-negative value
double min_magnitude = 3 [(buf.validate.field).double.gte = 0];

// Coordinate bounds (prefer using core.v1.GeoCoordinates instead)
double latitude = 1 [
  (buf.validate.field).double.gte = -90,
  (buf.validate.field).double.lte = 90
];

export const listWeatherStations: WeatherServiceHandler['listWeatherStations'] = async (
  _ctx: ServerContext,
  req: ListWeatherStationsRequest,
): Promise<ListWeatherStationsResponse> => {
  // ...
};

const client = new WeatherServiceClient('', { fetch: (...args) => globalThis.fetch(...args) });