@snaptrude/plugin-core 0.0.0-dev-20260708130115

package/src/api/entity/story.ts

@@ -0,0 +1,273 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+
+/**
+ * Story (floor/storey) management.
+ *
+ * A story represents a building floor in the Snaptrude project. Stories
+ * are identified by their integer **story value** (e.g. `1` for ground
+ * floor, `2` for first floor, `-1` for a basement).
+ *
+ * All methods are **host API calls** that return Promises and support
+ * undo/redo via Snaptrude's command system.
+ *
+ * Accessed via `snaptrude.entity.story`.
+ */
+export abstract class PluginStoryApi {
+  constructor() {}
+
+  /**
+   * Get properties of a story by its storey number.
+   *
+   * Only the properties listed in `properties`
+   * are returned — unlisted properties will be `undefined` in the result.
+   *
+   * @param storyValue - Integer storey number
+   *   (e.g. `1` for ground floor, `2` for first floor, `-1` for basement)
+   * @param properties - Array of property names
+   *   to retrieve. See {@linkcode PluginStoryGetProperty} for available values.
+   * @returns A partial {@linkcode PluginStoryGetResult} containing only the requested properties
+   * @throws If the story with the given value does not exist
+   *
+   * @examplePrompt What is the height of the ground floor?
+   * @examplePrompt How many rooms are on the second storey?
+   * @examplePrompt Get the total floor area of level 3
+   * @examplePrompt Is the first floor hidden in the viewport?
+   * @examplePrompt Show me the name and height of story 2
+   *
+   * # Example
+   * ```ts
+   * const info = await snaptrude.entity.story.get(1, ["height", "name", "spacesCount"])
+   * console.log(info.name, info.height, info.spacesCount)
+   * ```
+   */
+  public abstract get(
+    storyValue: number,
+    properties: PluginStoryGetProperty[],
+  ): PluginApiReturn<PluginStoryGetResult>
+
+  /**
+   * Get all stories in the current project.
+   *
+   * Returns basic identification data for every storey. Stories are sorted
+   * from **top to bottom** (highest story value first).
+   *
+   * @returns A {@linkcode PluginStoryGetAllResult} with a `stories` array,
+   *   each entry containing `value`, `id`, and `name`
+   *
+   * @examplePrompt How many floors does this building have?
+   * @examplePrompt List all the storeys in the project
+   * @examplePrompt Show me every level with its name
+   * @examplePrompt Which stories exist in this model?
+   *
+   * # Example
+   * ```ts
+   * const { stories } = await snaptrude.entity.story.getAll()
+   * for (const s of stories) {
+   *   console.log(`Story ${s.value}: ${s.name} (id: ${s.id})`)
+   * }
+   * ```
+   */
+  public abstract getAll(): PluginApiReturn<PluginStoryGetAllResult>
+
+  /**
+   * Create a new story (floor) in the project.
+   *
+   * The new story is inserted at the position specified by
+   * `storyValue`. This operation is undoable.
+   *
+   * @param storyValue - Integer storey number
+   *   to create (e.g. `3` to add a third floor)
+   * @param height - Optional height in Babylon
+   *   units. If omitted, the project's default storey height is used.
+   * @returns A {@linkcode PluginStoryCreateResult} with `storyId` and `storyValue`
+   * @throws If a story with the given value already exists or creation fails
+   *
+   * @examplePrompt Add a third floor to the building
+   * @examplePrompt Create a new storey above the second floor
+   * @examplePrompt Add a basement level to this project
+   * @examplePrompt Insert a new level with a custom floor height
+   * @examplePrompt Add another floor on top of the building
+   *
+   * # Example
+   * ```ts
+   * // Create a new third floor with custom height
+   * const { storyId } = await snaptrude.entity.story.create(3, 4.5)
+   * ```
+   */
+  public abstract create(
+    storyValue: number,
+    height?: number,
+  ): PluginApiReturn<PluginStoryCreateResult>
+
+  /**
+   * Update a story's height.
+   *
+   * Changes the floor-to-floor height of the specified story. This
+   * operation is undoable.
+   *
+   * @param storyValue - Integer storey number
+   *   identifying the story to update
+   * @param height - New height value in Babylon
+   *   units
+   * @returns A {@linkcode PluginStoryUpdateResult} with the updated `storyValue` and `height`
+   * @throws If the story does not exist or the update fails
+   *
+   * @examplePrompt Change the ground floor height to 3.5 metres
+   * @examplePrompt Make the second storey taller
+   * @examplePrompt Set the floor-to-floor height of level 1
+   * @examplePrompt Increase the height of the third floor
+   *
+   * # Example
+   * ```ts
+   * // Set ground floor height to 5 Babylon units
+   * const result = await snaptrude.entity.story.update(1, 5)
+   * ```
+   */
+  public abstract update(
+    storyValue: number,
+    height: number,
+  ): PluginApiReturn<PluginStoryUpdateResult>
+}
+
+/**
+ * Available properties that can be queried on a story.
+ *
+ * | Value | Type | Description |
+ * |---|---|---|
+ * | `"value"` | `number` | The integer storey number |
+ * | `"id"` | `string` | Unique story identifier |
+ * | `"name"` | `string` | Display name of the story |
+ * | `"height"` | `number` | Floor-to-floor height in Babylon units |
+ * | `"base"` | `number` | Base elevation in Babylon units |
+ * | `"hidden"` | `boolean` | Whether the story is hidden in the viewport |
+ * | `"spacesCount"` | `number` | Number of spaces on this story |
+ * | `"totalArea"` | `number` | Total floor area of this story |
+ */
+export const PluginStoryGetProperty = z.enum([
+  "value",
+  "id",
+  "name",
+  "height",
+  "base",
+  "hidden",
+  "spacesCount",
+  "totalArea",
+])
+
+export type PluginStoryGetProperty = z.infer<typeof PluginStoryGetProperty>
+
+/**
+ * Arguments for {@linkcode PluginStoryApi.get}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `storyValue` | `number` (int) | The storey number to query |
+ * | `properties` | {@linkcode PluginStoryGetProperty}`[]` | Properties to retrieve |
+ */
+export const PluginStoryGetArgs = z.object({
+  storyValue: z.number().int(),
+  properties: z.array(PluginStoryGetProperty),
+})
+
+export type PluginStoryGetArgs = z.infer<typeof PluginStoryGetArgs>
+
+/**
+ * Result of {@linkcode PluginStoryApi.get}.
+ *
+ * A partial object — only the properties that were requested in
+ * {@linkcode PluginStoryGetArgs.properties} will be present.
+ */
+export const PluginStoryGetResult = z
+  .object({
+    value: z.number(),
+    id: z.string(),
+    name: z.string(),
+    height: z.number(),
+    base: z.number(),
+    hidden: z.boolean(),
+    spacesCount: z.number(),
+    totalArea: z.number(),
+  })
+  .partial()
+
+export type PluginStoryGetResult = z.infer<typeof PluginStoryGetResult>
+
+/**
+ * Result of {@linkcode PluginStoryApi.getAll}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `stories` | `Array<{ value, id, name }>` | All stories, sorted top to bottom |
+ */
+export const PluginStoryGetAllResult = z.object({
+  stories: z.array(
+    z.object({
+      value: z.number(),
+      id: z.string(),
+      name: z.string(),
+    })
+  ),
+})
+
+export type PluginStoryGetAllResult = z.infer<typeof PluginStoryGetAllResult>
+
+/**
+ * Arguments for {@linkcode PluginStoryApi.create}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `storyValue` | `number` (int) | The storey number for the new story |
+ * | `height` | `number?` | Optional height in Babylon units |
+ */
+export const PluginStoryCreateArgs = z.object({
+  storyValue: z.number().int(),
+  height: z.number().optional(),
+})
+
+export type PluginStoryCreateArgs = z.infer<typeof PluginStoryCreateArgs>
+
+/**
+ * Result of {@linkcode PluginStoryApi.create}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `storyId` | `string` | Unique ID of the created story |
+ * | `storyValue` | `number` | The storey number of the created story |
+ */
+export const PluginStoryCreateResult = z.object({
+  storyId: z.string(),
+  storyValue: z.number(),
+})
+
+export type PluginStoryCreateResult = z.infer<typeof PluginStoryCreateResult>
+
+/**
+ * Arguments for {@linkcode PluginStoryApi.update}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `storyValue` | `number` (int) | Storey number of the story to update |
+ * | `height` | `number` | New height in Babylon units |
+ */
+export const PluginStoryUpdateArgs = z.object({
+  storyValue: z.number().int(),
+  height: z.number(),
+})
+
+export type PluginStoryUpdateArgs = z.infer<typeof PluginStoryUpdateArgs>
+
+/**
+ * Result of {@linkcode PluginStoryApi.update}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `storyValue` | `number` | The storey number of the updated story |
+ * | `height` | `number` | The new height after the update |
+ */
+export const PluginStoryUpdateResult = z.object({
+  storyValue: z.number(),
+  height: z.number(),
+})
+
+export type PluginStoryUpdateResult = z.infer<typeof PluginStoryUpdateResult>

