@k2b/cloud 0.6.0-rc.0

package/src/services/weather/forecast.ts

@@ -0,0 +1,323 @@
+import { redis } from "bun";
+import { logger } from "../logging";
+import { coreSettings } from "../settings/api";
+import type { CurrentWeather, DailyForecast, HourlyForecast, WeatherData, WeatherIcon } from "./types";
+
+const log = logger("weather");
+
+const BRIGHTSKY_API = "https://api.brightsky.dev";
+const BRIGHTSKY_TIMEOUT_MS = 400;
+
+export type ForecastLocationConfig = {
+  lat?: string;
+  lon?: string;
+};
+
+type ResolvedForecastLocation = {
+  lat: string;
+  lon: string;
+};
+
+const resolveForecastLocation = async (config?: ForecastLocationConfig): Promise<ResolvedForecastLocation | null> => {
+  const lat = (config?.lat ?? (await coreSettings.get<string>("weather.default_lat"))).trim();
+  const lon = (config?.lon ?? (await coreSettings.get<string>("weather.default_lon"))).trim();
+
+  if (!lat || !lon) {
+    log.error("Weather default coordinates are not configured", {
+      missing: [!lat ? "weather.default_lat" : null, !lon ? "weather.default_lon" : null].filter(Boolean),
+    });
+    return null;
+  }
+
+  return { lat, lon };
+};
+
+/** Brightsky current_weather API response */
+type BrightskyCurrentResponse = {
+  weather: {
+    timestamp: string;
+    source_id: number;
+    cloud_cover: number | null;
+    condition: string | null;
+    dew_point: number | null;
+    icon: WeatherIcon | null;
+    precipitation_10: number | null;
+    precipitation_30: number | null;
+    precipitation_60: number | null;
+    pressure_msl: number | null;
+    relative_humidity: number | null;
+    solar_10: number | null;
+    solar_30: number | null;
+    solar_60: number | null;
+    sunshine_30: number | null;
+    sunshine_60: number | null;
+    temperature: number | null;
+    visibility: number | null;
+    wind_direction_10: number | null;
+    wind_direction_30: number | null;
+    wind_direction_60: number | null;
+    wind_gust_direction_10: number | null;
+    wind_gust_direction_30: number | null;
+    wind_gust_direction_60: number | null;
+    wind_gust_speed_10: number | null;
+    wind_gust_speed_30: number | null;
+    wind_gust_speed_60: number | null;
+    wind_speed_10: number | null;
+    wind_speed_30: number | null;
+    wind_speed_60: number | null;
+  };
+  sources: Array<{
+    id: number;
+    dwd_station_id: string;
+    station_name: string;
+    lat: number;
+    lon: number;
+    height: number;
+    distance: number;
+  }>;
+};
+
+/** Brightsky weather (forecast) API response */
+type BrightskyWeatherResponse = {
+  weather: Array<{
+    timestamp: string;
+    temperature: number | null;
+    icon: WeatherIcon | null;
+    precipitation: number | null;
+    precipitation_probability: number | null;
+    wind_speed: number | null;
+    cloud_cover: number | null;
+    sunshine: number | null;
+  }>;
+  sources: Array<{
+    station_name: string;
+  }>;
+};
+
+/** Get cache key for location (default or custom). */
+const getCacheKey = (lat: string, lon: string): string => {
+  return `weather:${lat}:${lon}`;
+};
+
+/** Fetch current weather from Brightsky API. */
+const fetchCurrentFromApi = async (lat: string, lon: string): Promise<CurrentWeather | null> => {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), BRIGHTSKY_TIMEOUT_MS);
+
+  try {
+    const url = `${BRIGHTSKY_API}/current_weather?lat=${lat}&lon=${lon}`;
+    const response = await fetch(url, { signal: controller.signal });
+
+    if (!response.ok) {
+      log.error("Brightsky API error", { status: response.status });
+      return null;
+    }
+
+    const data: BrightskyCurrentResponse = await response.json();
+
+    if (!data.weather || data.weather.temperature === null) {
+      log.error("Invalid Brightsky response");
+      return null;
+    }
+
+    const w = data.weather;
+    const source = data.sources?.[0];
+
+    return {
+      temperature: Math.round(w.temperature!),
+      icon: w.icon ?? "cloudy",
+      cloudCover: w.cloud_cover ?? 0,
+      windSpeed: Math.round(w.wind_speed_10 ?? w.wind_speed_30 ?? 0),
+      windGust: w.wind_gust_speed_10 ? Math.round(w.wind_gust_speed_10) : null,
+      windDirection: w.wind_direction_10 ?? w.wind_direction_30 ?? null,
+      humidity: w.relative_humidity,
+      precipitation: w.precipitation_60 ?? 0,
+      pressure: w.pressure_msl != null ? Math.round(w.pressure_msl) : null,
+      visibility: w.visibility != null ? Math.round(w.visibility) : null,
+      dewPoint: w.dew_point != null ? Math.round(w.dew_point * 10) / 10 : null,
+      sunshine: w.sunshine_60 != null ? w.sunshine_60 : null,
+      stationName: source?.station_name ?? "Unknown",
+      timestamp: w.timestamp,
+    };
+  } catch (error) {
+    log.error("Failed to fetch from Brightsky", {
+      error: error instanceof Error ? error.message : String(error),
+      timeoutMs: BRIGHTSKY_TIMEOUT_MS,
+    });
+    return null;
+  } finally {
+    clearTimeout(timeout);
+  }
+};
+
+/** Get current weather, using Redis cache. */
+export const getCurrentWeather = async (config?: ForecastLocationConfig): Promise<CurrentWeather | null> => {
+  const location = await resolveForecastLocation(config);
+  if (!location) return null;
+
+  const { lat, lon } = location;
+  const cacheKey = getCacheKey(lat, lon);
+
+  const cached = await redis.get(cacheKey);
+  if (cached) {
+    try {
+      return JSON.parse(cached) as CurrentWeather;
+    } catch {
+      // Invalid cache, will refetch
+    }
+  }
+
+  const result = await fetchCurrentFromApi(lat, lon);
+  if (!result) return null;
+
+  const ttl = Math.round(((await coreSettings.get<number>("weather.cache_minutes")) ?? 30) * 60);
+  await redis.set(cacheKey, JSON.stringify(result), "EX", ttl);
+
+  return result;
+};
+
+/** Get most common icon from array. */
+const getMostCommonIcon = (icons: WeatherIcon[]): WeatherIcon => {
+  if (icons.length === 0) return "cloudy";
+  const counts = new Map<WeatherIcon, number>();
+  for (const icon of icons) {
+    counts.set(icon, (counts.get(icon) ?? 0) + 1);
+  }
+  let maxCount = 0;
+  let result: WeatherIcon = "cloudy";
+  for (const [icon, count] of counts) {
+    if (count > maxCount) {
+      maxCount = count;
+      result = icon;
+    }
+  }
+  return result;
+};
+
+/** Fetch weather forecast from Brightsky API. */
+const fetchForecastFromApi = async (lat: string, lon: string): Promise<{ hourly: HourlyForecast[]; daily: DailyForecast[] } | null> => {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), BRIGHTSKY_TIMEOUT_MS);
+
+  try {
+    const now = new Date();
+    const endDate = new Date(now.getTime() + 7 * 24 * 60 * 60 * 1000);
+
+    const dateStr = now.toISOString().split("T")[0];
+    const endDateStr = endDate.toISOString().split("T")[0];
+
+    const url = `${BRIGHTSKY_API}/weather?lat=${lat}&lon=${lon}&date=${dateStr}&last_date=${endDateStr}`;
+    const response = await fetch(url, { signal: controller.signal });
+
+    if (!response.ok) {
+      log.error("Brightsky forecast API error", { status: response.status });
+      return null;
+    }
+
+    const data: BrightskyWeatherResponse = await response.json();
+
+    if (!data.weather || data.weather.length === 0) {
+      return null;
+    }
+
+    const hourly: HourlyForecast[] = data.weather
+      .filter((w) => w.temperature !== null && new Date(w.timestamp) >= now)
+      .slice(0, 12)
+      .map((w) => ({
+        timestamp: w.timestamp,
+        temperature: Math.round(w.temperature ?? 0),
+        icon: w.icon ?? "cloudy",
+        precipitation: w.precipitation ?? 0,
+        precipitationProbability: w.precipitation_probability,
+        windSpeed: Math.round(w.wind_speed ?? 0),
+        cloudCover: w.cloud_cover ?? 0,
+      }));
+
+    const dailyMap = new Map<
+      string,
+      {
+        temps: number[];
+        icons: WeatherIcon[];
+        precip: number;
+        precipProb: number[];
+        sunshine: number;
+      }
+    >();
+
+    for (const w of data.weather) {
+      if (w.temperature === null) continue;
+      const date = w.timestamp.split("T")[0];
+      if (!date) continue;
+      const existing = dailyMap.get(date) ?? {
+        temps: [],
+        icons: [],
+        precip: 0,
+        precipProb: [],
+        sunshine: 0,
+      };
+      existing.temps.push(w.temperature);
+      if (w.icon) existing.icons.push(w.icon);
+      existing.precip += w.precipitation ?? 0;
+      if (w.precipitation_probability != null) {
+        existing.precipProb.push(w.precipitation_probability);
+      }
+      existing.sunshine += w.sunshine ?? 0;
+      dailyMap.set(date, existing);
+    }
+
+    const daily: DailyForecast[] = Array.from(dailyMap.entries())
+      .slice(0, 7)
+      .map(([date, day]) => ({
+        date,
+        tempMin: Math.round(Math.min(...day.temps)),
+        tempMax: Math.round(Math.max(...day.temps)),
+        icon: getMostCommonIcon(day.icons),
+        precipitation: Math.round(day.precip * 10) / 10,
+        precipitationProbability: day.precipProb.length > 0 ? Math.max(...day.precipProb) : null,
+        sunshine: Math.round(day.sunshine),
+      }));
+
+    return { hourly, daily };
+  } catch (error) {
+    log.error("Failed to fetch forecast", {
+      error: error instanceof Error ? error.message : String(error),
+      timeoutMs: BRIGHTSKY_TIMEOUT_MS,
+    });
+    return null;
+  } finally {
+    clearTimeout(timeout);
+  }
+};
+
+/** Get full weather data including forecasts. */
+export const getWeatherData = async (config?: ForecastLocationConfig): Promise<WeatherData | null> => {
+  const location = await resolveForecastLocation(config);
+  if (!location) return null;
+
+  const { lat, lon } = location;
+  const cacheKey = `weather:full:${lat}:${lon}`;
+
+  const cached = await redis.get(cacheKey);
+  if (cached) {
+    try {
+      return JSON.parse(cached) as WeatherData;
+    } catch {
+      // Invalid cache, will refetch
+    }
+  }
+
+  const [current, forecast] = await Promise.all([getCurrentWeather(location), fetchForecastFromApi(lat, lon)]);
+
+  if (!current) return null;
+
+  const result: WeatherData = {
+    current,
+    hourly: forecast?.hourly ?? [],
+    daily: forecast?.daily ?? [],
+  };
+
+  const ttl = Math.round(((await coreSettings.get<number>("weather.cache_minutes")) ?? 30) * 60);
+  await redis.set(cacheKey, JSON.stringify(result), "EX", ttl);
+
+  return result;
+};

