@snaptrude/plugin-core 0.0.6 → 0.0.7

package/src/api/entity/referenceLine.ts

@@ -0,0 +1,215 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+import { PProfile } from "../core/geom/profile"
+import { PCurve } from "../core/geom/curve"
+
+/**
+ * Reference line management — create, query, and delete reference lines.
+ *
+ * A **reference line** is a 2D guide line (or arc) in the Snaptrude scene,
+ * typically used for grid lines and alignment guides. Reference lines
+ * carry properties such as grid tags, labels, and line styles.
+ *
+ * All methods are **host API calls** that return Promises and support
+ * undo/redo via Snaptrude's command system.
+ *
+ * Accessed via `snaptrude.entity.referenceLine`.
+ */
+export abstract class PluginReferenceLineApi {
+  constructor() {}
+
+  /**
+   * Create multiple reference lines from a profile.
+   *
+   * Each {@linkcode PCurve} in the given {@linkcode PProfile} becomes
+   * a separate reference line. Uses `ReferenceLineConstructor.createFromProfile`
+   * internally.
+   *
+   * @param args - An object containing:
+   *   - {@linkcode PluginReferenceLineCreateMultiArgs.profile args.profile} — A
+   *     {@linkcode PProfile} whose curves define the reference lines to create
+   * @returns A {@linkcode PluginReferenceLineCreateMultiResult} with the
+   *   `referenceLineIds` of the created reference lines
+   * @throws If reference line creation fails
+   *
+   * # Example
+   * ```ts
+   * const { vec3 } = snaptrude.core.math
+   *
+   * const l1 = snaptrude.core.geom.line.new(vec3.new(0, 0, 0), vec3.new(10, 0, 0))
+   * const l2 = snaptrude.core.geom.line.new(vec3.new(10, 0, 0), vec3.new(10, 0, 10))
+   * const profile = snaptrude.core.geom.profile.new([l1, l2])
+   *
+   * const { referenceLineIds } = await snaptrude.entity.referenceLine.createMulti({
+   *   profile,
+   * })
+   * ```
+   */
+  public abstract createMulti(
+    args: PluginReferenceLineCreateMultiArgs
+  ): PluginApiReturn<PluginReferenceLineCreateMultiResult>
+
+  /**
+   * Get properties of a reference line by its ID.
+   *
+   * Only the properties listed in {@linkcode PluginReferenceLineGetArgs.properties
+   * args.properties} are returned — unlisted properties will be `undefined`
+   * in the result.
+   *
+   * @param args - An object containing:
+   *   - {@linkcode PluginReferenceLineGetArgs.referenceLineId args.referenceLineId} —
+   *     The unique reference line ID
+   *   - {@linkcode PluginReferenceLineGetArgs.properties args.properties} — Array of
+   *     property names to retrieve. See {@linkcode PluginReferenceLineGetProperty}.
+   * @returns A partial {@linkcode PluginReferenceLineGetResult} containing only the
+   *   requested properties
+   * @throws If the reference line does not exist
+   *
+   * # Example
+   * ```ts
+   * const result = await snaptrude.entity.referenceLine.get({
+   *   referenceLineId: "some-ref-line-id",
+   *   properties: ["curve"],
+   * })
+   * console.log(result.curve) // PCurve
+   * ```
+   */
+  public abstract get(
+    args: PluginReferenceLineGetArgs
+  ): PluginApiReturn<PluginReferenceLineGetResult>
+
+  /**
+   * Get the IDs of all reference lines in the current project.
+   *
+   * Returns every reference line across all stories.
+   * Use the returned IDs with {@linkcode PluginReferenceLineApi.get} to query
+   * individual reference line properties.
+   *
+   * @returns A {@linkcode PluginReferenceLineGetAllResult} with a
+   *   `referenceLineIds` array
+   *
+   * # Example
+   * ```ts
+   * const { referenceLineIds } = await snaptrude.entity.referenceLine.getAll()
+   * console.log(`Project has ${referenceLineIds.length} reference lines`)
+   * ```
+   */
+  public abstract getAll(): PluginApiReturn<PluginReferenceLineGetAllResult>
+
+  /**
+   * Delete a reference line by its ID.
+   *
+   * Permanently removes the reference line and its associated mesh from
+   * the scene. This operation is undoable via Snaptrude's command system.
+   *
+   * @param args - An object containing:
+   *   - {@linkcode PluginReferenceLineDeleteArgs.referenceLineId args.referenceLineId} —
+   *     The unique reference line ID to delete
+   * @throws If the reference line does not exist
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.entity.referenceLine.delete({
+   *   referenceLineId: "some-ref-line-id",
+   * })
+   * ```
+   */
+  public abstract delete(
+    args: PluginReferenceLineDeleteArgs
+  ): PluginApiReturn<PluginReferenceLineDeleteResult>
+}
+
+/**
+ * Arguments for {@linkcode PluginReferenceLineApi.createMulti}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `profile` | {@linkcode PProfile} | Profile whose curves define reference lines |
+ */
+export const PluginReferenceLineCreateMultiArgs = z.object({
+  profile: PProfile,
+})
+
+export type PluginReferenceLineCreateMultiArgs = z.infer<typeof PluginReferenceLineCreateMultiArgs>
+
+/**
+ * Result of {@linkcode PluginReferenceLineApi.createMulti}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `referenceLineIds` | `string[]` | IDs of the created reference lines |
+ */
+export const PluginReferenceLineCreateMultiResult = z.object({
+  referenceLineIds: z.array(z.string()),
+})
+
+export type PluginReferenceLineCreateMultiResult = z.infer<typeof PluginReferenceLineCreateMultiResult>
+
+/**
+ * Available properties that can be queried on a reference line.
+ *
+ * | Value | Return Type | Description |
+ * |---|---|---|
+ * | `"curve"` | {@linkcode PCurve} | The curve geometry of the reference line |
+ */
+export const PluginReferenceLineGetProperty = z.enum([
+  "curve",
+])
+
+/**
+ * Arguments for {@linkcode PluginReferenceLineApi.get}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `referenceLineId` | `string` | The reference line ID to query |
+ * | `properties` | {@linkcode PluginReferenceLineGetProperty}`[]` | Properties to retrieve |
+ */
+export const PluginReferenceLineGetArgs = z.object({
+  referenceLineId: z.string(),
+  properties: z.array(PluginReferenceLineGetProperty),
+})
+
+export type PluginReferenceLineGetArgs = z.infer<typeof PluginReferenceLineGetArgs>
+
+/**
+ * Result of {@linkcode PluginReferenceLineApi.get}.
+ *
+ * A partial object — only the properties that were requested in
+ * {@linkcode PluginReferenceLineGetArgs.properties} will be present.
+ */
+export const PluginReferenceLineGetResult = z
+  .object({
+    curve: PCurve,
+  })
+  .partial()
+
+export type PluginReferenceLineGetResult = z.infer<typeof PluginReferenceLineGetResult>
+
+/**
+ * Result of {@linkcode PluginReferenceLineApi.getAll}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `referenceLineIds` | `string[]` | IDs of all reference lines in the project |
+ */
+export const PluginReferenceLineGetAllResult = z.object({
+  referenceLineIds: z.array(z.string()),
+})
+
+export type PluginReferenceLineGetAllResult = z.infer<typeof PluginReferenceLineGetAllResult>
+
+/**
+ * Arguments for {@linkcode PluginReferenceLineApi.delete}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `referenceLineId` | `string` | The reference line ID to delete |
+ */
+export const PluginReferenceLineDeleteArgs = z.object({
+  referenceLineId: z.string(),
+})
+
+export type PluginReferenceLineDeleteArgs = z.infer<typeof PluginReferenceLineDeleteArgs>
+
+/** Result type for {@linkcode PluginReferenceLineApi.delete} — returns nothing on success. */
+export type PluginReferenceLineDeleteResult = void