package/src/api/index.ts

@@ -0,0 +1,37 @@
+import { PluginCoreApi } from "./core"
+import { PluginDesignApi } from "./design"
+import { PluginEntityApi } from "./entity"
+import { PluginProgramApi } from "./program"
+import { PluginPresentationApi } from "./presentation"
+
+/**
+ * Root API surface for Snaptrude plugins.
+ *
+ * Access all plugin capabilities through the namespaced properties:
+ *
+ * - {@linkcode PluginApi.core} — Math, geometry kernel, history, units, zoom, project, comments (infrastructure)
+ * - {@linkcode PluginApi.design} — Author, query & edit BIM geometry
+ * - {@linkcode PluginApi.entity} — CRUD operations on Snaptrude entities (spaces, stories)
+ * - {@linkcode PluginApi.program} — Program-mode planning reads (departments, metrics)
+ * - {@linkcode PluginApi.presentation} — Presentation preparation (views, AI Inspiration)
+ */
+export abstract class PluginApi {
+  /** Core math, geometry, history, and units primitives. See {@linkcode PluginCoreApi}. */
+  public abstract core: PluginCoreApi
+  /** Author, query & edit BIM geometry. See {@linkcode PluginDesignApi}. */
+  public abstract design: PluginDesignApi
+  /** CRUD operations on Snaptrude entities. See {@linkcode PluginEntityApi}. */
+  public abstract entity: PluginEntityApi
+  /** Program-mode planning reads — departments and area metrics. See {@linkcode PluginProgramApi}. */
+  public abstract program: PluginProgramApi
+  /** Presentation preparation reads — saved views. See {@linkcode PluginPresentationApi}. */
+  public abstract presentation: PluginPresentationApi
+
+  constructor() {}
+}
+
+export * from "./core"
+export * from "./design"
+export * from "./entity"
+export * from "./program"
+export * from "./presentation"