@snaptrude/plugin-core 0.0.0-bimsvg-20260928124803

package/dist/api/core/tags.d.ts

@@ -0,0 +1,860 @@
+import * as z from "zod";
+import { PluginApiReturn } from "../../types";
+import { ComponentHandle } from "../../handles";
+/**
+ * Tags — read and edit the tag catalog and its assignments.
+ *
+ * A **tag** is a colored label that lives in a **category**; a space carries at
+ * most one tag per category. This namespace is the catalog + assignment surface:
+ * the categories and tags themselves, which components carry which tags, and the
+ * assign/unassign operations. Tags attach to **Mass and Floor spaces only**.
+ *
+ * **Reserved sentinels.** The built-in **`DEPARTMENT`** category is owned by the
+ * program layer — it and the tags inside it are read-only here; create/update/
+ * delete reject it and direct you to {@linkcode PluginProgramApi}`.departments`.
+ * Every category also has a built-in **`DEFAULT`** tag that cannot be deleted;
+ * unassigning resets a component's category slot back to `DEFAULT` (a component
+ * is never left with a blank slot).
+ *
+ * Reads return plain records and never throw for a miss (`get*` return `null`,
+ * `list*` return `[]`). Ids are stable public strings.
+ *
+ * Sub-namespace members typed as optional (`?`) are **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 them (at which point they are promoted
+ * to required `abstract` members).
+ *
+ * Accessed via `snaptrude.core.tags`.
+ */
+export declare abstract class PluginCoreTagsApi {
+    constructor();
+    /**
+     * List the tag categories.
+     *
+     * @returns A {@linkcode PluginCoreTagsListCategoriesResult} with a `categories`
+     *   array (empty when there are none), including the reserved `DEPARTMENT`
+     *   category.
+     *
+     * @examplePrompt List all the tag categories
+     * @examplePrompt What tag categories do I have?
+     * @examplePrompt Show every category and its tags
+     *
+     * # Example
+     * ```ts
+     * const { categories } = await snaptrude.core.tags.listCategories()
+     * for (const c of categories) console.log(c.name, c.tagIds.length)
+     * ```
+     */
+    abstract listCategories(): PluginApiReturn<PluginCoreTagsListCategoriesResult>;
+    /**
+     * Get a single tag category by id.
+     *
+     * @param categoryId - The id of the category to read.
+     * @returns The matching {@linkcode PluginCoreTagCategory}, or `null` if no
+     *   category has that id.
+     *
+     * @examplePrompt Get the tag category with id cat_3
+     * @examplePrompt Look up a category by its id
+     * @examplePrompt Which tags are in this category?
+     *
+     * # Example
+     * ```ts
+     * const category = await snaptrude.core.tags.getCategory("cat_3")
+     * if (category) console.log(category.name, category.tagIds)
+     * ```
+     */
+    abstract getCategory(categoryId: string): PluginApiReturn<PluginCoreTagsGetCategoryResult>;
+    /**
+     * List tags, optionally within one category.
+     *
+     * @param categoryId - Optional category filter; omit to list every tag.
+     * @returns A {@linkcode PluginCoreTagsListResult} with a `tags` array (empty
+     *   when there are none).
+     *
+     * @examplePrompt List every tag in the project
+     * @examplePrompt Show the tags in category cat_3
+     * @examplePrompt What tags are available?
+     *
+     * # Example
+     * ```ts
+     * const { tags } = await snaptrude.core.tags.list("cat_3")
+     * for (const t of tags) console.log(t.name, t.color)
+     * ```
+     */
+    abstract list(categoryId?: string): PluginApiReturn<PluginCoreTagsListResult>;
+    /**
+     * Get a single tag by id.
+     *
+     * @param tagId - The id of the tag to read.
+     * @returns The matching {@linkcode PluginCoreTag}, or `null` if no tag has that
+     *   id.
+     *
+     * @examplePrompt Get the tag with id tag_9
+     * @examplePrompt Look up a single tag by its id
+     * @examplePrompt What color is this tag?
+     *
+     * # Example
+     * ```ts
+     * const tag = await snaptrude.core.tags.get("tag_9")
+     * if (tag) console.log(tag.name, tag.color)
+     * ```
+     */
+    abstract get(tagId: string): PluginApiReturn<PluginCoreTagsGetResult>;
+    /**
+     * List the tags carried by a component.
+     *
+     * Returns one entry per category the component is tagged in, each carrying the
+     * category and tag names and the tag color.
+     *
+     * @param componentId - The `Component.id` to read.
+     * @returns A {@linkcode PluginCoreTagsGetTagsForComponentResult} with a `tags`
+     *   array (empty when the component has none or does not exist).
+     *
+     * @examplePrompt What tags does this space have?
+     * @examplePrompt List the tags on component cmp_42
+     * @examplePrompt Show the labels applied to this room
+     *
+     * # Example
+     * ```ts
+     * const { tags } = await snaptrude.core.tags.getTagsForComponent("cmp_42")
+     * for (const t of tags) console.log(t.categoryName, t.tagName)
+     * ```
+     *
+     * @deprecated Use `core.tags.listForComponent`
+     */
+    abstract getTagsForComponent(componentId: ComponentHandle): PluginApiReturn<PluginCoreTagsGetTagsForComponentResult>;
+    /**
+     * List the tags carried by a component.
+     *
+     * Returns one entry per category the component is tagged in, each carrying the
+     * category and tag names and the tag color. Canonical home of the read formerly
+     * at `getTagsForComponent` (now deprecated).
+     *
+     * @param componentId - The `Component.id` to read.
+     * @returns A {@linkcode PluginCoreTagsGetTagsForComponentResult} with a `tags`
+     *   array (empty when the component has none or does not exist).
+     *
+     * @examplePrompt What tags does this space have?
+     * @examplePrompt List the tags on component cmp_42
+     * @examplePrompt Show the labels applied to this room
+     *
+     * # Example
+     * ```ts
+     * const { tags } = await snaptrude.core.tags.listForComponent("cmp_42")
+     * for (const t of tags) console.log(t.categoryName, t.tagName)
+     * ```
+     */
+    abstract listForComponent(componentId: ComponentHandle): PluginApiReturn<PluginCoreTagsGetTagsForComponentResult>;
+    /**
+     * List the tags carried by many components in one call.
+     *
+     * The plural of {@linkcode PluginCoreTagsApi.listForComponent}: pass
+     * `componentIds` to read specific components (unknown ids are skipped), or
+     * omit it to read **every** taggable component (Mass/Floor space) in the
+     * project. Each entry carries the component id and its tags — one per tagged
+     * category, with the tag's `color` — so a plugin can color every space by a
+     * chosen category's tag in a single round-trip.
+     *
+     * @param componentIds - Optional `Component.id`s to read; omit for all spaces.
+     * @returns A {@linkcode PluginCoreTagsListForComponentsResult} with a
+     *   `components` array, one entry per component (in input order when
+     *   `componentIds` is given).
+     *
+     * @performance One round-trip for any number of components — use this instead of a `listForComponent` loop.
+     *
+     * @examplePrompt Get the tags of every space with their colors
+     * @examplePrompt List the tags on all rooms so I can color them by Occupancy
+     * @examplePrompt Which tag does each selected space carry?
+     *
+     * # Example
+     * ```ts
+     * const { components } = await snaptrude.core.tags.listForComponents()
+     * for (const c of components) {
+     *   const occupancy = c.tags.find((t) => t.categoryName === "Occupancy")
+     *   if (occupancy) paint(c.componentId, occupancy.color)
+     * }
+     * ```
+     */
+    abstract listForComponents(componentIds?: ComponentHandle[]): PluginApiReturn<PluginCoreTagsListForComponentsResult>;
+    /**
+     * List the components carrying a given tag or category.
+     *
+     * Provide **exactly one** of `tagId` (components with that specific tag) or
+     * `categoryId` (components carrying any non-default tag in that category). With
+     * `categoryId`, pass `untagged: true` to instead return the components that have
+     * **no** non-default tag in that category. `untagged` is valid only alongside
+     * `categoryId`.
+     *
+     * @param filter - A {@linkcode PluginCoreTagsListComponentsArgs} filter with
+     *   exactly one of `tagId`, `categoryId`, plus optional `untagged` (with
+     *   `categoryId`).
+     * @returns A {@linkcode PluginCoreTagsListComponentsResult} with a
+     *   `componentIds` array (empty when none match).
+     *
+     * @examplePrompt Which spaces have the tag tag_9?
+     * @examplePrompt List every component tagged in category cat_3
+     * @examplePrompt Which spaces are untagged in the Occupancy category?
+     *
+     * # Example
+     * ```ts
+     * const { componentIds } = await snaptrude.core.tags.listComponents({ tagId: "tag_9" })
+     * console.log(`${componentIds.length} components`)
+     * ```
+     */
+    abstract listComponents(filter: {
+        tagId?: string;
+        categoryId?: string;
+        untagged?: boolean;
+    }): PluginApiReturn<PluginCoreTagsListComponentsResult>;
+    /**
+     * Create a new tag category.
+     *
+     * @param name - Display name of the new category.
+     * @returns The new {@linkcode PluginCoreTagCategory}.
+     * @throws If the name collides with the reserved `DEPARTMENT` category, or the
+     *   category could not be created.
+     *
+     * @examplePrompt Create a tag category called Fire Rating
+     * @examplePrompt Add a new category named Zone
+     * @examplePrompt Make a category for occupancy type
+     *
+     * # Example
+     * ```ts
+     * const category = await snaptrude.core.tags.createCategory("Fire Rating")
+     * ```
+     */
+    abstract createCategory(name: string): PluginApiReturn<PluginCoreTagsCreateCategoryResult>;
+    /**
+     * Rename a tag category.
+     *
+     * @param categoryId - The id of the category to rename.
+     * @param name - The category's new display name.
+     * @returns The updated {@linkcode PluginCoreTagCategory}.
+     * @throws If no category has the given id, or it is the reserved `DEPARTMENT`
+     *   category.
+     *
+     * @examplePrompt Rename category cat_3 to Occupancy
+     * @examplePrompt Change the name of this tag category
+     * @examplePrompt Update the Zone category's name
+     *
+     * # Example
+     * ```ts
+     * const category = await snaptrude.core.tags.updateCategory("cat_3", "Occupancy")
+     * ```
+     */
+    abstract updateCategory(categoryId: string, name: string): PluginApiReturn<PluginCoreTagsUpdateCategoryResult>;
+    /**
+     * Delete a tag category and all its tags.
+     *
+     * **Non-undoable.** Every component tagged in this category is reset to the
+     * category's `DEFAULT`; the result reports how many tags were removed and how
+     * many components were reset.
+     *
+     * @param categoryId - The id of the category to delete.
+     * @returns The impact counts (`deletedTagCount`, `resetComponentCount`).
+     * @throws If no category has the given id, or it is the reserved `DEPARTMENT`
+     *   category.
+     *
+     * @examplePrompt Delete the Zone tag category
+     * @examplePrompt Remove category cat_3 and all its tags
+     * @examplePrompt Delete this category
+     *
+     * # Example
+     * ```ts
+     * const { deletedTagCount } = await snaptrude.core.tags.deleteCategory("cat_3")
+     * ```
+     */
+    abstract deleteCategory(categoryId: string): PluginApiReturn<PluginCoreTagsDeleteCategoryResult>;
+    /**
+     * Create a new tag in a category.
+     *
+     * @param categoryId - The category the new tag belongs to.
+     * @param name - Display name of the new tag.
+     * @param color - Optional CSS hex color string (auto-assigned if omitted).
+     * @returns The new {@linkcode PluginCoreTag}.
+     * @throws If no category has the given id, or it is the reserved `DEPARTMENT`
+     *   category.
+     *
+     * @examplePrompt Add a tag called 2-hour to the Fire Rating category
+     * @examplePrompt Create a red High Priority tag in category cat_3
+     * @examplePrompt Make a new tag named Retail
+     *
+     * # Example
+     * ```ts
+     * const tag = await snaptrude.core.tags.create("cat_3", "Retail", "#b5e1dc")
+     * ```
+     */
+    abstract create(categoryId: string, name: string, color?: string): PluginApiReturn<PluginCoreTagsCreateResult>;
+    /**
+     * Update a tag's name and/or color.
+     *
+     * A **sparse** update: omitted fields are left unchanged.
+     *
+     * @param tagId - The id of the tag to update.
+     * @param options - Any of `name`, `color`; omitted fields are left unchanged.
+     * @returns The updated {@linkcode PluginCoreTag}.
+     * @throws If no tag has the given id, or it belongs to the reserved
+     *   `DEPARTMENT` category.
+     *
+     * @examplePrompt Rename tag tag_9 to Retail
+     * @examplePrompt Change this tag's color to #ff8800
+     * @examplePrompt Recolor the High Priority tag
+     *
+     * # Example
+     * ```ts
+     * const tag = await snaptrude.core.tags.update("tag_9", { name: "Retail" })
+     * ```
+     */
+    abstract update(tagId: string, options?: {
+        name?: string;
+        color?: string;
+    }): PluginApiReturn<PluginCoreTagsUpdateResult>;
+    /**
+     * Delete a tag.
+     *
+     * **Non-undoable.** Every component carrying this tag is reset to its
+     * category's `DEFAULT`; the result reports how many components were reset. The
+     * built-in `DEFAULT` tag of a category cannot be deleted.
+     *
+     * @param tagId - The id of the tag to delete.
+     * @returns The impact count (`resetComponentCount`).
+     * @throws If no tag has the given id, it is a `DEFAULT` tag, or it belongs to
+     *   the reserved `DEPARTMENT` category.
+     *
+     * @examplePrompt Delete the Retail tag
+     * @examplePrompt Remove tag tag_9
+     * @examplePrompt Delete this label
+     *
+     * # Example
+     * ```ts
+     * const { resetComponentCount } = await snaptrude.core.tags.delete("tag_9")
+     * ```
+     */
+    abstract delete(tagId: string): PluginApiReturn<PluginCoreTagsDeleteResult>;
+    /**
+     * Assign a tag to components, creating the category and tag if needed.
+     *
+     * Resolves `tagName` within the category named `categoryName`: if the category
+     * or the tag does not exist yet it is created, otherwise the existing one is
+     * reused. The resolved tag is then applied to each taggable component (Mass/Floor
+     * spaces) — resolve-or-create and assign are **one atomic, undoable action**.
+     * Because a component carries one tag per category, this replaces any existing
+     * tag from that category. Components that are locked, not taggable, or not found
+     * are returned in `skipped` with a reason — never silently dropped. Rejects the
+     * reserved `DEPARTMENT` category.
+     *
+     * @param componentIds - The components to tag (at least one).
+     * @param categoryName - The tag category; created if it does not exist (not
+     *   `DEPARTMENT`).
+     * @param tagName - The tag within the category; created if it does not exist,
+     *   else reused.
+     * @returns A {@linkcode PluginCoreTagsAssignResult} — the resolved
+     *   `categoryId`/`tagId`, whether each was created, and the `assigned`/`skipped`
+     *   split.
+     * @throws If `categoryName` is the reserved `DEPARTMENT` category.
+     *
+     * @examplePrompt Tag the selected spaces as Retail in the Zone category
+     * @examplePrompt Tag these rooms High Priority, creating the tag if it doesn't exist
+     * @examplePrompt Put cmp_1 and cmp_2 in Zone / Retail
+     *
+     * # Example
+     * ```ts
+     * const { tagId, tagCreated, assigned } = await snaptrude.core.tags.assign(
+     *   ["cmp_1", "cmp_2"],
+     *   "Zone",
+     *   "Retail",
+     * )
+     * ```
+     */
+    abstract assign(componentIds: ComponentHandle[], categoryName: string, tagName: string): PluginApiReturn<PluginCoreTagsAssignResult>;
+    /**
+     * Clear a category's tag from components.
+     *
+     * Resets each component's slot for the given category back to `DEFAULT` (a
+     * component always has a `DEFAULT` — the field is never blanked). Components
+     * that are locked, not taggable, or not found are returned in `skipped`.
+     *
+     * @param categoryId - The category slot to reset to default.
+     * @param componentIds - The components to clear (at least one).
+     * @returns A {@linkcode PluginCoreAssignOutcome} splitting `assigned` (reset to
+     *   default) from `skipped`.
+     * @throws If no category has the given id.
+     *
+     * @examplePrompt Remove the Occupancy tag from the selected spaces
+     * @examplePrompt Clear category cat_3 on components cmp_1 and cmp_2
+     * @examplePrompt Untag these rooms in the Zone category
+     *
+     * # Example
+     * ```ts
+     * await snaptrude.core.tags.unassign("cat_3", ["cmp_1", "cmp_2"])
+     * ```
+     */
+    abstract unassign(categoryId: string, componentIds: ComponentHandle[]): PluginApiReturn<PluginCoreTagsUnassignResult>;
+}
+/**
+ * A tag category — a named slot that holds a set of mutually-exclusive tags.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Stable public category id |
+ * | `name` | `string` | Display name |
+ * | `tagIds` | `string[]` | Ids of the tags in this category |
+ */
+export declare const PluginCoreTagCategory: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    tagIds: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type PluginCoreTagCategory = z.infer<typeof PluginCoreTagCategory>;
+/**
+ * A tag — a colored label within a category.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Stable public tag id |
+ * | `categoryId` | `string` | The id of the category this tag belongs to |
+ * | `name` | `string` | Display name |
+ * | `color` | `string` | CSS hex color string (e.g. `"#b5e1dc"`) |
+ */
+export declare const PluginCoreTag: z.ZodObject<{
+    id: z.ZodString;
+    categoryId: z.ZodString;
+    name: z.ZodString;
+    color: z.ZodString;
+}, z.core.$strip>;
+export type PluginCoreTag = z.infer<typeof PluginCoreTag>;
+/**
+ * A tag as carried by a component — the category and tag names resolved for
+ * display.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `categoryId` | `string` | The category's id |
+ * | `categoryName` | `string` | The category's display name |
+ * | `tagId` | `string` | The tag's id |
+ * | `tagName` | `string` | The tag's display name |
+ * | `color` | `string` | The tag's CSS hex color string |
+ */
+export declare const PluginCoreComponentTag: z.ZodObject<{
+    categoryId: z.ZodString;
+    categoryName: z.ZodString;
+    tagId: z.ZodString;
+    tagName: z.ZodString;
+    color: z.ZodString;
+}, z.core.$strip>;
+export type PluginCoreComponentTag = z.infer<typeof PluginCoreComponentTag>;
+/**
+ * The outcome of an assign/unassign — which components changed and which were
+ * skipped (with a reason).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `assigned` | `string[]` | Ids of the components that were changed |
+ * | `skipped` | `{ id: string; reason: "locked" \| "not-taggable" \| "not-found" }[]` | Components that were not changed, each with a reason |
+ */
+export declare const PluginCoreAssignOutcome: z.ZodObject<{
+    assigned: z.ZodArray<z.ZodString>;
+    skipped: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        reason: z.ZodEnum<{
+            locked: "locked";
+            "not-taggable": "not-taggable";
+            "not-found": "not-found";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginCoreAssignOutcome = z.infer<typeof PluginCoreAssignOutcome>;
+/**
+ * Result of {@linkcode PluginCoreTagsApi.listCategories}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `categories` | {@linkcode PluginCoreTagCategory}`[]` | Every tag category (including the reserved `DEPARTMENT`) |
+ */
+export declare const PluginCoreTagsListCategoriesResult: z.ZodObject<{
+    categories: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        tagIds: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginCoreTagsListCategoriesResult = z.infer<typeof PluginCoreTagsListCategoriesResult>;
+/**
+ * Arguments for {@linkcode PluginCoreTagsApi.getCategory}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `categoryId` | `string` | The id of the category to read |
+ */
+export declare const PluginCoreTagsGetCategoryArgs: z.ZodObject<{
+    categoryId: z.ZodString;
+}, z.core.$strip>;
+export type PluginCoreTagsGetCategoryArgs = z.infer<typeof PluginCoreTagsGetCategoryArgs>;
+/**
+ * Result of {@linkcode PluginCoreTagsApi.getCategory} — the category, or `null`
+ * when no category has the given id.
+ */
+export declare const PluginCoreTagsGetCategoryResult: z.ZodNullable<z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    tagIds: z.ZodArray<z.ZodString>;
+}, z.core.$strip>>;
+export type PluginCoreTagsGetCategoryResult = z.infer<typeof PluginCoreTagsGetCategoryResult>;
+/**
+ * Arguments for {@linkcode PluginCoreTagsApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `categoryId` | `string \| undefined` | Optional category filter; omit to list every tag |
+ */
+export declare const PluginCoreTagsListArgs: z.ZodObject<{
+    categoryId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PluginCoreTagsListArgs = z.infer<typeof PluginCoreTagsListArgs>;
+/**
+ * Result of {@linkcode PluginCoreTagsApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `tags` | {@linkcode PluginCoreTag}`[]` | The matching tags (empty when none) |
+ */
+export declare const PluginCoreTagsListResult: z.ZodObject<{
+    tags: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        categoryId: z.ZodString;
+        name: z.ZodString;
+        color: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginCoreTagsListResult = z.infer<typeof PluginCoreTagsListResult>;
+/**
+ * Arguments for {@linkcode PluginCoreTagsApi.get}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `tagId` | `string` | The id of the tag to read |
+ */
+export declare const PluginCoreTagsGetArgs: z.ZodObject<{
+    tagId: z.ZodString;
+}, z.core.$strip>;
+export type PluginCoreTagsGetArgs = z.infer<typeof PluginCoreTagsGetArgs>;
+/**
+ * Result of {@linkcode PluginCoreTagsApi.get} — the tag, or `null` when no tag
+ * has the given id.
+ */
+export declare const PluginCoreTagsGetResult: z.ZodNullable<z.ZodObject<{
+    id: z.ZodString;
+    categoryId: z.ZodString;
+    name: z.ZodString;
+    color: z.ZodString;
+}, z.core.$strip>>;
+export type PluginCoreTagsGetResult = z.infer<typeof PluginCoreTagsGetResult>;
+/**
+ * Arguments for {@linkcode PluginCoreTagsApi.getTagsForComponent}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `componentId` | `ComponentHandle` | The `Component.id` to read |
+ */
+export declare const PluginCoreTagsGetTagsForComponentArgs: z.ZodObject<{
+    componentId: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
+}, z.core.$strip>;
+export type PluginCoreTagsGetTagsForComponentArgs = z.infer<typeof PluginCoreTagsGetTagsForComponentArgs>;
+/**
+ * Result of {@linkcode PluginCoreTagsApi.getTagsForComponent}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `tags` | {@linkcode PluginCoreComponentTag}`[]` | The component's tags, one per tagged category (empty when none) |
+ */
+export declare const PluginCoreTagsGetTagsForComponentResult: z.ZodObject<{
+    tags: z.ZodArray<z.ZodObject<{
+        categoryId: z.ZodString;
+        categoryName: z.ZodString;
+        tagId: z.ZodString;
+        tagName: z.ZodString;
+        color: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginCoreTagsGetTagsForComponentResult = z.infer<typeof PluginCoreTagsGetTagsForComponentResult>;
+/**
+ * Arguments for {@linkcode PluginCoreTagsApi.listForComponents}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `componentIds` | `ComponentHandle[]?` | Components to read; omit for every taggable component |
+ */
+export declare const PluginCoreTagsListForComponentsArgs: z.ZodObject<{
+    componentIds: z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>>>;
+}, z.core.$strip>;
+export type PluginCoreTagsListForComponentsArgs = z.infer<typeof PluginCoreTagsListForComponentsArgs>;
+/**
+ * One component's tags, for {@linkcode PluginCoreTagsApi.listForComponents}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `componentId` | `ComponentHandle` | The component's id |
+ * | `tags` | {@linkcode PluginCoreComponentTag}`[]` | Its tags, one per tagged category (empty when none) |
+ */
+export declare const PluginCoreComponentTags: z.ZodObject<{
+    componentId: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
+    tags: z.ZodArray<z.ZodObject<{
+        categoryId: z.ZodString;
+        categoryName: z.ZodString;
+        tagId: z.ZodString;
+        tagName: z.ZodString;
+        color: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginCoreComponentTags = z.infer<typeof PluginCoreComponentTags>;
+/**
+ * Result of {@linkcode PluginCoreTagsApi.listForComponents}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `components` | {@linkcode PluginCoreComponentTags}`[]` | One entry per component |
+ */
+export declare const PluginCoreTagsListForComponentsResult: z.ZodObject<{
+    components: z.ZodArray<z.ZodObject<{
+        componentId: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
+        tags: z.ZodArray<z.ZodObject<{
+            categoryId: z.ZodString;
+            categoryName: z.ZodString;
+            tagId: z.ZodString;
+            tagName: z.ZodString;
+            color: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginCoreTagsListForComponentsResult = z.infer<typeof PluginCoreTagsListForComponentsResult>;
+/**
+ * Arguments for {@linkcode PluginCoreTagsApi.listComponents}. Provide exactly one
+ * of `tagId`, `categoryId`. `untagged` is valid only with `categoryId`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `tagId` | `string \| undefined` | Components carrying this specific tag |
+ * | `categoryId` | `string \| undefined` | Components carrying any non-default tag in this category |
+ * | `untagged` | `boolean \| undefined` | With `categoryId`, return components with **no** non-default tag in that category instead |
+ */
+export declare const PluginCoreTagsListComponentsArgs: z.ZodObject<{
+    tagId: z.ZodOptional<z.ZodString>;
+    categoryId: z.ZodOptional<z.ZodString>;
+    untagged: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type PluginCoreTagsListComponentsArgs = z.infer<typeof PluginCoreTagsListComponentsArgs>;
+/**
+ * Result of {@linkcode PluginCoreTagsApi.listComponents}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `componentIds` | `ComponentHandle[]` | Ids of the matching components (empty when none) |
+ */
+export declare const PluginCoreTagsListComponentsResult: z.ZodObject<{
+    componentIds: z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>>;
+}, z.core.$strip>;
+export type PluginCoreTagsListComponentsResult = z.infer<typeof PluginCoreTagsListComponentsResult>;
+/**
+ * Arguments for {@linkcode PluginCoreTagsApi.createCategory}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string` | Display name of the new category |
+ */
+export declare const PluginCoreTagsCreateCategoryArgs: z.ZodObject<{
+    name: z.ZodString;
+}, z.core.$strip>;
+export type PluginCoreTagsCreateCategoryArgs = z.infer<typeof PluginCoreTagsCreateCategoryArgs>;
+/** Result of {@linkcode PluginCoreTagsApi.createCategory} — the new category. */
+export declare const PluginCoreTagsCreateCategoryResult: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    tagIds: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type PluginCoreTagsCreateCategoryResult = z.infer<typeof PluginCoreTagsCreateCategoryResult>;
+/**
+ * Arguments for {@linkcode PluginCoreTagsApi.updateCategory}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `categoryId` | `string` | The id of the category to rename |
+ * | `name` | `string` | The category's new display name |
+ */
+export declare const PluginCoreTagsUpdateCategoryArgs: z.ZodObject<{
+    categoryId: z.ZodString;
+    name: z.ZodString;
+}, z.core.$strip>;
+export type PluginCoreTagsUpdateCategoryArgs = z.infer<typeof PluginCoreTagsUpdateCategoryArgs>;
+/** Result of {@linkcode PluginCoreTagsApi.updateCategory} — the updated category. */
+export declare const PluginCoreTagsUpdateCategoryResult: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    tagIds: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type PluginCoreTagsUpdateCategoryResult = z.infer<typeof PluginCoreTagsUpdateCategoryResult>;
+/**
+ * Arguments for {@linkcode PluginCoreTagsApi.deleteCategory}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `categoryId` | `string` | The id of the category to delete |
+ */
+export declare const PluginCoreTagsDeleteCategoryArgs: z.ZodObject<{
+    categoryId: z.ZodString;
+}, z.core.$strip>;
+export type PluginCoreTagsDeleteCategoryArgs = z.infer<typeof PluginCoreTagsDeleteCategoryArgs>;
+/**
+ * Result of {@linkcode PluginCoreTagsApi.deleteCategory} — the impact of the
+ * (non-undoable) delete.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `deletedTagCount` | `number` | Number of tags removed with the category |
+ * | `resetComponentCount` | `number` | Number of components reset to their default |
+ */
+export declare const PluginCoreTagsDeleteCategoryResult: z.ZodObject<{
+    deletedTagCount: z.ZodNumber;
+    resetComponentCount: z.ZodNumber;
+}, z.core.$strip>;
+export type PluginCoreTagsDeleteCategoryResult = z.infer<typeof PluginCoreTagsDeleteCategoryResult>;
+/**
+ * Arguments for {@linkcode PluginCoreTagsApi.create}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `categoryId` | `string` | The category the new tag belongs to |
+ * | `name` | `string` | Display name of the new tag |
+ * | `color` | `string \| undefined` | CSS hex color string (auto-assigned if omitted) |
+ */
+export declare const PluginCoreTagsCreateArgs: z.ZodObject<{
+    categoryId: z.ZodString;
+    name: z.ZodString;
+    color: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PluginCoreTagsCreateArgs = z.infer<typeof PluginCoreTagsCreateArgs>;
+/** Result of {@linkcode PluginCoreTagsApi.create} — the new tag. */
+export declare const PluginCoreTagsCreateResult: z.ZodObject<{
+    id: z.ZodString;
+    categoryId: z.ZodString;
+    name: z.ZodString;
+    color: z.ZodString;
+}, z.core.$strip>;
+export type PluginCoreTagsCreateResult = z.infer<typeof PluginCoreTagsCreateResult>;
+/**
+ * Arguments for {@linkcode PluginCoreTagsApi.update}. Sparse — only the provided
+ * fields are changed.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `tagId` | `string` | The id of the tag to update |
+ * | `name` | `string \| undefined` | New display name (unchanged if omitted) |
+ * | `color` | `string \| undefined` | New CSS hex color (unchanged if omitted) |
+ */
+export declare const PluginCoreTagsUpdateArgs: z.ZodObject<{
+    tagId: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    color: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PluginCoreTagsUpdateArgs = z.infer<typeof PluginCoreTagsUpdateArgs>;
+/** Result of {@linkcode PluginCoreTagsApi.update} — the updated tag. */
+export declare const PluginCoreTagsUpdateResult: z.ZodObject<{
+    id: z.ZodString;
+    categoryId: z.ZodString;
+    name: z.ZodString;
+    color: z.ZodString;
+}, z.core.$strip>;
+export type PluginCoreTagsUpdateResult = z.infer<typeof PluginCoreTagsUpdateResult>;
+/**
+ * Arguments for {@linkcode PluginCoreTagsApi.delete}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `tagId` | `string` | The id of the tag to delete |
+ */
+export declare const PluginCoreTagsDeleteArgs: z.ZodObject<{
+    tagId: z.ZodString;
+}, z.core.$strip>;
+export type PluginCoreTagsDeleteArgs = z.infer<typeof PluginCoreTagsDeleteArgs>;
+/**
+ * Result of {@linkcode PluginCoreTagsApi.delete} — the impact of the
+ * (non-undoable) delete.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `resetComponentCount` | `number` | Number of components reset to their category default |
+ */
+export declare const PluginCoreTagsDeleteResult: z.ZodObject<{
+    resetComponentCount: z.ZodNumber;
+}, z.core.$strip>;
+export type PluginCoreTagsDeleteResult = z.infer<typeof PluginCoreTagsDeleteResult>;
+/**
+ * Arguments for {@linkcode PluginCoreTagsApi.assign}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `componentIds` | `ComponentHandle[]` | The components to tag (at least one) |
+ * | `categoryName` | `string` | The tag category; created if it does not exist (not `DEPARTMENT`) |
+ * | `tagName` | `string` | The tag within the category; created if it does not exist, else reused |
+ */
+export declare const PluginCoreTagsAssignArgs: z.ZodObject<{
+    componentIds: z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>>;
+    categoryName: z.ZodString;
+    tagName: z.ZodString;
+}, z.core.$strip>;
+export type PluginCoreTagsAssignArgs = z.infer<typeof PluginCoreTagsAssignArgs>;
+/**
+ * Result of {@linkcode PluginCoreTagsApi.assign} — the resolved category/tag, what
+ * was created, and the assign outcome.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `categoryId` | `string` | Id of the resolved (or newly created) category |
+ * | `tagId` | `string` | Id of the resolved (or newly created) tag |
+ * | `categoryCreated` | `boolean` | Whether the category was created by this call |
+ * | `tagCreated` | `boolean` | Whether the tag was created by this call |
+ * | `assigned` | `string[]` | Ids of the components that were tagged |
+ * | `skipped` | `{ id: string; reason: "locked" \| "not-taggable" \| "not-found" }[]` | Components not tagged, each with a reason |
+ */
+export declare const PluginCoreTagsAssignResult: z.ZodObject<{
+    assigned: z.ZodArray<z.ZodString>;
+    skipped: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        reason: z.ZodEnum<{
+            locked: "locked";
+            "not-taggable": "not-taggable";
+            "not-found": "not-found";
+        }>;
+    }, z.core.$strip>>;
+    categoryId: z.ZodString;
+    tagId: z.ZodString;
+    categoryCreated: z.ZodBoolean;
+    tagCreated: z.ZodBoolean;
+}, z.core.$strip>;
+export type PluginCoreTagsAssignResult = z.infer<typeof PluginCoreTagsAssignResult>;
+/**
+ * Arguments for {@linkcode PluginCoreTagsApi.unassign}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `categoryId` | `string` | The category slot to reset to default |
+ * | `componentIds` | `ComponentHandle[]` | The components to clear (at least one) |
+ */
+export declare const PluginCoreTagsUnassignArgs: z.ZodObject<{
+    categoryId: z.ZodString;
+    componentIds: z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>>;
+}, z.core.$strip>;
+export type PluginCoreTagsUnassignArgs = z.infer<typeof PluginCoreTagsUnassignArgs>;
+/** Result of {@linkcode PluginCoreTagsApi.unassign} — the unassign outcome. */
+export declare const PluginCoreTagsUnassignResult: z.ZodObject<{
+    assigned: z.ZodArray<z.ZodString>;
+    skipped: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        reason: z.ZodEnum<{
+            locked: "locked";
+            "not-taggable": "not-taggable";
+            "not-found": "not-found";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginCoreTagsUnassignResult = z.infer<typeof PluginCoreTagsUnassignResult>;
+//# sourceMappingURL=tags.d.ts.map