package/src/services/weather/geo.ts

@@ -0,0 +1,119 @@
+import { err, fail, ok, type PageParams, type Paginated, type Result } from "@k2b/stdlib";
+import { type GeoPlace, geoService } from "../../server";
+import * as settings from "../settings";
+
+export const WEATHER_COUNTRY_CODE = "DE";
+
+export type WeatherCity = {
+  name: string;
+  lat: number;
+  lon: number;
+  country?: string;
+  state?: string;
+};
+
+const unavailable = <T>(): Result<T> =>
+  fail({
+    code: "WEATHER_CITY_SEARCH_UNAVAILABLE",
+    message: "Weather city search is unavailable",
+    status: 500,
+  });
+
+/**
+ * Adapts generic geo place data to the weather app's city model.
+ */
+const mapPlace = (place: GeoPlace): WeatherCity => ({
+  name: place.name,
+  lat: place.lat,
+  lon: place.lon,
+  country: place.country,
+  state: place.state,
+});
+
+/**
+ * Resolves and validates the configured geo service base URL.
+ */
+const getGeoBaseUrl = async (): Promise<Result<string>> => {
+  const geoUrl = (await settings.get<string>("weather.geo_url")).trim();
+  if (!geoUrl) {
+    return fail(err.internal("Geo API URL is not configured. Set weather.geo_url."));
+  }
+  return ok(geoUrl.replace(/\/$/, ""));
+};
+
+/**
+ * Searches city candidates via the geo backend and enforces weather-specific country constraints.
+ */
+const list = async (config: {
+  pagination?: PageParams;
+  signal?: AbortSignal;
+  filter: {
+    query: string;
+    country?: string;
+  };
+}): Promise<Result<Paginated<WeatherCity>>> => {
+  const query = config.filter.query.trim();
+  if (!query) {
+    return ok({
+      items: [],
+      page: config.pagination?.page ?? 1,
+      perPage: config.pagination?.perPage ?? 20,
+      total: 0,
+      hasNext: false,
+    });
+  }
+
+  const requestedCountry = config.filter.country?.trim().toUpperCase() ?? WEATHER_COUNTRY_CODE;
+  if (requestedCountry !== WEATHER_COUNTRY_CODE) {
+    return fail(err.badInput("Only German city search is supported (country=DE)."));
+  }
+
+  const baseUrlResult = await getGeoBaseUrl();
+  if (!baseUrlResult.ok) return unavailable();
+  const geoUrl = baseUrlResult.data;
+  const result = await geoService.place.list({
+    baseUrl: geoUrl,
+    pagination: config.pagination,
+    signal: config.signal,
+    filter: {
+      query,
+      country: WEATHER_COUNTRY_CODE,
+      featureClass: "P",
+    },
+  });
+  if (!result.ok) return unavailable();
+
+  return ok({
+    ...result.data,
+    items: result.data.items.map(mapPlace),
+  });
+};
+
+/**
+ * Resolves one place by coordinates via the geo backend.
+ */
+const get = async (config: { lat: number; lon: number }): Promise<Result<WeatherCity | null>> => {
+  const baseUrlResult = await getGeoBaseUrl();
+  if (!baseUrlResult.ok) return baseUrlResult;
+  const result = await geoService.place.get({
+    baseUrl: baseUrlResult.data,
+    lat: config.lat,
+    lon: config.lon,
+  });
+  if (!result.ok) return result;
+
+  const place = result.data;
+  if (!place) return ok(null);
+  if (place.featureClass !== undefined && place.featureClass !== "P") {
+    return ok(null);
+  }
+
+  return ok(mapPlace(place));
+};
+
+export const weatherCityService = {
+  list,
+  get,
+};
+
+export type WeatherCityService = typeof weatherCityService;