package/src/api/entity/space.ts

@@ -165,6 +165,38 @@ export abstract class PluginSpaceApi {
   public abstract delete({
     spaceId,
   }: PluginSpaceDeleteArgs): PluginApiReturn<PluginSpaceDeleteResult>
+
+  /**
+   * Update properties of a space by its ID.
+   *
+   * Only the properties provided in {@linkcode PluginSpaceUpdateArgs.properties
+   * args.properties} will be updated — omitted properties remain unchanged.
+   * This operation is undoable via Snaptrude's command system.
+   *
+   * @param args - An object containing:
+   *   - {@linkcode PluginSpaceUpdateArgs.spaceId args.spaceId} — The unique space ID
+   *     to update
+   *   - {@linkcode PluginSpaceUpdateArgs.properties args.properties} — Key/value pairs
+   *     of properties to update. See {@linkcode PluginSpaceUpdateArgs} for supported fields.
+   * @returns A {@linkcode PluginSpaceUpdateResult} echoing back the `spaceId` and
+   *   the updated property values
+   * @throws If the space does not exist or the component is not a space/mass
+   *
+   * # Example
+   * ```ts
+   * const result = await snaptrude.entity.space.update({
+   *   spaceId: "some-space-id",
+   *   properties: {
+   *     room_type: "Kitchen",
+   *     massType: "Room",
+   *     departmentId: "CORE",
+   *   },
+   * })
+   * ```
+   */
+  public abstract update(
+    args: PluginSpaceUpdateArgs
+  ): PluginApiReturn<PluginSpaceUpdateResult>
 }
 
 /**
@@ -184,7 +216,9 @@ export const PluginSpaceCreateRectangularArgs = z.object({
   }),
 })
 
-export type PluginSpaceCreateRectangularArgs = z.infer<typeof PluginSpaceCreateRectangularArgs>
+export type PluginSpaceCreateRectangularArgs = z.infer<
+  typeof PluginSpaceCreateRectangularArgs
+>
 
 /**
  * Result of {@linkcode PluginSpaceApi.createRectangular}.
@@ -197,7 +231,9 @@ export const PluginSpaceCreateRectangularResult = z.object({
   spaceId: z.string(),
 })
 
-export type PluginSpaceCreateRectangularResult = z.infer<typeof PluginSpaceCreateRectangularResult>
+export type PluginSpaceCreateRectangularResult = z.infer<
+  typeof PluginSpaceCreateRectangularResult
+>
 
 /**
  * Arguments for {@linkcode PluginSpaceApi.createFromProfile}.
@@ -214,7 +250,9 @@ export const PluginSpaceCreateFromProfileArgs = z.object({
   position: PVec3,
 })
 
-export type PluginSpaceCreateFromProfileArgs = z.infer<typeof PluginSpaceCreateFromProfileArgs>
+export type PluginSpaceCreateFromProfileArgs = z.infer<
+  typeof PluginSpaceCreateFromProfileArgs
+>
 
 /**
  * Result of {@linkcode PluginSpaceApi.createFromProfile}.
@@ -227,35 +265,72 @@ export const PluginSpaceCreateFromProfileResult = z.object({
   spaceId: z.string(),
 })
 
-export type PluginSpaceCreateFromProfileResult = z.infer<typeof PluginSpaceCreateFromProfileResult>
+export type PluginSpaceCreateFromProfileResult = z.infer<
+  typeof PluginSpaceCreateFromProfileResult
+>
 
 /**
  * Available properties that can be queried on a space.
  *
+ * **Basic:**
  * | Value | Return Type | Description |
  * |---|---|---|
  * | `"id"` | `string` | Unique space identifier |
  * | `"type"` | `string` | Component type |
  * | `"room_type"` | `string` | Room type classification |
  * | `"name"` | `string` | Display name of the space |
- * | `"area"` | `number` | Bottom (floor) area |
- * | `"department"` | `string` | Assigned department name |
+ *
+ * **Derived from parametric data:**
+ * | Value | Return Type | Description |
+ * |---|---|---|
+ * | `"area"` | `number` | Bottom face area (from `areas_bottomFace`) |
+ * | `"breadth"` | `number` | Breadth dimension |
+ * | `"depth"` | `number` | Depth dimension |
+ * | `"height"` | `number` | Height dimension |
+ * | `"massType"` | `string \| null` | Mass type classification |
+ * | `"spaceType"` | `string \| null` | Space type classification (Room, Balcony, etc.) |
+ * | `"storey"` | `number \| null` | Story the space belongs to |
+ * | `"departmentId"` | `string \| null` | Assigned department ID |
+ * | `"departmentName"` | `string` | Assigned department name |
+ * | `"departmentColor"` | `string` | Assigned department color (hex/CSS) |
+ *
+ * **Derived from mesh:**
+ * | Value | Return Type | Description |
+ * |---|---|---|
  * | `"position"` | {@linkcode PVec3} | Local position relative to parent |
  * | `"absolutePosition"` | {@linkcode PVec3} | Absolute position in the scene |
  * | `"rotation"` | {@linkcode PVec3} | Euler rotation angles (radians) |
  * | `"rotationQuaternion"` | {@linkcode PQuat} \| `null` | Quaternion rotation, or `null` if unset |
+ *
+ * **Derived from brep:**
+ * | Value | Return Type | Description |
+ * |---|---|---|
+ * | `"planPoints"` | {@linkcode PVec3}`[]` | Bottom outer profile points in world space with `y = 0` (2D plan). No closing duplicate point. |
  */
 export const PluginSpaceGetProperty = z.enum([
+  // Basic
   "id",
   "type",
   "room_type",
   "name",
+  // Derived from parametric data
   "area",
-  "department",
+  "breadth",
+  "depth",
+  "height",
+  "massType",
+  "spaceType",
+  "storey",
+  "departmentId",
+  "departmentName",
+  "departmentColor",
+  // Derived from mesh
   "position",
   "absolutePosition",
   "rotation",
   "rotationQuaternion",
+  // Derived from brep
+  "planPoints",
 ])
 
 /**
@@ -273,6 +348,33 @@ export const PluginSpaceGetArgs = z.object({
 
 export type PluginSpaceGetArgs = z.infer<typeof PluginSpaceGetArgs>
 
+/**
+ * Supported space type values.
+ *
+ * Mirrors the internal `SpaceType` enum from `spaceType.types.ts`.
+ *
+ * | Value | Description |
+ * |---|---|
+ * | `"Room"` | Standard room |
+ * | `"Program Block"` | Program/department block |
+ * | `"Balcony"` | Balcony space |
+ * | `"Road"` | Road |
+ * | `"Garden"` | Garden area |
+ * | `"Deck"` | Deck |
+ * | `"Pool"` | Pool |
+ * | `"Walkway"` | Walkway |
+ */
+export const PluginSpaceType = z.enum([
+  "Room",
+  "Program Block",
+  "Balcony",
+  "Road",
+  "Garden",
+  "Deck",
+  "Pool",
+  "Walkway",
+])
+
 /**
  * Result of {@linkcode PluginSpaceApi.get}.
  *
@@ -281,16 +383,29 @@ export type PluginSpaceGetArgs = z.infer<typeof PluginSpaceGetArgs>
  */
 export const PluginSpaceGetResult = z
   .object({
+    // Basic
     id: z.string(),
     type: z.string(),
     room_type: z.string(),
     name: z.string(),
+    // Derived from parametric data
     area: z.number(),
-    department: z.string(),
+    breadth: z.number(),
+    depth: z.number(),
+    height: z.number(),
+    massType: z.string().nullable(),
+    spaceType: PluginSpaceType.nullable(),
+    storey: z.number().nullable(),
+    departmentId: z.string().nullable(),
+    departmentName: z.string(),
+    departmentColor: z.string(),
+    // Derived from mesh
     position: PVec3,
     absolutePosition: PVec3,
     rotation: PVec3,
     rotationQuaternion: PQuat.nullable(),
+    // Derived from brep
+    planPoints: z.array(PVec3),
   })
   .partial()
 
