@snaptrude/plugin-core 0.9.17 → 0.9.18-edgesetbacks-20261021.1

package/src/api/program/departments.ts

@@ -1,517 +1,517 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../types"
-import { PluginAreaUnit } from "./metrics"
-import { ComponentHandle } from "../../handles"
-
-/**
- * Program departments — read the department groupings of the active program.
- *
- * In program mode a **department** is a named, colored grouping of spaces with an
- * optional gross area **target** and a unit **count** target. This is the program-planning view of departments
- * (their identity, color, and target area); the underlying space geometry is read
- * and edited through the geometry namespaces, not here.
- *
- * All methods are reads: they return plain records and never throw for a missing
- * department (`get` returns `null`, `list` returns `[]`).
- *
- * Accessed via `snaptrude.program.departments`.
- */
-export abstract class PluginProgramDepartmentsApi {
-  constructor() {}
-
-  /**
-   * List the departments in the active program.
-   *
-   * Returns every department — well-known (Default, Site, …) and user-created —
-   * with its identity, color, and area target (when one has been set).
-   *
-   * @returns A {@linkcode PluginProgramDepartmentsListResult} with a `departments`
-   *   array (empty when the project has none).
-   *
-   * @examplePrompt List all the departments in my program
-   * @examplePrompt What program groups do I have and what are their target areas?
-   * @examplePrompt Show every department with its colour
-   * @examplePrompt Get the area target for each department
-   * @examplePrompt How many departments are in this project?
-   *
-   * # Example
-   * ```ts
-   * const { units, departments } = await snaptrude.program.departments.list()
-   * for (const d of departments) console.log(d.name, d.color, d.targetArea, units)
-   * ```
-   */
-  public abstract list(): PluginApiReturn<PluginProgramDepartmentsListResult>
-
-  /**
-   * Get a single department by id.
-   *
-   * @param departmentId - The id of the department to read.
-   * @returns The matching {@linkcode PluginProgramDepartment}, or `null` if no
-   *   department has that id.
-   *
-   * @examplePrompt Get the department with id dep_123
-   * @examplePrompt Look up a single department by its id
-   * @examplePrompt What is the target area of this department id?
-   *
-   * # Example
-   * ```ts
-   * const dept = await snaptrude.program.departments.get("dep_123")
-   * if (dept) console.log(dept.name, dept.targetArea)
-   * ```
-   */
-  public abstract get(
-    departmentId: string,
-  ): PluginApiReturn<PluginProgramDepartmentsGetResult>
-
-  /**
-   * Create a new department in the active program.
-   *
-   * Adds a named, colored program grouping. The new department starts empty —
-   * put spaces in it with {@linkcode PluginProgramDepartmentsApi.assign}, and set
-   * its area goal with {@linkcode PluginProgramDepartmentsApi.setTargetArea}.
-   *
-   * @param name - Display name of the new department.
-   * @param color - CSS hex color string (e.g. `"#b5e1dc"`).
-   * @returns The new department's id (read the full record back with
-   *   {@linkcode PluginProgramDepartmentsApi.get}).
-   * @throws If the department could not be created.
-   *
-   * @examplePrompt Create a department called Bedrooms in light blue
-   * @examplePrompt Add a new program group named Circulation with color #cccccc
-   * @examplePrompt Make a Classrooms department
-   * @examplePrompt Set up a Lobby department in the program
-   *
-   * # Example
-   * ```ts
-   * const { departmentId } = await snaptrude.program.departments.create("Bedrooms", "#b5e1dc")
-   * ```
-   */
-  public abstract create(
-    name: string,
-    color: string,
-  ): PluginApiReturn<PluginProgramDepartmentsCreateResult>
-
-  /**
-   * Update a department's name and/or color.
-   *
-   * A **sparse** update: omitted fields are left unchanged. Use
-   * {@linkcode PluginProgramDepartmentsApi.setTargetArea} to change the area
-   * target (not this method).
-   *
-   * @param departmentId - The id of the department to update.
-   * @param options - Any of `name`, `color`; omitted fields are left unchanged.
-   * @returns The updated {@linkcode PluginProgramDepartment} (with the response
-   *   `units` for its `targetArea`).
-   * @throws If no department has the given id.
-   *
-   * @examplePrompt Rename the Bedrooms department to Suites
-   * @examplePrompt Change the Circulation department colour to #ff8800
-   * @examplePrompt Recolour department dep_123
-   * @examplePrompt Update the Lobby department's display name
-   *
-   * # Example
-   * ```ts
-   * const dept = await snaptrude.program.departments.update("dep_123", { name: "Suites" })
-   * ```
-   */
-  public abstract update(
-    departmentId: string,
-    options?: { name?: string; color?: string },
-  ): PluginApiReturn<PluginProgramDepartmentsUpdateResult>
-
-  /**
-   * Assign one or more spaces to a department.
-   *
-   * Moves each space into the given department — an undoable membership change.
-   * A space belongs to exactly one department, so assigning re-homes it from any
-   * previous one. Paired with {@linkcode PluginProgramDepartmentsApi.unassign}.
-   *
-   * @param departmentId - The department to assign the spaces to.
-   * @param spaceIds - The ids of the spaces to move into the department (at
-   *   least one).
-   * @returns The department and the space ids that were assigned.
-   * @throws If the department does not exist or a space id is invalid.
-   *
-   * @examplePrompt Assign the selected rooms to the Bedrooms department
-   * @examplePrompt Put spaces 12 and 13 in the Circulation department
-   * @examplePrompt Move this space into the Lobby department
-   * @examplePrompt Add the kitchen spaces to the Service department
-   *
-   * # Example
-   * ```ts
-   * await snaptrude.program.departments.assign("dep_123", ["sp_1", "sp_2"])
-   * ```
-   */
-  public abstract assign(
-    departmentId: string,
-    spaceIds: ComponentHandle[],
-  ): PluginApiReturn<PluginProgramDepartmentsAssignResult>
-
-  /**
-   * Remove one or more spaces from their department.
-   *
-   * Returns each space to the **Default** department — there is no "no
-   * department" state, so unassigning means reassigning to Default. Paired with
-   * {@linkcode PluginProgramDepartmentsApi.assign}.
-   *
-   * @param spaceIds - The ids of the spaces to remove from their current
-   *   department (at least one).
-   * @returns The space ids that were returned to Default.
-   * @throws If a space id is invalid.
-   *
-   * @examplePrompt Remove the selected rooms from their department
-   * @examplePrompt Unassign space sp_1 from any department
-   * @examplePrompt Clear the department on these spaces
-   * @examplePrompt Take the kitchen out of the Service department
-   *
-   * # Example
-   * ```ts
-   * await snaptrude.program.departments.unassign(["sp_1"])
-   * ```
-   */
-  public abstract unassign(
-    spaceIds: ComponentHandle[],
-  ): PluginApiReturn<PluginProgramDepartmentsUnassignResult>
-
-  /**
-   * Set a department's target area.
-   *
-   * The goal the program metrics compare allocated area against (see
-   * {@linkcode PluginProgramMetricsApi}). Pass `units` to say what unit
-   * `targetArea` is in; it defaults to the project's area units. Read the target
-   * back from {@linkcode PluginProgramDepartmentsApi.get} (`targetArea`).
-   *
-   * @param departmentId - The id of the department whose target to set.
-   * @param targetArea - The target area, in `units`.
-   * @param units - Unit of `targetArea` (defaults to the project's area units).
-   * @returns The updated {@linkcode PluginProgramDepartment} with its `units`.
-   * @throws If no department has the given id.
-   *
-   * @examplePrompt Set the Bedrooms department target area to 2000 sqft
-   * @examplePrompt Give the Circulation department a 500 sqm area target
-   * @examplePrompt Target 1500 square feet for the Classrooms department
-   * @examplePrompt Update the area goal for department dep_123
-   *
-   * # Example
-   * ```ts
-   * await snaptrude.program.departments.setTargetArea("dep_123", 2000, "ft2")
-   * ```
-   */
-  public abstract setTargetArea(
-    departmentId: string,
-    targetArea: number,
-    units?: PluginAreaUnit,
-  ): PluginApiReturn<PluginProgramDepartmentsSetTargetAreaResult>
-
-  /**
-   * Set a department's target unit count.
-   *
-   * The number of units (program blocks) the department is planned for — the
-   * count twin of {@linkcode PluginProgramDepartmentsApi.setTargetArea}, stored
-   * beside the gross area target on the department. Read it back from
-   * {@linkcode PluginProgramDepartmentsApi.get} (`targetCount`).
-   *
-   * @param departmentId - The id of the department whose count to set.
-   * @param targetCount - The target number of units (a non-negative integer).
-   * @returns The updated {@linkcode PluginProgramDepartment} with its `units`.
-   * @throws If no department has the given id.
-   *
-   * @examplePrompt Set the Bedrooms department unit count to 12
-   * @examplePrompt The program needs 4 clinic blocks — update the department count
-   * @examplePrompt Update the target count for department dep_123
-   *
-   * # Example
-   * ```ts
-   * await snaptrude.program.departments.setTargetCount("dep_123", 12)
-   * ```
-   */
-  public abstract setTargetCount(
-    departmentId: string,
-    targetCount: number,
-  ): PluginApiReturn<PluginProgramDepartmentsSetTargetCountResult>
-
-  /**
-   * Delete a department.
-   *
-   * Any spaces still assigned to it are returned to the **Default** department
-   * (no space is left orphaned). The reserved departments (Default, Site,
-   * Envelope, Core) cannot be deleted.
-   *
-   * @param departmentId - The id of the department to delete.
-   * @returns The id of the deleted department and the spaces that were reassigned
-   *   to Default.
-   * @throws If no department has the given id, or it is a reserved department.
-   *
-   * @examplePrompt Delete the Bedrooms department
-   * @examplePrompt Remove the empty Circulation department
-   * @examplePrompt Delete department dep_123 and move its rooms to Default
-   *
-   * # Example
-   * ```ts
-   * await snaptrude.program.departments.delete("dep_123")
-   * ```
-   */
-  public delete?: (
-    departmentId: string,
-  ) => PluginApiReturn<PluginProgramDepartmentsDeleteResult>
-}
-
-/**
- * A department in the active program. Its `targetArea` is in the enclosing
- * response's `units` (see the area-units convention in
- * {@linkcode PluginAreaUnit}).
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `id` | `string` | Unique department id |
- * | `name` | `string` | Display name |
- * | `color` | `string` | CSS hex color string (e.g. `"#b5e1dc"`) |
- * | `targetArea` | `number \| null` | Gross target area in the response's `units`, or `null` if no target is set |
- * | `targetCount` | `number` | Target number of units / program blocks (`0` when unset) |
- */
-export const PluginProgramDepartment = z.object({
-  id: z.string(),
-  name: z.string(),
-  color: z.string(),
-  targetArea: z.number().nullable(),
-  targetCount: z.number(),
-})
-export type PluginProgramDepartment = z.infer<typeof PluginProgramDepartment>
-
-/**
- * Result of {@linkcode PluginProgramDepartmentsApi.list}. Per the area-units
- * convention, `units` sits on this response envelope (not on each record).
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `units` | `"ft2" \| "m2"` | The unit every `targetArea` below is reported in |
- * | `departments` | {@linkcode PluginProgramDepartment}`[]` | All departments in the active program |
- */
-export const PluginProgramDepartmentsListResult = z.object({
-  units: PluginAreaUnit,
-  departments: z.array(PluginProgramDepartment),
-})
-export type PluginProgramDepartmentsListResult = z.infer<
-  typeof PluginProgramDepartmentsListResult
->
-
-/**
- * Arguments for {@linkcode PluginProgramDepartmentsApi.get}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `departmentId` | `string` | The id of the department to read |
- */
-export const PluginProgramDepartmentsGetArgs = z.object({
-  departmentId: z.string(),
-})
-export type PluginProgramDepartmentsGetArgs = z.infer<
-  typeof PluginProgramDepartmentsGetArgs
->
-
-/**
- * Result of {@linkcode PluginProgramDepartmentsApi.get} — the department, or
- * `null` when no department has the given id. This is a bare `.get` record, so
- * per the area-units convention `units` is carried on the record itself.
- */
-export const PluginProgramDepartmentsGetResult = PluginProgramDepartment.extend(
-  {
-    units: PluginAreaUnit,
-  },
-).nullable()
-export type PluginProgramDepartmentsGetResult = z.infer<
-  typeof PluginProgramDepartmentsGetResult
->
-
-/**
- * A department record with its area `units` — the shape returned by the
- * single-record department writes (`update`, `setTargetArea`). Per the
- * area-units convention, a bare record carries `units` on itself.
- */
-export const PluginProgramDepartmentRecord = PluginProgramDepartment.extend({
-  units: PluginAreaUnit,
-})
-export type PluginProgramDepartmentRecord = z.infer<
-  typeof PluginProgramDepartmentRecord
->
-
-/**
- * Arguments for {@linkcode PluginProgramDepartmentsApi.create}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `name` | `string` | Display name of the new department |
- * | `color` | `string` | CSS hex color string (e.g. `"#b5e1dc"`) |
- */
-export const PluginProgramDepartmentsCreateArgs = z.object({
-  name: z.string(),
-  color: z.string(),
-})
-export type PluginProgramDepartmentsCreateArgs = z.infer<
-  typeof PluginProgramDepartmentsCreateArgs
->
-
-/**
- * Result of {@linkcode PluginProgramDepartmentsApi.create} — the id of the
- * newly created department.
- */
-export const PluginProgramDepartmentsCreateResult = z.object({
-  departmentId: z.string(),
-})
-export type PluginProgramDepartmentsCreateResult = z.infer<
-  typeof PluginProgramDepartmentsCreateResult
->
-
-/**
- * Arguments for {@linkcode PluginProgramDepartmentsApi.update}. Sparse — only
- * the provided fields are changed.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `departmentId` | `string` | The id of the department to update |
- * | `name` | `string \| undefined` | New display name (unchanged if omitted) |
- * | `color` | `string \| undefined` | New CSS hex color (unchanged if omitted) |
- */
-export const PluginProgramDepartmentsUpdateArgs = z.object({
-  departmentId: z.string(),
-  name: z.string().optional(),
-  color: z.string().optional(),
-})
-export type PluginProgramDepartmentsUpdateArgs = z.infer<
-  typeof PluginProgramDepartmentsUpdateArgs
->
-
-/** Result of {@linkcode PluginProgramDepartmentsApi.update} — the updated record. */
-export const PluginProgramDepartmentsUpdateResult =
-  PluginProgramDepartmentRecord
-export type PluginProgramDepartmentsUpdateResult = z.infer<
-  typeof PluginProgramDepartmentsUpdateResult
->
-
-/**
- * Arguments for {@linkcode PluginProgramDepartmentsApi.assign}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `departmentId` | `string` | The department to assign the spaces to |
- * | `spaceIds` | `ComponentHandle[]` | The ids of the spaces to move into the department |
- */
-export const PluginProgramDepartmentsAssignArgs = z.object({
-  departmentId: z.string(),
-  spaceIds: z.array(ComponentHandle).min(1),
-})
-export type PluginProgramDepartmentsAssignArgs = z.infer<
-  typeof PluginProgramDepartmentsAssignArgs
->
-
-/** Result of {@linkcode PluginProgramDepartmentsApi.assign}. */
-export const PluginProgramDepartmentsAssignResult = z.object({
-  departmentId: z.string(),
-  spaceIds: z.array(ComponentHandle),
-})
-export type PluginProgramDepartmentsAssignResult = z.infer<
-  typeof PluginProgramDepartmentsAssignResult
->
-
-/**
- * Arguments for {@linkcode PluginProgramDepartmentsApi.unassign}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `spaceIds` | `ComponentHandle[]` | The ids of the spaces to return to the Default department |
- */
-export const PluginProgramDepartmentsUnassignArgs = z.object({
-  spaceIds: z.array(ComponentHandle).min(1),
-})
-export type PluginProgramDepartmentsUnassignArgs = z.infer<
-  typeof PluginProgramDepartmentsUnassignArgs
->
-
-/** Result of {@linkcode PluginProgramDepartmentsApi.unassign}. */
-export const PluginProgramDepartmentsUnassignResult = z.object({
-  spaceIds: z.array(ComponentHandle),
-})
-export type PluginProgramDepartmentsUnassignResult = z.infer<
-  typeof PluginProgramDepartmentsUnassignResult
->
-
-/**
- * Arguments for {@linkcode PluginProgramDepartmentsApi.setTargetArea}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `departmentId` | `string` | The id of the department whose target to set |
- * | `targetArea` | `number` | The target area, in `units` |
- * | `units` | `"ft2" \| "m2" \| undefined` | Unit of `targetArea` (defaults to the project's area units) |
- */
-export const PluginProgramDepartmentsSetTargetAreaArgs = z.object({
-  departmentId: z.string(),
-  targetArea: z.number(),
-  units: PluginAreaUnit.optional(),
-})
-export type PluginProgramDepartmentsSetTargetAreaArgs = z.infer<
-  typeof PluginProgramDepartmentsSetTargetAreaArgs
->
-
-/**
- * Result of {@linkcode PluginProgramDepartmentsApi.setTargetArea} — the updated
- * department record with its `units`.
- */
-export const PluginProgramDepartmentsSetTargetAreaResult =
-  PluginProgramDepartmentRecord
-export type PluginProgramDepartmentsSetTargetAreaResult = z.infer<
-  typeof PluginProgramDepartmentsSetTargetAreaResult
->
-
-/**
- * Arguments for {@linkcode PluginProgramDepartmentsApi.setTargetCount}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `departmentId` | `string` | The id of the department whose count to set |
- * | `targetCount` | `number` | Target number of units (non-negative integer) |
- */
-export const PluginProgramDepartmentsSetTargetCountArgs = z.object({
-  departmentId: z.string(),
-  targetCount: z.number().int().nonnegative(),
-})
-export type PluginProgramDepartmentsSetTargetCountArgs = z.infer<
-  typeof PluginProgramDepartmentsSetTargetCountArgs
->
-
-/** Result of {@linkcode PluginProgramDepartmentsApi.setTargetCount} — the updated record with `units`. */
-export const PluginProgramDepartmentsSetTargetCountResult =
-  PluginProgramDepartmentRecord
-export type PluginProgramDepartmentsSetTargetCountResult = z.infer<
-  typeof PluginProgramDepartmentsSetTargetCountResult
->
-
-/**
- * Arguments for {@linkcode PluginProgramDepartmentsApi.delete}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `departmentId` | `string` | The id of the department to delete |
- */
-export const PluginProgramDepartmentsDeleteArgs = z.object({
-  departmentId: z.string(),
-})
-export type PluginProgramDepartmentsDeleteArgs = z.infer<
-  typeof PluginProgramDepartmentsDeleteArgs
->
-
-/**
- * Result of {@linkcode PluginProgramDepartmentsApi.delete}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `departmentId` | `string` | The id of the deleted department |
- * | `reassignedSpaceIds` | `ComponentHandle[]` | Spaces that were returned to the Default department |
- */
-export const PluginProgramDepartmentsDeleteResult = z.object({
-  departmentId: z.string(),
-  reassignedSpaceIds: z.array(ComponentHandle),
-})
-export type PluginProgramDepartmentsDeleteResult = z.infer<
-  typeof PluginProgramDepartmentsDeleteResult
->
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+import { PluginAreaUnit } from "./metrics"
+import { ComponentHandle } from "../../handles"
+
+/**
+ * Program departments — read the department groupings of the active program.
+ *
+ * In program mode a **department** is a named, colored grouping of spaces with an
+ * optional gross area **target** and a unit **count** target. This is the program-planning view of departments
+ * (their identity, color, and target area); the underlying space geometry is read
+ * and edited through the geometry namespaces, not here.
+ *
+ * All methods are reads: they return plain records and never throw for a missing
+ * department (`get` returns `null`, `list` returns `[]`).
+ *
+ * Accessed via `snaptrude.program.departments`.
+ */
+export abstract class PluginProgramDepartmentsApi {
+  constructor() {}
+
+  /**
+   * List the departments in the active program.
+   *
+   * Returns every department — well-known (Default, Site, …) and user-created —
+   * with its identity, color, and area target (when one has been set).
+   *
+   * @returns A {@linkcode PluginProgramDepartmentsListResult} with a `departments`
+   *   array (empty when the project has none).
+   *
+   * @examplePrompt List all the departments in my program
+   * @examplePrompt What program groups do I have and what are their target areas?
+   * @examplePrompt Show every department with its colour
+   * @examplePrompt Get the area target for each department
+   * @examplePrompt How many departments are in this project?
+   *
+   * # Example
+   * ```ts
+   * const { units, departments } = await snaptrude.program.departments.list()
+   * for (const d of departments) console.log(d.name, d.color, d.targetArea, units)
+   * ```
+   */
+  public abstract list(): PluginApiReturn<PluginProgramDepartmentsListResult>
+
+  /**
+   * Get a single department by id.
+   *
+   * @param departmentId - The id of the department to read.
+   * @returns The matching {@linkcode PluginProgramDepartment}, or `null` if no
+   *   department has that id.
+   *
+   * @examplePrompt Get the department with id dep_123
+   * @examplePrompt Look up a single department by its id
+   * @examplePrompt What is the target area of this department id?
+   *
+   * # Example
+   * ```ts
+   * const dept = await snaptrude.program.departments.get("dep_123")
+   * if (dept) console.log(dept.name, dept.targetArea)
+   * ```
+   */
+  public abstract get(
+    departmentId: string,
+  ): PluginApiReturn<PluginProgramDepartmentsGetResult>
+
+  /**
+   * Create a new department in the active program.
+   *
+   * Adds a named, colored program grouping. The new department starts empty —
+   * put spaces in it with {@linkcode PluginProgramDepartmentsApi.assign}, and set
+   * its area goal with {@linkcode PluginProgramDepartmentsApi.setTargetArea}.
+   *
+   * @param name - Display name of the new department.
+   * @param color - CSS hex color string (e.g. `"#b5e1dc"`).
+   * @returns The new department's id (read the full record back with
+   *   {@linkcode PluginProgramDepartmentsApi.get}).
+   * @throws If the department could not be created.
+   *
+   * @examplePrompt Create a department called Bedrooms in light blue
+   * @examplePrompt Add a new program group named Circulation with color #cccccc
+   * @examplePrompt Make a Classrooms department
+   * @examplePrompt Set up a Lobby department in the program
+   *
+   * # Example
+   * ```ts
+   * const { departmentId } = await snaptrude.program.departments.create("Bedrooms", "#b5e1dc")
+   * ```
+   */
+  public abstract create(
+    name: string,
+    color: string,
+  ): PluginApiReturn<PluginProgramDepartmentsCreateResult>
+
+  /**
+   * Update a department's name and/or color.
+   *
+   * A **sparse** update: omitted fields are left unchanged. Use
+   * {@linkcode PluginProgramDepartmentsApi.setTargetArea} to change the area
+   * target (not this method).
+   *
+   * @param departmentId - The id of the department to update.
+   * @param options - Any of `name`, `color`; omitted fields are left unchanged.
+   * @returns The updated {@linkcode PluginProgramDepartment} (with the response
+   *   `units` for its `targetArea`).
+   * @throws If no department has the given id.
+   *
+   * @examplePrompt Rename the Bedrooms department to Suites
+   * @examplePrompt Change the Circulation department colour to #ff8800
+   * @examplePrompt Recolour department dep_123
+   * @examplePrompt Update the Lobby department's display name
+   *
+   * # Example
+   * ```ts
+   * const dept = await snaptrude.program.departments.update("dep_123", { name: "Suites" })
+   * ```
+   */
+  public abstract update(
+    departmentId: string,
+    options?: { name?: string; color?: string },
+  ): PluginApiReturn<PluginProgramDepartmentsUpdateResult>
+
+  /**
+   * Assign one or more spaces to a department.
+   *
+   * Moves each space into the given department — an undoable membership change.
+   * A space belongs to exactly one department, so assigning re-homes it from any
+   * previous one. Paired with {@linkcode PluginProgramDepartmentsApi.unassign}.
+   *
+   * @param departmentId - The department to assign the spaces to.
+   * @param spaceIds - The ids of the spaces to move into the department (at
+   *   least one).
+   * @returns The department and the space ids that were assigned.
+   * @throws If the department does not exist or a space id is invalid.
+   *
+   * @examplePrompt Assign the selected rooms to the Bedrooms department
+   * @examplePrompt Put spaces 12 and 13 in the Circulation department
+   * @examplePrompt Move this space into the Lobby department
+   * @examplePrompt Add the kitchen spaces to the Service department
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.program.departments.assign("dep_123", ["sp_1", "sp_2"])
+   * ```
+   */
+  public abstract assign(
+    departmentId: string,
+    spaceIds: ComponentHandle[],
+  ): PluginApiReturn<PluginProgramDepartmentsAssignResult>
+
+  /**
+   * Remove one or more spaces from their department.
+   *
+   * Returns each space to the **Default** department — there is no "no
+   * department" state, so unassigning means reassigning to Default. Paired with
+   * {@linkcode PluginProgramDepartmentsApi.assign}.
+   *
+   * @param spaceIds - The ids of the spaces to remove from their current
+   *   department (at least one).
+   * @returns The space ids that were returned to Default.
+   * @throws If a space id is invalid.
+   *
+   * @examplePrompt Remove the selected rooms from their department
+   * @examplePrompt Unassign space sp_1 from any department
+   * @examplePrompt Clear the department on these spaces
+   * @examplePrompt Take the kitchen out of the Service department
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.program.departments.unassign(["sp_1"])
+   * ```
+   */
+  public abstract unassign(
+    spaceIds: ComponentHandle[],
+  ): PluginApiReturn<PluginProgramDepartmentsUnassignResult>
+
+  /**
+   * Set a department's target area.
+   *
+   * The goal the program metrics compare allocated area against (see
+   * {@linkcode PluginProgramMetricsApi}). Pass `units` to say what unit
+   * `targetArea` is in; it defaults to the project's area units. Read the target
+   * back from {@linkcode PluginProgramDepartmentsApi.get} (`targetArea`).
+   *
+   * @param departmentId - The id of the department whose target to set.
+   * @param targetArea - The target area, in `units`.
+   * @param units - Unit of `targetArea` (defaults to the project's area units).
+   * @returns The updated {@linkcode PluginProgramDepartment} with its `units`.
+   * @throws If no department has the given id.
+   *
+   * @examplePrompt Set the Bedrooms department target area to 2000 sqft
+   * @examplePrompt Give the Circulation department a 500 sqm area target
+   * @examplePrompt Target 1500 square feet for the Classrooms department
+   * @examplePrompt Update the area goal for department dep_123
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.program.departments.setTargetArea("dep_123", 2000, "ft2")
+   * ```
+   */
+  public abstract setTargetArea(
+    departmentId: string,
+    targetArea: number,
+    units?: PluginAreaUnit,
+  ): PluginApiReturn<PluginProgramDepartmentsSetTargetAreaResult>
+
+  /**
+   * Set a department's target unit count.
+   *
+   * The number of units (program blocks) the department is planned for — the
+   * count twin of {@linkcode PluginProgramDepartmentsApi.setTargetArea}, stored
+   * beside the gross area target on the department. Read it back from
+   * {@linkcode PluginProgramDepartmentsApi.get} (`targetCount`).
+   *
+   * @param departmentId - The id of the department whose count to set.
+   * @param targetCount - The target number of units (a non-negative integer).
+   * @returns The updated {@linkcode PluginProgramDepartment} with its `units`.
+   * @throws If no department has the given id.
+   *
+   * @examplePrompt Set the Bedrooms department unit count to 12
+   * @examplePrompt The program needs 4 clinic blocks — update the department count
+   * @examplePrompt Update the target count for department dep_123
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.program.departments.setTargetCount("dep_123", 12)
+   * ```
+   */
+  public abstract setTargetCount(
+    departmentId: string,
+    targetCount: number,
+  ): PluginApiReturn<PluginProgramDepartmentsSetTargetCountResult>
+
+  /**
+   * Delete a department.
+   *
+   * Any spaces still assigned to it are returned to the **Default** department
+   * (no space is left orphaned). The reserved departments (Default, Site,
+   * Envelope, Core) cannot be deleted.
+   *
+   * @param departmentId - The id of the department to delete.
+   * @returns The id of the deleted department and the spaces that were reassigned
+   *   to Default.
+   * @throws If no department has the given id, or it is a reserved department.
+   *
+   * @examplePrompt Delete the Bedrooms department
+   * @examplePrompt Remove the empty Circulation department
+   * @examplePrompt Delete department dep_123 and move its rooms to Default
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.program.departments.delete("dep_123")
+   * ```
+   */
+  public delete?: (
+    departmentId: string,
+  ) => PluginApiReturn<PluginProgramDepartmentsDeleteResult>
+}
+
+/**
+ * A department in the active program. Its `targetArea` is in the enclosing
+ * response's `units` (see the area-units convention in
+ * {@linkcode PluginAreaUnit}).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Unique department id |
+ * | `name` | `string` | Display name |
+ * | `color` | `string` | CSS hex color string (e.g. `"#b5e1dc"`) |
+ * | `targetArea` | `number \| null` | Gross target area in the response's `units`, or `null` if no target is set |
+ * | `targetCount` | `number` | Target number of units / program blocks (`0` when unset) |
+ */
+export const PluginProgramDepartment = z.object({
+  id: z.string(),
+  name: z.string(),
+  color: z.string(),
+  targetArea: z.number().nullable(),
+  targetCount: z.number(),
+})
+export type PluginProgramDepartment = z.infer<typeof PluginProgramDepartment>
+
+/**
+ * Result of {@linkcode PluginProgramDepartmentsApi.list}. Per the area-units
+ * convention, `units` sits on this response envelope (not on each record).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `units` | `"ft2" \| "m2"` | The unit every `targetArea` below is reported in |
+ * | `departments` | {@linkcode PluginProgramDepartment}`[]` | All departments in the active program |
+ */
+export const PluginProgramDepartmentsListResult = z.object({
+  units: PluginAreaUnit,
+  departments: z.array(PluginProgramDepartment),
+})
+export type PluginProgramDepartmentsListResult = z.infer<
+  typeof PluginProgramDepartmentsListResult
+>
+
+/**
+ * Arguments for {@linkcode PluginProgramDepartmentsApi.get}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `departmentId` | `string` | The id of the department to read |
+ */
+export const PluginProgramDepartmentsGetArgs = z.object({
+  departmentId: z.string(),
+})
+export type PluginProgramDepartmentsGetArgs = z.infer<
+  typeof PluginProgramDepartmentsGetArgs
+>
+
+/**
+ * Result of {@linkcode PluginProgramDepartmentsApi.get} — the department, or
+ * `null` when no department has the given id. This is a bare `.get` record, so
+ * per the area-units convention `units` is carried on the record itself.
+ */
+export const PluginProgramDepartmentsGetResult = PluginProgramDepartment.extend(
+  {
+    units: PluginAreaUnit,
+  },
+).nullable()
+export type PluginProgramDepartmentsGetResult = z.infer<
+  typeof PluginProgramDepartmentsGetResult
+>
+
+/**
+ * A department record with its area `units` — the shape returned by the
+ * single-record department writes (`update`, `setTargetArea`). Per the
+ * area-units convention, a bare record carries `units` on itself.
+ */
+export const PluginProgramDepartmentRecord = PluginProgramDepartment.extend({
+  units: PluginAreaUnit,
+})
+export type PluginProgramDepartmentRecord = z.infer<
+  typeof PluginProgramDepartmentRecord
+>
+
+/**
+ * Arguments for {@linkcode PluginProgramDepartmentsApi.create}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string` | Display name of the new department |
+ * | `color` | `string` | CSS hex color string (e.g. `"#b5e1dc"`) |
+ */
+export const PluginProgramDepartmentsCreateArgs = z.object({
+  name: z.string(),
+  color: z.string(),
+})
+export type PluginProgramDepartmentsCreateArgs = z.infer<
+  typeof PluginProgramDepartmentsCreateArgs
+>
+
+/**
+ * Result of {@linkcode PluginProgramDepartmentsApi.create} — the id of the
+ * newly created department.
+ */
+export const PluginProgramDepartmentsCreateResult = z.object({
+  departmentId: z.string(),
+})
+export type PluginProgramDepartmentsCreateResult = z.infer<
+  typeof PluginProgramDepartmentsCreateResult
+>
+
+/**
+ * Arguments for {@linkcode PluginProgramDepartmentsApi.update}. Sparse — only
+ * the provided fields are changed.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `departmentId` | `string` | The id of the department to update |
+ * | `name` | `string \| undefined` | New display name (unchanged if omitted) |
+ * | `color` | `string \| undefined` | New CSS hex color (unchanged if omitted) |
+ */
+export const PluginProgramDepartmentsUpdateArgs = z.object({
+  departmentId: z.string(),
+  name: z.string().optional(),
+  color: z.string().optional(),
+})
+export type PluginProgramDepartmentsUpdateArgs = z.infer<
+  typeof PluginProgramDepartmentsUpdateArgs
+>
+
+/** Result of {@linkcode PluginProgramDepartmentsApi.update} — the updated record. */
+export const PluginProgramDepartmentsUpdateResult =
+  PluginProgramDepartmentRecord
+export type PluginProgramDepartmentsUpdateResult = z.infer<
+  typeof PluginProgramDepartmentsUpdateResult
+>
+
+/**
+ * Arguments for {@linkcode PluginProgramDepartmentsApi.assign}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `departmentId` | `string` | The department to assign the spaces to |
+ * | `spaceIds` | `ComponentHandle[]` | The ids of the spaces to move into the department |
+ */
+export const PluginProgramDepartmentsAssignArgs = z.object({
+  departmentId: z.string(),
+  spaceIds: z.array(ComponentHandle).min(1),
+})
+export type PluginProgramDepartmentsAssignArgs = z.infer<
+  typeof PluginProgramDepartmentsAssignArgs
+>
+
+/** Result of {@linkcode PluginProgramDepartmentsApi.assign}. */
+export const PluginProgramDepartmentsAssignResult = z.object({
+  departmentId: z.string(),
+  spaceIds: z.array(ComponentHandle),
+})
+export type PluginProgramDepartmentsAssignResult = z.infer<
+  typeof PluginProgramDepartmentsAssignResult
+>
+
+/**
+ * Arguments for {@linkcode PluginProgramDepartmentsApi.unassign}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `spaceIds` | `ComponentHandle[]` | The ids of the spaces to return to the Default department |
+ */
+export const PluginProgramDepartmentsUnassignArgs = z.object({
+  spaceIds: z.array(ComponentHandle).min(1),
+})
+export type PluginProgramDepartmentsUnassignArgs = z.infer<
+  typeof PluginProgramDepartmentsUnassignArgs
+>
+
+/** Result of {@linkcode PluginProgramDepartmentsApi.unassign}. */
+export const PluginProgramDepartmentsUnassignResult = z.object({
+  spaceIds: z.array(ComponentHandle),
+})
+export type PluginProgramDepartmentsUnassignResult = z.infer<
+  typeof PluginProgramDepartmentsUnassignResult
+>
+
+/**
+ * Arguments for {@linkcode PluginProgramDepartmentsApi.setTargetArea}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `departmentId` | `string` | The id of the department whose target to set |
+ * | `targetArea` | `number` | The target area, in `units` |
+ * | `units` | `"ft2" \| "m2" \| undefined` | Unit of `targetArea` (defaults to the project's area units) |
+ */
+export const PluginProgramDepartmentsSetTargetAreaArgs = z.object({
+  departmentId: z.string(),
+  targetArea: z.number(),
+  units: PluginAreaUnit.optional(),
+})
+export type PluginProgramDepartmentsSetTargetAreaArgs = z.infer<
+  typeof PluginProgramDepartmentsSetTargetAreaArgs
+>
+
+/**
+ * Result of {@linkcode PluginProgramDepartmentsApi.setTargetArea} — the updated
+ * department record with its `units`.
+ */
+export const PluginProgramDepartmentsSetTargetAreaResult =
+  PluginProgramDepartmentRecord
+export type PluginProgramDepartmentsSetTargetAreaResult = z.infer<
+  typeof PluginProgramDepartmentsSetTargetAreaResult
+>
+
+/**
+ * Arguments for {@linkcode PluginProgramDepartmentsApi.setTargetCount}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `departmentId` | `string` | The id of the department whose count to set |
+ * | `targetCount` | `number` | Target number of units (non-negative integer) |
+ */
+export const PluginProgramDepartmentsSetTargetCountArgs = z.object({
+  departmentId: z.string(),
+  targetCount: z.number().int().nonnegative(),
+})
+export type PluginProgramDepartmentsSetTargetCountArgs = z.infer<
+  typeof PluginProgramDepartmentsSetTargetCountArgs
+>
+
+/** Result of {@linkcode PluginProgramDepartmentsApi.setTargetCount} — the updated record with `units`. */
+export const PluginProgramDepartmentsSetTargetCountResult =
+  PluginProgramDepartmentRecord
+export type PluginProgramDepartmentsSetTargetCountResult = z.infer<
+  typeof PluginProgramDepartmentsSetTargetCountResult
+>
+
+/**
+ * Arguments for {@linkcode PluginProgramDepartmentsApi.delete}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `departmentId` | `string` | The id of the department to delete |
+ */
+export const PluginProgramDepartmentsDeleteArgs = z.object({
+  departmentId: z.string(),
+})
+export type PluginProgramDepartmentsDeleteArgs = z.infer<
+  typeof PluginProgramDepartmentsDeleteArgs
+>
+
+/**
+ * Result of {@linkcode PluginProgramDepartmentsApi.delete}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `departmentId` | `string` | The id of the deleted department |
+ * | `reassignedSpaceIds` | `ComponentHandle[]` | Spaces that were returned to the Default department |
+ */
+export const PluginProgramDepartmentsDeleteResult = z.object({
+  departmentId: z.string(),
+  reassignedSpaceIds: z.array(ComponentHandle),
+})
+export type PluginProgramDepartmentsDeleteResult = z.infer<
+  typeof PluginProgramDepartmentsDeleteResult
+>