@snaptrude/plugin-core 0.2.1 → 0.2.3

package/src/api/entity/buildableEnvelope.ts

@@ -0,0 +1,277 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+
+/**
+ * Buildable Envelope management — create and update parametric zoning envelopes.
+ *
+ * A **buildable envelope** is the regulated volume inside which a building may
+ * be massed. The host owns envelope identity: {@linkcode PluginBuildableEnvelopeApi.create create}
+ * mints a `buildableEnvelopeId` and returns it; {@linkcode PluginBuildableEnvelopeApi.update update}
+ * requires that id to target the existing envelope.
+ *
+ * Accessed via `snaptrude.entity.buildableEnvelope`.
+ */
+export abstract class PluginBuildableEnvelopeApi {
+  constructor() {}
+
+  /**
+   * Create a new parametric buildable envelope.
+   *
+   * @param args - A {@linkcode PluginBuildableEnvelopeCreateArgs} object.
+   * @returns A {@linkcode PluginBuildableEnvelopeCreateResult} with the
+   *   `buildableEnvelopeId` of the created envelope.
+   * @throws If validation fails or generation produces no renderable geometry.
+   *
+   * # Example
+   * ```ts
+   * const { buildableEnvelopeId } = await snaptrude.entity.buildableEnvelope.create({
+   *   sitePolygon: [
+   *     { x: 0, z: 0 },
+   *     { x: 100, z: 0 },
+   *     { x: 100, z: 80 },
+   *     { x: 0, z: 80 },
+   *   ],
+   *   lengthUnit: "ft",
+   *   setbacks: [
+   *     { aboveHeight: 0, front: 10, side: 5, rear: 10 },
+   *     { aboveHeight: 100, front: 20, side: 10, rear: 20 },
+   *   ],
+   *   verticalCap: { kind: "max_height", maxHeight: 150 },
+   *   floorToFloor: 12,
+   * })
+   * ```
+   */
+  public abstract create(
+    args: PluginBuildableEnvelopeCreateArgs
+  ): PluginApiReturn<PluginBuildableEnvelopeCreateResult>
+
+  /**
+   * Update an existing parametric buildable envelope.
+   *
+   * @param args - A {@linkcode PluginBuildableEnvelopeUpdateArgs} object.
+   *   `buildableEnvelopeId` is required and must match an existing envelope on
+   *   the canvas.
+   * @returns A {@linkcode PluginBuildableEnvelopeUpdateResult} with the
+   *   `buildableEnvelopeId` of the updated envelope.
+   * @throws If validation fails, the envelope does not exist, or generation
+   *   produces no renderable geometry.
+   *
+   * # Example
+   * ```ts
+   * const { buildableEnvelopeId } = await snaptrude.entity.buildableEnvelope.update({
+   *   buildableEnvelopeId: existingId,
+   *   sitePolygon: [
+   *     { x: 0, z: 0 },
+   *     { x: 100, z: 0 },
+   *     { x: 100, z: 80 },
+   *     { x: 0, z: 80 },
+   *   ],
+   *   lengthUnit: "ft",
+   *   setbacks: [{ aboveHeight: 0, front: 10, side: 5, rear: 10 }],
+   *   verticalCap: { kind: "max_height", maxHeight: 175 },
+   *   floorToFloor: 12,
+   * })
+   * ```
+   */
+  public abstract update(
+    args: PluginBuildableEnvelopeUpdateArgs
+  ): PluginApiReturn<PluginBuildableEnvelopeUpdateResult>
+}
+
+/**
+ * Site polygon vertex in the request `lengthUnit`.
+ *
+ * Vertices may be passed as `{x, z}` objects or `[x, z]` tuples. Numeric
+ * values must be finite (no `NaN` or `±Infinity`).
+ */
+export const PluginBuildableEnvelopePolygonVertex = z.union([
+  z.object({ x: z.number().finite(), z: z.number().finite() }).strict(),
+  z.tuple([z.number().finite(), z.number().finite()]),
+])
+
+export type PluginBuildableEnvelopePolygonVertex = z.infer<
+  typeof PluginBuildableEnvelopePolygonVertex
+>
+
+/**
+ * Vertical cap for a buildable envelope.
+ *
+ * Use exactly one shape:
+ * - `{ kind: "max_height", maxHeight }`
+ * - `{ kind: "max_floors", maxFloors }`
+ *
+ * Floor-to-floor height is not nested here; it is always supplied as the
+ * top-level `floorToFloor` argument.
+ */
+export const PluginBuildableEnvelopeVerticalCap = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("max_height"),
+    maxHeight: z.number().finite().positive(),
+  }).strict(),
+  z.object({
+    kind: z.literal("max_floors"),
+    maxFloors: z.number().finite().int().positive(),
+  }).strict(),
+])
+
+export type PluginBuildableEnvelopeVerticalCap = z.infer<
+  typeof PluginBuildableEnvelopeVerticalCap
+>
+
+/**
+ * One tier of a buildable envelope's setback profile.
+ *
+ * Tiers are ordered by `aboveHeight`. The first tier (index 0) must have
+ * `aboveHeight: 0` and describes the ground footprint; each subsequent tier
+ * describes the complete setback at a strictly greater height. Each tier
+ * carries its own `front`, `side`, and `rear` values — there is no
+ * inheritance from earlier tiers.
+ *
+ * All numeric values must be finite and nonnegative, in the request
+ * `lengthUnit`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `aboveHeight` | `number` | Height at or above which this tier applies; the ground tier uses `0` |
+ * | `front` | `number` | Front setback for this tier |
+ * | `side` | `number` | Side setback for this tier |
+ * | `rear` | `number` | Rear setback for this tier |
+ */
+export const PluginBuildableEnvelopeSetbackTier = z.object({
+  aboveHeight: z.number().finite().nonnegative(),
+  front: z.number().finite().nonnegative(),
+  side: z.number().finite().nonnegative(),
+  rear: z.number().finite().nonnegative(),
+}).strict()
+
+export type PluginBuildableEnvelopeSetbackTier = z.infer<
+  typeof PluginBuildableEnvelopeSetbackTier
+>
+
+// Enforces setback tier ordering invariants on the parsed args shape:
+//   - setbacks[0].aboveHeight === 0
+//   - aboveHeight strictly increasing thereafter
+// Length >= 1 is enforced earlier by z.array(...).min(1).
+function refineSetbackTiers(
+  args: { setbacks: PluginBuildableEnvelopeSetbackTier[] },
+  ctx: z.RefinementCtx
+): void {
+  const tiers = args.setbacks
+  if (tiers.length === 0) return
+  if (tiers[0].aboveHeight !== 0) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["setbacks", 0, "aboveHeight"],
+      message: "Ground tier required: setbacks[0].aboveHeight must be 0.",
+    })
+  }
+  for (let i = 1; i < tiers.length; i++) {
+    if (!(tiers[i].aboveHeight > tiers[i - 1].aboveHeight)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["setbacks", i, "aboveHeight"],
+        message:
+          "Setback tiers must be ordered by strictly increasing aboveHeight.",
+      })
+    }
+  }
+}
+
+/**
+ * Arguments for {@linkcode PluginBuildableEnvelopeApi.create}.
+ *
+ * Strict schema. The host owns identity — no `buildableEnvelopeId` is accepted
+ * on create; the id is minted by the host and returned in
+ * {@linkcode PluginBuildableEnvelopeCreateResult}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sitePolygon` | {@linkcode PluginBuildableEnvelopePolygonVertex}`[]` | Site polygon vertices in `lengthUnit`; minimum 3 vertices |
+ * | `lengthUnit` | `"ft" \| "m"` | Unit used by all length fields |
+ * | `setbacks` | {@linkcode PluginBuildableEnvelopeSetbackTier}`[]` | Setback profile, ground tier first; minimum 1 tier |
+ * | `verticalCap` | {@linkcode PluginBuildableEnvelopeVerticalCap} | Maximum height or floor count |
+ * | `floorToFloor` | `number` | Required floor-to-floor height in `lengthUnit` |
+ * | `farRatio` | `number?` | Optional FAR value, positive when provided |
+ * | `lotCoverageMaxPct` | `number?` | Optional lot coverage cap, `0..100` |
+ */
+export const PluginBuildableEnvelopeCreateArgs = z
+  .object({
+    sitePolygon: z.array(PluginBuildableEnvelopePolygonVertex).min(3),
+    lengthUnit: z.union([z.literal("ft"), z.literal("m")]),
+    setbacks: z.array(PluginBuildableEnvelopeSetbackTier).min(1),
+    verticalCap: PluginBuildableEnvelopeVerticalCap,
+    floorToFloor: z.number().finite().positive(),
+    farRatio: z.number().finite().positive().optional(),
+    lotCoverageMaxPct: z.number().finite().min(0).max(100).optional(),
+  })
+  .strict()
+  .superRefine(refineSetbackTiers)
+
+export type PluginBuildableEnvelopeCreateArgs = z.infer<
+  typeof PluginBuildableEnvelopeCreateArgs
+>
+
+/**
+ * Result of {@linkcode PluginBuildableEnvelopeApi.create}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildableEnvelopeId` | `string` | Non-empty unique ID of the created buildable envelope |
+ */
+export const PluginBuildableEnvelopeCreateResult = z.object({
+  buildableEnvelopeId: z.string().min(1),
+}).strict()
+
+export type PluginBuildableEnvelopeCreateResult = z.infer<
+  typeof PluginBuildableEnvelopeCreateResult
+>
+
+/**
+ * Arguments for {@linkcode PluginBuildableEnvelopeApi.update}.
+ *
+ * Strict schema. `buildableEnvelopeId` is required and identifies the prior
+ * envelope on the canvas to update.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildableEnvelopeId` | `string` | Existing envelope ID to update; non-empty |
+ * | `sitePolygon` | {@linkcode PluginBuildableEnvelopePolygonVertex}`[]` | Site polygon vertices in `lengthUnit`; minimum 3 vertices |
+ * | `lengthUnit` | `"ft" \| "m"` | Unit used by all length fields |
+ * | `setbacks` | {@linkcode PluginBuildableEnvelopeSetbackTier}`[]` | Setback profile, ground tier first; minimum 1 tier |
+ * | `verticalCap` | {@linkcode PluginBuildableEnvelopeVerticalCap} | Maximum height or floor count |
+ * | `floorToFloor` | `number` | Required floor-to-floor height in `lengthUnit` |
+ * | `farRatio` | `number?` | Optional FAR value, positive when provided |
+ * | `lotCoverageMaxPct` | `number?` | Optional lot coverage cap, `0..100` |
+ */
+export const PluginBuildableEnvelopeUpdateArgs = z
+  .object({
+    buildableEnvelopeId: z.string().min(1),
+    sitePolygon: z.array(PluginBuildableEnvelopePolygonVertex).min(3),
+    lengthUnit: z.union([z.literal("ft"), z.literal("m")]),
+    setbacks: z.array(PluginBuildableEnvelopeSetbackTier).min(1),
+    verticalCap: PluginBuildableEnvelopeVerticalCap,
+    floorToFloor: z.number().finite().positive(),
+    farRatio: z.number().finite().positive().optional(),
+    lotCoverageMaxPct: z.number().finite().min(0).max(100).optional(),
+  })
+  .strict()
+  .superRefine(refineSetbackTiers)
+
+export type PluginBuildableEnvelopeUpdateArgs = z.infer<
+  typeof PluginBuildableEnvelopeUpdateArgs
+>
+
+/**
+ * Result of {@linkcode PluginBuildableEnvelopeApi.update}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildableEnvelopeId` | `string` | Non-empty unique ID of the updated buildable envelope |
+ */
+export const PluginBuildableEnvelopeUpdateResult = z.object({
+  buildableEnvelopeId: z.string().min(1),
+}).strict()
+
+export type PluginBuildableEnvelopeUpdateResult = z.infer<
+  typeof PluginBuildableEnvelopeUpdateResult
+>