@@ -324,3 +439,111 @@ export type PluginSpaceDeleteArgs = z.infer<typeof PluginSpaceDeleteArgs>
 
 /** Result type for {@linkcode PluginSpaceApi.delete} — returns nothing on success. */
 export type PluginSpaceDeleteResult = void
+
+/**
+ * Supported mass type values for {@linkcode PluginSpaceUpdateArgs.properties.massType}.
+ *
+ * Mirrors the internal `MASS_TYPES` enum.
+ *
+ * | Value | Description |
+ * |---|---|
+ * | `"Plinth"` | Plinth mass |
+ * | `"Void"` | Void/cut-out |
+ * | `"Pergola"` | Pergola structure |
+ * | `"Furniture"` | Furniture element |
+ * | `"Facade element"` | Facade element |
+ * | `"Generic mass"` | Generic mass |
+ * | `"Room"` | Room (default for spaces) |
+ * | `"Department"` | Department block |
+ * | `"Building"` | Building envelope |
+ * | `"Revit Import"` | Imported from Revit |
+ * | `"Mass"` | Generic mass type |
+ * | `"Site"` | Site object |
+ */
+export const PluginMassType = z.enum([
+  "Plinth",
+  "Void",
+  "Pergola",
+  "Furniture",
+  "Facade element",
+  "Generic mass",
+  "Room",
+  "Department",
+  "Building",
+  "Revit Import",
+  "Mass",
+  "Site",
+])
+
+/**
+ * Well-known (built-in) department IDs.
+ *
+ * | Value | Department |
+ * |---|---|
+ * | `"DEFAULT"` | Default department |
+ * | `"SITE"` | Site department |
+ * | `"ENVELOPE"` | Envelope department |
+ * | `"CORE"` | Core department |
+ */
+export const PluginWellKnownDepartmentId = z.enum([
+  "DEFAULT",
+  "SITE",
+  "ENVELOPE",
+  "CORE",
+])
+
+/**
+ * Accepted department ID values — either a {@linkcode PluginWellKnownDepartmentId}
+ * or a UUID string for custom (user-created) departments.
+ */
+export const PluginDepartmentId = z.union([
+  PluginWellKnownDepartmentId,
+  z.uuid(),
+])
+
+/**
+ * Arguments for {@linkcode PluginSpaceApi.update}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `spaceId` | `string` | The space ID to update |
+ * | `properties` | `object` | Key/value pairs of properties to update (all optional) |
+ * | `properties.room_type` | `string?` | New room type label |
+ * | `properties.massType` | {@linkcode PluginMassType}`?` | New mass type |
+ * | `properties.departmentId` | {@linkcode PluginDepartmentId}`?` | New department ID |
+ */
+export const PluginSpaceUpdateArgs = z.object({
+  spaceId: z.string(),
+  properties: z.object({
+    room_type: z.string().optional(),
+    massType: PluginMassType.optional(),
+    spaceType: PluginSpaceType.optional(),
+    departmentId: PluginDepartmentId.optional(),
+  }),
+})
+
+export type PluginSpaceUpdateArgs = z.infer<typeof PluginSpaceUpdateArgs>
+
+/**
+ * Result of {@linkcode PluginSpaceApi.update}.
+ *
+ * Echoes back the `spaceId` and the values of properties that were updated.
+ * Properties that were not included in the update request will be `undefined`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `spaceId` | `string` | The space ID that was updated |
+ * | `room_type` | `string?` | Updated room type (if changed) |
+ * | `massType` | `string?` | Updated mass type (if changed) |
+ * | `spaceType` | `string?` | Updated space type (if changed) |
+ * | `departmentId` | `string \| null?` | Updated department ID (if changed) |
+ */
+export const PluginSpaceUpdateResult = z.object({
+  spaceId: z.string(),
+  room_type: z.string().optional(),
+  massType: z.string().optional(),
+  spaceType: z.string().optional(),
+  departmentId: z.string().nullable().optional(),
+})
+
+export type PluginSpaceUpdateResult = z.infer<typeof PluginSpaceUpdateResult>

