@snaptrude/plugin-core 0.3.0 → 0.6.0

package/src/api/core/buildings.ts

@@ -0,0 +1,485 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+
+/**
+ * Buildings — read and edit the buildings of the active project.
+ *
+ * A **building** is the top of the project's spatial hierarchy: a named container
+ * of storeys, positioned by its base elevation. This namespace reads a building's
+ * identity and base elevation and lists the storeys it holds; storey detail is
+ * read through the entity story surface (`snaptrude.entity.story`).
+ *
+ * Reads return plain records and never throw for a missing building (`get` and
+ * `getActive` return `null`, `list` returns `[]`). Ids are stable public strings.
+ *
+ * Sub-namespace members typed as optional (`?`) are **authored ahead of the
+ * host** — declared so plugins and codegen can see the shape, but kept out of the
+ * discovery manifest until the host lands them (at which point they are promoted
+ * to required `abstract` members).
+ *
+ * Accessed via `snaptrude.core.buildings`.
+ */
+export abstract class PluginCoreBuildingsApi {
+  constructor() {}
+
+  /**
+   * List the buildings in the active project.
+   *
+   * @returns A {@linkcode PluginCoreBuildingsListResult} with a `buildings` array
+   *   (empty when the project has none).
+   *
+   * @examplePrompt List all the buildings in my project
+   * @examplePrompt How many buildings are in this model?
+   * @examplePrompt Show every building with its base elevation
+   *
+   * # Example
+   * ```ts
+   * const { buildings } = await snaptrude.core.buildings.list()
+   * for (const b of buildings) console.log(b.name, b.baseElevation)
+   * ```
+   */
+  public abstract list(): PluginApiReturn<PluginCoreBuildingsListResult>
+
+  /**
+   * Get a single building by id.
+   *
+   * @param buildingId - The id of the building to read.
+   * @returns The matching {@linkcode PluginCoreBuildingRef}, or `null` if no
+   *   building has that id.
+   *
+   * @examplePrompt Get the building with id blg_1
+   * @examplePrompt Look up a single building by its id
+   * @examplePrompt What is the base elevation of building blg_2?
+   *
+   * # Example
+   * ```ts
+   * const building = await snaptrude.core.buildings.get("blg_1")
+   * if (building) console.log(building.name, building.baseElevation)
+   * ```
+   */
+  public abstract get(
+    buildingId: string,
+  ): PluginApiReturn<PluginCoreBuildingsGetResult>
+
+  /**
+   * List the storeys of a building.
+   *
+   * Returns the building's storeys as stable storey ids, in the project's storey
+   * order. Read each storey's detail through `snaptrude.entity.story`.
+   *
+   * @param buildingId - The id of the building whose storeys to list.
+   * @returns A {@linkcode PluginCoreBuildingsListStoreysResult} with a `storeyIds`
+   *   array (empty when the building is missing or has no storeys).
+   *
+   * @examplePrompt List the storeys in building blg_1
+   * @examplePrompt How many floors does this building have?
+   * @examplePrompt Get the storey ids of the active building
+   *
+   * # Example
+   * ```ts
+   * const { storeyIds } = await snaptrude.core.buildings.listStoreys("blg_1")
+   * console.log(`${storeyIds.length} storeys`)
+   * ```
+   */
+  public abstract listStoreys(
+    buildingId: string,
+  ): PluginApiReturn<PluginCoreBuildingsListStoreysResult>
+
+  /**
+   * Get the active building.
+   *
+   * The active building is the one new storeys and edits target. Paired with
+   * {@linkcode PluginCoreBuildingsApi.setActive}.
+   *
+   * @returns A {@linkcode PluginCoreBuildingsGetActiveResult} with the active
+   *   `buildingId`, or `null` if there is no active building.
+   *
+   * @examplePrompt Which building is active?
+   * @examplePrompt Get the current building
+   * @examplePrompt What building am I working in?
+   *
+   * # Example
+   * ```ts
+   * const active = await snaptrude.core.buildings.getActive()
+   * if (active) console.log(active.buildingId)
+   * ```
+   */
+  public abstract getActive(): PluginApiReturn<PluginCoreBuildingsGetActiveResult>
+
+  /**
+   * Make a building the active building.
+   *
+   * Paired with {@linkcode PluginCoreBuildingsApi.getActive}.
+   *
+   * @param buildingId - The id of the building to activate.
+   * @returns The id of the now-active building.
+   * @throws If no building has the given id.
+   *
+   * @examplePrompt Switch to building blg_2
+   * @examplePrompt Make this building the active one
+   * @examplePrompt Set the active building to blg_1
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.buildings.setActive("blg_2")
+   * ```
+   */
+  public abstract setActive(
+    buildingId: string,
+  ): PluginApiReturn<PluginCoreBuildingsSetActiveResult>
+
+  /**
+   * Create a new building.
+   *
+   * Adds a named building at the given base elevation (defaults to `0`). The new
+   * building starts empty — add storeys through the storeys namespace.
+   *
+   * @param name - Display name of the new building.
+   * @param baseElevation - Base elevation in meters (defaults to `0`).
+   * @returns The new building's id (read the full record back with
+   *   {@linkcode PluginCoreBuildingsApi.get}).
+   * @throws If the building could not be created.
+   *
+   * @examplePrompt Create a building called Tower B
+   * @examplePrompt Add a new building at elevation 12 meters
+   * @examplePrompt Make a second building named Annex
+   *
+   * # Example
+   * ```ts
+   * const { buildingId } = await snaptrude.core.buildings.create("Tower B", 0)
+   * ```
+   */
+  public abstract create(
+    name: string,
+    baseElevation?: number,
+  ): PluginApiReturn<PluginCoreBuildingsCreateResult>
+
+  /**
+   * Update a building's name and/or base elevation.
+   *
+   * A **sparse** update: omitted fields are left unchanged.
+   *
+   * @param buildingId - The id of the building to update.
+   * @param options - Any of `name`, `baseElevation`; omitted fields are left
+   *   unchanged.
+   * @returns The updated {@linkcode PluginCoreBuildingRef}.
+   * @throws If no building has the given id.
+   *
+   * @examplePrompt Rename building blg_1 to Tower A
+   * @examplePrompt Move the building up to elevation 6 meters
+   * @examplePrompt Change the base elevation of blg_2
+   *
+   * # Example
+   * ```ts
+   * const building = await snaptrude.core.buildings.update("blg_1", { name: "Tower A" })
+   * ```
+   */
+  public abstract update(
+    buildingId: string,
+    options?: { name?: string; baseElevation?: number },
+  ): PluginApiReturn<PluginCoreBuildingsUpdateResult>
+
+  /**
+   * Copy a building.
+   *
+   * Copies the building — its storeys, components, and drawing layers — into a new
+   * building. `asInstances` controls the copy's geometry: `true` shares the source
+   * geometry as instances (low memory), `false` makes independent editable copies
+   * (the host defaults to `true`). Optionally override the copy's `name` and
+   * `baseElevation`.
+   *
+   * @param buildingId - The id of the building to copy.
+   * @param options - Optional `name`, `baseElevation`, `asInstances` overrides
+   *   for the copy.
+   * @returns The new building's id.
+   * @throws If no building has the given id.
+   *
+   * @examplePrompt Copy building blg_1
+   * @examplePrompt Make an independent editable copy of this building
+   * @examplePrompt Copy Tower A as instances to save memory
+   *
+   * # Example
+   * ```ts
+   * const { buildingId } = await snaptrude.core.buildings.copy("blg_1", {
+   *   name: "Tower A Copy",
+   *   asInstances: false,
+   * })
+   * ```
+   */
+  public abstract copy(
+    buildingId: string,
+    options?: { name?: string; baseElevation?: number; asInstances?: boolean },
+  ): PluginApiReturn<PluginCoreBuildingsCopyResult>
+
+  /**
+   * Delete a building.
+   *
+   * **Gated and destructive.** Deleting a building cascades through its meshes,
+   * storeys, and the building itself, and removes its saved views — **saved views
+   * are not restored on undo.** The project's only remaining building cannot be
+   * deleted.
+   *
+   * @param buildingId - The id of the building to delete.
+   * @returns Confirmation that the building was deleted.
+   * @throws If no building has the given id, or it is the only building.
+   *
+   * @examplePrompt Delete building blg_2
+   * @examplePrompt Remove the Annex building and everything in it
+   * @examplePrompt Delete this building
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.buildings.delete("blg_2")
+   * ```
+   */
+  public abstract delete(
+    buildingId: string,
+  ): PluginApiReturn<PluginCoreBuildingsDeleteResult>
+}
+
+/**
+ * A building in the active project.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Stable public building id (e.g. `"blg_1"`) |
+ * | `name` | `string` | Display name |
+ * | `baseElevation` | `number` | Base elevation in meters, positive up (default `0`) |
+ */
+export const PluginCoreBuildingRef = z.object({
+  id: z.string(),
+  name: z.string(),
+  baseElevation: z.number(),
+})
+export type PluginCoreBuildingRef = z.infer<typeof PluginCoreBuildingRef>
+
+/**
+ * Result of {@linkcode PluginCoreBuildingsApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildings` | {@linkcode PluginCoreBuildingRef}`[]` | Every building in the active project |
+ */
+export const PluginCoreBuildingsListResult = z.object({
+  buildings: z.array(PluginCoreBuildingRef),
+})
+export type PluginCoreBuildingsListResult = z.infer<
+  typeof PluginCoreBuildingsListResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreBuildingsApi.get}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildingId` | `string` | The id of the building to read |
+ */
+export const PluginCoreBuildingsGetArgs = z.object({
+  buildingId: z.string(),
+})
+export type PluginCoreBuildingsGetArgs = z.infer<
+  typeof PluginCoreBuildingsGetArgs
+>
+
+/**
+ * Result of {@linkcode PluginCoreBuildingsApi.get} — the building, or `null` when
+ * no building has the given id.
+ */
+export const PluginCoreBuildingsGetResult = PluginCoreBuildingRef.nullable()
+export type PluginCoreBuildingsGetResult = z.infer<
+  typeof PluginCoreBuildingsGetResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreBuildingsApi.listStoreys}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildingId` | `string` | The id of the building whose storeys to list |
+ */
+export const PluginCoreBuildingsListStoreysArgs = z.object({
+  buildingId: z.string(),
+})
+export type PluginCoreBuildingsListStoreysArgs = z.infer<
+  typeof PluginCoreBuildingsListStoreysArgs
+>
+
+/**
+ * Result of {@linkcode PluginCoreBuildingsApi.listStoreys}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `storeyIds` | `string[]` | The building's storey ids in storey order (empty when missing or none) |
+ */
+export const PluginCoreBuildingsListStoreysResult = z.object({
+  storeyIds: z.array(z.string()),
+})
+export type PluginCoreBuildingsListStoreysResult = z.infer<
+  typeof PluginCoreBuildingsListStoreysResult
+>
+
+/**
+ * Result of {@linkcode PluginCoreBuildingsApi.getActive} — the active building's
+ * id, or `null` when there is no active building.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildingId` | `string` | The id of the active building |
+ */
+export const PluginCoreBuildingsGetActiveResult = z
+  .object({
+    buildingId: z.string(),
+  })
+  .nullable()
+export type PluginCoreBuildingsGetActiveResult = z.infer<
+  typeof PluginCoreBuildingsGetActiveResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreBuildingsApi.setActive}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildingId` | `string` | The id of the building to activate |
+ */
+export const PluginCoreBuildingsSetActiveArgs = z.object({
+  buildingId: z.string(),
+})
+export type PluginCoreBuildingsSetActiveArgs = z.infer<
+  typeof PluginCoreBuildingsSetActiveArgs
+>
+
+/**
+ * Result of {@linkcode PluginCoreBuildingsApi.setActive} — the now-active
+ * building's id.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildingId` | `string` | The id of the now-active building |
+ */
+export const PluginCoreBuildingsSetActiveResult = z.object({
+  buildingId: z.string(),
+})
+export type PluginCoreBuildingsSetActiveResult = z.infer<
+  typeof PluginCoreBuildingsSetActiveResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreBuildingsApi.create}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string` | Display name of the new building |
+ * | `baseElevation` | `number \| undefined` | Base elevation in meters (defaults to `0`) |
+ */
+export const PluginCoreBuildingsCreateArgs = z.object({
+  name: z.string(),
+  baseElevation: z.number().optional(),
+})
+export type PluginCoreBuildingsCreateArgs = z.infer<
+  typeof PluginCoreBuildingsCreateArgs
+>
+
+/**
+ * Result of {@linkcode PluginCoreBuildingsApi.create} — the id of the new
+ * building.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildingId` | `string` | The id of the newly created building |
+ */
+export const PluginCoreBuildingsCreateResult = z.object({
+  buildingId: z.string(),
+})
+export type PluginCoreBuildingsCreateResult = z.infer<
+  typeof PluginCoreBuildingsCreateResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreBuildingsApi.update}. Sparse — only the
+ * provided fields are changed.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildingId` | `string` | The id of the building to update |
+ * | `name` | `string \| undefined` | New display name (unchanged if omitted) |
+ * | `baseElevation` | `number \| undefined` | New base elevation in meters (unchanged if omitted) |
+ */
+export const PluginCoreBuildingsUpdateArgs = z.object({
+  buildingId: z.string(),
+  name: z.string().optional(),
+  baseElevation: z.number().optional(),
+})
+export type PluginCoreBuildingsUpdateArgs = z.infer<
+  typeof PluginCoreBuildingsUpdateArgs
+>
+
+/** Result of {@linkcode PluginCoreBuildingsApi.update} — the updated record. */
+export const PluginCoreBuildingsUpdateResult = PluginCoreBuildingRef
+export type PluginCoreBuildingsUpdateResult = z.infer<
+  typeof PluginCoreBuildingsUpdateResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreBuildingsApi.copy}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildingId` | `string` | The id of the building to copy |
+ * | `name` | `string \| undefined` | Name for the copy (auto-generated if omitted) |
+ * | `baseElevation` | `number \| undefined` | Base elevation for the copy in meters (source's if omitted) |
+ * | `asInstances` | `boolean \| undefined` | `true` shares source geometry as instances; `false` makes independent copies (host default `true`) |
+ */
+export const PluginCoreBuildingsCopyArgs = z.object({
+  buildingId: z.string(),
+  name: z.string().optional(),
+  baseElevation: z.number().optional(),
+  asInstances: z.boolean().optional(),
+})
+export type PluginCoreBuildingsCopyArgs = z.infer<
+  typeof PluginCoreBuildingsCopyArgs
+>
+
+/**
+ * Result of {@linkcode PluginCoreBuildingsApi.copy} — the id of the new
+ * building.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildingId` | `string` | The id of the copied building |
+ */
+export const PluginCoreBuildingsCopyResult = z.object({
+  buildingId: z.string(),
+})
+export type PluginCoreBuildingsCopyResult = z.infer<
+  typeof PluginCoreBuildingsCopyResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreBuildingsApi.delete}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildingId` | `string` | The id of the building to delete |
+ */
+export const PluginCoreBuildingsDeleteArgs = z.object({
+  buildingId: z.string(),
+})
+export type PluginCoreBuildingsDeleteArgs = z.infer<
+  typeof PluginCoreBuildingsDeleteArgs
+>
+
+/**
+ * Result of {@linkcode PluginCoreBuildingsApi.delete} — confirmation that the
+ * building was deleted.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `deleted` | `true` | Always `true` on success |
+ */
+export const PluginCoreBuildingsDeleteResult = z.object({
+  deleted: z.literal(true),
+})
+export type PluginCoreBuildingsDeleteResult = z.infer<
+  typeof PluginCoreBuildingsDeleteResult
+>