@snaptrude/plugin-core 0.8.0 → 0.9.1

package/src/api/program/site.ts

@@ -10,8 +10,10 @@ import { PluginAreaUnit } from "./metrics"
  * in Snaptrude units — the same plan space as a space's `planPoints`), and —
  * when the project is geo-located on terrain — their geographic
  * (latitude/longitude) rings. This is the program-planning view of the site;
- * zoning numbers (setbacks, FAR/FSI, height limits) live in the site-analysis
- * sheet and are not read here.
+ * zoning numbers (FAR/FSI, height limits) live in the site-analysis sheet and
+ * are not read here — with one exception: `listEdges` reads each parcel's
+ * per-edge front/side/rear classification and effective base setbacks, the
+ * same resolution the buildable-envelope setback pills show on canvas.
  *
  * All methods are reads: they return plain records and never throw — `get`
  * returns an empty snapshot (zero totals) when there is no site, and the `list`
@@ -85,6 +87,47 @@ export abstract class PluginProgramSiteApi {
    */
   public abstract listPolygons(): PluginApiReturn<PluginProgramSiteListPolygonsResult>
 
+  /**
+   * List each site parcel's boundary edges with their front / side / rear
+   * classification — the same per-edge roles the buildable-envelope setback
+   * pills show on canvas, so a plugin can pick up the user's edge tagging
+   * without asking them to set it up again.
+   *
+   * Role resolution mirrors the canvas exactly: the user's per-edge overrides
+   * (set via the setback pills) win over the tangent heuristic
+   * (`roleSource: "override"` vs `"heuristic"`). `"street"` never appears — it
+   * resolves to `front`. When a parcel has a linked zoning buildable envelope,
+   * `setbackMeters` is the effective base setback of the edge (a per-edge
+   * exception when one exists, else the role's value); parcels without a
+   * zoning envelope classify by heuristic alone and report
+   * `setbackMeters: null`.
+   *
+   * Coordinates are **world meters** (`lengthUnit: "m"`) — unlike
+   * {@linkcode PluginProgramSiteApi.listPolygons} footprints, which are
+   * Snaptrude units. `edgeIndex` is keyed to the canonicalized (sanitized,
+   * CCW) boundary, the same index space the envelope's `edgeOverrides` use.
+   * `staleOverridesDropped: true` means the site was edited after the
+   * envelope was configured and the persisted overrides no longer align with
+   * the live boundary — the heuristic classification is reported instead.
+   *
+   * @returns A {@linkcode PluginProgramSiteListEdgesResult} with one entry per
+   *   parcel. Empty when the project has no site.
+   *
+   * @examplePrompt Which edge of my site is the front?
+   * @examplePrompt Read the front / side / rear edges of the plot
+   * @examplePrompt What setback applies to each site edge?
+   * @examplePrompt Get the site edges the way the setback pills show them
+   *
+   * # Example
+   * ```ts
+   * const { sites } = await snaptrude.program.site.listEdges()
+   * for (const site of sites)
+   *   for (const e of site.edges)
+   *     console.log(e.edgeIndex, e.role, e.roleSource, e.setbackMeters)
+   * ```
+   */
+  public abstract listEdges(): PluginApiReturn<PluginProgramSiteListEdgesResult>
+
   /**
    * List the site parcels as geographic latitude/longitude rings.
    *
@@ -186,6 +229,56 @@ export abstract class PluginProgramSiteApi {
    * ```
    */
   public 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}`)
+   * ```
+   */
+  public 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)
+   * ```
+   */
+  public abstract getWeather(): PluginApiReturn<PluginProgramSiteWeatherResult>
 }
 
 /**
@@ -420,3 +513,113 @@ export const PluginProgramSiteNorthAngleResult = z.number().nullable()
 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 const PluginProgramSiteTimezoneResult = z.string().nullable()
+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 const PluginProgramSiteWeather = z.object({
+  weatherFileId: z.string(),
+  station: z.string(),
+  checksum: z.string(),
+  selectionMethod: z.enum([
+    "nearest-station",
+    "user-upload",
+    "project-override",
+  ]),
+})
+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 const PluginProgramSiteWeatherResult =
+  PluginProgramSiteWeather.nullable()
+export type PluginProgramSiteWeatherResult = z.infer<
+  typeof PluginProgramSiteWeatherResult
+>
+
+/**
+ * Front / side / rear classification of one site-boundary edge. `"street"`
+ * never appears — the backend synonym resolves to `front`.
+ */
+export const PluginProgramSiteEdgeRole = z.enum(["front", "side", "rear"])
+export type PluginProgramSiteEdgeRole = z.infer<typeof PluginProgramSiteEdgeRole>
+
+/**
+ * One boundary edge of a site parcel, as {@linkcode PluginProgramSiteApi.listEdges}
+ * returns it. Coordinates and lengths are world meters.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `edgeIndex` | `number` | Index in the canonicalized (sanitized, CCW) boundary — the same index space the envelope's `edgeOverrides` use |
+ * | `start` / `end` | `{ x, z }` | Edge endpoints, world XZ meters |
+ * | `lengthMeters` | `number` | Edge length in meters |
+ * | `role` | `"front" \| "side" \| "rear"` | Resolved classification (user override wins over the heuristic) |
+ * | `roleSource` | `"override" \| "heuristic"` | Whether the user reassigned this edge's role or the tangent heuristic classified it |
+ * | `setbackMeters` | `number \| null` | Effective base setback (per-edge exception ?? role value); `null` when the parcel has no zoning envelope |
+ */
+export const PluginProgramSiteEdge = z.object({
+  edgeIndex: z.number().int().nonnegative(),
+  start: z.object({ x: z.number(), z: z.number() }),
+  end: z.object({ x: z.number(), z: z.number() }),
+  lengthMeters: z.number(),
+  role: PluginProgramSiteEdgeRole,
+  roleSource: z.enum(["override", "heuristic"]),
+  setbackMeters: z.number().nullable(),
+})
+export type PluginProgramSiteEdge = z.infer<typeof PluginProgramSiteEdge>
+
+/**
+ * Per-parcel entry of {@linkcode PluginProgramSiteApi.listEdges}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `siteId` | `string` | The parcel's component id (same id space as `listPolygons`) |
+ * | `buildableEnvelopeId` | `string \| null` | Linked zoning envelope, when one exists |
+ * | `usingLiveSiteBoundary` | `boolean` | `true` when edges come from the live site boundary; `false` when only the envelope's persisted source polygon was resolvable |
+ * | `staleOverridesDropped` | `boolean` | `true` when persisted edge overrides no longer index-align with the live boundary and were ignored |
+ * | `edges` | `PluginProgramSiteEdge[]` | The classified boundary edges |
+ */
+export const PluginProgramSiteEdgesEntry = z.object({
+  siteId: z.string(),
+  buildableEnvelopeId: z.string().nullable(),
+  usingLiveSiteBoundary: z.boolean(),
+  staleOverridesDropped: z.boolean(),
+  edges: z.array(PluginProgramSiteEdge),
+})
+export type PluginProgramSiteEdgesEntry = z.infer<
+  typeof PluginProgramSiteEdgesEntry
+>
+
+/**
+ * Result of {@linkcode PluginProgramSiteApi.listEdges} — one entry per site
+ * parcel; empty when the project has no site. `lengthUnit` is always `"m"`.
+ */
+export const PluginProgramSiteListEdgesResult = z.object({
+  lengthUnit: z.literal("m"),
+  sites: z.array(PluginProgramSiteEdgesEntry),
+})
+export type PluginProgramSiteListEdgesResult = z.infer<
+  typeof PluginProgramSiteListEdgesResult
+>

package/src/api/program/spreadsheet.ts

@@ -68,6 +68,12 @@ export abstract class PluginProgramSpreadsheetApi {
    */
   public abstract bindings: PluginProgramSpreadsheetBindingsApi
 
+  /**
+   * Plugin datasets — named, plugin-supplied row sets that bindings can render
+   * and auto-refresh on rerun. See {@linkcode PluginProgramSpreadsheetDatasetsApi}.
+   */
+  public abstract datasets: PluginProgramSpreadsheetDatasetsApi
+
   /**
    * Render a titled, formatted table onto a named sheet (create-or-replace).
    *
@@ -204,6 +210,9 @@ export abstract class PluginProgramSpreadsheetApi {
    * single-sheet: it serializes one sheet's used range — pass `options.sheetName`
    * to choose which sheet, or omit it to serialize the active sheet.
    *
+   * For a different export intent, see `core.io.export.model` (the 3D model
+   * file) and `presentation.export` (Present-mode layout sheets to PDF/PNG/JPG).
+   *
    * @param format - The file format to export to.
    * @param options - Optional `fileName` (without extension; a default is used
    *   when omitted) and `sheetName` — the sheet to serialize for `csv`
@@ -315,6 +324,55 @@ export abstract class PluginProgramSpreadsheetApi {
     },
   ): PluginApiReturn<PluginProgramSpreadsheetAddChartResult>
 
+  /**
+   * Place a floating image on a workbook sheet from a base64 data URI.
+   *
+   * The image is anchored at a cell's top-left corner (default `"A1"`) and
+   * floats over the grid (a SpreadJS floating picture — it does not occupy
+   * cells). Only base64 `data:image/png|jpeg|svg+xml` URIs are accepted —
+   * never URLs — and the URI is capped at 2 MB. Passing a `name` gives the
+   * picture a stable id: re-running with the same `name` replaces the previous
+   * picture (rerun-friendly); when omitted a name is generated.
+   *
+   * For images on Present-mode sheets (the tldraw canvas), use
+   * `presentation.shapes` instead — this verb places floating pictures in the
+   * SpreadJS workbook.
+   *
+   * @param sheetName - Sheet to place the image on.
+   * @param image - The image payload: a base64 `dataUri`
+   *   (`data:image/png|jpeg|svg+xml;base64,…`, max 2 MB).
+   * @param options - Optional `anchorCell` (A1 notation, default `"A1"`),
+   *   `size` in px (intrinsic size when omitted), and stable `name`
+   *   (replace-on-rerun).
+   * @returns A {@linkcode PluginProgramSpreadsheetAddImageResult} with the sheet
+   *   and the picture's name.
+   * @throws If the sheet does not exist, or the data URI is not an accepted
+   *   image type or exceeds 2 MB.
+   *
+   * @examplePrompt Add my logo image to the report sheet
+   * @examplePrompt Place a PNG at cell B2 on the Takeoff sheet
+   * @examplePrompt Put an SVG diagram on a spreadsheet sheet
+   * @examplePrompt Insert an image into the workbook
+   *
+   * # Example
+   * ```ts
+   * const { name } = await snaptrude.program.spreadsheet.addImage(
+   *   "Report",
+   *   { dataUri: "data:image/png;base64,iVBORw0..." },
+   *   { anchorCell: "B2", size: { width: 240, height: 120 }, name: "logo" },
+   * )
+   * ```
+   */
+  public abstract addImage(
+    sheetName: string,
+    image: { dataUri: string },
+    options?: {
+      anchorCell?: string
+      size?: { width: number; height: number }
+      name?: string
+    },
+  ): PluginApiReturn<PluginProgramSpreadsheetAddImageResult>
+
   /**
    * Highlight a range of cells (background color and optional emphasis).
    *
@@ -911,6 +969,76 @@ export abstract class PluginProgramSpreadsheetBindingsApi {
   public abstract list(): PluginApiReturn<PluginProgramSpreadsheetBindingsListResult>
 }
 
+/**
+ * Program-spreadsheet plugin datasets — named, plugin-supplied row sets stored
+ * alongside the workbook so bindings can render and re-render them.
+ *
+ * A dataset is uploaded with {@linkcode PluginProgramSpreadsheetDatasetsApi.set}
+ * (upsert by name). A binding whose source is `{ dataset: "plugin", name }`
+ * renders the dataset at its target anchor, and re-renders automatically every
+ * time the dataset is set again — the "refresh on rerun" behaviour. Accessed
+ * via `snaptrude.program.spreadsheet.datasets`.
+ */
+export abstract class PluginProgramSpreadsheetDatasetsApi {
+  constructor() {}
+
+  /**
+   * Store (upsert) a named plugin dataset.
+   *
+   * Re-using a `name` replaces the dataset and automatically refreshes every
+   * binding whose source is `{ dataset: "plugin", name }` — no extra plugin
+   * calls needed to keep bound ranges current. Limits: at most 10,000 rows and
+   * 2 MB serialized.
+   *
+   * @param name - Dataset name (re-using a name overwrites it).
+   * @param columns - Column definitions (see {@linkcode PluginSpreadsheetColumn});
+   *   their order is the column order bindings render.
+   * @param rows - Row objects keyed by column `key`.
+   * @returns A {@linkcode PluginProgramSpreadsheetDatasetsSetResult} with the
+   *   stored row count.
+   * @throws If the dataset exceeds 10,000 rows or 2 MB serialized.
+   *
+   * @examplePrompt Store my plugin's rows as a named dataset
+   * @examplePrompt Upload data the sheets can bind to and refresh
+   * @examplePrompt Save a dataset for a live sheet binding
+   * @examplePrompt Push my computed table so a binding keeps it fresh
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.program.spreadsheet.datasets.set(
+   *   "costs",
+   *   [
+   *     { key: "item", header: "Item" },
+   *     { key: "cost", header: "Cost", align: "right" },
+   *   ],
+   *   [{ item: "Concrete", cost: 120 }],
+   * )
+   * ```
+   */
+  public abstract set(
+    name: string,
+    columns: PluginSpreadsheetColumn[],
+    rows: Record<string, PluginSpreadsheetCell>[],
+  ): PluginApiReturn<PluginProgramSpreadsheetDatasetsSetResult>
+
+  /**
+   * List the stored plugin datasets.
+   *
+   * @returns A {@linkcode PluginProgramSpreadsheetDatasetsListResult} with each
+   *   dataset's `name`, `rowCount`, and `updatedAt` timestamp.
+   *
+   * @examplePrompt List my plugin datasets
+   * @examplePrompt What datasets are stored for the sheets?
+   * @examplePrompt Show the data sets bindings can use
+   *
+   * # Example
+   * ```ts
+   * const { datasets } = await snaptrude.program.spreadsheet.datasets.list()
+   * ```
+   */
+  public abstract list(): PluginApiReturn<PluginProgramSpreadsheetDatasetsListResult>
+}
+
 /** A single spreadsheet cell value. */
 export const PluginSpreadsheetCell = z.union([
   z.string(),
@@ -2011,16 +2139,18 @@ export type PluginProgramSpreadsheetTemplatesApplyResult = z.infer<
 // --- bindings.* ------------------------------------------------------------
 
 /**
- * A binding's data source. Currently only the takeoff dataset; `program` is
- * reserved for a future source.
+ * A binding's data source — the built-in takeoff dataset, or a named plugin
+ * dataset stored via {@linkcode PluginProgramSpreadsheetDatasetsApi.set}.
  *
  * | Property | Type | Description |
  * |---|---|---|
- * | `dataset` | `"takeoff"` | The dataset the binding pulls from |
+ * | `dataset` | `"takeoff" \| "plugin"` | The dataset kind the binding pulls from |
+ * | `name` | `string` | (`"plugin"` only) The stored dataset's name |
  */
-export const PluginSpreadsheetBindingSource = z.object({
-  dataset: z.enum(["takeoff"]),
-})
+export const PluginSpreadsheetBindingSource = z.discriminatedUnion("dataset", [
+  z.object({ dataset: z.literal("takeoff") }),
+  z.object({ dataset: z.literal("plugin"), name: z.string() }),
+])
 export type PluginSpreadsheetBindingSource = z.infer<
   typeof PluginSpreadsheetBindingSource
 >
@@ -2169,3 +2299,118 @@ export const PluginProgramSpreadsheetBindingsListResult = z.object({
 export type PluginProgramSpreadsheetBindingsListResult = z.infer<
   typeof PluginProgramSpreadsheetBindingsListResult
 >
+
+// --- datasets.* ------------------------------------------------------------
+
+/**
+ * Arguments for {@linkcode PluginProgramSpreadsheetDatasetsApi.set}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string` | Dataset name (re-using a name overwrites it) |
+ * | `columns` | {@linkcode PluginSpreadsheetColumn}`[]` | Column definitions (at least one) |
+ * | `rows` | `Record<string, cell>[]` | Row objects keyed by column `key` (max 10,000) |
+ */
+export const PluginProgramSpreadsheetDatasetsSetArgs = z.object({
+  name: z.string(),
+  columns: z.array(PluginSpreadsheetColumn).min(1),
+  rows: z.array(z.record(z.string(), PluginSpreadsheetCell)).max(10_000),
+})
+export type PluginProgramSpreadsheetDatasetsSetArgs = z.infer<
+  typeof PluginProgramSpreadsheetDatasetsSetArgs
+>
+
+/**
+ * Result of {@linkcode PluginProgramSpreadsheetDatasetsApi.set}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string` | The stored dataset's name |
+ * | `rowCount` | `number` | Number of rows stored |
+ */
+export const PluginProgramSpreadsheetDatasetsSetResult = z.object({
+  name: z.string(),
+  rowCount: z.number(),
+})
+export type PluginProgramSpreadsheetDatasetsSetResult = z.infer<
+  typeof PluginProgramSpreadsheetDatasetsSetResult
+>
+
+/**
+ * A stored plugin dataset's summary, for
+ * {@linkcode PluginProgramSpreadsheetDatasetsApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string` | Dataset name |
+ * | `rowCount` | `number` | Number of rows stored |
+ * | `updatedAt` | `string` | ISO timestamp of the last `set` |
+ */
+export const PluginSpreadsheetDataset = z.object({
+  name: z.string(),
+  rowCount: z.number(),
+  updatedAt: z.string(),
+})
+export type PluginSpreadsheetDataset = z.infer<typeof PluginSpreadsheetDataset>
+
+/**
+ * Result of {@linkcode PluginProgramSpreadsheetDatasetsApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `datasets` | {@linkcode PluginSpreadsheetDataset}`[]` | Every stored dataset |
+ */
+export const PluginProgramSpreadsheetDatasetsListResult = z.object({
+  datasets: z.array(PluginSpreadsheetDataset),
+})
+export type PluginProgramSpreadsheetDatasetsListResult = z.infer<
+  typeof PluginProgramSpreadsheetDatasetsListResult
+>
+
+// --- addImage --------------------------------------------------------------
+
+/**
+ * Arguments for {@linkcode PluginProgramSpreadsheetApi.addImage}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetName` | `string` | Sheet to place the image on |
+ * | `image` | `{ dataUri: string }` | Base64 `data:image/png\|jpeg\|svg+xml` URI (max 2 MB; URLs rejected) |
+ * | `anchorCell` | `string?` | Anchor cell in A1 notation (default `"A1"`) |
+ * | `size` | `{ width; height }?` | Size in px; intrinsic size when omitted |
+ * | `name` | `string?` | Stable picture id — same name replaces on rerun; generated when omitted |
+ */
+export const PluginProgramSpreadsheetAddImageArgs = z.object({
+  sheetName: z.string(),
+  image: z.object({
+    dataUri: z
+      .string()
+      .max(2_097_152, "image.dataUri exceeds the 2 MB limit")
+      .regex(
+        /^data:image\/(png|jpeg|svg\+xml);base64,/,
+        "image.dataUri must be a base64 data:image/png, jpeg, or svg+xml URI",
+      ),
+  }),
+  anchorCell: z.string().optional(),
+  size: z.object({ width: z.number(), height: z.number() }).optional(),
+  name: z.string().optional(),
+})
+export type PluginProgramSpreadsheetAddImageArgs = z.infer<
+  typeof PluginProgramSpreadsheetAddImageArgs
+>
+
+/**
+ * Result of {@linkcode PluginProgramSpreadsheetApi.addImage}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetName` | `string` | The sheet the image was placed on |
+ * | `name` | `string` | The picture's (stable or generated) name |
+ */
+export const PluginProgramSpreadsheetAddImageResult = z.object({
+  sheetName: z.string(),
+  name: z.string(),
+})
+export type PluginProgramSpreadsheetAddImageResult = z.infer<
+  typeof PluginProgramSpreadsheetAddImageResult
+>