@snaptrude/plugin-core 0.3.0 → 0.6.0

package/src/api/program/adjacency.ts

@@ -0,0 +1,164 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+
+/**
+ * Program adjacency — the proximity relationships between departments or
+ * spaces.
+ *
+ * Adjacency is stage one of the product's space-planning workflow (compute →
+ * arrange → pack): the AI service scores which program elements need to be
+ * near each other, and the geometry contributes physical contact. Cell values:
+ *
+ * | Value | Meaning |
+ * |---|---|
+ * | `2` | Direct — adjacency required |
+ * | `1` | Indirect — nearby preferred, or physical contact |
+ * | `-1` | Restricted — must NOT be adjacent |
+ * | `0` | No relationship — or adjacency was never computed |
+ *
+ * Zeros are ambiguous **by design** (the engine cannot distinguish "no
+ * relationship" from "never computed"): call
+ * {@linkcode PluginProgramAdjacencyApi.compute} first when you need fresh
+ * data. Persisted matrices auto-hydrate on scene load, so warm reads are the
+ * common case. The arrange/pack stages of the workflow live in
+ * {@linkcode PluginProgramLayoutApi} (`program.layout`).
+ *
+ * Accessed via `snaptrude.program.adjacency`.
+ */
+export abstract class PluginProgramAdjacencyApi {
+  constructor() {}
+
+  /**
+   * Read the adjacency matrix at the department or space level.
+   *
+   * Returns a square `matrix` whose rows/columns are aligned to `ids`
+   * (component ids). Pass `ids` to read a sub-matrix in that order; omit it to
+   * get every eligible element at that level. Cell values:
+   *
+   * | Value | Meaning |
+   * |---|---|
+   * | `2` | Direct — adjacency required |
+   * | `1` | Indirect — nearby preferred, or physical contact |
+   * | `-1` | Restricted — must NOT be adjacent |
+   * | `0` | No relationship — or adjacency was never computed |
+   *
+   * Zeros are ambiguous by design — call
+   * {@linkcode PluginProgramAdjacencyApi.compute} first for fresh data
+   * (persisted matrices auto-hydrate on scene load, so warm reads are the
+   * common case). Space-level relationships are computed within a storey:
+   * cross-storey pairs always read `0`. At the `department` level the result
+   * also carries `departmentIds`, a parallel array joining each row to the
+   * department entity ids returned by `program.departments.list` (the row
+   * `ids` are department-mass component ids, not department entity ids).
+   *
+   * @param level - Read the `"department"` or `"space"` matrix.
+   * @param ids - Component ids to read a sub-matrix for, in this order
+   *   (defaults to every eligible element at the level).
+   * @returns A {@linkcode PluginProgramAdjacencyGetMatrixResult} with `ids`,
+   *   the square `matrix`, and (at department level) `departmentIds`.
+   * @throws If an id is unknown or does not match the requested level.
+   *
+   * @examplePrompt Get the space adjacency matrix
+   * @examplePrompt Which departments must be adjacent?
+   * @examplePrompt Show the adjacency relationships between departments
+   * @examplePrompt Read the adjacency matrix for these spaces
+   * @examplePrompt Which rooms are restricted from being next to each other?
+   *
+   * # Example
+   * ```ts
+   * const { ids, matrix } = await snaptrude.program.adjacency.getMatrix("department")
+   * ```
+   */
+  public abstract getMatrix(
+    level: PluginAdjacencyLevel,
+    ids?: string[],
+  ): PluginApiReturn<PluginProgramAdjacencyGetMatrixResult>
+
+  /**
+   * Compute (or refresh) the adjacency data for the project.
+   *
+   * Runs the AI adjacency precompute and persists the result; a no-op when
+   * the stored data is already fresh. A real run takes **~2s at minimum**
+   * (engine pacing) plus the AI service round-trip. This is a write (it
+   * mutates and persists project analysis data), so it is blocked when plugin
+   * writes are disabled.
+   *
+   * @returns A {@linkcode PluginProgramAdjacencyComputeResult} —
+   *   `{ success: true }` when the data is fresh or the run completed;
+   *   `{ success: false, error }` when the AI service could not be reached.
+   *
+   * @examplePrompt Refresh adjacency analysis
+   * @examplePrompt Compute the adjacency matrix for this project
+   * @examplePrompt Recalculate which departments should be adjacent
+   *
+   * # Example
+   * ```ts
+   * const { success } = await snaptrude.program.adjacency.compute()
+   * if (success) {
+   *   const data = await snaptrude.program.adjacency.getMatrix("space")
+   * }
+   * ```
+   */
+  public abstract compute(): PluginApiReturn<PluginProgramAdjacencyComputeResult>
+}
+
+/**
+ * The level an adjacency matrix is read at.
+ *
+ * | Value | Description |
+ * |---|---|
+ * | `"department"` | One row/column per department mass |
+ * | `"space"` | One row/column per space (within a storey) |
+ */
+export const PluginAdjacencyLevel = z.enum(["department", "space"])
+export type PluginAdjacencyLevel = z.infer<typeof PluginAdjacencyLevel>
+
+/**
+ * Arguments for {@linkcode PluginProgramAdjacencyApi.getMatrix}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `level` | {@linkcode PluginAdjacencyLevel} | Read the `"department"` or `"space"` matrix |
+ * | `ids` | `string[] \| undefined` | Component ids to read a sub-matrix for, in this order (defaults to every eligible element at the level) |
+ */
+export const PluginProgramAdjacencyGetMatrixArgs = z.object({
+  level: PluginAdjacencyLevel,
+  ids: z.array(z.string()).optional(),
+})
+export type PluginProgramAdjacencyGetMatrixArgs = z.infer<
+  typeof PluginProgramAdjacencyGetMatrixArgs
+>
+
+/**
+ * Result of {@linkcode PluginProgramAdjacencyApi.getMatrix}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `ids` | `string[]` | Component ids, in matrix row/column order |
+ * | `departmentIds` | `(string \| null)[] \| undefined` | Department level only: parallel to `ids`, the department entity id each row belongs to (joinable against `program.departments.list`), `null` when unassigned |
+ * | `matrix` | `number[][]` | Square matrix aligned to `ids`; values in `{-1, 0, 1, 2}` |
+ */
+export const PluginProgramAdjacencyGetMatrixResult = z.object({
+  ids: z.array(z.string()),
+  departmentIds: z.array(z.string().nullable()).optional(),
+  matrix: z.array(z.array(z.number())),
+})
+export type PluginProgramAdjacencyGetMatrixResult = z.infer<
+  typeof PluginProgramAdjacencyGetMatrixResult
+>
+
+/**
+ * Result of {@linkcode PluginProgramAdjacencyApi.compute}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `success` | `boolean` | `true` when the data is fresh or the run completed |
+ * | `error` | `string \| undefined` | Failure reason when `success` is `false` |
+ */
+export const PluginProgramAdjacencyComputeResult = z.object({
+  success: z.boolean(),
+  error: z.string().optional(),
+})
+export type PluginProgramAdjacencyComputeResult = z.infer<
+  typeof PluginProgramAdjacencyComputeResult
+>

