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

package/src/api/program/labels.ts

@@ -1,332 +1,332 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../types"
-import { PluginAreaUnit } from "./metrics"
-
-/**
- * Program labels — the **program rows** of the active program: each label is a
- * named space type (e.g. "Exam Room", "Nurse Station") inside a department,
- * carrying an area **target** and a unit **count** target.
- *
- * Labels are the non-department planning entities of program mode. A
- * department groups labels; a label groups the spaces (masses) that realize it.
- * Target areas live on **departments** ({@linkcode PluginProgramDepartmentsApi.setTargetArea})
- * and on **labels** (this namespace) — an individual space carries no target of
- * its own; it inherits its label's `targetArea / targetCount`. Program Blocks
- * (spaces whose space type is "Program Block") are likewise targeted through
- * their label.
- *
- * `targetArea` is the label's **total** target (all units), in the response's
- * `units`; the per-unit target is `targetArea / targetCount`.
- *
- * Reads never throw for a miss (`get` returns `null`, `list` returns `[]`).
- * Writes are undoable and autosaved; when the project has proposals they write
- * the **active proposal's** targets.
- *
- * Accessed via `snaptrude.program.labels`.
- */
-export abstract class PluginProgramLabelsApi {
-  constructor() {}
-
-  /**
-   * List the labels (program rows) of the active program.
-   *
-   * @returns A {@linkcode PluginProgramLabelsListResult} with `units` and a
-   *   `labels` array (empty when the project has none).
-   *
-   * @examplePrompt List all the program rows with their target areas
-   * @examplePrompt What space labels are in the program and how many of each?
-   * @examplePrompt Show every label with its department and target
-   *
-   * # Example
-   * ```ts
-   * const { units, labels } = await snaptrude.program.labels.list()
-   * for (const l of labels) console.log(l.name, l.targetArea, units, l.targetCount)
-   * ```
-   */
-  public abstract list(): PluginApiReturn<PluginProgramLabelsListResult>
-
-  /**
-   * Get a single label by id.
-   *
-   * @param labelId - The id of the label to read.
-   * @returns The matching {@linkcode PluginProgramLabelRecord} (with `units`), or
-   *   `null` if no label has that id.
-   *
-   * @examplePrompt Get the label with id lbl_12
-   * @examplePrompt What is the target area of this program row?
-   *
-   * # Example
-   * ```ts
-   * const label = await snaptrude.program.labels.get("lbl_12")
-   * if (label) console.log(label.name, label.targetArea, label.units)
-   * ```
-   */
-  public abstract get(
-    labelId: string,
-  ): PluginApiReturn<PluginProgramLabelsGetResult>
-
-  /**
-   * Create labels (program rows), optionally creating their spaces too.
-   *
-   * Each item names a label and its targets. A label is unique per
-   * (`name`, department); an item matching an existing label **updates** that
-   * label's targets instead of duplicating it. Unknown departments are created
-   * by name when `departmentName` is given; omit both department fields for the
-   * Default department.
-   *
-   * By default only the program rows are created (targets to plan against).
-   * Pass `createSpaces: true` to also instantiate `targetCount` massing spaces
-   * per label on the canvas, laid out automatically — the same path Program
-   * Mode's CSV/Interpret import uses.
-   *
-   * @param items - The labels to create (1–500).
-   * @param options - Optional `units` for every `targetArea` (defaults to the
-   *   project's area units) and `createSpaces` (default `false`).
-   * @returns A {@linkcode PluginProgramLabelsCreateResult} with the created or
-   *   updated label ids, in input order.
-   * @throws If an item's `departmentId` does not exist.
-   *
-   * @examplePrompt Add program rows for 4 exam rooms of 120 sqft each
-   * @examplePrompt Create the labels from this interpreted program
-   * @examplePrompt Add an Office label with a 2000 sqft target to the Admin department
-   * @examplePrompt Create program rows and their spaces on the canvas
-   *
-   * # Example
-   * ```ts
-   * const { labelIds } = await snaptrude.program.labels.create(
-   *   [{ name: "Exam Room", targetArea: 480, targetCount: 4, departmentName: "Clinic" }],
-   *   { units: "ft2" },
-   * )
-   * ```
-   */
-  public abstract create(
-    items: PluginProgramLabelCreateItem[],
-    options?: { units?: PluginAreaUnit; createSpaces?: boolean },
-  ): PluginApiReturn<PluginProgramLabelsCreateResult>
-
-  /**
-   * Set a label's total target area.
-   *
-   * The goal the program metrics compare the label's allocated area against.
-   * Pass `units` to say what unit `targetArea` is in; it defaults to the
-   * project's area units. Read it back with {@linkcode PluginProgramLabelsApi.get}.
-   *
-   * @param labelId - The id of the label whose target to set.
-   * @param targetArea - The total target area (all units), in `units`.
-   * @param units - Unit of `targetArea` (defaults to the project's area units).
-   * @returns The updated {@linkcode PluginProgramLabelRecord} with its `units`.
-   * @throws If no label has the given id.
-   *
-   * @examplePrompt Set the Exam Room target area to 480 sqft
-   * @examplePrompt Give the Corridor program row a 150 sqm target
-   * @examplePrompt Update the area target for label lbl_12
-   *
-   * # Example
-   * ```ts
-   * await snaptrude.program.labels.setTargetArea("lbl_12", 480, "ft2")
-   * ```
-   */
-  public abstract setTargetArea(
-    labelId: string,
-    targetArea: number,
-    units?: PluginAreaUnit,
-  ): PluginApiReturn<PluginProgramLabelsSetTargetAreaResult>
-
-  /**
-   * Set a label's target unit count (how many of this space the program calls for).
-   *
-   * @param labelId - The id of the label whose count to set.
-   * @param targetCount - The target number of units (a non-negative integer).
-   * @returns The updated {@linkcode PluginProgramLabelRecord} with its `units`.
-   * @throws If no label has the given id.
-   *
-   * @examplePrompt Set the Exam Room count to 6
-   * @examplePrompt The program needs 12 patient rooms — update the count
-   *
-   * # Example
-   * ```ts
-   * await snaptrude.program.labels.setTargetCount("lbl_12", 6)
-   * ```
-   */
-  public abstract setTargetCount(
-    labelId: string,
-    targetCount: number,
-  ): PluginApiReturn<PluginProgramLabelsSetTargetCountResult>
-}
-
-/**
- * A label (program row) in the active program. `targetArea` is the label's
- * **total** target in the enclosing response's `units`.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `id` | `string` | Stable label id |
- * | `name` | `string` | Label (space type) name |
- * | `color` | `string` | CSS hex color string |
- * | `departmentId` | `string` | Id of the department the label belongs to |
- * | `targetArea` | `number \| null` | Total target area (all units), or `null` when no target is set |
- * | `targetCount` | `number` | Target number of units (`0` when unset) |
- * | `storey` | `number \| null` | Default storey new spaces of this label are placed on |
- */
-export const PluginProgramLabel = z.object({
-  id: z.string(),
-  name: z.string(),
-  color: z.string(),
-  departmentId: z.string(),
-  targetArea: z.number().nullable(),
-  targetCount: z.number(),
-  storey: z.number().nullable(),
-})
-export type PluginProgramLabel = z.infer<typeof PluginProgramLabel>
-
-/** A bare label record carrying its area `units` (per the area-units convention). */
-export const PluginProgramLabelRecord = PluginProgramLabel.extend({
-  units: PluginAreaUnit,
-})
-export type PluginProgramLabelRecord = z.infer<typeof PluginProgramLabelRecord>
-
-/**
- * Result of {@linkcode PluginProgramLabelsApi.list}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `units` | `"ft2" \| "m2"` | The unit every `targetArea` below is reported in |
- * | `labels` | {@linkcode PluginProgramLabel}`[]` | All labels in the active program |
- */
-export const PluginProgramLabelsListResult = z.object({
-  units: PluginAreaUnit,
-  labels: z.array(PluginProgramLabel),
-})
-export type PluginProgramLabelsListResult = z.infer<
-  typeof PluginProgramLabelsListResult
->
-
-/** Arguments for {@linkcode PluginProgramLabelsApi.get}. */
-export const PluginProgramLabelsGetArgs = z.object({
-  labelId: z.string(),
-})
-export type PluginProgramLabelsGetArgs = z.infer<
-  typeof PluginProgramLabelsGetArgs
->
-
-/** Result of {@linkcode PluginProgramLabelsApi.get} — the record with `units`, or `null`. */
-export const PluginProgramLabelsGetResult = PluginProgramLabelRecord.nullable()
-export type PluginProgramLabelsGetResult = z.infer<
-  typeof PluginProgramLabelsGetResult
->
-
-/**
- * One label to create via {@linkcode PluginProgramLabelsApi.create}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `name` | `string` | Label (space type) name |
- * | `targetArea` | `number?` | Total target area (all units), in the call's `units` |
- * | `targetCount` | `number?` | Target number of units (default `1`) |
- * | `departmentId` | `string?` | Existing department to file the label under |
- * | `departmentName` | `string?` | Department by name — created when it does not exist (ignored when `departmentId` is given) |
- * | `color` | `string?` | CSS hex color (a light color is generated when omitted) |
- * | `storey` | `number?` | Storey for spaces of this label (default `1`) |
- * | `height` | `number?` | Space height in project length units (for `createSpaces`) |
- * | `width` | `number?` | Space width in project length units (for `createSpaces`) |
- */
-export const PluginProgramLabelCreateItem = z.object({
-  name: z.string().trim().min(1),
-  targetArea: z.number().finite().nonnegative().optional(),
-  targetCount: z.number().int().nonnegative().optional(),
-  departmentId: z.string().optional(),
-  departmentName: z.string().optional(),
-  color: z.string().optional(),
-  storey: z.number().int().optional(),
-  height: z.number().finite().positive().optional(),
-  width: z.number().finite().positive().optional(),
-})
-export type PluginProgramLabelCreateItem = z.infer<
-  typeof PluginProgramLabelCreateItem
->
-
-/** Maximum items per {@linkcode PluginProgramLabelsApi.create} call. */
-export const PLUGIN_PROGRAM_LABELS_BATCH_LIMIT = 500
-
-/**
- * Arguments for {@linkcode PluginProgramLabelsApi.create}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `items` | {@linkcode PluginProgramLabelCreateItem}`[]` | 1–500 labels |
- * | `units` | `"ft2" \| "m2"?` | Unit of every `targetArea` (defaults to the project's area units) |
- * | `createSpaces` | `boolean?` | Also create `targetCount` spaces per label on the canvas (default `false`) |
- */
-export const PluginProgramLabelsCreateArgs = z.object({
-  items: z
-    .array(PluginProgramLabelCreateItem)
-    .min(1)
-    .max(PLUGIN_PROGRAM_LABELS_BATCH_LIMIT),
-  units: PluginAreaUnit.optional(),
-  createSpaces: z.boolean().optional(),
-})
-export type PluginProgramLabelsCreateArgs = z.infer<
-  typeof PluginProgramLabelsCreateArgs
->
-
-/**
- * Result of {@linkcode PluginProgramLabelsApi.create}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `labelIds` | `string[]` | The created (or updated) label ids, in input order |
- * | `createdSpaces` | `boolean` | Whether spaces were also created on the canvas |
- */
-export const PluginProgramLabelsCreateResult = z.object({
-  labelIds: z.array(z.string()),
-  createdSpaces: z.boolean(),
-})
-export type PluginProgramLabelsCreateResult = z.infer<
-  typeof PluginProgramLabelsCreateResult
->
-
-/**
- * Arguments for {@linkcode PluginProgramLabelsApi.setTargetArea}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `labelId` | `string` | The label whose target to set |
- * | `targetArea` | `number` | Total target area, in `units` |
- * | `units` | `"ft2" \| "m2"?` | Unit of `targetArea` (defaults to the project's area units) |
- */
-export const PluginProgramLabelsSetTargetAreaArgs = z.object({
-  labelId: z.string(),
-  targetArea: z.number().finite().nonnegative(),
-  units: PluginAreaUnit.optional(),
-})
-export type PluginProgramLabelsSetTargetAreaArgs = z.infer<
-  typeof PluginProgramLabelsSetTargetAreaArgs
->
-
-/** Result of {@linkcode PluginProgramLabelsApi.setTargetArea} — the updated record with `units`. */
-export const PluginProgramLabelsSetTargetAreaResult = PluginProgramLabelRecord
-export type PluginProgramLabelsSetTargetAreaResult = z.infer<
-  typeof PluginProgramLabelsSetTargetAreaResult
->
-
-/**
- * Arguments for {@linkcode PluginProgramLabelsApi.setTargetCount}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `labelId` | `string` | The label whose count to set |
- * | `targetCount` | `number` | Target number of units (non-negative integer) |
- */
-export const PluginProgramLabelsSetTargetCountArgs = z.object({
-  labelId: z.string(),
-  targetCount: z.number().int().nonnegative(),
-})
-export type PluginProgramLabelsSetTargetCountArgs = z.infer<
-  typeof PluginProgramLabelsSetTargetCountArgs
->
-
-/** Result of {@linkcode PluginProgramLabelsApi.setTargetCount} — the updated record with `units`. */
-export const PluginProgramLabelsSetTargetCountResult = PluginProgramLabelRecord
-export type PluginProgramLabelsSetTargetCountResult = z.infer<
-  typeof PluginProgramLabelsSetTargetCountResult
->
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+import { PluginAreaUnit } from "./metrics"
+
+/**
+ * Program labels — the **program rows** of the active program: each label is a
+ * named space type (e.g. "Exam Room", "Nurse Station") inside a department,
+ * carrying an area **target** and a unit **count** target.
+ *
+ * Labels are the non-department planning entities of program mode. A
+ * department groups labels; a label groups the spaces (masses) that realize it.
+ * Target areas live on **departments** ({@linkcode PluginProgramDepartmentsApi.setTargetArea})
+ * and on **labels** (this namespace) — an individual space carries no target of
+ * its own; it inherits its label's `targetArea / targetCount`. Program Blocks
+ * (spaces whose space type is "Program Block") are likewise targeted through
+ * their label.
+ *
+ * `targetArea` is the label's **total** target (all units), in the response's
+ * `units`; the per-unit target is `targetArea / targetCount`.
+ *
+ * Reads never throw for a miss (`get` returns `null`, `list` returns `[]`).
+ * Writes are undoable and autosaved; when the project has proposals they write
+ * the **active proposal's** targets.
+ *
+ * Accessed via `snaptrude.program.labels`.
+ */
+export abstract class PluginProgramLabelsApi {
+  constructor() {}
+
+  /**
+   * List the labels (program rows) of the active program.
+   *
+   * @returns A {@linkcode PluginProgramLabelsListResult} with `units` and a
+   *   `labels` array (empty when the project has none).
+   *
+   * @examplePrompt List all the program rows with their target areas
+   * @examplePrompt What space labels are in the program and how many of each?
+   * @examplePrompt Show every label with its department and target
+   *
+   * # Example
+   * ```ts
+   * const { units, labels } = await snaptrude.program.labels.list()
+   * for (const l of labels) console.log(l.name, l.targetArea, units, l.targetCount)
+   * ```
+   */
+  public abstract list(): PluginApiReturn<PluginProgramLabelsListResult>
+
+  /**
+   * Get a single label by id.
+   *
+   * @param labelId - The id of the label to read.
+   * @returns The matching {@linkcode PluginProgramLabelRecord} (with `units`), or
+   *   `null` if no label has that id.
+   *
+   * @examplePrompt Get the label with id lbl_12
+   * @examplePrompt What is the target area of this program row?
+   *
+   * # Example
+   * ```ts
+   * const label = await snaptrude.program.labels.get("lbl_12")
+   * if (label) console.log(label.name, label.targetArea, label.units)
+   * ```
+   */
+  public abstract get(
+    labelId: string,
+  ): PluginApiReturn<PluginProgramLabelsGetResult>
+
+  /**
+   * Create labels (program rows), optionally creating their spaces too.
+   *
+   * Each item names a label and its targets. A label is unique per
+   * (`name`, department); an item matching an existing label **updates** that
+   * label's targets instead of duplicating it. Unknown departments are created
+   * by name when `departmentName` is given; omit both department fields for the
+   * Default department.
+   *
+   * By default only the program rows are created (targets to plan against).
+   * Pass `createSpaces: true` to also instantiate `targetCount` massing spaces
+   * per label on the canvas, laid out automatically — the same path Program
+   * Mode's CSV/Interpret import uses.
+   *
+   * @param items - The labels to create (1–500).
+   * @param options - Optional `units` for every `targetArea` (defaults to the
+   *   project's area units) and `createSpaces` (default `false`).
+   * @returns A {@linkcode PluginProgramLabelsCreateResult} with the created or
+   *   updated label ids, in input order.
+   * @throws If an item's `departmentId` does not exist.
+   *
+   * @examplePrompt Add program rows for 4 exam rooms of 120 sqft each
+   * @examplePrompt Create the labels from this interpreted program
+   * @examplePrompt Add an Office label with a 2000 sqft target to the Admin department
+   * @examplePrompt Create program rows and their spaces on the canvas
+   *
+   * # Example
+   * ```ts
+   * const { labelIds } = await snaptrude.program.labels.create(
+   *   [{ name: "Exam Room", targetArea: 480, targetCount: 4, departmentName: "Clinic" }],
+   *   { units: "ft2" },
+   * )
+   * ```
+   */
+  public abstract create(
+    items: PluginProgramLabelCreateItem[],
+    options?: { units?: PluginAreaUnit; createSpaces?: boolean },
+  ): PluginApiReturn<PluginProgramLabelsCreateResult>
+
+  /**
+   * Set a label's total target area.
+   *
+   * The goal the program metrics compare the label's allocated area against.
+   * Pass `units` to say what unit `targetArea` is in; it defaults to the
+   * project's area units. Read it back with {@linkcode PluginProgramLabelsApi.get}.
+   *
+   * @param labelId - The id of the label whose target to set.
+   * @param targetArea - The total target area (all units), in `units`.
+   * @param units - Unit of `targetArea` (defaults to the project's area units).
+   * @returns The updated {@linkcode PluginProgramLabelRecord} with its `units`.
+   * @throws If no label has the given id.
+   *
+   * @examplePrompt Set the Exam Room target area to 480 sqft
+   * @examplePrompt Give the Corridor program row a 150 sqm target
+   * @examplePrompt Update the area target for label lbl_12
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.program.labels.setTargetArea("lbl_12", 480, "ft2")
+   * ```
+   */
+  public abstract setTargetArea(
+    labelId: string,
+    targetArea: number,
+    units?: PluginAreaUnit,
+  ): PluginApiReturn<PluginProgramLabelsSetTargetAreaResult>
+
+  /**
+   * Set a label's target unit count (how many of this space the program calls for).
+   *
+   * @param labelId - The id of the label whose count to set.
+   * @param targetCount - The target number of units (a non-negative integer).
+   * @returns The updated {@linkcode PluginProgramLabelRecord} with its `units`.
+   * @throws If no label has the given id.
+   *
+   * @examplePrompt Set the Exam Room count to 6
+   * @examplePrompt The program needs 12 patient rooms — update the count
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.program.labels.setTargetCount("lbl_12", 6)
+   * ```
+   */
+  public abstract setTargetCount(
+    labelId: string,
+    targetCount: number,
+  ): PluginApiReturn<PluginProgramLabelsSetTargetCountResult>
+}
+
+/**
+ * A label (program row) in the active program. `targetArea` is the label's
+ * **total** target in the enclosing response's `units`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Stable label id |
+ * | `name` | `string` | Label (space type) name |
+ * | `color` | `string` | CSS hex color string |
+ * | `departmentId` | `string` | Id of the department the label belongs to |
+ * | `targetArea` | `number \| null` | Total target area (all units), or `null` when no target is set |
+ * | `targetCount` | `number` | Target number of units (`0` when unset) |
+ * | `storey` | `number \| null` | Default storey new spaces of this label are placed on |
+ */
+export const PluginProgramLabel = z.object({
+  id: z.string(),
+  name: z.string(),
+  color: z.string(),
+  departmentId: z.string(),
+  targetArea: z.number().nullable(),
+  targetCount: z.number(),
+  storey: z.number().nullable(),
+})
+export type PluginProgramLabel = z.infer<typeof PluginProgramLabel>
+
+/** A bare label record carrying its area `units` (per the area-units convention). */
+export const PluginProgramLabelRecord = PluginProgramLabel.extend({
+  units: PluginAreaUnit,
+})
+export type PluginProgramLabelRecord = z.infer<typeof PluginProgramLabelRecord>
+
+/**
+ * Result of {@linkcode PluginProgramLabelsApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `units` | `"ft2" \| "m2"` | The unit every `targetArea` below is reported in |
+ * | `labels` | {@linkcode PluginProgramLabel}`[]` | All labels in the active program |
+ */
+export const PluginProgramLabelsListResult = z.object({
+  units: PluginAreaUnit,
+  labels: z.array(PluginProgramLabel),
+})
+export type PluginProgramLabelsListResult = z.infer<
+  typeof PluginProgramLabelsListResult
+>
+
+/** Arguments for {@linkcode PluginProgramLabelsApi.get}. */
+export const PluginProgramLabelsGetArgs = z.object({
+  labelId: z.string(),
+})
+export type PluginProgramLabelsGetArgs = z.infer<
+  typeof PluginProgramLabelsGetArgs
+>
+
+/** Result of {@linkcode PluginProgramLabelsApi.get} — the record with `units`, or `null`. */
+export const PluginProgramLabelsGetResult = PluginProgramLabelRecord.nullable()
+export type PluginProgramLabelsGetResult = z.infer<
+  typeof PluginProgramLabelsGetResult
+>
+
+/**
+ * One label to create via {@linkcode PluginProgramLabelsApi.create}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string` | Label (space type) name |
+ * | `targetArea` | `number?` | Total target area (all units), in the call's `units` |
+ * | `targetCount` | `number?` | Target number of units (default `1`) |
+ * | `departmentId` | `string?` | Existing department to file the label under |
+ * | `departmentName` | `string?` | Department by name — created when it does not exist (ignored when `departmentId` is given) |
+ * | `color` | `string?` | CSS hex color (a light color is generated when omitted) |
+ * | `storey` | `number?` | Storey for spaces of this label (default `1`) |
+ * | `height` | `number?` | Space height in project length units (for `createSpaces`) |
+ * | `width` | `number?` | Space width in project length units (for `createSpaces`) |
+ */
+export const PluginProgramLabelCreateItem = z.object({
+  name: z.string().trim().min(1),
+  targetArea: z.number().finite().nonnegative().optional(),
+  targetCount: z.number().int().nonnegative().optional(),
+  departmentId: z.string().optional(),
+  departmentName: z.string().optional(),
+  color: z.string().optional(),
+  storey: z.number().int().optional(),
+  height: z.number().finite().positive().optional(),
+  width: z.number().finite().positive().optional(),
+})
+export type PluginProgramLabelCreateItem = z.infer<
+  typeof PluginProgramLabelCreateItem
+>
+
+/** Maximum items per {@linkcode PluginProgramLabelsApi.create} call. */
+export const PLUGIN_PROGRAM_LABELS_BATCH_LIMIT = 500
+
+/**
+ * Arguments for {@linkcode PluginProgramLabelsApi.create}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `items` | {@linkcode PluginProgramLabelCreateItem}`[]` | 1–500 labels |
+ * | `units` | `"ft2" \| "m2"?` | Unit of every `targetArea` (defaults to the project's area units) |
+ * | `createSpaces` | `boolean?` | Also create `targetCount` spaces per label on the canvas (default `false`) |
+ */
+export const PluginProgramLabelsCreateArgs = z.object({
+  items: z
+    .array(PluginProgramLabelCreateItem)
+    .min(1)
+    .max(PLUGIN_PROGRAM_LABELS_BATCH_LIMIT),
+  units: PluginAreaUnit.optional(),
+  createSpaces: z.boolean().optional(),
+})
+export type PluginProgramLabelsCreateArgs = z.infer<
+  typeof PluginProgramLabelsCreateArgs
+>
+
+/**
+ * Result of {@linkcode PluginProgramLabelsApi.create}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `labelIds` | `string[]` | The created (or updated) label ids, in input order |
+ * | `createdSpaces` | `boolean` | Whether spaces were also created on the canvas |
+ */
+export const PluginProgramLabelsCreateResult = z.object({
+  labelIds: z.array(z.string()),
+  createdSpaces: z.boolean(),
+})
+export type PluginProgramLabelsCreateResult = z.infer<
+  typeof PluginProgramLabelsCreateResult
+>
+
+/**
+ * Arguments for {@linkcode PluginProgramLabelsApi.setTargetArea}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `labelId` | `string` | The label whose target to set |
+ * | `targetArea` | `number` | Total target area, in `units` |
+ * | `units` | `"ft2" \| "m2"?` | Unit of `targetArea` (defaults to the project's area units) |
+ */
+export const PluginProgramLabelsSetTargetAreaArgs = z.object({
+  labelId: z.string(),
+  targetArea: z.number().finite().nonnegative(),
+  units: PluginAreaUnit.optional(),
+})
+export type PluginProgramLabelsSetTargetAreaArgs = z.infer<
+  typeof PluginProgramLabelsSetTargetAreaArgs
+>
+
+/** Result of {@linkcode PluginProgramLabelsApi.setTargetArea} — the updated record with `units`. */
+export const PluginProgramLabelsSetTargetAreaResult = PluginProgramLabelRecord
+export type PluginProgramLabelsSetTargetAreaResult = z.infer<
+  typeof PluginProgramLabelsSetTargetAreaResult
+>
+
+/**
+ * Arguments for {@linkcode PluginProgramLabelsApi.setTargetCount}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `labelId` | `string` | The label whose count to set |
+ * | `targetCount` | `number` | Target number of units (non-negative integer) |
+ */
+export const PluginProgramLabelsSetTargetCountArgs = z.object({
+  labelId: z.string(),
+  targetCount: z.number().int().nonnegative(),
+})
+export type PluginProgramLabelsSetTargetCountArgs = z.infer<
+  typeof PluginProgramLabelsSetTargetCountArgs
+>
+
+/** Result of {@linkcode PluginProgramLabelsApi.setTargetCount} — the updated record with `units`. */
+export const PluginProgramLabelsSetTargetCountResult = PluginProgramLabelRecord
+export type PluginProgramLabelsSetTargetCountResult = z.infer<
+  typeof PluginProgramLabelsSetTargetCountResult
+>