package/src/services/weather/index.ts

@@ -0,0 +1,67 @@
+import { err, fail, ok, type Result } from "@k2b/stdlib";
+import { registerSettings, toLegacySettingDefs } from "../settings/defaults";
+import { getCurrentWeather, getWeatherData } from "./forecast";
+import { WEATHER_COUNTRY_CODE } from "./geo";
+import { weatherLocationService } from "./location";
+import { weatherLocationsService } from "./locations";
+import { WEATHER_SETTINGS } from "./settings";
+import type { WeatherData } from "./types";
+import { weatherUiService } from "./ui";
+
+registerSettings(toLegacySettingDefs(WEATHER_SETTINGS));
+
+/**
+ * Resolves a city name to coordinates and returns weather for the first match.
+ */
+const getByCityName = async (config: { query: string }): Promise<Result<WeatherData>> => {
+  const query = config.query.trim();
+  if (!query) {
+    return fail(err.badInput("City query is required"));
+  }
+
+  const cityResult = await weatherLocationService.city.list({
+    pagination: { page: 1, perPage: 1 },
+    filter: {
+      query,
+      country: WEATHER_COUNTRY_CODE,
+    },
+  });
+  if (!cityResult.ok) return cityResult;
+
+  const city = cityResult.data.items[0];
+  if (!city) {
+    return fail(err.notFound("City"));
+  }
+
+  const weather = await getWeatherData({
+    lat: String(city.lat),
+    lon: String(city.lon),
+  });
+  if (!weather) {
+    return fail(err.notFound("Weather data for city"));
+  }
+
+  return ok(weather);
+};
+
+export const weatherService = {
+  forecast: {
+    get: getWeatherData,
+    current: {
+      get: getCurrentWeather,
+    },
+    getByCityName,
+  },
+  location: weatherLocationService,
+  locations: weatherLocationsService,
+  ui: weatherUiService,
+};
+
+export type WeatherService = typeof weatherService;
+export type {
+  CurrentWeather,
+  DailyForecast,
+  HourlyForecast,
+  WeatherData,
+  WeatherIcon,
+} from "./types";

