@snaptrude/plugin-core 0.9.7 → 0.9.9

package/src/api/program/labels.ts

@@ -0,0 +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
+>

package/src/api/program/metadata.ts

@@ -0,0 +1,364 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+import { ComponentHandle } from "../../handles"
+import { PluginSpreadsheetCell } from "./spreadsheet"
+
+/**
+ * Program metadata — the user-defined **custom columns** of the Program Data
+ * sheet and their per-space values.
+ *
+ * In program mode a **metadata header** is a custom column (e.g. "Department
+ * Code", "Occupancy", "Finish Level") added to the Program Data sheet; every
+ * space can then carry one **value** per header. This is the same store the
+ * Program tab reads and writes — values set here appear in the default Program
+ * Data sheet and in every custom sheet that shows the column, and values typed
+ * into the sheet are read back here. The store lives in the editor, so **no
+ * method in this namespace needs the Program tab open**.
+ *
+ * Headers are identified by a stable `headerId`. Values are plain cells
+ * (`string | number | boolean | null`); `null` clears a value. Departments and
+ * labels also carry metadata in the engine, but this namespace covers **spaces**
+ * (Mass/Floor components) — the per-space case plugins asked for.
+ *
+ * Reads never throw for a miss (`get` returns `null`, `list*` return `[]`).
+ * Writes are undoable and autosaved.
+ *
+ * Accessed via `snaptrude.program.metadata`.
+ */
+export abstract class PluginProgramMetadataApi {
+  constructor() {}
+
+  /**
+   * List the metadata headers (custom columns) of the Program Data sheet.
+   *
+   * @returns A {@linkcode PluginProgramMetadataListHeadersResult} with a
+   *   `headers` array (empty when the project has no custom columns).
+   *
+   * @examplePrompt List the custom metadata columns in program mode
+   * @examplePrompt What metadata headers does the program sheet have?
+   * @examplePrompt Show every custom column with its id
+   *
+   * # Example
+   * ```ts
+   * const { headers } = await snaptrude.program.metadata.listHeaders()
+   * for (const h of headers) console.log(h.headerId, h.name)
+   * ```
+   */
+  public abstract listHeaders(): PluginApiReturn<PluginProgramMetadataListHeadersResult>
+
+  /**
+   * Create a metadata header (a custom column on the Program Data sheet).
+   *
+   * Header names are unique per sheet: when a header with the same name already
+   * exists it is **reused** and returned (no duplicate column is created), so
+   * re-running a plugin is safe. The new column is appended after the sheet's
+   * existing custom columns.
+   *
+   * @param name - Column header text (non-empty).
+   * @param options - Optional `description` shown in the column's description
+   *   row.
+   * @returns The created (or reused) {@linkcode PluginProgramMetadataHeader}.
+   * @throws If `name` is blank.
+   *
+   * @examplePrompt Add a custom column called Occupancy to the program sheet
+   * @examplePrompt Create a metadata header named Department Code
+   * @examplePrompt Make a new program-mode column for Finish Level
+   *
+   * # Example
+   * ```ts
+   * const header = await snaptrude.program.metadata.createHeader("Occupancy", {
+   *   description: "People per room",
+   * })
+   * ```
+   */
+  public abstract createHeader(
+    name: string,
+    options?: { description?: string },
+  ): PluginApiReturn<PluginProgramMetadataCreateHeaderResult>
+
+  /**
+   * Get one space's metadata values, keyed by header id.
+   *
+   * @param spaceId - The space (component id) to read.
+   * @returns A {@linkcode PluginProgramMetadataRecord} — `values` holds one entry
+   *   per header the space has a value for — or `null` when no space has that id.
+   *
+   * @examplePrompt Get the metadata on this space
+   * @examplePrompt Read the custom column values for space sp_12
+   * @examplePrompt What is this room's Occupancy metadata?
+   *
+   * # Example
+   * ```ts
+   * const record = await snaptrude.program.metadata.get("sp_12")
+   * if (record) console.log(record.values)
+   * ```
+   */
+  public abstract get(
+    spaceId: ComponentHandle,
+  ): PluginApiReturn<PluginProgramMetadataGetResult>
+
+  /**
+   * List metadata values for many spaces at once.
+   *
+   * Pass `spaceIds` to read specific spaces (unknown ids are skipped), or omit
+   * it to read every space in the project. One host round-trip regardless of
+   * the number of spaces — prefer this over calling
+   * {@linkcode PluginProgramMetadataApi.get} in a loop.
+   *
+   * @param spaceIds - Optional space ids to read; omit for all spaces.
+   * @returns A {@linkcode PluginProgramMetadataListResult} with one
+   *   {@linkcode PluginProgramMetadataRecord} per space.
+   *
+   * @performance One round-trip for any number of spaces — use this instead of a `get` loop.
+   *
+   * @examplePrompt List the metadata of every space
+   * @examplePrompt Read the custom column values for all rooms
+   * @examplePrompt Get the metadata for these three spaces in one call
+   *
+   * # Example
+   * ```ts
+   * const { records } = await snaptrude.program.metadata.list()
+   * const byId = Object.fromEntries(records.map((r) => [r.spaceId, r.values]))
+   * ```
+   */
+  public abstract list(
+    spaceIds?: ComponentHandle[],
+  ): PluginApiReturn<PluginProgramMetadataListResult>
+
+  /**
+   * Update a space's metadata values (sparse).
+   *
+   * Only the headers present in `values` change; `null` clears a value. Every
+   * key must be an existing `headerId` (create columns first with
+   * {@linkcode PluginProgramMetadataApi.createHeader}). Undoable as one step.
+   *
+   * @param spaceId - The space (component id) to write.
+   * @param values - Header id → new cell value (`null` clears).
+   * @returns The space's full {@linkcode PluginProgramMetadataRecord} after the
+   *   write.
+   * @throws If the space or any header id does not exist.
+   *
+   * @examplePrompt Set the Occupancy metadata of this space to 4
+   * @examplePrompt Store a department code on the selected rooms
+   * @examplePrompt Write custom column values onto space sp_12
+   * @examplePrompt Clear the Finish Level metadata on this space
+   *
+   * # Example
+   * ```ts
+   * const header = await snaptrude.program.metadata.createHeader("Occupancy")
+   * await snaptrude.program.metadata.update("sp_12", { [header.headerId]: 4 })
+   * ```
+   */
+  public abstract update(
+    spaceId: ComponentHandle,
+    values: Record<string, PluginSpreadsheetCell>,
+  ): PluginApiReturn<PluginProgramMetadataUpdateResult>
+
+  /**
+   * Update metadata values on many spaces in one undoable step.
+   *
+   * The plural of {@linkcode PluginProgramMetadataApi.update}: each item names a
+   * space and its sparse `values`. Results are in input order. Capped at 1000
+   * items per call.
+   *
+   * @param items - The spaces and the values to write on each.
+   * @returns A {@linkcode PluginProgramMetadataUpdateManyResult} with one record
+   *   per item, in input order.
+   * @throws If any space or header id does not exist (nothing is written).
+   *
+   * @performance One round-trip and one undo step for up to 1000 spaces — use this instead of an `update` loop.
+   *
+   * @examplePrompt Fill the Occupancy column for all bedrooms
+   * @examplePrompt Write metadata onto every selected space at once
+   * @examplePrompt Bulk-update custom column values
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.program.metadata.updateMany([
+   *   { spaceId: "sp_12", values: { [headerId]: 4 } },
+   *   { spaceId: "sp_13", values: { [headerId]: 2 } },
+   * ])
+   * ```
+   */
+  public abstract updateMany(
+    items: PluginProgramMetadataUpdateItem[],
+  ): PluginApiReturn<PluginProgramMetadataUpdateManyResult>
+}
+
+/**
+ * A metadata header — one custom column of the Program Data sheet.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `headerId` | `string` | Stable header id (the key used in metadata `values`) |
+ * | `name` | `string` | Column header text |
+ * | `description` | `string` | Column description (`""` when none) |
+ * | `columnIndex` | `number` | Zero-based column index on the Program Data sheet |
+ */
+export const PluginProgramMetadataHeader = z.object({
+  headerId: z.string(),
+  name: z.string(),
+  description: z.string(),
+  columnIndex: z.number(),
+})
+export type PluginProgramMetadataHeader = z.infer<
+  typeof PluginProgramMetadataHeader
+>
+
+/**
+ * Result of {@linkcode PluginProgramMetadataApi.listHeaders}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `headers` | {@linkcode PluginProgramMetadataHeader}`[]` | Every custom column, in sheet column order |
+ */
+export const PluginProgramMetadataListHeadersResult = z.object({
+  headers: z.array(PluginProgramMetadataHeader),
+})
+export type PluginProgramMetadataListHeadersResult = z.infer<
+  typeof PluginProgramMetadataListHeadersResult
+>
+
+/**
+ * Arguments for {@linkcode PluginProgramMetadataApi.createHeader}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string` | Column header text (non-empty) |
+ * | `description` | `string?` | Column description |
+ */
+export const PluginProgramMetadataCreateHeaderArgs = z.object({
+  name: z.string().trim().min(1),
+  description: z.string().optional(),
+})
+export type PluginProgramMetadataCreateHeaderArgs = z.infer<
+  typeof PluginProgramMetadataCreateHeaderArgs
+>
+
+/** Result of {@linkcode PluginProgramMetadataApi.createHeader} — the created or reused header. */
+export const PluginProgramMetadataCreateHeaderResult = PluginProgramMetadataHeader
+export type PluginProgramMetadataCreateHeaderResult = z.infer<
+  typeof PluginProgramMetadataCreateHeaderResult
+>
+
+/**
+ * One space's metadata values.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `spaceId` | `ComponentHandle` | The space's component id |
+ * | `values` | `Record<string, cell>` | Header id → value, one entry per header the space has a value for |
+ */
+export const PluginProgramMetadataRecord = z.object({
+  spaceId: ComponentHandle,
+  values: z.record(z.string(), PluginSpreadsheetCell),
+})
+export type PluginProgramMetadataRecord = z.infer<
+  typeof PluginProgramMetadataRecord
+>
+
+/** Arguments for {@linkcode PluginProgramMetadataApi.get}. */
+export const PluginProgramMetadataGetArgs = z.object({
+  spaceId: ComponentHandle,
+})
+export type PluginProgramMetadataGetArgs = z.infer<
+  typeof PluginProgramMetadataGetArgs
+>
+
+/** Result of {@linkcode PluginProgramMetadataApi.get} — the record, or `null` when the space does not exist. */
+export const PluginProgramMetadataGetResult = PluginProgramMetadataRecord.nullable()
+export type PluginProgramMetadataGetResult = z.infer<
+  typeof PluginProgramMetadataGetResult
+>
+
+/**
+ * Arguments for {@linkcode PluginProgramMetadataApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `spaceIds` | `ComponentHandle[]?` | Spaces to read; omit for every space |
+ */
+export const PluginProgramMetadataListArgs = z.object({
+  spaceIds: z.array(ComponentHandle).optional(),
+})
+export type PluginProgramMetadataListArgs = z.infer<
+  typeof PluginProgramMetadataListArgs
+>
+
+/**
+ * Result of {@linkcode PluginProgramMetadataApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `records` | {@linkcode PluginProgramMetadataRecord}`[]` | One record per space (unknown ids skipped) |
+ */
+export const PluginProgramMetadataListResult = z.object({
+  records: z.array(PluginProgramMetadataRecord),
+})
+export type PluginProgramMetadataListResult = z.infer<
+  typeof PluginProgramMetadataListResult
+>
+
+/**
+ * Arguments for {@linkcode PluginProgramMetadataApi.update}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `spaceId` | `ComponentHandle` | The space to write |
+ * | `values` | `Record<string, cell>` | Header id → new value (`null` clears); at least one entry |
+ */
+export const PluginProgramMetadataUpdateArgs = z.object({
+  spaceId: ComponentHandle,
+  values: z
+    .record(z.string(), PluginSpreadsheetCell)
+    .refine((v) => Object.keys(v).length > 0, "values must not be empty"),
+})
+export type PluginProgramMetadataUpdateArgs = z.infer<
+  typeof PluginProgramMetadataUpdateArgs
+>
+
+/** Result of {@linkcode PluginProgramMetadataApi.update} — the space's record after the write. */
+export const PluginProgramMetadataUpdateResult = PluginProgramMetadataRecord
+export type PluginProgramMetadataUpdateResult = z.infer<
+  typeof PluginProgramMetadataUpdateResult
+>
+
+/** One item of {@linkcode PluginProgramMetadataApi.updateMany} — mirrors the `update` args. */
+export const PluginProgramMetadataUpdateItem = PluginProgramMetadataUpdateArgs
+export type PluginProgramMetadataUpdateItem = z.infer<
+  typeof PluginProgramMetadataUpdateItem
+>
+
+/** Maximum items per {@linkcode PluginProgramMetadataApi.updateMany} call. */
+export const PLUGIN_PROGRAM_METADATA_BATCH_LIMIT = 1000
+
+/**
+ * Arguments for {@linkcode PluginProgramMetadataApi.updateMany}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `items` | {@linkcode PluginProgramMetadataUpdateItem}`[]` | 1–1000 space updates |
+ */
+export const PluginProgramMetadataUpdateManyArgs = z.object({
+  items: z
+    .array(PluginProgramMetadataUpdateItem)
+    .min(1)
+    .max(PLUGIN_PROGRAM_METADATA_BATCH_LIMIT),
+})
+export type PluginProgramMetadataUpdateManyArgs = z.infer<
+  typeof PluginProgramMetadataUpdateManyArgs
+>
+
+/**
+ * Result of {@linkcode PluginProgramMetadataApi.updateMany}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `records` | {@linkcode PluginProgramMetadataRecord}`[]` | One record per item, in input order |
+ */
+export const PluginProgramMetadataUpdateManyResult = z.object({
+  records: z.array(PluginProgramMetadataRecord),
+})
+export type PluginProgramMetadataUpdateManyResult = z.infer<
+  typeof PluginProgramMetadataUpdateManyResult
+>