@snaptrude/plugin-core 0.9.17 → 0.9.18-networks-20261016.1

package/src/api/analysis/solar.ts

@@ -1,237 +1,237 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../types"
-import { PluginWeatherSourceMeta } from "./weather"
-
-/**
- * Analysis solar — sample solar exposure at caller-chosen points.
- *
- * Unlike the heatmap studies (which raster the model's own surfaces), this
- * samples solar exposure at **points you supply** — an instant (sun visible? /
- * irradiance now) or aggregated over a date range (shaded fraction / cumulative
- * irradiance). Positions are **world plan-space** coordinates, the same units
- * and frame as plugin geometry reads; the backend echoes them verbatim and
- * never re-projects.
- *
- * Raw numbers only: this renders no heatmap, mutates no geometry, and writes no
- * save commands — visualization is the plugin's job. Large grids run as a job
- * (`status: "running"` until complete); every result carries `modelRevision` +
- * `inputHash` so the caller can mark it stale after a geometry change.
- *
- * Accessed via `snaptrude.analysis.solar`.
- */
-export abstract class PluginAnalysisSolarApi {
-  constructor() {}
-
-  /**
-   * Sample solar exposure at a set of points.
-   *
-   * Provide **exactly one** timing mode: `dateTime` (a single instant →
-   * `mode: "instant"`, results in `W/m²`), or `startDate` + `endDate` (a range
-   * → `mode: "range"`, results aggregated in `kWh/m²`). `results` is paged —
-   * follow `nextCursor` until it is `null`. Each point's optional `normal`
-   * gives plane-of-array irradiance; omit it for a horizontal sample.
-   *
-   * @param args - {@linkcode PluginSolarSampleGridArgs}: the `points`, exactly
-   *   one timing mode (`dateTime` XOR `startDate`+`endDate`), and an optional
-   *   `includeHourlyArtifact` to attach a downloadable per-hour series.
-   * @returns A {@linkcode PluginSolarSampleGridResult} — the run `status`,
-   *   `mode`/`units`, provenance (`weather`, `modelRevision`, `inputHash`),
-   *   this page of `results`, an optional `hourlyArtifact`, and `nextCursor`.
-   * @throws When the project has no geo-located site (no location to sample
-   *   solar exposure for).
-   *
-   * @examplePrompt What's the irradiance at these facade points at noon on June 21?
-   * @examplePrompt How shaded are these balcony points across the summer?
-   * @examplePrompt Sample direct sun visibility at these roof points right now
-   *
-   * # Example
-   * ```ts
-   * const grid = await snaptrude.analysis.solar.sampleGrid({
-   *   points: [
-   *     { id: "a", position: [0, 3, 0] },
-   *     { id: "b", position: [5, 3, 0], normal: [0, 0, 1] },
-   *   ],
-   *   dateTime: "2026-06-21T12:00:00+05:30",
-   * })
-   * for (const r of grid.results) {
-   *   console.log(r.id, r.directSunVisible, r.totalIrradiance, grid.units)
-   * }
-   * ```
-   */
-  public abstract sampleGrid(
-    args: PluginSolarSampleGridArgs,
-  ): PluginApiReturn<PluginSolarSampleGridResult>
-}
-
-/**
- * Status of a {@linkcode PluginAnalysisSolarApi.sampleGrid} run.
- *
- * | Value | Meaning |
- * |---|---|
- * | `"running"` | The job is in flight — poll again |
- * | `"complete"` | Results are final |
- * | `"cancelled"` | The run was cancelled |
- * | `"failed"` | The run failed |
- */
-export const PluginSolarRunStatus = z.enum([
-  "running",
-  "complete",
-  "cancelled",
-  "failed",
-])
-export type PluginSolarRunStatus = z.infer<typeof PluginSolarRunStatus>
-
-/**
- * Timing mode of the run — chosen by which timing args were supplied.
- *
- * | Value | Meaning |
- * |---|---|
- * | `"instant"` | Single `dateTime` — irradiance in `W/m²` |
- * | `"range"` | `startDate`+`endDate` — irradiance aggregated in `kWh/m²` |
- */
-export const PluginSolarSampleMode = z.enum(["instant", "range"])
-export type PluginSolarSampleMode = z.infer<typeof PluginSolarSampleMode>
-
-/**
- * Irradiance units of the results — `W/m²` (instant) or `kWh/m²` (range).
- */
-export const PluginSolarUnits = z.enum(["W/m2", "kWh/m2"])
-export type PluginSolarUnits = z.infer<typeof PluginSolarUnits>
-
-/**
- * Downloadable per-hour artifact (present only when `includeHourlyArtifact`).
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `url` | `string` | Signed download URL |
- * | `format` | `"parquet" \| "csv-gz"` | File format |
- * | `expiresAt` | `string` | ISO 8601 expiry of the signed URL |
- */
-export const PluginSolarHourlyArtifact = z.object({
-  url: z.string(),
-  format: z.enum(["parquet", "csv-gz"]),
-  expiresAt: z.string(),
-})
-export type PluginSolarHourlyArtifact = z.infer<
-  typeof PluginSolarHourlyArtifact
->
-
-/**
- * A caller-supplied point to sample.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `id` | `string` | Caller-chosen id, echoed back verbatim on the result |
- * | `position` | `[number, number, number]` | World plan-space `[x, y, z]` |
- * | `normal` | `[number, number, number]`? | Surface normal for plane-of-array; omit = horizontal |
- */
-export const PluginSolarSamplePoint = z.object({
-  id: z.string(),
-  position: z.tuple([z.number(), z.number(), z.number()]),
-  normal: z.tuple([z.number(), z.number(), z.number()]).optional(),
-})
-export type PluginSolarSamplePoint = z.infer<typeof PluginSolarSamplePoint>
-
-/**
- * Arguments for {@linkcode PluginAnalysisSolarApi.sampleGrid}.
- *
- * Provide **exactly one** timing mode: `dateTime` (instant) XOR
- * `startDate`+`endDate` (range).
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `points` | {@linkcode PluginSolarSamplePoint}`[]` | Points to sample |
- * | `dateTime` | `string`? | Instant mode: local ISO 8601 with offset |
- * | `startDate` | `string`? | Range mode: inclusive start `"YYYY-MM-DD"` |
- * | `endDate` | `string`? | Range mode: inclusive end `"YYYY-MM-DD"` |
- * | `includeHourlyArtifact` | `boolean`? | Attach a downloadable per-hour series |
- */
-export const PluginSolarSampleGridArgs = z
-  .object({
-    points: z.array(PluginSolarSamplePoint),
-    dateTime: z.string().optional(),
-    startDate: z.string().optional(),
-    endDate: z.string().optional(),
-    includeHourlyArtifact: z.boolean().optional(),
-  })
-  .superRefine((a, ctx) => {
-    const hasInstant = a.dateTime !== undefined
-    const hasStart = a.startDate !== undefined
-    const hasEnd = a.endDate !== undefined
-    const hasRange = hasStart || hasEnd
-    if (hasInstant === hasRange) {
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        message:
-          "provide exactly one timing mode: dateTime (instant), or startDate+endDate (range)",
-      })
-    }
-    if (hasRange && !(hasStart && hasEnd)) {
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        message: "range mode requires both startDate and endDate",
-      })
-    }
-  })
-export type PluginSolarSampleGridArgs = z.infer<
-  typeof PluginSolarSampleGridArgs
->
-
-/**
- * One sampled point's result. Irradiance fields are in the enclosing result's
- * `units` and are omitted when the backend did not compute them.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `id` | `string` | The point's caller-chosen id |
- * | `directSunVisible` | `boolean` | Instant mode: sun disc visible from the point |
- * | `shadeFraction` | `number` | `0`..`1`; range mode: fraction of sun-up hours shaded |
- * | `directIrradiance` | `number`? | Direct component, in the result's `units` |
- * | `diffuseIrradiance` | `number`? | Diffuse component, in the result's `units` |
- * | `totalIrradiance` | `number`? | Total (direct + diffuse), in the result's `units` |
- */
-export const PluginSolarSampleResult = z.object({
-  id: z.string(),
-  directSunVisible: z.boolean(),
-  shadeFraction: z.number(),
-  directIrradiance: z.number().optional(),
-  diffuseIrradiance: z.number().optional(),
-  totalIrradiance: z.number().optional(),
-})
-export type PluginSolarSampleResult = z.infer<typeof PluginSolarSampleResult>
-
-/**
- * Result of {@linkcode PluginAnalysisSolarApi.sampleGrid} — one page.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `status` | {@linkcode PluginSolarRunStatus} | Run status |
- * | `mode` | {@linkcode PluginSolarSampleMode} | `"instant"` or `"range"` |
- * | `coordinateSystem` | `"world-plan-space"` | Echo of the input frame |
- * | `modelRevision` | `string` | Geometry revision sampled against (staleness key) |
- * | `inputHash` | `string` | Hash of points+dates+geometry (staleness key) |
- * | `units` | {@linkcode PluginSolarUnits} | `"W/m2"` (instant) or `"kWh/m2"` (range) |
- * | `sunUpHours` | `number` | Sun-up hours over the sampled window |
- * | `weather` | {@linkcode PluginWeatherSourceMeta} \| `null` | Resolved weather file, or `null` |
- * | `weatherQuality` | `string[]` | Deduped quality flags present in the consumed rows |
- * | `results` | {@linkcode PluginSolarSampleResult}`[]` | This page of per-point results |
- * | `hourlyArtifact` | {@linkcode PluginSolarHourlyArtifact} \| `null` | Per-hour download, or `null` |
- * | `nextCursor` | `string \| null` | Next page cursor; `null` = last page |
- */
-export const PluginSolarSampleGridResult = z.object({
-  status: PluginSolarRunStatus,
-  mode: PluginSolarSampleMode,
-  coordinateSystem: z.literal("world-plan-space"),
-  modelRevision: z.string(),
-  inputHash: z.string(),
-  units: PluginSolarUnits,
-  sunUpHours: z.number(),
-  weather: PluginWeatherSourceMeta.nullable(),
-  weatherQuality: z.array(z.string()),
-  results: z.array(PluginSolarSampleResult),
-  hourlyArtifact: PluginSolarHourlyArtifact.nullable(),
-  nextCursor: z.string().nullable(),
-})
-export type PluginSolarSampleGridResult = z.infer<
-  typeof PluginSolarSampleGridResult
->
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+import { PluginWeatherSourceMeta } from "./weather"
+
+/**
+ * Analysis solar — sample solar exposure at caller-chosen points.
+ *
+ * Unlike the heatmap studies (which raster the model's own surfaces), this
+ * samples solar exposure at **points you supply** — an instant (sun visible? /
+ * irradiance now) or aggregated over a date range (shaded fraction / cumulative
+ * irradiance). Positions are **world plan-space** coordinates, the same units
+ * and frame as plugin geometry reads; the backend echoes them verbatim and
+ * never re-projects.
+ *
+ * Raw numbers only: this renders no heatmap, mutates no geometry, and writes no
+ * save commands — visualization is the plugin's job. Large grids run as a job
+ * (`status: "running"` until complete); every result carries `modelRevision` +
+ * `inputHash` so the caller can mark it stale after a geometry change.
+ *
+ * Accessed via `snaptrude.analysis.solar`.
+ */
+export abstract class PluginAnalysisSolarApi {
+  constructor() {}
+
+  /**
+   * Sample solar exposure at a set of points.
+   *
+   * Provide **exactly one** timing mode: `dateTime` (a single instant →
+   * `mode: "instant"`, results in `W/m²`), or `startDate` + `endDate` (a range
+   * → `mode: "range"`, results aggregated in `kWh/m²`). `results` is paged —
+   * follow `nextCursor` until it is `null`. Each point's optional `normal`
+   * gives plane-of-array irradiance; omit it for a horizontal sample.
+   *
+   * @param args - {@linkcode PluginSolarSampleGridArgs}: the `points`, exactly
+   *   one timing mode (`dateTime` XOR `startDate`+`endDate`), and an optional
+   *   `includeHourlyArtifact` to attach a downloadable per-hour series.
+   * @returns A {@linkcode PluginSolarSampleGridResult} — the run `status`,
+   *   `mode`/`units`, provenance (`weather`, `modelRevision`, `inputHash`),
+   *   this page of `results`, an optional `hourlyArtifact`, and `nextCursor`.
+   * @throws When the project has no geo-located site (no location to sample
+   *   solar exposure for).
+   *
+   * @examplePrompt What's the irradiance at these facade points at noon on June 21?
+   * @examplePrompt How shaded are these balcony points across the summer?
+   * @examplePrompt Sample direct sun visibility at these roof points right now
+   *
+   * # Example
+   * ```ts
+   * const grid = await snaptrude.analysis.solar.sampleGrid({
+   *   points: [
+   *     { id: "a", position: [0, 3, 0] },
+   *     { id: "b", position: [5, 3, 0], normal: [0, 0, 1] },
+   *   ],
+   *   dateTime: "2026-06-21T12:00:00+05:30",
+   * })
+   * for (const r of grid.results) {
+   *   console.log(r.id, r.directSunVisible, r.totalIrradiance, grid.units)
+   * }
+   * ```
+   */
+  public abstract sampleGrid(
+    args: PluginSolarSampleGridArgs,
+  ): PluginApiReturn<PluginSolarSampleGridResult>
+}
+
+/**
+ * Status of a {@linkcode PluginAnalysisSolarApi.sampleGrid} run.
+ *
+ * | Value | Meaning |
+ * |---|---|
+ * | `"running"` | The job is in flight — poll again |
+ * | `"complete"` | Results are final |
+ * | `"cancelled"` | The run was cancelled |
+ * | `"failed"` | The run failed |
+ */
+export const PluginSolarRunStatus = z.enum([
+  "running",
+  "complete",
+  "cancelled",
+  "failed",
+])
+export type PluginSolarRunStatus = z.infer<typeof PluginSolarRunStatus>
+
+/**
+ * Timing mode of the run — chosen by which timing args were supplied.
+ *
+ * | Value | Meaning |
+ * |---|---|
+ * | `"instant"` | Single `dateTime` — irradiance in `W/m²` |
+ * | `"range"` | `startDate`+`endDate` — irradiance aggregated in `kWh/m²` |
+ */
+export const PluginSolarSampleMode = z.enum(["instant", "range"])
+export type PluginSolarSampleMode = z.infer<typeof PluginSolarSampleMode>
+
+/**
+ * Irradiance units of the results — `W/m²` (instant) or `kWh/m²` (range).
+ */
+export const PluginSolarUnits = z.enum(["W/m2", "kWh/m2"])
+export type PluginSolarUnits = z.infer<typeof PluginSolarUnits>
+
+/**
+ * Downloadable per-hour artifact (present only when `includeHourlyArtifact`).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `url` | `string` | Signed download URL |
+ * | `format` | `"parquet" \| "csv-gz"` | File format |
+ * | `expiresAt` | `string` | ISO 8601 expiry of the signed URL |
+ */
+export const PluginSolarHourlyArtifact = z.object({
+  url: z.string(),
+  format: z.enum(["parquet", "csv-gz"]),
+  expiresAt: z.string(),
+})
+export type PluginSolarHourlyArtifact = z.infer<
+  typeof PluginSolarHourlyArtifact
+>
+
+/**
+ * A caller-supplied point to sample.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Caller-chosen id, echoed back verbatim on the result |
+ * | `position` | `[number, number, number]` | World plan-space `[x, y, z]` |
+ * | `normal` | `[number, number, number]`? | Surface normal for plane-of-array; omit = horizontal |
+ */
+export const PluginSolarSamplePoint = z.object({
+  id: z.string(),
+  position: z.tuple([z.number(), z.number(), z.number()]),
+  normal: z.tuple([z.number(), z.number(), z.number()]).optional(),
+})
+export type PluginSolarSamplePoint = z.infer<typeof PluginSolarSamplePoint>
+
+/**
+ * Arguments for {@linkcode PluginAnalysisSolarApi.sampleGrid}.
+ *
+ * Provide **exactly one** timing mode: `dateTime` (instant) XOR
+ * `startDate`+`endDate` (range).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `points` | {@linkcode PluginSolarSamplePoint}`[]` | Points to sample |
+ * | `dateTime` | `string`? | Instant mode: local ISO 8601 with offset |
+ * | `startDate` | `string`? | Range mode: inclusive start `"YYYY-MM-DD"` |
+ * | `endDate` | `string`? | Range mode: inclusive end `"YYYY-MM-DD"` |
+ * | `includeHourlyArtifact` | `boolean`? | Attach a downloadable per-hour series |
+ */
+export const PluginSolarSampleGridArgs = z
+  .object({
+    points: z.array(PluginSolarSamplePoint),
+    dateTime: z.string().optional(),
+    startDate: z.string().optional(),
+    endDate: z.string().optional(),
+    includeHourlyArtifact: z.boolean().optional(),
+  })
+  .superRefine((a, ctx) => {
+    const hasInstant = a.dateTime !== undefined
+    const hasStart = a.startDate !== undefined
+    const hasEnd = a.endDate !== undefined
+    const hasRange = hasStart || hasEnd
+    if (hasInstant === hasRange) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message:
+          "provide exactly one timing mode: dateTime (instant), or startDate+endDate (range)",
+      })
+    }
+    if (hasRange && !(hasStart && hasEnd)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "range mode requires both startDate and endDate",
+      })
+    }
+  })
+export type PluginSolarSampleGridArgs = z.infer<
+  typeof PluginSolarSampleGridArgs
+>
+
+/**
+ * One sampled point's result. Irradiance fields are in the enclosing result's
+ * `units` and are omitted when the backend did not compute them.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | The point's caller-chosen id |
+ * | `directSunVisible` | `boolean` | Instant mode: sun disc visible from the point |
+ * | `shadeFraction` | `number` | `0`..`1`; range mode: fraction of sun-up hours shaded |
+ * | `directIrradiance` | `number`? | Direct component, in the result's `units` |
+ * | `diffuseIrradiance` | `number`? | Diffuse component, in the result's `units` |
+ * | `totalIrradiance` | `number`? | Total (direct + diffuse), in the result's `units` |
+ */
+export const PluginSolarSampleResult = z.object({
+  id: z.string(),
+  directSunVisible: z.boolean(),
+  shadeFraction: z.number(),
+  directIrradiance: z.number().optional(),
+  diffuseIrradiance: z.number().optional(),
+  totalIrradiance: z.number().optional(),
+})
+export type PluginSolarSampleResult = z.infer<typeof PluginSolarSampleResult>
+
+/**
+ * Result of {@linkcode PluginAnalysisSolarApi.sampleGrid} — one page.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `status` | {@linkcode PluginSolarRunStatus} | Run status |
+ * | `mode` | {@linkcode PluginSolarSampleMode} | `"instant"` or `"range"` |
+ * | `coordinateSystem` | `"world-plan-space"` | Echo of the input frame |
+ * | `modelRevision` | `string` | Geometry revision sampled against (staleness key) |
+ * | `inputHash` | `string` | Hash of points+dates+geometry (staleness key) |
+ * | `units` | {@linkcode PluginSolarUnits} | `"W/m2"` (instant) or `"kWh/m2"` (range) |
+ * | `sunUpHours` | `number` | Sun-up hours over the sampled window |
+ * | `weather` | {@linkcode PluginWeatherSourceMeta} \| `null` | Resolved weather file, or `null` |
+ * | `weatherQuality` | `string[]` | Deduped quality flags present in the consumed rows |
+ * | `results` | {@linkcode PluginSolarSampleResult}`[]` | This page of per-point results |
+ * | `hourlyArtifact` | {@linkcode PluginSolarHourlyArtifact} \| `null` | Per-hour download, or `null` |
+ * | `nextCursor` | `string \| null` | Next page cursor; `null` = last page |
+ */
+export const PluginSolarSampleGridResult = z.object({
+  status: PluginSolarRunStatus,
+  mode: PluginSolarSampleMode,
+  coordinateSystem: z.literal("world-plan-space"),
+  modelRevision: z.string(),
+  inputHash: z.string(),
+  units: PluginSolarUnits,
+  sunUpHours: z.number(),
+  weather: PluginWeatherSourceMeta.nullable(),
+  weatherQuality: z.array(z.string()),
+  results: z.array(PluginSolarSampleResult),
+  hourlyArtifact: PluginSolarHourlyArtifact.nullable(),
+  nextCursor: z.string().nullable(),
+})
+export type PluginSolarSampleGridResult = z.infer<
+  typeof PluginSolarSampleGridResult
+>