package/src/api/entity/index.ts

@@ -1,3 +1,4 @@
+import { PluginBuildableEnvelopeApi } from "./buildableEnvelope"
 import { PluginDepartmentApi } from "./department"
 import { PluginReferenceLineApi } from "./referenceLine"
 import { PluginSpaceApi } from "./space"
@@ -10,6 +11,7 @@ import { PluginStoryApi } from "./story"
  * - {@linkcode PluginEntityApi.story} — Create, query, and update stories (floors)
  * - {@linkcode PluginEntityApi.referenceLine} — Create, query, and delete reference lines
  * - {@linkcode PluginEntityApi.department} — Create and query departments
+ * - {@linkcode PluginEntityApi.buildableEnvelope} — Create or update parametric buildable envelopes
  */
 export abstract class PluginEntityApi {
   /** Space (room/mass) operations. See {@linkcode PluginSpaceApi}. */
@@ -20,10 +22,13 @@ export abstract class PluginEntityApi {
   public abstract referenceLine: PluginReferenceLineApi
   /** Department operations. See {@linkcode PluginDepartmentApi}. */
   public abstract department: PluginDepartmentApi
+  /** Buildable Envelope operations. See {@linkcode PluginBuildableEnvelopeApi}. */
+  public abstract buildableEnvelope: PluginBuildableEnvelopeApi
 
   constructor() {}
 }
 
+export * from "./buildableEnvelope"
 export * from "./department"
 export * from "./referenceLine"
 export * from "./space"