@snaptrude/plugin-core 0.9.16 → 0.9.18-edgesetbacks-20261021.1

package/src/api/analysis/weather.ts

@@ -1,179 +1,179 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../types"
-
-/**
- * Analysis weather — read the project site's typical-year weather series.
- *
- * Returns the hourly weather rows (temperature, humidity, wind, solar
- * irradiance) of the EPW file the sustainability analyses compute against,
- * resolved from the project's geo-located site. This is a **synchronous,
- * paged read** of an already-resolved weather file — not a job: call
- * {@linkcode PluginAnalysisWeatherApi.getSeries} for a date range, then follow
- * `nextCursor` until it is `null`.
- *
- * The weather file is resolved by the **same** code path the daylight /
- * sunlight-hours analyses use, so the `source.weatherFileId` here matches the
- * provenance a {@linkcode PluginAnalysisDaylightApi} run echoes. Dates cross as
- * ISO 8601 date strings (`"YYYY-MM-DD"`); each row's `timestamp` is a local
- * ISO 8601 string **with** its UTC offset, and `utcOffsetMinutes` restates the
- * offset so consumers never re-derive it.
- *
- * Reads never throw for "no data": when the project has no geo-located site
- * (no weather file to resolve) the host surfaces that per its read contract.
- *
- * Accessed via `snaptrude.analysis.weather`.
- */
-export abstract class PluginAnalysisWeatherApi {
-  constructor() {}
-
-  /**
-   * Get the hourly weather series for a date range, paged.
-   *
-   * Returns the resolved weather file's provenance (`source`) plus the weather
-   * `rows` for the requested range. The page size is backend-chosen; when
-   * `nextCursor` is a string, pass it back as `args.cursor` to fetch the next
-   * page, and stop when it is `null`.
-   *
-   * @param args - {@linkcode PluginWeatherGetSeriesArgs}: the inclusive
-   *   `startDate`/`endDate` ISO dates, an optional `interval` (`"hourly"` is
-   *   the only v1 value), and an optional `cursor` for paging.
-   * @returns A {@linkcode PluginWeatherSeriesResult} — the resolved weather
-   *   `source`, the `rows` for this page, and `nextCursor` (`null` at the end).
-   *
-   * @examplePrompt Get the weather series for June at my site
-   * @examplePrompt Pull the hourly temperature and irradiance for this location
-   * @examplePrompt What EPW weather file is my project using?
-   *
-   * # Example
-   * ```ts
-   * let cursor: string | undefined = undefined
-   * const rows = []
-   * do {
-   *   const page = await snaptrude.analysis.weather.getSeries({
-   *     startDate: "2026-06-01",
-   *     endDate: "2026-06-30",
-   *     cursor,
-   *   })
-   *   rows.push(...page.rows)
-   *   cursor = page.nextCursor ?? undefined
-   * } while (cursor)
-   * ```
-   */
-  public abstract getSeries(
-    args: PluginWeatherGetSeriesArgs,
-  ): PluginApiReturn<PluginWeatherSeriesResult>
-}
-
-/**
- * How the weather file was matched to the project site.
- *
- * | Value | Meaning |
- * |---|---|
- * | `"nearest-station"` | Auto-resolved to the closest weather station |
- * | `"user-upload"` | A weather file the user uploaded (`core.io.import.epw`) |
- * | `"project-override"` | A station pinned for the project regardless of distance |
- */
-export const PluginWeatherSelectionMethod = z.enum([
-  "nearest-station",
-  "user-upload",
-  "project-override",
-])
-export type PluginWeatherSelectionMethod = z.infer<
-  typeof PluginWeatherSelectionMethod
->
-
-/**
- * Provenance of the resolved weather file — where the numbers came from.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `weatherFileId` | `string` | Catalog id (same key as `core.io.import.epw`'s `weatherFileId`) |
- * | `station` | `string` | Station/file name, e.g. `"USA_IL_Chicago-OHare.Intl.AP.725300_TMY3"` |
- * | `sourceId` | `string` | WMO/station identifier from the EPW header |
- * | `distanceKm` | `number \| null` | Station → project site distance, km; `null` for pinned project-override files |
- * | `selectionMethod` | {@linkcode PluginWeatherSelectionMethod} | How the file was matched |
- * | `checksum` | `string` | sha256 of the EPW file — the provenance key |
- * | `windReferenceHeightM` | `number` | Anemometer height the wind rows are valid at |
- */
-export const PluginWeatherSourceMeta = z.object({
-  weatherFileId: z.string(),
-  station: z.string(),
-  sourceId: z.string(),
-  distanceKm: z.number().nullable(),
-  selectionMethod: PluginWeatherSelectionMethod,
-  checksum: z.string(),
-  windReferenceHeightM: z.number(),
-})
-export type PluginWeatherSourceMeta = z.infer<typeof PluginWeatherSourceMeta>
-
-/**
- * One hourly weather reading.
- *
- * `flags` is empty for a clean measured/typical value; known flag strings are
- * `"missing"`, `"substituted"`, and `"interpolated"` (kept as `string[]` so the
- * backend can add flag kinds without a contract break).
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `timestamp` | `string` | Local ISO 8601 with offset, e.g. `"2026-06-21T14:00:00+05:30"` |
- * | `utcOffsetMinutes` | `number` | UTC offset in minutes (restates the timestamp's offset) |
- * | `dryBulbC` | `number` | Dry-bulb temperature, °C |
- * | `relativeHumidityPercent` | `number` | Relative humidity, % |
- * | `windSpeedMps` | `number` | Wind speed, m/s (at `source.windReferenceHeightM`) |
- * | `ghiWm2` | `number` | Global horizontal irradiance, W/m² |
- * | `dniWm2` | `number` | Direct normal irradiance, W/m² |
- * | `dhiWm2` | `number` | Diffuse horizontal irradiance, W/m² |
- * | `flags` | `string[]` | Quality flags; `[]` = clean value |
- */
-export const PluginWeatherRow = z.object({
-  timestamp: z.string(),
-  utcOffsetMinutes: z.number(),
-  dryBulbC: z.number(),
-  relativeHumidityPercent: z.number(),
-  windSpeedMps: z.number(),
-  ghiWm2: z.number(),
-  dniWm2: z.number(),
-  dhiWm2: z.number(),
-  flags: z.array(z.string()),
-})
-export type PluginWeatherRow = z.infer<typeof PluginWeatherRow>
-
-/**
- * Arguments for {@linkcode PluginAnalysisWeatherApi.getSeries}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `startDate` | `string` | Inclusive range start, ISO `"YYYY-MM-DD"` |
- * | `endDate` | `string` | Inclusive range end, ISO `"YYYY-MM-DD"` |
- * | `interval` | `"hourly"`? | Sampling interval; `"hourly"` is the only v1 value |
- * | `cursor` | `string`? | Paging cursor from a prior page's `nextCursor` |
- */
-export const PluginWeatherGetSeriesArgs = z.object({
-  startDate: z.string(),
-  endDate: z.string(),
-  interval: z.enum(["hourly"]).optional(),
-  cursor: z.string().optional(),
-})
-export type PluginWeatherGetSeriesArgs = z.infer<
-  typeof PluginWeatherGetSeriesArgs
->
-
-/**
- * Result of {@linkcode PluginAnalysisWeatherApi.getSeries} — one page.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `source` | {@linkcode PluginWeatherSourceMeta} | The resolved weather file's provenance |
- * | `rows` | {@linkcode PluginWeatherRow}`[]` | Weather rows for this page |
- * | `nextCursor` | `string \| null` | Pass back as `args.cursor`; `null` = last page |
- * | `warnings` | `string[]`? | Degradation notices (e.g. `"override lookup failed; served nearest-station"`); omitted when the page is clean |
- */
-export const PluginWeatherSeriesResult = z.object({
-  source: PluginWeatherSourceMeta,
-  rows: z.array(PluginWeatherRow),
-  nextCursor: z.string().nullable(),
-  warnings: z.array(z.string()).optional(),
-})
-export type PluginWeatherSeriesResult = z.infer<
-  typeof PluginWeatherSeriesResult
->
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+
+/**
+ * Analysis weather — read the project site's typical-year weather series.
+ *
+ * Returns the hourly weather rows (temperature, humidity, wind, solar
+ * irradiance) of the EPW file the sustainability analyses compute against,
+ * resolved from the project's geo-located site. This is a **synchronous,
+ * paged read** of an already-resolved weather file — not a job: call
+ * {@linkcode PluginAnalysisWeatherApi.getSeries} for a date range, then follow
+ * `nextCursor` until it is `null`.
+ *
+ * The weather file is resolved by the **same** code path the daylight /
+ * sunlight-hours analyses use, so the `source.weatherFileId` here matches the
+ * provenance a {@linkcode PluginAnalysisDaylightApi} run echoes. Dates cross as
+ * ISO 8601 date strings (`"YYYY-MM-DD"`); each row's `timestamp` is a local
+ * ISO 8601 string **with** its UTC offset, and `utcOffsetMinutes` restates the
+ * offset so consumers never re-derive it.
+ *
+ * Reads never throw for "no data": when the project has no geo-located site
+ * (no weather file to resolve) the host surfaces that per its read contract.
+ *
+ * Accessed via `snaptrude.analysis.weather`.
+ */
+export abstract class PluginAnalysisWeatherApi {
+  constructor() {}
+
+  /**
+   * Get the hourly weather series for a date range, paged.
+   *
+   * Returns the resolved weather file's provenance (`source`) plus the weather
+   * `rows` for the requested range. The page size is backend-chosen; when
+   * `nextCursor` is a string, pass it back as `args.cursor` to fetch the next
+   * page, and stop when it is `null`.
+   *
+   * @param args - {@linkcode PluginWeatherGetSeriesArgs}: the inclusive
+   *   `startDate`/`endDate` ISO dates, an optional `interval` (`"hourly"` is
+   *   the only v1 value), and an optional `cursor` for paging.
+   * @returns A {@linkcode PluginWeatherSeriesResult} — the resolved weather
+   *   `source`, the `rows` for this page, and `nextCursor` (`null` at the end).
+   *
+   * @examplePrompt Get the weather series for June at my site
+   * @examplePrompt Pull the hourly temperature and irradiance for this location
+   * @examplePrompt What EPW weather file is my project using?
+   *
+   * # Example
+   * ```ts
+   * let cursor: string | undefined = undefined
+   * const rows = []
+   * do {
+   *   const page = await snaptrude.analysis.weather.getSeries({
+   *     startDate: "2026-06-01",
+   *     endDate: "2026-06-30",
+   *     cursor,
+   *   })
+   *   rows.push(...page.rows)
+   *   cursor = page.nextCursor ?? undefined
+   * } while (cursor)
+   * ```
+   */
+  public abstract getSeries(
+    args: PluginWeatherGetSeriesArgs,
+  ): PluginApiReturn<PluginWeatherSeriesResult>
+}
+
+/**
+ * How the weather file was matched to the project site.
+ *
+ * | Value | Meaning |
+ * |---|---|
+ * | `"nearest-station"` | Auto-resolved to the closest weather station |
+ * | `"user-upload"` | A weather file the user uploaded (`core.io.import.epw`) |
+ * | `"project-override"` | A station pinned for the project regardless of distance |
+ */
+export const PluginWeatherSelectionMethod = z.enum([
+  "nearest-station",
+  "user-upload",
+  "project-override",
+])
+export type PluginWeatherSelectionMethod = z.infer<
+  typeof PluginWeatherSelectionMethod
+>
+
+/**
+ * Provenance of the resolved weather file — where the numbers came from.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `weatherFileId` | `string` | Catalog id (same key as `core.io.import.epw`'s `weatherFileId`) |
+ * | `station` | `string` | Station/file name, e.g. `"USA_IL_Chicago-OHare.Intl.AP.725300_TMY3"` |
+ * | `sourceId` | `string` | WMO/station identifier from the EPW header |
+ * | `distanceKm` | `number \| null` | Station → project site distance, km; `null` for pinned project-override files |
+ * | `selectionMethod` | {@linkcode PluginWeatherSelectionMethod} | How the file was matched |
+ * | `checksum` | `string` | sha256 of the EPW file — the provenance key |
+ * | `windReferenceHeightM` | `number` | Anemometer height the wind rows are valid at |
+ */
+export const PluginWeatherSourceMeta = z.object({
+  weatherFileId: z.string(),
+  station: z.string(),
+  sourceId: z.string(),
+  distanceKm: z.number().nullable(),
+  selectionMethod: PluginWeatherSelectionMethod,
+  checksum: z.string(),
+  windReferenceHeightM: z.number(),
+})
+export type PluginWeatherSourceMeta = z.infer<typeof PluginWeatherSourceMeta>
+
+/**
+ * One hourly weather reading.
+ *
+ * `flags` is empty for a clean measured/typical value; known flag strings are
+ * `"missing"`, `"substituted"`, and `"interpolated"` (kept as `string[]` so the
+ * backend can add flag kinds without a contract break).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `timestamp` | `string` | Local ISO 8601 with offset, e.g. `"2026-06-21T14:00:00+05:30"` |
+ * | `utcOffsetMinutes` | `number` | UTC offset in minutes (restates the timestamp's offset) |
+ * | `dryBulbC` | `number` | Dry-bulb temperature, °C |
+ * | `relativeHumidityPercent` | `number` | Relative humidity, % |
+ * | `windSpeedMps` | `number` | Wind speed, m/s (at `source.windReferenceHeightM`) |
+ * | `ghiWm2` | `number` | Global horizontal irradiance, W/m² |
+ * | `dniWm2` | `number` | Direct normal irradiance, W/m² |
+ * | `dhiWm2` | `number` | Diffuse horizontal irradiance, W/m² |
+ * | `flags` | `string[]` | Quality flags; `[]` = clean value |
+ */
+export const PluginWeatherRow = z.object({
+  timestamp: z.string(),
+  utcOffsetMinutes: z.number(),
+  dryBulbC: z.number(),
+  relativeHumidityPercent: z.number(),
+  windSpeedMps: z.number(),
+  ghiWm2: z.number(),
+  dniWm2: z.number(),
+  dhiWm2: z.number(),
+  flags: z.array(z.string()),
+})
+export type PluginWeatherRow = z.infer<typeof PluginWeatherRow>
+
+/**
+ * Arguments for {@linkcode PluginAnalysisWeatherApi.getSeries}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `startDate` | `string` | Inclusive range start, ISO `"YYYY-MM-DD"` |
+ * | `endDate` | `string` | Inclusive range end, ISO `"YYYY-MM-DD"` |
+ * | `interval` | `"hourly"`? | Sampling interval; `"hourly"` is the only v1 value |
+ * | `cursor` | `string`? | Paging cursor from a prior page's `nextCursor` |
+ */
+export const PluginWeatherGetSeriesArgs = z.object({
+  startDate: z.string(),
+  endDate: z.string(),
+  interval: z.enum(["hourly"]).optional(),
+  cursor: z.string().optional(),
+})
+export type PluginWeatherGetSeriesArgs = z.infer<
+  typeof PluginWeatherGetSeriesArgs
+>
+
+/**
+ * Result of {@linkcode PluginAnalysisWeatherApi.getSeries} — one page.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `source` | {@linkcode PluginWeatherSourceMeta} | The resolved weather file's provenance |
+ * | `rows` | {@linkcode PluginWeatherRow}`[]` | Weather rows for this page |
+ * | `nextCursor` | `string \| null` | Pass back as `args.cursor`; `null` = last page |
+ * | `warnings` | `string[]`? | Degradation notices (e.g. `"override lookup failed; served nearest-station"`); omitted when the page is clean |
+ */
+export const PluginWeatherSeriesResult = z.object({
+  source: PluginWeatherSourceMeta,
+  rows: z.array(PluginWeatherRow),
+  nextCursor: z.string().nullable(),
+  warnings: z.array(z.string()).optional(),
+})
+export type PluginWeatherSeriesResult = z.infer<
+  typeof PluginWeatherSeriesResult
+>