package/src/services/weather/location.ts

@@ -0,0 +1,24 @@
+import { weatherCityService } from "./geo";
+import { weatherLocationsService } from "./locations";
+
+/** Weather location cookie name. */
+export const WEATHER_LOCATION_COOKIE = "weather_location";
+
+/** Parse weather location from cookie value. */
+export const parseLocationCookie = (cookieValue: string | undefined): { lat: string; lon: string } | undefined => {
+  if (!cookieValue) return undefined;
+  const [lat, lon] = cookieValue.split(",");
+  if (!lat || !lon) return undefined;
+  return { lat, lon };
+};
+
+export const weatherLocationService = {
+  saved: weatherLocationsService,
+  city: weatherCityService,
+  cookie: {
+    name: WEATHER_LOCATION_COOKIE,
+    parse: parseLocationCookie,
+  },
+};
+
+export type WeatherLocationService = typeof weatherLocationService;

package/src/services/weather/locations.ts

@@ -0,0 +1,133 @@
+import { err, fail, ok, type PageParams, type Paginated, paginate, type Result } from "@k2b/stdlib";
+import { sql } from "bun";
+import { logger } from "../logging";
+import { withWeatherLocationShortId } from "./short-id";
+
+const log = logger("weather");
+
+export type Location = {
+  id: string;
+  name: string;
+  state: string | null;
+  lat: number;
+  lon: number;
+};
+
+/**
+ * Stores one user-owned weather location and returns the persisted row.
+ */
+const create = async (config: {
+  userId: string;
+  data: {
+    name: string;
+    state?: string;
+    lat: number;
+    lon: number;
+  };
+}): Promise<Result<Location>> => {
+  try {
+    const location = await sql.begin(async (tx) => {
+      await tx`SELECT pg_advisory_xact_lock(hashtext('cloud.weather.location-short-id-backfill'))`;
+      return withWeatherLocationShortId(async (shortId) => {
+        const [row] = await tx`
+          INSERT INTO weather_locations (short_id, user_id, name, state, lat, lon)
+          VALUES (${shortId}, ${config.userId}, ${config.data.name}, ${config.data.state ?? null}, ${config.data.lat}, ${config.data.lon})
+          ON CONFLICT (short_id) DO NOTHING
+          RETURNING short_id AS id, name, state, lat, lon
+        `;
+        return (row as Location | undefined) ?? null;
+      });
+    });
+    return ok(location);
+  } catch (error) {
+    log.error("Failed to create location", {
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return fail(err.internal("Failed to create location"));
+  }
+};
+
+/**
+ * Deletes one saved location owned by the user and reports `NOT_FOUND` when no row matches.
+ */
+const remove = async (config: { id: string; userId: string }): Promise<Result<void>> => {
+  try {
+    const result = await sql`
+      DELETE FROM weather_locations
+      WHERE short_id = ${config.id} AND user_id = ${config.userId}
+      RETURNING short_id
+    `;
+
+    if (result.length === 0) {
+      return fail(err.notFound("Location"));
+    }
+
+    return ok();
+  } catch (error) {
+    log.error("Failed to delete location", {
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return fail(err.internal("Failed to delete location"));
+  }
+};
+
+/**
+ * Lists all saved weather locations for one user with optional search and pagination.
+ */
+const list = async (config: { userId: string; pagination?: PageParams; filter?: { query?: string } }): Promise<Paginated<Location>> => {
+  const query = config.filter?.query?.trim().toLowerCase() ?? "";
+  const queryMatch =
+    query.length > 0
+      ? sql`(
+          POSITION(${query} IN LOWER(name)) > 0
+          OR POSITION(${query} IN LOWER(COALESCE(state, ''))) > 0
+        )`
+      : sql`true`;
+  const pagination = config.pagination ? paginate(config.pagination) : null;
+
+  const [countRow] = await sql<{ count: number }[]>`
+    SELECT COUNT(*)::int AS count
+    FROM weather_locations
+    WHERE user_id = ${config.userId}
+      AND ${queryMatch}
+  `;
+
+  const items = (await sql`
+    SELECT short_id AS id, name, state, lat, lon
+    FROM weather_locations
+    WHERE user_id = ${config.userId}
+      AND ${queryMatch}
+    ORDER BY created_at ASC, id ASC
+    LIMIT ${pagination?.perPage ?? null}
+    OFFSET ${pagination?.offset ?? 0}
+  `) as Location[];
+  const total = countRow?.count ?? 0;
+  const page = pagination?.page ?? 1;
+  const perPage = pagination?.perPage ?? total;
+  return {
+    items,
+    page,
+    perPage,
+    total,
+    hasNext: pagination !== null && page * perPage < total,
+  };
+};
+
+/**
+ * Returns one saved location for the owning user, or `null` if it is missing/inaccessible.
+ */
+const get = async (config: { id: string; userId: string }): Promise<Location | null> => {
+  const [location] = await sql`
+    SELECT short_id AS id, name, state, lat, lon
+    FROM weather_locations
+    WHERE short_id = ${config.id} AND user_id = ${config.userId}
+  `;
+  return (location as Location) ?? null;
+};
+
+export const weatherLocationsService = {
+  list,
+  get,
+  create,
+  remove,
+};