package/src/api/units/index.ts

@@ -25,6 +25,8 @@ export abstract class PluginUnitsApi {
    *     to convert from. See {@linkcode PUnitType} for supported values.
    *   - {@linkcode PluginUnitsConvertFromArgs.value args.value} — The numeric
    *     value in the source unit
+   *   - {@linkcode PluginUnitsConvertFromArgs.degree args.degree} — (Optional)
+   *     Degree of the unit: 1 for length, 2 for area, 3 for volume. Defaults to 1
    * @returns A {@linkcode PluginUnitsConvertFromResult} containing the converted
    *   `value` in Babylon units
    *
@@ -53,6 +55,8 @@ export abstract class PluginUnitsApi {
    *     to convert to. See {@linkcode PUnitType} for supported values.
    *   - {@linkcode PluginUnitsConvertToArgs.value args.value} — The numeric
    *     value in Babylon units
+   *   - {@linkcode PluginUnitsConvertToArgs.degree args.degree} — (Optional)
+   *     Degree of the unit: 1 for length, 2 for area, 3 for volume. Defaults to 1
    * @returns A {@linkcode PluginUnitsConvertToResult} containing the converted
    *   `value` in the target unit
    *
@@ -66,6 +70,7 @@ export abstract class PluginUnitsApi {
    * const areaInMeters = await snaptrude.units.convertTo({
    *   unit: "meters",
    *   value: info.area!,
+   *   degree: 2,
    * })
    * ```
    */
@@ -104,10 +109,12 @@ export type PUnitType = z.infer<typeof PUnitType>
  * |---|---|---|
  * | `unit` | {@linkcode PUnitType} | Source real-world unit |
  * | `value` | `number` | Numeric value in the source unit |
+ * | `degree` | `1 \| 2 \| 3` | (Optional) Degree of the unit (e.g. 1 for length, 2 for area, 3 for volume). Defaults to 1 |
  */
 export const PluginUnitsConvertFromArgs = z.object({
   unit: PUnitType,
   value: z.number(),
+  degree: z.number().int().min(1).max(3).optional(),
 })
 
 export type PluginUnitsConvertFromArgs = z.infer<typeof PluginUnitsConvertFromArgs>
@@ -132,10 +139,12 @@ export type PluginUnitsConvertFromResult = z.infer<typeof PluginUnitsConvertFrom
  * |---|---|---|
  * | `unit` | {@linkcode PUnitType} | Target real-world unit |
  * | `value` | `number` | Numeric value in Babylon units |
+ * | `degree` | `1 \| 2 \| 3` | (Optional) Degree of the unit (e.g. 1 for length, 2 for area, 3 for volume). Defaults to 1 |
  */
 export const PluginUnitsConvertToArgs = z.object({
   unit: PUnitType,
   value: z.number(),
+  degree: z.number().int().min(1).max(3).optional(),
 })
 
 export type PluginUnitsConvertToArgs = z.infer<typeof PluginUnitsConvertToArgs>

package/tsup.config.ts

@@ -6,7 +6,6 @@ export default defineConfig( (options) => {
     format: ["cjs", "esm"],
     dts: false,
     sourcemap: true,
-    clean: true,
     onSuccess: "tsc", // Run tsc to generate d.ts and d.ts.map
     watch: options.watch,
   }