package/src/api/program/areas.ts

@@ -0,0 +1,335 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+import { PluginAreaUnit } from "./metrics"
+import { ComponentHandle } from "../../handles"
+
+/**
+ * Program areas — the FAR / built-up-area rollup for the active program.
+ *
+ * This is the zoning-compliance lens on the model: carpet / built-up / excluded
+ * area totals, the site area, and the achieved-vs-target **FAR** (Floor Area
+ * Ratio). It complements {@linkcode PluginProgramMetricsApi}, which is the
+ * department-allocation lens (targets vs allocated area per department); this
+ * namespace is the whole-program area/FAR summary and its groupings.
+ *
+ * `achievedFar` is **derived and read-only** — computed from built-up area and
+ * site area. `targetFar` is the goal you set (via {@linkcode
+ * PluginProgramAreasApi.update}); the two are the same ratio, one measured and
+ * one intended. The surface speaks **FAR only** — there is no FSI alias.
+ *
+ * Reads return plain records and never throw. The write member typed as optional
+ * (`?`) is **authored ahead of the host** — declared so plugins and codegen can
+ * see the shape, but kept out of the discovery manifest until the host lands it
+ * (at which point it is promoted to a required `abstract` member).
+ *
+ * Accessed via `snaptrude.program.areas`.
+ */
+export abstract class PluginProgramAreasApi {
+  constructor() {}
+
+  /**
+   * Get the program area summary.
+   *
+   * Returns the whole-program totals — carpet / built-up / excluded area, site
+   * area, and achieved vs target FAR — with the area unit they are reported in.
+   *
+   * @returns A {@linkcode PluginProgramAreaSummary}. `achievedFar` is `null` when
+   *   the site area or target FAR is not set.
+   *
+   * @examplePrompt What's my FAR right now?
+   * @examplePrompt Give me the program area summary
+   * @examplePrompt How much built-up area have I used against the site area?
+   * @examplePrompt Am I within my FAR target?
+   *
+   * # Example
+   * ```ts
+   * const s = await snaptrude.program.areas.get()
+   * console.log(s.builtUp, s.siteArea, s.achievedFar, s.targetFar, s.areaUnit)
+   * ```
+   */
+  public abstract get(): PluginApiReturn<PluginProgramAreasGetResult>
+
+  /**
+   * List the program area rollup grouped by a facet.
+   *
+   * Breaks the program's area totals into buckets — by label, storey, building,
+   * department, or tag category.
+   *
+   * @param groupBy - The facet to group by (a {@linkcode PluginProgramAreaGroupBy}).
+   * @param categoryId - The tag category to group by (required when `groupBy` is
+   *   `"tagCategories"`).
+   * @returns A {@linkcode PluginProgramAreasListResult} with a `groups` array
+   *   (empty when the program has no spaces).
+   *
+   * @examplePrompt Break down the area by storey
+   * @examplePrompt Show the area rollup per department
+   * @examplePrompt Group the built-up area by building
+   *
+   * # Example
+   * ```ts
+   * const { groups } = await snaptrude.program.areas.list("storeys")
+   * for (const g of groups) console.log(g.name, g.builtUp, g.count)
+   * ```
+   */
+  public abstract list(
+    groupBy: PluginProgramAreaGroupBy,
+    categoryId?: string,
+  ): PluginApiReturn<PluginProgramAreasListResult>
+
+  /**
+   * List the spaces that make up one area group.
+   *
+   * Drills into a single bucket returned by {@linkcode
+   * PluginProgramAreasApi.list} and returns its member spaces with their per-space
+   * area figures.
+   *
+   * @param groupBy - The same facet used to produce the group (a {@linkcode
+   *   PluginProgramAreaGroupBy}).
+   * @param groupId - The id of the group to expand.
+   * @param categoryId - The tag category context (required when `groupBy` is
+   *   `"tagCategories"`).
+   * @returns A {@linkcode PluginProgramAreasListMembersResult} with a `members`
+   *   array (empty when the group is missing or empty).
+   *
+   * @examplePrompt List the spaces on this storey with their areas
+   * @examplePrompt What rooms are in the Bedrooms department bucket?
+   * @examplePrompt Break the storey area down into individual spaces
+   *
+   * # Example
+   * ```ts
+   * const { members } = await snaptrude.program.areas.listMembers("storeys", "st_2")
+   * for (const m of members) console.log(m.label, m.carpet)
+   * ```
+   */
+  public abstract listMembers(
+    groupBy: PluginProgramAreaGroupBy,
+    groupId: string,
+    categoryId?: string,
+  ): PluginApiReturn<PluginProgramAreasListMembersResult>
+
+  /**
+   * Update the program's FAR settings.
+   *
+   * A **sparse** update of the program-level FAR inputs — target FAR, the site
+   * area, and the allowed deviation. This is a **non-undoable settings write**
+   * (persisted with the project). `achievedFar` recomputes from these.
+   *
+   * @param options - Any of `targetFar`, `siteArea`, `deviation`; omitted fields
+   *   are left unchanged.
+   * @returns The recomputed {@linkcode PluginProgramAreaSummary}.
+   * @throws If a value is out of range.
+   *
+   * @examplePrompt Set the target FAR to 2.5
+   * @examplePrompt Override the site area to 5000
+   * @examplePrompt Allow a 10 percent FAR deviation
+   *
+   * # Example
+   * ```ts
+   * const s = await snaptrude.program.areas.update({ targetFar: 2.5 })
+   * console.log(s.achievedFar, s.targetFar)
+   * ```
+   */
+  public abstract update(
+    options?: { targetFar?: number; siteArea?: number; deviation?: number },
+  ): PluginApiReturn<PluginProgramAreasUpdateResult>
+}
+
+/**
+ * The whole-program area / FAR summary. All area figures are in `areaUnit`;
+ * ratios (`achievedFar`, `targetFar`, `deviation`) are unitless.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `count` | `number` | Number of spaces in the program (a count, not an area) |
+ * | `hiddenCount` | `number` | Number of those spaces that are currently hidden |
+ * | `carpet` | `number` | Total carpet area in `areaUnit` |
+ * | `builtUp` | `number` | Total built-up area in `areaUnit` |
+ * | `excluded` | `number` | Total excluded area in `areaUnit` |
+ * | `farBuiltUp` | `number` | Built-up area that counts toward FAR, in `areaUnit` |
+ * | `siteArea` | `number` | Site/plot area in `areaUnit` |
+ * | `achievedFar` | `number \| null` | Derived FAR (`farBuiltUp / siteArea`); `null` when site area or target FAR is unset |
+ * | `targetFar` | `number` | The target FAR goal (set via `update`) |
+ * | `deviation` | `number` | Allowed FAR deviation, as a percentage |
+ * | `areaUnit` | `"ft2" \| "m2"` | The unit every area figure above is reported in |
+ */
+export const PluginProgramAreaSummary = z.object({
+  count: z.number().int(),
+  hiddenCount: z.number().int(),
+  carpet: z.number(),
+  builtUp: z.number(),
+  excluded: z.number(),
+  farBuiltUp: z.number(),
+  siteArea: z.number(),
+  achievedFar: z.number().nullable(),
+  targetFar: z.number(),
+  deviation: z.number(),
+  areaUnit: PluginAreaUnit,
+})
+export type PluginProgramAreaSummary = z.infer<typeof PluginProgramAreaSummary>
+
+/**
+ * One bucket of the area rollup. Carpet / built-up / excluded figures are in the
+ * program's area unit (see {@linkcode PluginProgramAreaSummary.areaUnit});
+ * `targetArea` is in `targetUnit`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `groupId` | `string` | Stable id of the group (e.g. storey id, department id) |
+ * | `name` | `string` | Display name of the group |
+ * | `color` | `string` | CSS hex color string for the group |
+ * | `carpet` | `number` | Carpet area for this group |
+ * | `builtUp` | `number` | Built-up area for this group |
+ * | `excluded` | `number` | Excluded area for this group |
+ * | `count` | `number` | Number of spaces in this group |
+ * | `targetArea` | `number` | Target area for this group, in `targetUnit` |
+ * | `targetUnit` | `"ft2" \| "m2"` | The unit `targetArea` is reported in |
+ */
+export const PluginProgramAreaGroup = z.object({
+  groupId: z.string(),
+  name: z.string(),
+  color: z.string(),
+  carpet: z.number(),
+  builtUp: z.number(),
+  excluded: z.number(),
+  count: z.number().int(),
+  targetArea: z.number(),
+  targetUnit: PluginAreaUnit,
+})
+export type PluginProgramAreaGroup = z.infer<typeof PluginProgramAreaGroup>
+
+/**
+ * A single space within an area group. Area figures are in the program's area
+ * unit (see {@linkcode PluginProgramAreaSummary.areaUnit}).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `ComponentHandle` | `Component.id` of the space (never a mesh handle) |
+ * | `label` | `string` | Display label of the space |
+ * | `carpet` | `number` | Carpet area of the space |
+ * | `builtUp` | `number` | Built-up area of the space |
+ * | `excluded` | `number` | Excluded area of the space |
+ * | `isVisible` | `boolean` | Whether the space is currently visible |
+ */
+export const PluginProgramAreaMember = z.object({
+  id: ComponentHandle,
+  label: z.string(),
+  carpet: z.number(),
+  builtUp: z.number(),
+  excluded: z.number(),
+  isVisible: z.boolean(),
+})
+export type PluginProgramAreaMember = z.infer<typeof PluginProgramAreaMember>
+
+/** The facet to group the area rollup by. */
+export const PluginProgramAreaGroupBy = z.enum([
+  "labels",
+  "storeys",
+  "buildings",
+  "departments",
+  "tagCategories",
+])
+export type PluginProgramAreaGroupBy = z.infer<typeof PluginProgramAreaGroupBy>
+
+/** Result of {@linkcode PluginProgramAreasApi.get} — the program area summary. */
+export const PluginProgramAreasGetResult = PluginProgramAreaSummary
+export type PluginProgramAreasGetResult = z.infer<
+  typeof PluginProgramAreasGetResult
+>
+
+/**
+ * Arguments for {@linkcode PluginProgramAreasApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `groupBy` | {@linkcode PluginProgramAreaGroupBy} | The facet to group by |
+ * | `categoryId` | `string \| undefined` | Tag category to group by; required when `groupBy` is `"tagCategories"` |
+ */
+export const PluginProgramAreasListArgs = z
+  .object({
+    groupBy: PluginProgramAreaGroupBy,
+    categoryId: z.string().optional(),
+  })
+  .refine((v) => v.groupBy !== "tagCategories" || v.categoryId != null, {
+    message: 'categoryId is required when groupBy is "tagCategories"',
+  })
+export type PluginProgramAreasListArgs = z.infer<
+  typeof PluginProgramAreasListArgs
+>
+
+/**
+ * Result of {@linkcode PluginProgramAreasApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `groups` | {@linkcode PluginProgramAreaGroup}`[]` | The area buckets (empty when the program has no spaces) |
+ */
+export const PluginProgramAreasListResult = z.object({
+  groups: z.array(PluginProgramAreaGroup),
+})
+export type PluginProgramAreasListResult = z.infer<
+  typeof PluginProgramAreasListResult
+>
+
+/**
+ * Arguments for {@linkcode PluginProgramAreasApi.listMembers}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `groupBy` | {@linkcode PluginProgramAreaGroupBy} | The facet the group came from |
+ * | `groupId` | `string` | The id of the group to expand |
+ * | `categoryId` | `string \| undefined` | Tag category context; required when `groupBy` is `"tagCategories"` |
+ */
+export const PluginProgramAreasListMembersArgs = z
+  .object({
+    groupBy: PluginProgramAreaGroupBy,
+    groupId: z.string(),
+    categoryId: z.string().optional(),
+  })
+  .refine((v) => v.groupBy !== "tagCategories" || v.categoryId != null, {
+    message: 'categoryId is required when groupBy is "tagCategories"',
+  })
+export type PluginProgramAreasListMembersArgs = z.infer<
+  typeof PluginProgramAreasListMembersArgs
+>
+
+/**
+ * Result of {@linkcode PluginProgramAreasApi.listMembers}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `members` | {@linkcode PluginProgramAreaMember}`[]` | The group's member spaces (empty when missing or empty) |
+ */
+export const PluginProgramAreasListMembersResult = z.object({
+  members: z.array(PluginProgramAreaMember),
+})
+export type PluginProgramAreasListMembersResult = z.infer<
+  typeof PluginProgramAreasListMembersResult
+>
+
+/**
+ * Arguments for {@linkcode PluginProgramAreasApi.update}. Sparse — only the
+ * provided fields are changed.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `targetFar` | `number \| undefined` | New target FAR (≥ 0) |
+ * | `siteArea` | `number \| undefined` | Site-area override (> 0), in the program's area unit |
+ * | `deviation` | `number \| undefined` | Allowed FAR deviation percentage (0–100) |
+ */
+export const PluginProgramAreasUpdateArgs = z.object({
+  targetFar: z.number().min(0).optional(),
+  siteArea: z.number().positive().optional(),
+  deviation: z.number().min(0).max(100).optional(),
+})
+export type PluginProgramAreasUpdateArgs = z.infer<
+  typeof PluginProgramAreasUpdateArgs
+>
+
+/**
+ * Result of {@linkcode PluginProgramAreasApi.update} — the recomputed program
+ * area summary.
+ */
+export const PluginProgramAreasUpdateResult = PluginProgramAreaSummary
+export type PluginProgramAreasUpdateResult = z.infer<
+  typeof PluginProgramAreasUpdateResult
+>

package/src/api/program/classification.ts

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