@snaptrude/plugin-core 0.0.0-bimsvg-20260928124803

package/src/api/program/classification.ts

@@ -0,0 +1,138 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+
+/**
+ * Program classification — the catalog of space-classification options, and a
+ * space's display tags.
+ *
+ * Only the genuinely program-specific reads live here: the selectable
+ * space-type / area-class / mass-type options, and a space's tags for display.
+ * Reading or changing a *single space's* classification (its type, label, area
+ * class, or department) is done through the space reads/writes, not duplicated
+ * here. Tag definitions are managed elsewhere — these methods are display-only.
+ *
+ * Both methods are reads.
+ *
+ * Accessed via `snaptrude.program.classification`.
+ */
+export abstract class PluginProgramClassificationApi {
+  constructor() {}
+
+  /**
+   * List the selectable classification options for spaces.
+   *
+   * The static catalog (project-independent) of space types, area classes, and
+   * mass types a space can be classified as.
+   *
+   * @returns A {@linkcode PluginProgramClassificationTypesResult} with the
+   *   `spaceTypes`, `areaClasses`, and `massTypes` option lists.
+   *
+   * @examplePrompt What space types can I assign?
+   * @examplePrompt List the available area classifications
+   * @examplePrompt What classification options exist?
+   * @examplePrompt Show me the valid space-type values
+   *
+   * # Example
+   * ```ts
+   * const { spaceTypes, areaClasses } = await snaptrude.program.classification.listTypes()
+   * ```
+   */
+  public abstract listTypes(): PluginApiReturn<PluginProgramClassificationTypesResult>
+
+  /**
+   * List a space's tags for display, grouped by category.
+   *
+   * @param id - The id of the space whose tags to read.
+   * @returns A {@linkcode PluginProgramClassificationTagsResult} with the space's
+   *   `tagIds` and `tagsByCategory`.
+   *
+   * @examplePrompt What tags are on this space?
+   * @examplePrompt Show the tags grouped by category for sp_4
+   * @examplePrompt List this room's display tags
+   * @examplePrompt Which tags does this space have?
+   *
+   * # Example
+   * ```ts
+   * const { tagsByCategory } = await snaptrude.program.classification.listTags("sp_4")
+   * ```
+   */
+  public abstract listTags(
+    id: string,
+  ): PluginApiReturn<PluginProgramClassificationTagsResult>
+}
+
+/**
+ * A selectable classification option.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `value` | `string` | Stored value |
+ * | `label` | `string` | Display label |
+ */
+export const PluginClassificationOption = z.object({
+  value: z.string(),
+  label: z.string(),
+})
+export type PluginClassificationOption = z.infer<
+  typeof PluginClassificationOption
+>
+
+/**
+ * Result of {@linkcode PluginProgramClassificationApi.listTypes}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `spaceTypes` | {@linkcode PluginClassificationOption}`[]` | Selectable space types |
+ * | `areaClasses` | {@linkcode PluginClassificationOption}`[]` | Selectable area classes (NET/GROSS/EXCLUDED) |
+ * | `massTypes` | {@linkcode PluginClassificationOption}`[]` | Selectable mass/object types |
+ */
+export const PluginProgramClassificationTypesResult = z.object({
+  spaceTypes: z.array(PluginClassificationOption),
+  areaClasses: z.array(PluginClassificationOption),
+  massTypes: z.array(PluginClassificationOption),
+})
+export type PluginProgramClassificationTypesResult = z.infer<
+  typeof PluginProgramClassificationTypesResult
+>
+
+/** Arguments for {@linkcode PluginProgramClassificationApi.listTags}. */
+export const PluginProgramClassificationListTagsArgs = z.object({
+  id: z.string(),
+})
+export type PluginProgramClassificationListTagsArgs = z.infer<
+  typeof PluginProgramClassificationListTagsArgs
+>
+
+/**
+ * A display tag on a space.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `tagId` | `string` | Tag id |
+ * | `tagName` | `string` | Tag display name |
+ * | `color` | `string` | CSS hex color string |
+ * | `categoryId` | `string` | Id of the tag's category |
+ */
+export const PluginSpaceTag = z.object({
+  tagId: z.string(),
+  tagName: z.string(),
+  color: z.string(),
+  categoryId: z.string(),
+})
+export type PluginSpaceTag = z.infer<typeof PluginSpaceTag>
+
+/**
+ * Result of {@linkcode PluginProgramClassificationApi.listTags}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `tagIds` | `string[]` | All tag ids on the space |
+ * | `tagsByCategory` | `Record<string, `{@linkcode PluginSpaceTag}`>` | Tags keyed by category name |
+ */
+export const PluginProgramClassificationTagsResult = z.object({
+  tagIds: z.array(z.string()),
+  tagsByCategory: z.record(z.string(), PluginSpaceTag),
+})
+export type PluginProgramClassificationTagsResult = z.infer<
+  typeof PluginProgramClassificationTagsResult
+>

package/src/api/program/cores.ts

@@ -0,0 +1,83 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+
+/**
+ * Program cores — the building's vertical-circulation cores (lift / stair / shaft
+ * shells).
+ *
+ * Read the cores in the scene and test whether a space is a core. Both are reads;
+ * there is no core-generation trigger on this surface (core geometry is owned by
+ * the geometry layer, not here).
+ *
+ * Accessed via `snaptrude.program.cores`.
+ */
+export abstract class PluginProgramCoresApi {
+  constructor() {}
+
+  /**
+   * List the cores currently in the building.
+   *
+   * @returns A {@linkcode PluginProgramCoresListResult} with each core's id,
+   *   core group, and storey (empty when there are none).
+   *
+   * @examplePrompt List the cores in the building
+   * @examplePrompt How many cores are placed?
+   * @examplePrompt Show me the lift and stair cores
+   * @examplePrompt Which storeys have cores?
+   *
+   * # Example
+   * ```ts
+   * const { cores } = await snaptrude.program.cores.list()
+   * ```
+   */
+  public abstract list(): PluginApiReturn<PluginProgramCoresListResult>
+
+  /**
+   * Test whether a space is a circulation core element.
+   *
+   * @param id - The id of the space to test.
+   * @returns `true` if the space is a core element.
+   *
+   * @examplePrompt Is this space a core?
+   * @examplePrompt Does this mass belong to the core?
+   * @examplePrompt Check if space sp_1 is a circulation core
+   *
+   * # Example
+   * ```ts
+   * const isCore = await snaptrude.program.cores.isCore("sp_1")
+   * ```
+   */
+  public abstract isCore(id: string): PluginApiReturn<boolean>
+}
+
+/**
+ * A circulation core element in the building.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Component id of the core element |
+ * | `groupId` | `string` | Id of the core group this element belongs to |
+ * | `storey` | `number` | Storey (floor number) the element sits on |
+ */
+export const PluginProgramCore = z.object({
+  id: z.string(),
+  groupId: z.string(),
+  storey: z.number(),
+})
+export type PluginProgramCore = z.infer<typeof PluginProgramCore>
+
+/** Result of {@linkcode PluginProgramCoresApi.list}. */
+export const PluginProgramCoresListResult = z.object({
+  cores: z.array(PluginProgramCore),
+})
+export type PluginProgramCoresListResult = z.infer<
+  typeof PluginProgramCoresListResult
+>
+
+/** Arguments for {@linkcode PluginProgramCoresApi.isCore}. */
+export const PluginProgramCoresIsCoreArgs = z.object({
+  id: z.string(),
+})
+export type PluginProgramCoresIsCoreArgs = z.infer<
+  typeof PluginProgramCoresIsCoreArgs
+>