@snaptrude/plugin-core 0.8.0 → 0.9.0

package/dist/api/presentation/shapes.d.ts

@@ -0,0 +1,481 @@
+import * as z from "zod";
+import { PluginApiReturn } from "../../types";
+/**
+ * Presentation shapes — a stable, plugin-owned shape lifecycle on Present-mode
+ * sheets.
+ *
+ * Where {@linkcode PluginPresentationAnnotateApi} is fire-and-forget (every call
+ * creates a new shape), this namespace keys each shape by a caller-chosen
+ * string, so rerunning an analysis **updates** its sheet output in place instead
+ * of duplicating it:
+ *
+ * - {@linkcode PluginPresentationShapesApi.upsert} — create or update the shape for a key
+ * - {@linkcode PluginPresentationShapesApi.remove} — delete the shape for a key
+ * - {@linkcode PluginPresentationShapesApi.removeAll} — delete every shape owned by the calling plugin
+ * - {@linkcode PluginPresentationShapesApi.list} — the calling plugin's shapes (key, shapeId, type)
+ *
+ * Shape ids are derived deterministically from the plugin id + key, so upserts
+ * converge across collaborators. Mutations require **Present mode to be open**
+ * (`list` is a never-throw read); each plugin sees and mutates only its own
+ * shapes.
+ *
+ * Accessed via `snaptrude.presentation.shapes`.
+ */
+export declare abstract class PluginPresentationShapesApi {
+    constructor();
+    /**
+     * Create or update the shape for a key.
+     *
+     * The `shape` spec is a discriminated union over the same four annotation
+     * kinds as `presentation.annotate` (`text`, `note`, `arrow`, `geo`), with the
+     * same option shapes. On first call for a key the shape is created on the
+     * target sheet (`options.sheetId`, default: the first sheet) and nested under
+     * the sheet frame; on later calls the existing shape is updated in place —
+     * same shape id, same sheet, one undo step. Positions/bounds are relative to
+     * the sheet's top-left, in canvas units. Requires Present mode to be open.
+     *
+     * @param key - Caller-chosen stable identifier for the shape (per plugin).
+     * @param shape - The desired shape ({@linkcode PluginPresentationShapeSpec}):
+     *   `{ type: "text" | "note" | "arrow" | "geo", ... }` with the matching
+     *   annotate options. Changing `type` for an existing key replaces the shape
+     *   (same shape id).
+     * @param options - Optional `sheetId` — the sheet to create the shape on
+     *   (defaults to the first sheet; ignored on update, the shape stays on its
+     *   sheet).
+     * @returns A {@linkcode PluginPresentationShapesUpsertResult} — the stable
+     *   `shapeId` and `created` (`true` on first upsert, `false` on update).
+     * @throws If Present mode is not open, the args are invalid, or the sheet id
+     *   is unknown.
+     *
+     * @examplePrompt Update the analysis label on the sheet instead of adding another one
+     * @examplePrompt Rerun the daylight report and refresh its annotations
+     * @examplePrompt Keep one "FAR: 2.4" text on Sheet 1 that updates on each run
+     * @examplePrompt Draw a highlight rectangle the plugin can move on the next run
+     *
+     * # Example
+     * ```ts
+     * const { shapeId, created } = await snaptrude.presentation.shapes.upsert("far-label", {
+     *   type: "text",
+     *   text: "FAR: 2.4",
+     *   position: { x: 40, y: 40 },
+     *   color: "blue",
+     * })
+     * ```
+     */
+    abstract upsert(key: string, shape: PluginPresentationShapeSpec, options?: {
+        sheetId?: string;
+    }): PluginApiReturn<PluginPresentationShapesUpsertResult>;
+    /**
+     * Delete the shape for a key.
+     *
+     * Removes the calling plugin's shape registered under `key`, if it exists.
+     * Requires Present mode to be open.
+     *
+     * @param key - The key passed to {@linkcode PluginPresentationShapesApi.upsert}.
+     * @returns `true` if a shape was deleted, `false` if no shape exists for the
+     *   key.
+     * @throws If Present mode is not open or the key is invalid.
+     *
+     * @examplePrompt Remove the FAR label from the sheet
+     * @examplePrompt Delete the highlight the plugin added earlier
+     * @examplePrompt Clear the "far-label" annotation
+     *
+     * # Example
+     * ```ts
+     * const removed = await snaptrude.presentation.shapes.remove("far-label")
+     * ```
+     */
+    abstract remove(key: string): PluginApiReturn<boolean>;
+    /**
+     * Delete every shape owned by the calling plugin.
+     *
+     * Removes all shapes the calling plugin has upserted (across all sheets) in
+     * one undo step. Requires Present mode to be open.
+     *
+     * @returns The number of shapes deleted.
+     * @throws If Present mode is not open.
+     *
+     * @examplePrompt Clear all annotations my plugin added
+     * @examplePrompt Reset the sheet output before rerunning the analysis
+     * @examplePrompt Remove every plugin-drawn shape
+     *
+     * # Example
+     * ```ts
+     * const deleted = await snaptrude.presentation.shapes.removeAll()
+     * ```
+     */
+    abstract removeAll(): PluginApiReturn<number>;
+    /**
+     * List the calling plugin's shapes.
+     *
+     * Returns one entry per live shape the calling plugin has upserted — its
+     * `key`, the underlying canvas `shapeId`, and the shape `type`. A never-throw
+     * read: returns an empty list when Present mode is closed.
+     *
+     * @returns A {@linkcode PluginPresentationShapesListResult} with the `shapes`
+     *   array (empty when Present mode is closed).
+     *
+     * @examplePrompt Which annotations has my plugin placed on the sheets?
+     * @examplePrompt List the plugin's shapes before refreshing them
+     * @examplePrompt Check whether the FAR label already exists
+     *
+     * # Example
+     * ```ts
+     * const { shapes } = await snaptrude.presentation.shapes.list()
+     * const hasLabel = shapes.some((s) => s.key === "far-label")
+     * ```
+     */
+    abstract list(): PluginApiReturn<PluginPresentationShapesListResult>;
+}
+/**
+ * Desired shape for {@linkcode PluginPresentationShapesApi.upsert} — a
+ * discriminated union over the four annotate kinds, with the same option shapes
+ * as the matching `presentation.annotate` call:
+ *
+ * | `type` | Payload | Mirrors |
+ * |---|---|---|
+ * | `"text"` | `text`, `position?`, `size?`, `color?` | `annotate.text` |
+ * | `"note"` | `text`, `position?`, `color?`, `size?` | `annotate.note` |
+ * | `"arrow"` | `start`, `end`, `color?`, `size?` | `annotate.arrow` |
+ * | `"geo"` | `kind`, `bounds`, `color?`, `fill?` | `annotate.shape` |
+ *
+ * Positions/bounds are relative to the sheet's top-left, in canvas units.
+ */
+export declare const PluginPresentationShapeSpec: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"text">;
+    text: z.ZodString;
+    position: z.ZodOptional<z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>>;
+    size: z.ZodOptional<z.ZodEnum<{
+        m: "m";
+        s: "s";
+        l: "l";
+        xl: "xl";
+    }>>;
+    color: z.ZodOptional<z.ZodEnum<{
+        black: "black";
+        grey: "grey";
+        "light-violet": "light-violet";
+        violet: "violet";
+        blue: "blue";
+        "light-blue": "light-blue";
+        yellow: "yellow";
+        orange: "orange";
+        green: "green";
+        "light-green": "light-green";
+        "light-red": "light-red";
+        red: "red";
+        white: "white";
+    }>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"note">;
+    text: z.ZodString;
+    position: z.ZodOptional<z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>>;
+    color: z.ZodOptional<z.ZodEnum<{
+        black: "black";
+        grey: "grey";
+        "light-violet": "light-violet";
+        violet: "violet";
+        blue: "blue";
+        "light-blue": "light-blue";
+        yellow: "yellow";
+        orange: "orange";
+        green: "green";
+        "light-green": "light-green";
+        "light-red": "light-red";
+        red: "red";
+        white: "white";
+    }>>;
+    size: z.ZodOptional<z.ZodEnum<{
+        m: "m";
+        s: "s";
+        l: "l";
+        xl: "xl";
+    }>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"arrow">;
+    start: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>;
+    end: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>;
+    color: z.ZodOptional<z.ZodEnum<{
+        black: "black";
+        grey: "grey";
+        "light-violet": "light-violet";
+        violet: "violet";
+        blue: "blue";
+        "light-blue": "light-blue";
+        yellow: "yellow";
+        orange: "orange";
+        green: "green";
+        "light-green": "light-green";
+        "light-red": "light-red";
+        red: "red";
+        white: "white";
+    }>>;
+    size: z.ZodOptional<z.ZodEnum<{
+        m: "m";
+        s: "s";
+        l: "l";
+        xl: "xl";
+    }>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"geo">;
+    kind: z.ZodEnum<{
+        rectangle: "rectangle";
+        ellipse: "ellipse";
+        triangle: "triangle";
+        diamond: "diamond";
+        hexagon: "hexagon";
+        oval: "oval";
+        rhombus: "rhombus";
+        star: "star";
+        cloud: "cloud";
+        heart: "heart";
+        "x-box": "x-box";
+        "check-box": "check-box";
+        "arrow-left": "arrow-left";
+        "arrow-up": "arrow-up";
+        "arrow-right": "arrow-right";
+        "arrow-down": "arrow-down";
+    }>;
+    bounds: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        w: z.ZodNumber;
+        h: z.ZodNumber;
+    }, z.core.$strip>;
+    color: z.ZodOptional<z.ZodEnum<{
+        black: "black";
+        grey: "grey";
+        "light-violet": "light-violet";
+        violet: "violet";
+        blue: "blue";
+        "light-blue": "light-blue";
+        yellow: "yellow";
+        orange: "orange";
+        green: "green";
+        "light-green": "light-green";
+        "light-red": "light-red";
+        red: "red";
+        white: "white";
+    }>>;
+    fill: z.ZodOptional<z.ZodEnum<{
+        pattern: "pattern";
+        none: "none";
+        semi: "semi";
+        solid: "solid";
+    }>>;
+}, z.core.$strip>], "type">;
+export type PluginPresentationShapeSpec = z.infer<typeof PluginPresentationShapeSpec>;
+/** The shape kind of a plugin-owned shape (the `type` discriminant of {@linkcode PluginPresentationShapeSpec}). */
+export declare const PluginPresentationShapeType: z.ZodEnum<{
+    text: "text";
+    note: "note";
+    arrow: "arrow";
+    geo: "geo";
+}>;
+export type PluginPresentationShapeType = z.infer<typeof PluginPresentationShapeType>;
+/**
+ * Arguments for {@linkcode PluginPresentationShapesApi.upsert}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `key` | `string` | Caller-chosen stable identifier (non-empty) |
+ * | `shape` | {@linkcode PluginPresentationShapeSpec} | The desired shape |
+ * | `sheetId` | `string \| undefined` | Sheet to create on (default: first sheet; ignored on update) |
+ */
+export declare const PluginPresentationShapesUpsertArgs: z.ZodObject<{
+    key: z.ZodString;
+    shape: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"text">;
+        text: z.ZodString;
+        position: z.ZodOptional<z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strip>>;
+        size: z.ZodOptional<z.ZodEnum<{
+            m: "m";
+            s: "s";
+            l: "l";
+            xl: "xl";
+        }>>;
+        color: z.ZodOptional<z.ZodEnum<{
+            black: "black";
+            grey: "grey";
+            "light-violet": "light-violet";
+            violet: "violet";
+            blue: "blue";
+            "light-blue": "light-blue";
+            yellow: "yellow";
+            orange: "orange";
+            green: "green";
+            "light-green": "light-green";
+            "light-red": "light-red";
+            red: "red";
+            white: "white";
+        }>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"note">;
+        text: z.ZodString;
+        position: z.ZodOptional<z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strip>>;
+        color: z.ZodOptional<z.ZodEnum<{
+            black: "black";
+            grey: "grey";
+            "light-violet": "light-violet";
+            violet: "violet";
+            blue: "blue";
+            "light-blue": "light-blue";
+            yellow: "yellow";
+            orange: "orange";
+            green: "green";
+            "light-green": "light-green";
+            "light-red": "light-red";
+            red: "red";
+            white: "white";
+        }>>;
+        size: z.ZodOptional<z.ZodEnum<{
+            m: "m";
+            s: "s";
+            l: "l";
+            xl: "xl";
+        }>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"arrow">;
+        start: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strip>;
+        end: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strip>;
+        color: z.ZodOptional<z.ZodEnum<{
+            black: "black";
+            grey: "grey";
+            "light-violet": "light-violet";
+            violet: "violet";
+            blue: "blue";
+            "light-blue": "light-blue";
+            yellow: "yellow";
+            orange: "orange";
+            green: "green";
+            "light-green": "light-green";
+            "light-red": "light-red";
+            red: "red";
+            white: "white";
+        }>>;
+        size: z.ZodOptional<z.ZodEnum<{
+            m: "m";
+            s: "s";
+            l: "l";
+            xl: "xl";
+        }>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"geo">;
+        kind: z.ZodEnum<{
+            rectangle: "rectangle";
+            ellipse: "ellipse";
+            triangle: "triangle";
+            diamond: "diamond";
+            hexagon: "hexagon";
+            oval: "oval";
+            rhombus: "rhombus";
+            star: "star";
+            cloud: "cloud";
+            heart: "heart";
+            "x-box": "x-box";
+            "check-box": "check-box";
+            "arrow-left": "arrow-left";
+            "arrow-up": "arrow-up";
+            "arrow-right": "arrow-right";
+            "arrow-down": "arrow-down";
+        }>;
+        bounds: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            w: z.ZodNumber;
+            h: z.ZodNumber;
+        }, z.core.$strip>;
+        color: z.ZodOptional<z.ZodEnum<{
+            black: "black";
+            grey: "grey";
+            "light-violet": "light-violet";
+            violet: "violet";
+            blue: "blue";
+            "light-blue": "light-blue";
+            yellow: "yellow";
+            orange: "orange";
+            green: "green";
+            "light-green": "light-green";
+            "light-red": "light-red";
+            red: "red";
+            white: "white";
+        }>>;
+        fill: z.ZodOptional<z.ZodEnum<{
+            pattern: "pattern";
+            none: "none";
+            semi: "semi";
+            solid: "solid";
+        }>>;
+    }, z.core.$strip>], "type">;
+    sheetId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PluginPresentationShapesUpsertArgs = z.infer<typeof PluginPresentationShapesUpsertArgs>;
+/**
+ * Result of {@linkcode PluginPresentationShapesApi.upsert}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapeId` | `string` | Stable id of the canvas shape for the key |
+ * | `created` | `boolean` | `true` if the shape was created, `false` if updated |
+ */
+export declare const PluginPresentationShapesUpsertResult: z.ZodObject<{
+    shapeId: z.ZodString;
+    created: z.ZodBoolean;
+}, z.core.$strip>;
+export type PluginPresentationShapesUpsertResult = z.infer<typeof PluginPresentationShapesUpsertResult>;
+/**
+ * Arguments for {@linkcode PluginPresentationShapesApi.remove}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `key` | `string` | The key the shape was upserted under (non-empty) |
+ */
+export declare const PluginPresentationShapesRemoveArgs: z.ZodObject<{
+    key: z.ZodString;
+}, z.core.$strip>;
+export type PluginPresentationShapesRemoveArgs = z.infer<typeof PluginPresentationShapesRemoveArgs>;
+/**
+ * Result of {@linkcode PluginPresentationShapesApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapes` | `{ key: string; shapeId: string; type: `{@linkcode PluginPresentationShapeType}` }[]` | One entry per live plugin-owned shape |
+ */
+export declare const PluginPresentationShapesListResult: z.ZodObject<{
+    shapes: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        shapeId: z.ZodString;
+        type: z.ZodEnum<{
+            text: "text";
+            note: "note";
+            arrow: "arrow";
+            geo: "geo";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginPresentationShapesListResult = z.infer<typeof PluginPresentationShapesListResult>;
+//# sourceMappingURL=shapes.d.ts.map

package/dist/api/presentation/shapes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shapes.d.ts","sourceRoot":"","sources":["../../../src/api/presentation/shapes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAQ7C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,8BAAsB,2BAA2B;;IAG/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsCG;aACa,MAAM,CACpB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,2BAA2B,EAClC,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAC7B,eAAe,CAAC,oCAAoC,CAAC;IAExD;;;;;;;;;;;;;;;;;;;OAmBG;aACa,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC;IAE7D;;;;;;;;;;;;;;;;;OAiBG;aACa,SAAS,IAAI,eAAe,CAAC,MAAM,CAAC;IAEpD;;;;;;;;;;;;;;;;;;;OAmBG;aACa,IAAI,IAAI,eAAe,CAAC,kCAAkC,CAAC;CAC5E;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BAkCtC,CAAA;AACF,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAC/C,OAAO,2BAA2B,CACnC,CAAA;AAED,mHAAmH;AACnH,eAAO,MAAM,2BAA2B;;;;;EAKtC,CAAA;AACF,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAC/C,OAAO,2BAA2B,CACnC,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,kCAAkC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAI7C,CAAA;AACF,MAAM,MAAM,kCAAkC,GAAG,CAAC,CAAC,KAAK,CACtD,OAAO,kCAAkC,CAC1C,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,oCAAoC;;;iBAG/C,CAAA;AACF,MAAM,MAAM,oCAAoC,GAAG,CAAC,CAAC,KAAK,CACxD,OAAO,oCAAoC,CAC5C,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,kCAAkC;;iBAE7C,CAAA;AACF,MAAM,MAAM,kCAAkC,GAAG,CAAC,CAAC,KAAK,CACtD,OAAO,kCAAkC,CAC1C,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,kCAAkC;;;;;;;;;;;iBAQ7C,CAAA;AACF,MAAM,MAAM,kCAAkC,GAAG,CAAC,CAAC,KAAK,CACtD,OAAO,kCAAkC,CAC1C,CAAA"}

package/dist/api/program/site.d.ts

@@ -177,6 +177,54 @@ export declare abstract class PluginProgramSiteApi {
      * ```
      */
     abstract getNorthAngle(): PluginApiReturn<PluginProgramSiteNorthAngleResult>;
+    /**
+     * Get the IANA timezone of the project's geographic location.
+     *
+     * The timezone identifier (e.g. `"America/New_York"`, `"Asia/Kolkata"`)
+     * looked up from the same geo-location
+     * {@linkcode PluginProgramSiteApi.getLocation} returns. Returns `null` when
+     * the project is not geo-located on terrain.
+     *
+     * @returns A {@linkcode PluginProgramSiteTimezoneResult} — the IANA timezone
+     *   id string, or `null` when the project has no geo-located site.
+     *
+     * @examplePrompt What timezone is this project in?
+     * @examplePrompt Get the site's IANA timezone
+     * @examplePrompt What's the local time zone at the project location?
+     * @examplePrompt Which timezone should I use for the sun study schedule?
+     *
+     * # Example
+     * ```ts
+     * const timezone = await snaptrude.program.site.getTimezone()
+     * if (timezone) console.log(`Project timezone: ${timezone}`)
+     * ```
+     */
+    abstract getTimezone(): PluginApiReturn<PluginProgramSiteTimezoneResult>;
+    /**
+     * Get the weather file resolved for the project site.
+     *
+     * A lightweight read of the EPW weather file the `analysis.*` sun and
+     * daylight studies compute against — its catalog id, station name, content
+     * checksum, and how it was selected. This is the same file (same
+     * `weatherFileId`) that {@linkcode PluginAnalysisWeatherApi.getSeries} reads
+     * rows from and that a daylight run echoes in its provenance. Returns `null`
+     * when the project has no geo-located site (no weather file to resolve).
+     *
+     * @returns A {@linkcode PluginProgramSiteWeatherResult} —
+     *   `{ weatherFileId, station, checksum, selectionMethod }`, or `null` when
+     *   the project has no geo-located site.
+     *
+     * @examplePrompt Which weather file is my project using?
+     * @examplePrompt What EPW station was resolved for this site?
+     * @examplePrompt Get the weather file id for the daylight analysis
+     *
+     * # Example
+     * ```ts
+     * const weather = await snaptrude.program.site.getWeather()
+     * if (weather) console.log(weather.station, weather.selectionMethod)
+     * ```
+     */
+    abstract getWeather(): PluginApiReturn<PluginProgramSiteWeatherResult>;
 }
 /**
  * A 2D ground-plane point of a site parcel footprint, in world XZ plan
@@ -451,4 +499,50 @@ export type PluginProgramSiteLocationResult = z.infer<typeof PluginProgramSiteLo
  */
 export declare const PluginProgramSiteNorthAngleResult: z.ZodNullable<z.ZodNumber>;
 export type PluginProgramSiteNorthAngleResult = z.infer<typeof PluginProgramSiteNorthAngleResult>;
+/**
+ * Result of {@linkcode PluginProgramSiteApi.getTimezone} — the IANA timezone
+ * id of the project's geo-location (e.g. `"Europe/London"`), or `null` when
+ * the project is not geo-located.
+ */
+export declare const PluginProgramSiteTimezoneResult: z.ZodNullable<z.ZodString>;
+export type PluginProgramSiteTimezoneResult = z.infer<typeof PluginProgramSiteTimezoneResult>;
+/**
+ * A summary of the weather file resolved for the project site. Matches the
+ * relevant fields of `analysis.weather`'s `PluginWeatherSourceMeta`;
+ * `selectionMethod` is one of `"nearest-station"`, `"user-upload"`, or
+ * `"project-override"`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `weatherFileId` | `string` | Catalog id (same key as `core.io.import.epw`) |
+ * | `station` | `string` | Station/file name |
+ * | `checksum` | `string` | sha256 of the EPW file |
+ * | `selectionMethod` | `"nearest-station" \| "user-upload" \| "project-override"` | How the file was matched |
+ */
+export declare const PluginProgramSiteWeather: z.ZodObject<{
+    weatherFileId: z.ZodString;
+    station: z.ZodString;
+    checksum: z.ZodString;
+    selectionMethod: z.ZodEnum<{
+        "nearest-station": "nearest-station";
+        "user-upload": "user-upload";
+        "project-override": "project-override";
+    }>;
+}, z.core.$strip>;
+export type PluginProgramSiteWeather = z.infer<typeof PluginProgramSiteWeather>;
+/**
+ * Result of {@linkcode PluginProgramSiteApi.getWeather} — the resolved weather
+ * file summary, or `null` when the project has no geo-located site.
+ */
+export declare const PluginProgramSiteWeatherResult: z.ZodNullable<z.ZodObject<{
+    weatherFileId: z.ZodString;
+    station: z.ZodString;
+    checksum: z.ZodString;
+    selectionMethod: z.ZodEnum<{
+        "nearest-station": "nearest-station";
+        "user-upload": "user-upload";
+        "project-override": "project-override";
+    }>;
+}, z.core.$strip>>;
+export type PluginProgramSiteWeatherResult = z.infer<typeof PluginProgramSiteWeatherResult>;
 //# sourceMappingURL=site.d.ts.map

package/dist/api/program/site.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"site.d.ts","sourceRoot":"","sources":["../../../src/api/program/site.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAG7C;;;;;;;;;;;;;;;;GAgBG;AACH,8BAAsB,oBAAoB;;IAGxC;;;;;;;;;;;;;;;;;;OAkBG;aACa,GAAG,IAAI,eAAe,CAAC,yBAAyB,CAAC;IAEjE;;;;;;;;;;;;;;;;;;OAkBG;aACa,OAAO,IAAI,eAAe,CAAC,2BAA2B,CAAC;IAEvE;;;;;;;;;;;;;;;;;;OAkBG;aACa,YAAY,IAAI,eAAe,CAAC,mCAAmC,CAAC;IAEpF;;;;;;;;;;;;;;;;;;;;OAoBG;aACa,eAAe,IAAI,eAAe,CAAC,sCAAsC,CAAC;IAE1F;;;;;;;;;;;;;;;;;;;OAmBG;aACa,UAAU,IAAI,eAAe,CAAC,8BAA8B,CAAC;IAE7E;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;aACa,WAAW,IAAI,eAAe,CAAC,+BAA+B,CAAC;IAE/E;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;aACa,aAAa,IAAI,eAAe,CAAC,iCAAiC,CAAC;CACpF;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB;;;iBAGnC,CAAA;AACF,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAA;AAE/E;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB;;;;iBAI7B,CAAA;AACF,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAA;AAEnE;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;iBAK5B,CAAA;AACF,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAA;AAEjE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;iBAKpC,CAAA;AACF,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAC7C,OAAO,yBAAyB,CACjC,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B;;;;;;iBAGtC,CAAA;AACF,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAC/C,OAAO,2BAA2B,CACnC,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,mCAAmC;;;;;;;;;;;;;;iBAG9C,CAAA;AACF,MAAM,MAAM,mCAAmC,GAAG,CAAC,CAAC,KAAK,CACvD,OAAO,mCAAmC,CAC3C,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,sCAAsC;;;;;;iBAEjD,CAAA;AACF,MAAM,MAAM,sCAAsC,GAAG,CAAC,CAAC,KAAK,CAC1D,OAAO,sCAAsC,CAC9C,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB;;;iBAG3B,CAAA;AACF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAA;AAE/D;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB;;;;;iBAK3B,CAAA;AACF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAA;AAE/D;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB;;;;;;iBAGlC,CAAA;AACF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAA;AAE7E;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;iBAOnC,CAAA;AACF,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAA;AAE/E;;;GAGG;AACH,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;;kBACN,CAAA;AACrC,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,KAAK,CAClD,OAAO,8BAA8B,CACtC,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB;;;iBAGpC,CAAA;AACF,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAC7C,OAAO,yBAAyB,CACjC,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,+BAA+B;;;kBACN,CAAA;AACtC,MAAM,MAAM,+BAA+B,GAAG,CAAC,CAAC,KAAK,CACnD,OAAO,+BAA+B,CACvC,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,iCAAiC,4BAAwB,CAAA;AACtE,MAAM,MAAM,iCAAiC,GAAG,CAAC,CAAC,KAAK,CACrD,OAAO,iCAAiC,CACzC,CAAA"}
+{"version":3,"file":"site.d.ts","sourceRoot":"","sources":["../../../src/api/program/site.ts"],"names":[],"mappings":"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"}